doc/src/man/rmr_support.3.xfm

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19 .if false
  20         Mnemonic        rmr_support_man.xfm
  21         Abstract        The manual page for the rmr_ functions that support the library
  22                                 and are available to support other applications such as the route
  23                                 table generator, but are not directly related to message sending
  24                                 and receiving.  These "second class" functions therefore are
  25                                 likely not to need a dedicated man page, so we lump them all
  26                                 here.
  27         Author          E. Scott Daniels
  28         Date            28 January 2019
  29 .fi
  30
  31 .** if formatting with tfm, the roff.im will cause roff output to be generated
  32 .** if formatting with pfm, then pretty postscript will be generated
  33 .gv e LIB lib
  34 .if pfm
  35         .im &{lib}/generic_ps.im
  36 .ei
  37         .gv e OUTPUT_RST use_rst
  38         .if .ev &use_rst 1 =
  39                 .im &{lib}/rst.im
  40         .ei
  41                 .im &{lib}/roff.im
  42         .fi
  43 .fi
  44
  45 &line_len(6i)
  46
  47 &h1(RMR Library Functions)
  48 &h2(NAME)
  49         RMR support functions
  50
  51 &h2(SYNOPSIS )
  52 &indent
  53 &ex_start
  54 #include <rmr/rmr.h>
  55 #include <rmr/ring_inline.h>
  56
  57 char* rmr_fib( char* fname );
  58 int rmr_has_str( char const* buf, char const* str, char sep, int max );
  59 int rmr_tokenise( char* buf, char** tokens, int max, char sep );
  60 void* rmr_mk_ring( int size );
  61 void rmr_ring_free( void* vr );
  62
  63 static inline void* rmr_ring_extract( void* vr )
  64 static inline int rmr_ring_insert( void* vr, void* new_data )
  65 &ex_end
  66 &uindent
  67
  68 &h2(DESCRIPTION)
  69 These functions support the RMR library, and are made available to user applications
  70 as some (e.g. route table generators) might need and/or want to make use of them.
  71
  72
  73
  74 The &cw(rmr_fib) function accepts a file name and reads the entire file into a single buffer.
  75 The intent is to provide an easy way to load a static route table without a lot of
  76 buffered I/O hoops.
  77
  78 &space
  79 The &cw(rmr_has_str) function accepts a &ital(buffer) containing a set of delimited tokens (e.g. foo,bar,goo)
  80 and returns true if the target string, &ital(str,) matches one of the tokens.
  81 The &ital(sep) parameter provides the separation character in the buffer (e.g a comma)
  82 and &ital(max) indicates the maximum number of tokens to split the buffer into
  83 before checking.
  84
  85 &space
  86 The &cw(rmr_tokenise) function is a simple tokeniser which splits &ital(buf) into tokens
  87 at each occurrence of &ital(sep).
  88 Multiple occurrences of the separator character (e.g. a,,b) result in a nil token.
  89 Pointers to the tokens are placed into the &ital(tokens) array provided by the caller which
  90 is assumed to have at least enough space for &ital(max) entries.
  91
  92 &space
  93 The &cw(rmr_mk_ring) function creates a buffer ring with &ital(size) entries.
  94
  95 &space
  96 The &cw(rmr_ring_free) function accepts a pointer to a ring context and frees the associated memory.
  97
  98 &space
  99 The &cw(rmr_ring_insert) and &cw(rmr_ring_extract) functions are provided as static inline functions
 100 via the &ital(rmr/ring_inline.h) header file.
 101 These functions both accept the ring &ital(context) returned by &cw(mk_ring,) and either insert a
 102 pointer at the next available slot (tail) or extract the data at the head.
 103
 104 &h2(RETURN VALUES)
 105 The following are the return values for each of these functions.
 106
 107 &space
 108 The &cw(rmr_fib) function returns a pointer to the buffer containing the contents of the
 109 file.
 110 The buffer is terminated with a single nil character (0) making it a legitimate C string.
 111 If the file was empty or nonexistent, a buffer with an immediate nil character.
 112 If it is important to the calling programme to know if the file was empty or did not exist,
 113 the caller should use the system stat function call to make that determination.
 114
 115 &space
 116 The &cw(rmr_has_str) function returns 1 if &ital(buf) contains the token referenced by &ita(str,)
 117 and false (0) if it does not.
 118 On error, a -1 value is returned and &cw(errno) is set accordingly.
 119
 120 &space
 121 The &cw(rmr_tokenise) function returns the actual number of token pointers placed into &ital(tokens)
 122
 123 &space
 124 The &cw(rmr_mk_ring) function  returns a void pointer which is the &ital(context) for the ring.
 125
 126 &space
 127 The &cw(rmr_ring_insert) function returns 1 if the data was successfully inserted into the ring, and
 128 0 if the ring is full and the pointer could not be deposited.
 129
 130 &space
 131 The &cw(rmr_ring_extract) will return the data which is at the head of the ring, or NULL if the
 132 ring is empty.
 133
 134 &h2(ERRORS)
 135 Not many of these functions set the value in &cw(errno,) however the value may be one of the following:
 136 &beg_dlist(.75i : ^&bold_font )
 137 &di(INVAL) Parameter(s) passed to the function were not valid.
 138 &end_dlist
 139
 140 &h2(EXAMPLE)
 141
 142 &h2(SEE ALSO )
 143 .ju off
 144 rmr_alloc_msg(3),
 145 rmr_call(3),
 146 rmr_free_msg(3),
 147 rmr_init(3),
 148 rmr_payload_size(3),
 149 rmr_send_msg(3),
 150 rmr_rcv_msg(3),
 151 rmr_rcv_specific(3),
 152 rmr_rts_msg(3),
 153 rmr_ready(3),
 154 .ju on
 155
 156
 157 .qu
 158