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