X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_torcv_msg.3.rst;h=66f98e359978869216c2d368be3d20e101d7ec7a;hb=4f3e23473e3453d4b9c24d1cd727c481e5f59c74;hp=11e89408b769675293a0a52e7480c62b451eb843;hpb=503fe41e88b66ff8986c991bfbd075331b0bd166;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr_torcv_msg.3.rst b/docs/rmr_torcv_msg.3.rst index 11e8940..66f98e3 100644 --- a/docs/rmr_torcv_msg.3.rst +++ b/docs/rmr_torcv_msg.3.rst @@ -1,159 +1,168 @@ - - -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - - -============================================================================================ -Man Page: rmr_torcv_msg -============================================================================================ - -RMR Library Functions -============================================================================================ - - -NAME --------------------------------------------------------------------------------------------- - -rmr_torcv_msg - -SYNOPSIS --------------------------------------------------------------------------------------------- - - -:: - - #include - rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to ); - - - -DESCRIPTION --------------------------------------------------------------------------------------------- - -The rmr_torcv_msg function will pause for *ms_to* -milliseconds waiting for a message to arrive. If a message -arrives before the timeout expires the message buffer -returned will have a status of RMR_OK and the payload will -contain the data received. If the timeout expires before the -message is received, the status will have the value -RMR_ERR_TIMEOUT. When a received message is returned the -message buffer will also contain the message type and length -set by the sender. If messages were queued while waiting for -the response to a previous invocation of rmr_call, the oldest -message is removed from the queue and returned without delay. - -The *vctx* pointer is the pointer returned by the rmr_init -function. *Old_msg* is a pointer to a previously used message -buffer or NULL. The ability to reuse message buffers helps to -avoid alloc/free cycles in the user application. When no -buffer is available to supply, the receive function will -allocate one. - -RETURN VALUE --------------------------------------------------------------------------------------------- - -The function returns a pointer to the rmr_mbuf_t structure -which references the message information (state, length, -payload), or a nil pointer in the case of an extreme error. - -ERRORS --------------------------------------------------------------------------------------------- - -The *state* field in the message buffer will be one of the -following: - - - -RMR_OK - - The message buffer (payload) references the received data. - - -RMR_ERR_INITFAILED - - The first call to this function must initialise an - underlying system notification mechanism. On failure, this - error is returned and errno will have the system error - status set. If this function fails to intialise, the poll - mechansim, it is likely that message receives will never - be successful. - - -RMR_ERR_TIMEOUT - - The timeout expired before a complete message was - received. All other fields in the message buffer are not - valid. - - -RMR_ERR_EMPTY - - A message was received, but it had no payload. All other - fields in the message buffer are not valid. - - - - -INVAL - - Parameter(s) passed to the function were not valid. - - -EBADF - - The underlying message transport is unable to process the - request. - - -ENOTSUP - - The underlying message transport is unable to process the - request. - - -EFSM - - The underlying message transport is unable to process the - request. - - -EAGAIN - - The underlying message transport is unable to process the - request. - - -EINTR - - The underlying message transport is unable to process the - request. - - -ETIMEDOUT - - The underlying message transport is unable to process the - request. - - -ETERM - - The underlying message transport is unable to process the - request. - - -EXAMPLE --------------------------------------------------------------------------------------------- - - -SEE ALSO --------------------------------------------------------------------------------------------- - -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3), -rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3), -rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), -rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3) +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_torcv_msg +============================================================================================ + + + + +RMR LIBRARY FUNCTIONS +===================== + + + +NAME +---- + +rmr_torcv_msg + + +SYNOPSIS +-------- + + +:: + + #include + + rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to ); + + + +DESCRIPTION +----------- + +The ``rmr_torcv_msg`` function will pause for *ms_to* +milliseconds waiting for a message to arrive. If a message +arrives before the timeout expires the message buffer +returned will have a status of RMR_OK and the payload will +contain the data received. If the timeout expires before the +message is received, the status will have the value +RMR_ERR_TIMEOUT. When a received message is returned the +message buffer will also contain the message type and length +set by the sender. If messages were queued while waiting for +the response to a previous invocation of ``rmr_call,`` the +oldest message is removed from the queue and returned without +delay. + +The *vctx* pointer is the pointer returned by the +``rmr_init`` function. *Old_msg* is a pointer to a previously +used message buffer or NULL. The ability to reuse message +buffers helps to avoid alloc/free cycles in the user +application. When no buffer is available to supply, the +receive function will allocate one. + + +RETURN VALUE +------------ + +The function returns a pointer to the ``rmr_mbuf_t`` +structure which references the message information (state, +length, payload), or a nil pointer in the case of an extreme +error. + + +ERRORS +------ + +The *state* field in the message buffer will be one of the +following: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_OK** + - + The message buffer (payload) references the received data. + + * - **RMR_ERR_INITFAILED** + - + The first call to this function must initialise an underlying + system notification mechanism. On failure, this error is + returned and errno will have the system error status set. If + this function fails to initialise, the poll mechanism, it is + likely that message receives will never be successful. + + * - **RMR_ERR_TIMEOUT** + - + The timeout expired before a complete message was received. + All other fields in the message buffer are not valid. + + * - **RMR_ERR_EMPTY** + - + A message was received, but it had no payload. All other + fields in the message buffer are not valid. + + +Upon return the system error number, *errno* might be set +with a value that can help to explain the meaning of the +state indicated in the message. The following are possible: + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid. + + * - **EBADF** + - + The underlying message transport is unable to process the + request. + + * - **ENOTSUP** + - + The underlying message transport is unable to process the + request. + + * - **EFSM** + - + The underlying message transport is unable to process the + request. + + * - **EAGAIN** + - + The underlying message transport is unable to process the + request. + + * - **EINTR** + - + The underlying message transport is unable to process the + request. + + * - **ETIMEDOUT** + - + The underlying message transport is unable to process the + request. + + * - **ETERM** + - + The underlying message transport is unable to process the + request. + + + + +EXAMPLE +------- + + + +SEE ALSO +-------- + +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3), +rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3), +rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), +rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)