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