rmr_support.3
rmr_torcv_msg.3
rmr_wh_send_msg.3
+ rmr_get_trace.3
+ rmr_init_trace.3
+ rmr_set_trace.3
+ rmr_tralloc_msg.3
+ rmr_get_trlen.3
)
# empty list of roff/troff input files we generated
&h2(SEE ALSO )
.ju off
rmr_alloc_msg(3),
+rmr_tralloc_msg(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_rcv_msg(3),
rmr_rcv_specific(3),
rmr_tokenise(3),
rmr_mk_ring(3),
rmr_ring_free(3),
+rmr_set_trace(3),
rmr_torcv_msg(3),
rmr_wh_open(3),
rmr_wh_send_msg(3)
&ex_start
#include <rmr/rmr.h>
-rmr_mbuf_t* rmr_alloc_msg( void* a, int size );
+rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
&ex_end
&uindent
out of the buffer.
If the value passed in &cw(size) is 0, then the default size supplied on the
&ital(rmr_init) call will be used.
-The &ital(a) parameter is the void context pointer that was returned by
+The &ital(ctx) parameter is the void context pointer that was returned by
the &ital(rmr_init) function.
&space
int mtype;
int len;
unsigned char* payload;
- unsigned char* a;
+ unsigned char* xaction;
} rmr_mbuf_t;
&ex_end
&half_space
-&ditem(a ) The &ital(a) 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(a) field.
+&ital(xaction) field.
&end_dlist
&h2(RETURN VALUE)
.** &h2(EXAMPLE)
&h2(SEE ALSO )
-rmr_mbuf(3)
+rmr_tralloc_msg(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_has_str(3),
rmr_tokenise(3),
rmr_mk_ring(3),
-rmr_ring_free(3)
-
+rmr_ring_free(3),
+rmr_set_trace(3)
.qu
--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 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.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+
+.if false
+ Mnemonic rmr_get_trace.3.xfm
+ Abstract The manual page for the rmr_get_trace function.
+ Author E. Scott Daniels
+ Date 19 April 2019
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+ .im &{lib}/generic_ps.im
+.ei
+ .gv e OUTPUT_RST use_rst
+ .if .ev &use_rst 1 =
+ .im &{lib}/rst.im
+ .ei
+ .im &{lib}/roff.im
+ .fi
+.fi
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_get_trace
+
+&h2(SYNOPSIS)
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size )
+&ex_end
+
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_get_trace) function will copy the trace information from the message into the user's
+allocated memory referenced by &cw(dest.)
+The &cw(size) parameter is assumed to be the maximum number of bytes which can be copied (size
+of the destination buffer).
+
+&h2(RETURN VALUE)
+On success, the number of bytes actually copied is returned.
+If the return value is 0, no bytes copied, then the reason could be that the message pointer
+was nil, or the size parameter was <= 0.
+
+
+&h2(SEE ALSO )
+.ju off
+rmr_alloc_msg(3),
+rmr_tralloc_msg(3),
+rmr_bytes2xact(3),
+rmr_bytes2meid(3),
+rmr_call(3),
+rmr_free_msg(3),
+rmr_get_rcvfd(3),
+rmr_get_trlen(3),
+rmr_init(3),
+rmr_init_trace(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_str2meid(3),
+rmr_str2xact(3),
+rmr_wh_open(3),
+rmr_wh_send_msg(3),
+rmr_set_trace(3)
+.ju on
+
+
+.qu
+
--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 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.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+.if false
+ Mnemonic rmr_get_trlen
+ Abstract The manual page for the get trace len function.
+ Author E. Scott Daniels
+ Date 19 April 2019
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+ .im &{lib}/generic_ps.im
+.ei
+ .gv e OUTPUT_RST use_rst
+ .if .ev &use_rst 1 =
+ .im &{lib}/rst.im
+ .ei
+ .im &{lib}/roff.im
+ .fi
+.fi
+
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_get_trlen
+
+&h2(SYNOPSIS )
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+int rmr_get_trlen( rmr_mbuf_t* msg );
+&ex_end
+&uindent
+
+&h2(DESCRIPTION)
+Given a message buffer, this function returns the amount of space (bytes)
+that have been allocated for trace data.
+If no trace data has been allocated, then 0 is returned.
+
+&h2(RETURN VALUE)
+The number of bytes allocated for trace information in the given message.
+
+&h2(ERRORS)
+&beg_dlist(.75i : ^&bold_font )
+&di(INVAL) Parameter(s) passed to the function were not valid.
+&end_dlist
+
+
+&h2(SEE ALSO )
+rmr_alloc_msg(3),
+rmr_call(3),
+rmr_free_msg(3),
+rmr_get_trace(3),
+rmr_init(3),
+rmr_init_trace(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_tralloc_msg(3)
+
+
+.qu
+
--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 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.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+
+.if false
+ Mnemonic rmr_init_trace_man.xfm
+ Abstract The manual page for the rmr_init_trace function.
+ Author E. Scott Daniels
+ Date 19 April 2019
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+ .im &{lib}/generic_ps.im
+.ei
+ .gv e OUTPUT_RST use_rst
+ .if .ev &use_rst 1 =
+ .im &{lib}/rst.im
+ .ei
+ .im &{lib}/roff.im
+ .fi
+.fi
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_init_trace
+
+&h2(SYNOPSIS)
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+void* rmr_init_trace( void* ctx )
+&ex_end
+
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_init_trace) function establishes the default trace space placed in each
+message buffer allocated with &cw(rmr_alloc_msg().)
+If this function is never called, then no trace space is allocated by default into
+any message buffer.
+
+.sp
+Trace space allows the user application to pass some trace token, or other data
+with the message, but outside of the payload.
+Trace data may be added to any message with &cw(rmr_set_trace(),) and may be extracted
+from a message with &cw(rmr_get_trace().)
+The number of bytes that a message contains for/with trace data can be determined by
+invoking &cw(rmr_get_trlen().)
+
+.sp
+This function may be safely called at any time during the life of the user programme
+to (re)set the default trace space reserved.
+If the user programme needs to allocate a message with trace space of a different
+size than is allocated by default, without fear of extra overhead of reallocating
+a message later, the &cw(rmr_tralloc_msg()) function can be used.
+
+&h2(RETURN VALUE)
+A value of 1 is returned on success, and 0 on failure. A failure indicates that the
+RMr context (void *) passed to this function was not valid.
+
+&h2(SEE ALSO )
+rmr_alloc_msg(3),
+rmr_tr_alloc_msg(3),
+rmr_call(3),
+rmr_free_msg(3),
+rmr_get_rcvfd(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)
+
+
+.qu
+
--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 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.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+
+.if false
+ Mnemonic rmr_set_trace.xfm
+ Abstract The manual page for the rmr_set_trace function.
+ Author E. Scott Daniels
+ Date 19 April 2019
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+ .im &{lib}/generic_ps.im
+.ei
+ .gv e OUTPUT_RST use_rst
+ .if .ev &use_rst 1 =
+ .im &{lib}/rst.im
+ .ei
+ .im &{lib}/roff.im
+ .fi
+.fi
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_set_trace
+
+&h2(SYNOPSIS)
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+int rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* data, int len )
+&ex_end
+
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_set_trace) function will copy &cw(len) bytes from &cw(data) into the trace portion of
+&cw(mbuf.)
+If the trace area of &cw(mbuf) is not the correct size, the message buffer will be reallocated
+to ensure that enough space is available for the trace data.
+
+
+&h2(RETURN VALUE)
+The &cw(rmr_set_trace) function returns the number of bytes successfully copied to the message.
+If 0 is returned either the message pointer was nil, or the size in the parameters was <= 0.
+
+
+
+&h2(SEE ALSO )
+rmr_alloc_msg(3),
+rmr_tralloc_msg(3),
+rmr_bytes2xact(3),
+rmr_bytes2payload(3),
+rmr_call(3),
+rmr_free_msg(3),
+rmr_get_rcvfd(3),
+rmr_get_meid(3),
+rmr_get_trace(3),
+rmr_get_trlen(3),
+rmr_init(3),
+rmr_init_trace(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_str2meid(3),
+rmr_str2xact(3),
+rmr_wh_open(3),
+rmr_wh_send_msg(3)
+
+
+
+.qu
+
--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 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.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.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
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+ .im &{lib}/generic_ps.im
+.ei
+ .gv e OUTPUT_RST use_rst
+ .if .ev &use_rst 1 =
+ .im &{lib}/rst.im
+ .ei
+ .im &{lib}/roff.im
+ .fi
+.fi
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_tralloc_msg
+
+&h2(SYNOPSIS )
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
+ 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 buffer is allocated such that sending it requires no additional copying
+from the buffer as it passes through the underlying transport mechanism.
+.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
+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.
+
+The &ital(vctx) parameter is the void context pointer that was returned by
+the &ital(rmr_init) function.
+
+
+&space
+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.
+
+&space
+&ex_start
+typedef struct {
+ int state;
+ int mtype;
+ int len;
+ unsigned char* payload;
+ unsigned char* xaction;
+} rmr_mbuf_t;
+&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.
+
+&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.
+&end_dlist
+
+&h2(RETURN VALUE)
+The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error.
+
+&h2(ERRORS)
+&beg_dlist(.75i : ^&bold_font )
+&di(ENOMEM) Unable to allocate memory.
+&end_dlist
+
+.** &h2(EXAMPLE)
+
+&h2(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)
+
+
+.qu
+
Code Review / ric-plt / lib / rmr.git / commitdiff