docs/rmr_init_trace.3.rst

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