X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr_torcv_msg.3.xfm;h=a596cbee5d47b94b561c0c97ba84a839f0112faf;hb=a3a121ca4a0426ec964fa684fb27c397f2ee9e24;hp=ffe26dc46612505e66c93cfc25b37371e8970653;hpb=7d1b7b0de82414ad25ebd323b2913de72ab448c1;p=ric-plt%2Flib%2Frmr.git diff --git a/doc/src/man/rmr_torcv_msg.3.xfm b/doc/src/man/rmr_torcv_msg.3.xfm index ffe26dc..a596cbe 100644 --- a/doc/src/man/rmr_torcv_msg.3.xfm +++ b/doc/src/man/rmr_torcv_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,20 +17,20 @@ ================================================================================== .fi .if false - Mnemonic rmr_torcv_msg_man.xfm - Abstract The manual page for the rmr_torcv_msg function. - Author E. Scott Daniels - Date 29 January 2019 + Mnemonic rmr_torcv_msg_man.xfm + Abstract The manual page for the rmr_torcv_msg function. + Author E. Scott Daniels + Date 29 January 2019 .fi .gv e LIB lib -.im &{lib}/man/setup.im +.im &{lib}/man/setup.im &line_len(6i) &h1(RMR Library Functions) &h2(NAME) - rmr_torcv_msg + rmr_torcv_msg &h2(SYNOPSIS ) &indent @@ -43,74 +43,68 @@ rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to ); &h2(DESCRIPTION) The &cw(rmr_torcv_msg) function will pause for &ital(ms_to) milliseconds waiting -for a message to arrive. +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 +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 &cw(rmr_call,) the oldest message is removed from the queue and returned +If messages were queued while waiting for the response to a previous invocation +of &cw(rmr_call,) the oldest message is removed from the queue and returned without delay. &space The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function. -&ital(Old_msg) is a pointer to a previously used message buffer or NULL. +&ital(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. +user application. When no buffer is available to supply, the receive function will allocate one. &h2(RETURN VALUE) The function returns a pointer to the &cw(rmr_mbuf_t) structure which references -the message information (state, length, payload), or a NULL pointer in the case +the message information (state, length, payload), or a nil pointer in the case of an extreme error. &h2(ERRORS) The &ital(state) field in the message buffer will be one of the following: &space + &beg_dlist(.75i : ^&bold_font ) -&di(RMR_OK) The message buffer (payload) references the received data. +&ditem(RMR_OK) The message buffer (payload) references the received data. -&space -&di(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. +&ditem(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. -&space -&di(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received. - All other fields in the message buffer are not valid. +&ditem(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received. + All other fields in the message buffer are not valid. -&space -&di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other - fields in the message buffer are not valid. +&ditem(RMR_ERR_EMPTY) A message was received, but it had no payload. All other + fields in the message buffer are not valid. &end_dlist -&space + +Upon return the system error number, &ital(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: &beg_dlist(.75i : ^&bold_font ) -&di(INVAL) Parameter(s) passed to the function were not valid. +&ditem(INVAL) Parameter(s) passed to the function were not valid. -&half_space -&di(EBADF) The underlying message transport is unable to process the request. +&ditem(EBADF) The underlying message transport is unable to process the request. -&half_space -&di(ENOTSUP) The underlying message transport is unable to process the request. +&ditem(ENOTSUP) The underlying message transport is unable to process the request. -&half_space -&di(EFSM) The underlying message transport is unable to process the request. +&ditem(EFSM) The underlying message transport is unable to process the request. -&half_space -&di(EAGAIN) The underlying message transport is unable to process the request. +&ditem(EAGAIN) The underlying message transport is unable to process the request. -&half_space -&di(EINTR) The underlying message transport is unable to process the request. +&ditem(EINTR) The underlying message transport is unable to process the request. -&half_space -&di(ETIMEDOUT) The underlying message transport is unable to process the request. +&ditem(ETIMEDOUT) The underlying message transport is unable to process the request. -&half_space -&di(ETERM) The underlying message transport is unable to process the request. +&ditem(ETERM) The underlying message transport is unable to process the request. &end_dlist &h2(EXAMPLE) @@ -135,6 +129,3 @@ rmr_mk_ring(3), rmr_ring_free(3) .ju on - -.qu -