Release commit: move 4.0.2 to release repo
[ric-plt/lib/rmr.git] / 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