Code Review / ric-plt / lib / rmr.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | review | tree
raw | inline | side by side
Repair minor flaws in wormhole function docs
[ric-plt/lib/rmr.git] / doc / src / man / rmr_tralloc_msg.3.xfm
diff --git a/doc/src/man/rmr_tralloc_msg.3.xfm b/doc/src/man/rmr_tralloc_msg.3.xfm
index 0f26cf1..76c65d1 100644 (file)
--- a/doc/src/man/rmr_tralloc_msg.3.xfm
+++ b/doc/src/man/rmr_tralloc_msg.3.xfm
@@ -1,7 +1,7 @@
 .if false
 ==================================================================================
 .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.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -17,41 +17,41 @@
 ==================================================================================
 .fi
 .if false
 ==================================================================================
 .fi
 .if false
-       Mnemonic        rmr_tralloc_msg.xfm
-       Abstract        The manual page for the rmr_tralloc_msg function.
-       Author          E. Scott Daniels
-       Date            19 April 2019
+    Mnemonic    rmr_tralloc_msg.xfm
+    Abstract    The manual page for the rmr_tralloc_msg function.
+    Author      E. Scott Daniels
+    Date        19 April 2019
 .fi
 
 .gv e LIB lib
 .fi
 
 .gv e LIB lib
-.im &{lib}/man/setup.im 
+.im &{lib}/man/setup.im
 
 &line_len(6i)
 
 &h1(RMR Library Functions)
 &h2(NAME)
 
 &line_len(6i)
 
 &h1(RMR Library Functions)
 &h2(NAME)
-       rmr_tralloc_msg
+    rmr_tralloc_msg
 
 &h2(SYNOPSIS )
 &indent
 &ex_start
 #include <rmr/rmr.h>
 
 
 &h2(SYNOPSIS )
 &indent
 &ex_start
 #include <rmr/rmr.h>
 
-rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size, 
+rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
                              int trace_size, unsigned const char *tr_data );
 &ex_end
 &uindent
 
 &h2(DESCRIPTION)
                              int trace_size, unsigned const char *tr_data );
 &ex_end
 &uindent
 
 &h2(DESCRIPTION)
-The &cw(rmr_alloc_msg) function is used to allocate a buffer which the user 
-programme can write into and then send through the a library.
+The &cw(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
 The buffer is allocated such that sending it requires no additional copying
-from the buffer as it passes through the underlying transport mechanism. 
+from the buffer as it passes through the underlying transport mechanism.
 .sp
 
 .sp
 
-The &ital(size) parameter is used to set the payload length in the message and
-If it is 0, then the default size supplied on the &ital(rmr_init) call will be used. 
-In addition to allocating the payload, a space in the buffer is 
+The &ital(size) parameter is used to set the payload length in the message.
+If it is 0, then the default size supplied on the &ital(rmr_init) call will be used.
+In addition to allocating the payload, a space in the buffer is
 reserved for &ital(trace) data (tr_size bytes), and the bytes pointed to
 by &ital(tr_data) are copied into that portion of the message.
 
 reserved for &ital(trace) data (tr_size bytes), and the bytes pointed to
 by &ital(tr_data) are copied into that portion of the message.
 
@@ -60,7 +60,7 @@ the &ital(rmr_init) function.
 
 
 &space
 
 
 &space
-The pointer to the message buffer returned is a structure which has some 
+The pointer to the message buffer returned is a structure which has some
 user application visible fields; the structure is described in &cw(rmr.h,)
 and is illustrated below.
 
 user application visible fields; the structure is described in &cw(rmr.h,)
 and is illustrated below.
 
@@ -76,46 +76,44 @@ typedef struct {
 &ex_end
 
 &space
 &ex_end
 
 &space
-&beg_dlist(.75i : ^&bold_font )
-&ditem(state )  Is the current buffer state.  Following a call to &cw(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 &cw(a_OK) the buffer represents an empty buffer that the application
-may fill in in preparation to send.
-
-&half_space
-&ditem(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. 
-
-&half_space
-&ditem(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.
-
+Where:
 &half_space
 &half_space
-&ditem(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 &cw(rmr_send, rmr_call)
-or &cw(rmr_reply) function call.  
-Once the buffer has been passed back to a a library function the user programme
-should &bold(NOT) make use of the payload pointer.
 
 
-
-&half_space
-&ditem(xaction) The &ital(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 &cw(rmr_call)
-function to send a message and wait for the reply; the underlying a processing
-expects that the matching reply message will also contain the same data in the
-&ital(xaction) field.
+&beg_dlist(.75i : ^&bold_font )
+&ditem(state)  Is the current buffer state.  Following a call to &cw(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 &cw(a_OK) the buffer represents an empty buffer that the application
+       may fill in in preparation to send.
+
+&ditem(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.
+
+&ditem(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.
+
+&ditem(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 &cw(rmr_send, rmr_call)
+       or &cw(rmr_reply) function call.
+       Once the buffer has been passed back to a a library function the user programme
+       should &bold(NOT) make use of the payload pointer.
+
+&ditem(xaction) The &ital(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 &cw(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
+       &ital(xaction) field.
 &end_dlist
 
 &h2(RETURN VALUE)
 &end_dlist
 
 &h2(RETURN VALUE)
@@ -123,12 +121,13 @@ The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error.
 
 &h2(ERRORS)
 &beg_dlist(.75i : ^&bold_font )
 
 &h2(ERRORS)
 &beg_dlist(.75i : ^&bold_font )
-&di(ENOMEM) Unable to allocate memory.
+&ditem(ENOMEM) Unable to allocate memory.
 &end_dlist
 
 .** &h2(EXAMPLE)
 
 &h2(SEE ALSO )
 &end_dlist
 
 .** &h2(EXAMPLE)
 
 &h2(SEE ALSO )
+.ju off
 rmr_alloc_msg(3),
 rmr_mbuf(3)
 rmr_call(3),
 rmr_alloc_msg(3),
 rmr_mbuf(3)
 rmr_call(3),
@@ -149,7 +148,5 @@ rmr_tokenise(3),
 rmr_mk_ring(3),
 rmr_ring_free(3),
 rmr_set_trace(3)
 rmr_mk_ring(3),
 rmr_ring_free(3),
 rmr_set_trace(3)
-
-
-.qu
+.ju on
 
 
An library for low latency message routing based on message type