docs/rmr_init_trace.3.rst

   1
   2
   3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   4 .. SPDX-License-Identifier: CC-BY-4.0
   5 .. CAUTION: this document is generated from source in doc/src/rtd.
   6 .. To make changes edit the source and recompile the document.
   7 .. Do NOT make changes directly to .rst or .md files.
   8
   9
  10 ============================================================================================
  11 Man Page: rmr_init_trace
  12 ============================================================================================
  13
  14 RMR Library Functions
  15 ============================================================================================
  16
  17
  18 NAME
  19 --------------------------------------------------------------------------------------------
  20
  21 rmr_init_trace
  22
  23 SYNOPSIS
  24 --------------------------------------------------------------------------------------------
  25
  26
  27 ::
  28
  29  #include <rmr/rmr.h>
  30  void* rmr_init_trace( void* ctx )
  31
  32
  33
  34 DESCRIPTION
  35 --------------------------------------------------------------------------------------------
  36
  37 The rmr_init_trace function establishes the default trace
  38 space placed in each message buffer allocated with
  39 rmr_alloc_msg(). If this function is never called, then no
  40 trace space is allocated by default into any message buffer.
  41
  42 Trace space allows the user application to pass some trace
  43 token, or other data with the message, but outside of the
  44 payload. Trace data may be added to any message with
  45 rmr_set_trace(), and may be extracted from a message with
  46 rmr_get_trace(). The number of bytes that a message contains
  47 for/with trace data can be determined by invoking
  48 rmr_get_trlen().
  49
  50 This function may be safely called at any time during the
  51 life of the user programme to (re)set the default trace space
  52 reserved. If the user programme needs to allocate a message
  53 with trace space of a different size than is allocated by
  54 default, without fear of extra overhead of reallocating a
  55 message later, the rmr_tralloc_msg() function can be used.
  56
  57 RETURN VALUE
  58 --------------------------------------------------------------------------------------------
  59
  60 A value of 1 is returned on success, and 0 on failure. A
  61 failure indicates that the RMr context (a void pointer passed
  62 to this function was not valid.
  63
  64 SEE ALSO
  65 --------------------------------------------------------------------------------------------
  66
  67 rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
  68 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
  69 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
  70 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
  71 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
  72 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)