X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_tralloc_msg.3.rst;h=59ee5b300cd2c8b380e12108eff54a453d6faffb;hb=ece5bbead6922f59982227c9941babdd6054cf17;hp=02a8a7ca1fa6a273e12507f0982e39c73fadb89f;hpb=a3a121ca4a0426ec964fa684fb27c397f2ee9e24;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr_tralloc_msg.3.rst b/docs/rmr_tralloc_msg.3.rst index 02a8a7c..59ee5b3 100644 --- a/docs/rmr_tralloc_msg.3.rst +++ b/docs/rmr_tralloc_msg.3.rst @@ -1,14 +1,14 @@ -.. 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_tralloc_msg -============================================================================================ - - +.. 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_tralloc_msg +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,147 +19,147 @@ RMR LIBRARY FUNCTIONS NAME ---- -rmr_tralloc_msg +rmr_tralloc_msg SYNOPSIS -------- - -:: - - #include - - rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size, - int trace_size, unsigned const char *tr_data ); - + +:: + + #include + + rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size, + int trace_size, unsigned const char *tr_data ); + DESCRIPTION ----------- -The ``rmr_tralloc_msg`` function is used to allocate a buffer -which the user programme can write into and then send through -the library. The buffer is allocated such that sending it -requires no additional copying from the buffer as it passes -through the underlying transport mechanism. - -The *size* parameter is used to set the payload length in the -message. If it is 0, then the default size supplied on the -*rmr_init* call will be used. In addition to allocating the -payload, a space in the buffer is reserved for *trace* data -(tr_size bytes), and the bytes pointed to by *tr_data* are -copied into that portion of the message. The *vctx* parameter -is the void context pointer that was returned by the -*rmr_init* function. - -The pointer to the message buffer returned is a structure -which has some user application visible fields; the structure -is described in ``rmr.h,`` and is illustrated below. - - -:: - - typedef struct { - int state; - int mtype; - int len; - unsigned char* payload; - unsigned char* xaction; - } rmr_mbuf_t; - - -Where: - - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **state** - - - Is the current buffer state. Following a call to - ``rmr_send_msg`` the state indicates whether the buffer was - successfully sent which determines exactly what the payload - points to. If the send failed, the payload referenced by the - buffer is the message that failed to send (allowing the - application to attempt a retransmission). When the state is - ``a_OK`` the buffer represents an empty buffer that the - application may fill in in preparation to send. - - * - **mtype** - - - When sending a message, the application is expected to set - this field to the appropriate message type value (as - determined by the user programme). Upon send this value - determines how the a library will route the message. For a - buffer which has been received, this field will contain the - message type that was set by the sending application. - - * - **len** - - - The application using a buffer to send a message is expected - to set the length value to the actual number of bytes that it - placed into the message. This is likely less than the total - number of bytes that the message can carry. For a message - buffer that is passed to the application as the result of a - receive call, this will be the value that the sending - application supplied and should indicate the number of bytes - in the payload which are valid. - - * - **payload** - - - The payload is a pointer to the actual received data. The - user programme may read and write from/to the memory - referenced by the payload up until the point in time that the - buffer is used on a ``rmr_send, rmr_call`` or - ``rmr_reply`` function call. Once the buffer has been passed - back to a a library function the user programme should - **NOT** make use of the payload pointer. - - * - **xaction** - - - The *xaction* field is a pointer to a fixed sized area in the - message into which the user may write a transaction ID. The - ID is optional with the exception of when the user - application uses the ``rmr_call`` function to send a message - and wait for the reply; the underlying processing expects - that the matching reply message will also contain the same - data in the *xaction* field. - - +The ``rmr_tralloc_msg`` function is used to allocate a buffer +which the user programme can write into and then send through +the library. The buffer is allocated such that sending it +requires no additional copying from the buffer as it passes +through the underlying transport mechanism. + +The *size* parameter is used to set the payload length in the +message. If it is 0, then the default size supplied on the +*rmr_init* call will be used. In addition to allocating the +payload, a space in the buffer is reserved for *trace* data +(tr_size bytes), and the bytes pointed to by *tr_data* are +copied into that portion of the message. The *vctx* parameter +is the void context pointer that was returned by the +*rmr_init* function. + +The pointer to the message buffer returned is a structure +which has some user application visible fields; the structure +is described in ``rmr.h,`` and is illustrated below. + + +:: + + typedef struct { + int state; + int mtype; + int len; + unsigned char* payload; + unsigned char* xaction; + } rmr_mbuf_t; + + +Where: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **state** + - + Is the current buffer state. Following a call to + ``rmr_send_msg`` the state indicates whether the buffer was + successfully sent which determines exactly what the payload + points to. If the send failed, the payload referenced by the + buffer is the message that failed to send (allowing the + application to attempt a retransmission). When the state is + ``a_OK`` the buffer represents an empty buffer that the + application may fill in in preparation to send. + + * - **mtype** + - + When sending a message, the application is expected to set + this field to the appropriate message type value (as + determined by the user programme). Upon send this value + determines how the a library will route the message. For a + buffer which has been received, this field will contain the + message type that was set by the sending application. + + * - **len** + - + The application using a buffer to send a message is expected + to set the length value to the actual number of bytes that it + placed into the message. This is likely less than the total + number of bytes that the message can carry. For a message + buffer that is passed to the application as the result of a + receive call, this will be the value that the sending + application supplied and should indicate the number of bytes + in the payload which are valid. + + * - **payload** + - + The payload is a pointer to the actual received data. The + user programme may read and write from/to the memory + referenced by the payload up until the point in time that the + buffer is used on a ``rmr_send, rmr_call`` or + ``rmr_reply`` function call. Once the buffer has been passed + back to a a library function the user programme should + **NOT** make use of the payload pointer. + + * - **xaction** + - + The *xaction* field is a pointer to a fixed sized area in the + message into which the user may write a transaction ID. The + ID is optional with the exception of when the user + application uses the ``rmr_call`` function to send a message + and wait for the reply; the underlying processing expects + that the matching reply message will also contain the same + data in the *xaction* field. + + RETURN VALUE ------------ -The function returns a pointer to a ``rmr_mbuf`` structure, -or NULL on error. +The function returns a pointer to a ``rmr_mbuf`` structure, +or NULL on error. ERRORS ------ - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **ENOMEM** - - - Unable to allocate memory. - - + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **ENOMEM** + - + Unable to allocate memory. + + SEE ALSO -------- -rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3), -rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), -rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_rcv_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), rmr_set_trace(3) +rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3), +rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), +rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_rcv_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), rmr_set_trace(3)