docs/rmr_support.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_support
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 RMR support functions
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31   #include <rmr/rmr.h>
  32   #include <rmr/ring_inline.h>
  33
  34   char* rmr_fib( char* fname );
  35   int rmr_has_str( char const* buf, char const* str, char sep, int max );
  36   int rmr_tokenise( char* buf, char** tokens, int max, char sep );
  37   void* rmr_mk_ring( int size );
  38   void rmr_ring_free( void* vr );
  39
  40   static inline void* rmr_ring_extract( void* vr )
  41   static inline int rmr_ring_insert( void* vr, void* new_data )
  42
  43
  44
  45 DESCRIPTION
  46 -----------
  47
  48 These functions support the RMR library, and are made
  49 available to user applications as some (e.g. route table
  50 generators) might need and/or want to make use of them. The
  51 ``rmr_fib`` function accepts a file name and reads the entire
  52 file into a single buffer. The intent is to provide an easy
  53 way to load a static route table without a lot of buffered
  54 I/O hoops.
  55
  56 The ``rmr_has_str`` function accepts a *buffer* containing a
  57 set of delimited tokens (e.g. foo,bar,goo) and returns true
  58 if the target string, *str,* matches one of the tokens. The
  59 *sep* parameter provides the separation character in the
  60 buffer (e.g a comma) and *max* indicates the maximum number
  61 of tokens to split the buffer into before checking.
  62
  63 The ``rmr_tokenise`` function is a simple tokeniser which
  64 splits *buf* into tokens at each occurrence of *sep*.
  65 Multiple occurrences of the separator character (e.g. a,,b)
  66 result in a nil token. Pointers to the tokens are placed into
  67 the *tokens* array provided by the caller which is assumed to
  68 have at least enough space for *max* entries.
  69
  70 The ``rmr_mk_ring`` function creates a buffer ring with
  71 *size* entries.
  72
  73 The ``rmr_ring_free`` function accepts a pointer to a ring
  74 context and frees the associated memory.
  75
  76 The ``rmr_ring_insert`` and ``rmr_ring_extract`` functions
  77 are provided as static inline functions via the
  78 *rmr/ring_inline.h* header file. These functions both accept
  79 the ring *context* returned by ``mk_ring,`` and either insert
  80 a pointer at the next available slot (tail) or extract the
  81 data at the head.
  82
  83
  84 RETURN VALUES
  85 -------------
  86
  87 The following are the return values for each of these
  88 functions.
  89
  90 The ``rmr_fib`` function returns a pointer to the buffer
  91 containing the contents of the file. The buffer is terminated
  92 with a single nil character (0) making it a legitimate C
  93 string. If the file was empty or nonexistent, a buffer with
  94 an immediate nil character. If it is important to the calling
  95 programme to know if the file was empty or did not exist, the
  96 caller should use the system stat function call to make that
  97 determination.
  98
  99 The ``rmr_has_str`` function returns 1 if *buf* contains the
 100 token referenced by &ita and false (0) if it does not. On
 101 error, a -1 value is returned and ``errno`` is set
 102 accordingly.
 103
 104 The ``rmr_tokenise`` function returns the actual number of
 105 token pointers placed into *tokens*
 106
 107 The ``rmr_mk_ring`` function returns a void pointer which is
 108 the *context* for the ring.
 109
 110 The ``rmr_ring_insert`` function returns 1 if the data was
 111 successfully inserted into the ring, and 0 if the ring is
 112 full and the pointer could not be deposited.
 113
 114 The ``rmr_ring_extract`` will return the data which is at the
 115 head of the ring, or NULL if the ring is empty.
 116
 117
 118 ERRORS
 119 ------
 120
 121 Not many of these functions set the value in ``errno,``
 122 however the value may be one of the following:
 123
 124     .. list-table::
 125       :widths: auto
 126       :header-rows: 0
 127       :class: borderless
 128
 129       * - **INVAL**
 130         -
 131           Parameter(s) passed to the function were not valid.
 132
 133
 134
 135
 136 EXAMPLE
 137 -------
 138
 139
 140
 141 SEE ALSO
 142 --------
 143
 144 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
 145 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 146 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),