--- /dev/null
+
+Change Summaries
+
+2019 July 11; Version 1.0.37
+
+ librmr and librmr_nng
+ - Add message buffer API function rmr_trace_ref()
+ (see rmr_trace_ref.3 manual page in dev package).
set( major_version "1" ) # should be automatically populated from git tag later, but until CI process sets a tag we use this
set( minor_version "0" )
-set( patch_level "36" )
+set( patch_level "37" )
set( install_root "${CMAKE_INSTALL_PREFIX}" )
set( install_lib "lib" )
rmr_mt_call.3
rmr_mt_rcv.3
rmr_get_srcip.3
+ rmr_trace_ref.3
)
# initialise lists of files we generated
rmr_str2xact(3),
rmr_wh_open(3),
rmr_wh_send_msg(3),
-rmr_set_trace(3)
+rmr_set_trace(3),
+rmr_trace_ref(3)
.ju on
--- /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_trace_ref.3.xfm
+ Abstract The manual page for the rmr_trace_ref function.
+ Author E. Scott Daniels
+ Date 11 July 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_trace_ref
+
+&h2(SYNOPSIS)
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
+&ex_end
+
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_trace_ref) function return a pointer to the trace area in the message, and optionally
+populate the user programme supplied size integer with the trace area size, if &ital(sizeptr) is
+not nil.
+
+&h2(RETURN VALUE)
+On success, a void pointer to the trace area of the message is returned.
+A nil pointer is returned if the message has no trace data area allocated, or if the message
+itself is invalid.
+
+
+&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
+
extern void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
extern void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
extern int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str );
+extern void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr );
extern int rmr_get_trlen( rmr_mbuf_t* msg );
extern int rmr_get_trace( rmr_mbuf_t* msg, unsigned char* dest, int size );
}
+/*
+ Returns a pointer (reference) to the trace data in the message. If sizeptr
+ is supplied, then the trace data size is assigned to the referenced
+ integer so that the caller doesn't need to make a second call to get the
+ value.
+
+ CAUTION: user programmes should avoid writing to the referenced trace
+ area (use rmr_set_trace() to avoid possible data overruns. This
+ function is a convenience, and it is expected that users will
+ use the trace data as read-only so as a copy is not necessary.
+*/
+extern void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr ) {
+ uta_mhdr_t* hdr = NULL;
+ int size = 0;
+
+ if( sizeptr != NULL ) {
+ *sizeptr = 0; // ensure reset if we bail
+ }
+
+ if( msg == NULL ) {
+ return NULL;
+ }
+
+ hdr = msg->header;
+ if( (size = RMR_TR_LEN( hdr )) <= 0 ) {
+ return NULL;
+ }
+
+ if( sizeptr != NULL ) {
+ *sizeptr = size;
+ }
+
+ return (void *) TRACE_ADDR( hdr );
+}
+
/*
Copies the trace bytes from the message header into the buffer provided by
the user. If the trace data in the header is less than size, then only
/*
Returns the string with the IP address as reported by the sender. This is
the IP address that the sender has sussed off of one of the interfaces
- and cannot be guarenteed to be the acutal IP address which was used to
+ and cannot be guarenteed to be the acutal IP address which was used to
establish the connection. The caller must provide a buffer of at least
64 bytes; the string will be nil terminated. A pointer to the user's buffer
is returned on success, nil on failure.
int state;
int errors = 0;
char* buf;
+ void* ptr;
rmr_mbuf_t* mbuf;
unsigned char src_buf[256];
state = rmr_get_trlen( NULL ); // coverage test on nil check
errors += fail_not_equal( state, 0, "get trace length with nil msg didn't return expected 0 status" );
+ ptr = rmr_trace_ref( NULL, NULL );
+ errors += fail_not_nil( ptr, "trace ref returned non-nil pointer when given nil message" );
+
+ mbuf = test_mk_msg( 2048, 0 ); // initially no trace size to force realloc
+ ptr = rmr_trace_ref( mbuf, NULL );
+ errors += fail_not_nil( ptr, "trace ref returned non-nil pointer when given a message without trace data" );
+
+ i = 100; // ensure that i is reset when there is no trace data
+ ptr = rmr_trace_ref( mbuf, &i );
+ errors += fail_not_nil( ptr, "trace ref returned non-nil pointer when given a message without trace data" );
+ errors += fail_not_equal( i, 0, "trace ref returned non zero size (a) when no trace info in message" );
+
+ i = 100;
+ mbuf = test_mk_msg( 2048, 113 ); // alloc with a trace data area
+ ptr = rmr_trace_ref( mbuf, &i );
+ errors += fail_if_nil( ptr, "trace ref returned nil pointer when given a message with trace data" );
+ errors += fail_not_equal( i, 113, "trace ref returned bad size (a), expected (b)" );
+
src_buf[0] = 0;
state = rmr_set_trace( mbuf, "foo bar was here", 17 ); // should force a realloc