Add route table guide and formatting tweaks

[ric-plt/lib/rmr.git] / doc / src / man / rmr_alloc_msg.3.xfm

diff --git a/doc/src/man/rmr_alloc_msg.3.xfm b/doc/src/man/rmr_alloc_msg.3.xfm
index cbd3dc2..e83bf60 100644 (file)
--- a/doc/src/man/rmr_alloc_msg.3.xfm
+++ b/doc/src/man/rmr_alloc_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.
@@ -50,7 +50,7 @@ If the value passed in &cw(size) is less than or equal to 0, then the
 When &ital(size) is greater than zero, the message allocated will have at least
 the indicated number of bytes in the payload.
 There is no maximum size imposed by RMR, however the underlying system memory
-managerment (e.g. malloc) functions may impose a limit.
+management (e.g. malloc) functions may impose a limit.
 
 &space
 The &ital(ctx) parameter is the void context pointer that was returned by
@@ -75,8 +75,9 @@ typedef struct {
 &ex_end
 
 &space
+Where:
 &beg_dlist(.75i : ^&bold_font )
-&diitem(state)  Is the current buffer state.  Following a call to &cw(rmr_send_msg)
+&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
@@ -84,23 +85,20 @@ attempt a retransmission).
 When the state is &cw(RMR_OK) the buffer represents an empty buffer that the application
 may fill in in preparation to send.
 
-&half_space
-&diitem(mtype)  When sending a message, the application is expected to set this field
+&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 RMR 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
-&diitem(len) The application using a buffer to send a message is expected to set the
+&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.
 
-&half_space
-&diitem(payload) The payload is a pointer to the actual received data.  The
+&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.
@@ -108,16 +106,14 @@ Once the buffer has been passed back to a RMR library function the user programm
 should &bold(NOT) make use of the payload pointer.
 
 
-&half_space
-&diitem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
+&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 RMR processing
 expects that the matching reply message will also contain the same data in the
 &ital(xaction) field.
 
-&half_space
-&diitem(sub_id)
+&ditem(sub_id)
 This value is the subscription ID. It, in combination with the message type is used
 by rmr to determine the target endpoint when sending a message.
 If the application to application protocol does not warrant the use of a subscription
@@ -125,8 +121,7 @@ ID, the RMR constant RMR_VOID_SUBID should be placed in this field.
 When an application is forwarding or returning a buffer to the sender, it is the
 application's responsibility to set/reset this value.
 
-&half_space
-&diitem(tp_state)
+&ditem(tp_state)
 For C applications making use of RMR, the state of a transport based failure will
 often be available via &cw(errno.)
 However, some wrapper environments may not have direct access to the C-lib &cw(errno)
@@ -146,8 +141,6 @@ The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error.
 &di(ENOMEM) Unable to allocate memory.
 &end_dlist
 
-.** &h2(EXAMPLE)
-
 &h2(SEE ALSO )
 rmr_tralloc_msg(3),
 rmr_call(3),