From: E. Scott Daniels Date: Thu, 11 Jul 2019 14:24:01 +0000 (-0400) Subject: generate Add mbuf api funcion to reference to trace dat1 X-Git-Tag: 1.0.44~10 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=a7610c690a3976e296ca768977e38ceb9aafa5ff;p=ric-plt%2Flib%2Frmr.git generate Add mbuf api funcion to reference to trace dat1 The rmr_trace_ref() function has been added to allow the user programme the ability to obtain a direct reference to the trace data in a message buffer. Signed-off-by: E. Scott Daniels Change-Id: I2450dc4473b815460a8f011897f4b0a16d45fc51 Signed-off-by: E. Scott Daniels --- diff --git a/CHANGES b/CHANGES new file mode 100644 index 0000000..0d8dbfa --- /dev/null +++ b/CHANGES @@ -0,0 +1,8 @@ + +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). diff --git a/CMakeLists.txt b/CMakeLists.txt index 9127049..7e27358 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -31,7 +31,7 @@ cmake_minimum_required( VERSION 3.5 ) 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" ) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index a4be121..27becbd 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -83,6 +83,7 @@ if( BUILD_DOC ) rmr_mt_call.3 rmr_mt_rcv.3 rmr_get_srcip.3 + rmr_trace_ref.3 ) # initialise lists of files we generated diff --git a/doc/src/man/rmr_get_trace.3.xfm b/doc/src/man/rmr_get_trace.3.xfm index 70417c9..f22596a 100644 --- a/doc/src/man/rmr_get_trace.3.xfm +++ b/doc/src/man/rmr_get_trace.3.xfm @@ -93,7 +93,8 @@ rmr_str2meid(3), 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 diff --git a/doc/src/man/rmr_trace_ref.3.xfm b/doc/src/man/rmr_trace_ref.3.xfm new file mode 100644 index 0000000..a5db1dd --- /dev/null +++ b/doc/src/man/rmr_trace_ref.3.xfm @@ -0,0 +1,100 @@ +.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 + +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 + diff --git a/src/rmr/common/include/rmr.h b/src/rmr/common/include/rmr.h index eb24e55..a824a2a 100644 --- a/src/rmr/common/include/rmr.h +++ b/src/rmr/common/include/rmr.h @@ -138,6 +138,7 @@ extern int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str ); 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 ); diff --git a/src/rmr/common/src/mbuf_api.c b/src/rmr/common/src/mbuf_api.c index 6d9042a..1074e37 100644 --- a/src/rmr/common/src/mbuf_api.c +++ b/src/rmr/common/src/mbuf_api.c @@ -279,6 +279,41 @@ extern int rmr_set_trace( rmr_mbuf_t* msg, unsigned const char* data, 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 @@ -351,7 +386,7 @@ extern unsigned char* rmr_get_src( rmr_mbuf_t* msg, unsigned char* dest ) { /* 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. diff --git a/test/mbuf_api_static_test.c b/test/mbuf_api_static_test.c index 8b17968..2482f0c 100644 --- a/test/mbuf_api_static_test.c +++ b/test/mbuf_api_static_test.c @@ -47,6 +47,7 @@ int mbuf_api_test( ) { int state; int errors = 0; char* buf; + void* ptr; rmr_mbuf_t* mbuf; unsigned char src_buf[256]; @@ -219,6 +220,24 @@ int mbuf_api_test( ) { 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