X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr_rts_msg.3.xfm;h=016e82638329668ac65aad06580c1796a5849a1c;hb=fa454008020483ac35e1d20300cddfe877d8dd6d;hp=830f6a67f2a825c8390bc4fa7dfe6515e857c1e6;hpb=e30fc3a978dd2d34b35342273e6601ae6148b4bf;p=ric-plt%2Flib%2Frmr.git diff --git a/doc/src/man/rmr_rts_msg.3.xfm b/doc/src/man/rmr_rts_msg.3.xfm index 830f6a6..016e826 100644 --- a/doc/src/man/rmr_rts_msg.3.xfm +++ b/doc/src/man/rmr_rts_msg.3.xfm @@ -1,7 +1,7 @@ .if false ================================================================================== - Copyright (c) 2019 Nokia - Copyright (c) 2018-2019 AT&T Intellectual Property. + Copyright (c) 2019-2020 Nokia + Copyright (c) 2018-2020 AT&T Intellectual Property. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -17,31 +17,20 @@ ================================================================================== .fi .if false - Mnemonic rmr_rts_msg_man.xfm - Abstract The manual page for the rmr_rts_msg function. - Author E. Scott Daniels - Date 28 January 2019 + Mnemonic rmr_rts_msg_man.xfm + Abstract The manual page for the rmr_rts_msg function. + Author E. Scott Daniels + Date 28 January 2019 .fi -.** if formatting with tfm, the roff.im will cause roff output to be generated -.** if formatting with pfm, then pretty postscript will be generated .gv e LIB lib -.if pfm - .im &{lib}/generic_ps.im -.ei - .gv e OUTPUT_RST use_rst - .if .ev &use_rst 1 = - .im &{lib}/rst.im - .ei - .im &{lib}/roff.im - .fi -.fi +.im &{lib}/man/setup.im &line_len(6i) &h1(RMR Library Functions) &h2(NAME) - rmr_rts_msg + rmr_rts_msg &h2(SYNOPSIS ) &indent @@ -54,13 +43,26 @@ rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg ); &h2(DESCRIPTION) The &cw(rmr_rts_msg) function sends a message returning it to the endpoint -which sent the message rather than selecting an endpoint based on the -message type and routing table. +which sent the message rather than selecting an endpoint based on the +message type and routing table. Other than this small difference, the behaviour is exactly the same as &cw(rmr_send_msg.) .** pull in common retry text -.im &{lib}/man/retry.im +.im &{lib}/man/retry.im + +&h2(PAYLOAD SIZE) +When crafting a response based on a received message, the user application must +take care not to write more bytes to the message payload than the allocated message +has. +In the case of a received message, it is possible that the response needs to be +larger than the payload associated with the inbound message. +In order to use the return to sender function, the source information in the original +message must be present in the response; information which cannot be added to a +message buffer allocated through the standard RMR allocation function. +To allocate a buffer with a larger payload, and which retains the necessary sender +data needed by this function, the &ital(rmr_realloc_payload()) function must be +used to extend the payload to a size suitable for the response. &h2(RETURN VALUE) On success, a new message buffer, with an empty payload, is returned for the application @@ -69,64 +71,54 @@ The state in this buffer will reflect the overall send operation state and shoul &cw(RMR_OK.) &space -If the state in the returned buffer is anything other than &cw(UT_OK,) the user application +If the state in the returned buffer is anything other than &cw(RMR_OK,) the user application may need to attempt a retransmission of the message, or take other action depending on the -setting of &cw(errno) as described below. +setting of &cw(errno) as described below. &space -In the event of extreme failure, a NULL pointer is returned. In this case the value of -&cw(errno) might be of some use, for documentation, but there will be little that the +In the event of extreme failure, a nil pointer is returned. In this case the value of +&cw(errno) might be of some use, for documentation, but there will be little that the user application can do other than to move on. &h2(ERRORS) The following values may be passed back in the &ital(state) field of the returned message -buffer. +buffer. &space &beg_dlist(.75i : ^&bold_font ) -&di(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message. -&di(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted. -&di(RMR_ERR_NOENDPT) The message type in the message buffer did not map to a known endpoint. -&di(RMR_ERR_SENDFAILED) The send failed; &cw(errno) has the possible reason. +&ditem(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message. +&ditem(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted. +&ditem(RMR_ERR_NOENDPT) The message type in the message buffer did not map to a known endpoint. +&ditem(RMR_ERR_SENDFAILED) The send failed; &cw(errno) has the possible reason. &end_dlist &space The following values may be assigned to &cw(errno) on failure. + &beg_dlist(.75i : ^&bold_font ) -&di(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message. +&ditem(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message. -&half_space -&di(ENOKEY) The header information in the message buffer was invalid. +&ditem(ENOKEY) The header information in the message buffer was invalid. -&half_space -&di(ENXIO) No known endpoint for the message could be found. +&ditem(ENXIO) No known endpoint for the message could be found. -&half_space -&di(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent). +&ditem(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent). -&half_space -&di(EFAULT) The message referenced by the message buffer is corrupt (NULL pointer or bad internal length). +&ditem(EFAULT) The message referenced by the message buffer is corrupt (nil pointer or bad internal length). -&half_space -&di(EBADF) Internal RMR error; information provided to the message transport environment was not valid. +&ditem(EBADF) Internal RMR error; information provided to the message transport environment was not valid. -&half_space -&di(ENOTSUP) Sending was not supported by the underlying message transport. +&ditem(ENOTSUP) Sending was not supported by the underlying message transport. -&half_space -&di(EFSM) The device is not in a state that can accept the message. +&ditem(EFSM) The device is not in a state that can accept the message. -&half_space -&di(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend. +&ditem(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend. -&half_space -&di(EINTR) The operation was interrupted by delivery of a signal before the message was sent. +&ditem(EINTR) The operation was interrupted by delivery of a signal before the message was sent. -&half_space -&di(ETIMEDOUT) The underlying message environment timed out during the send process. +&ditem(ETIMEDOUT) The underlying message environment timed out during the send process. -&half_space -&di(ETERM) The underlying message environment is in a shutdown state. +&ditem(ETERM) The underlying message environment is in a shutdown state. &end_dlist &h2(EXAMPLE) @@ -150,6 +142,3 @@ rmr_mk_ring(3), rmr_ring_free(3) .ju on - -.qu -