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.
7 ============================================================================================
9 ============================================================================================
32 #include <rmr/ring_inline.h>
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 );
40 static inline void* rmr_ring_extract( void* vr )
41 static inline int rmr_ring_insert( void* vr, void* new_data )
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
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.
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.
70 The ``rmr_mk_ring`` function creates a buffer ring with
73 The ``rmr_ring_free`` function accepts a pointer to a ring
74 context and frees the associated memory.
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
87 The following are the return values for each of these
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
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
104 The ``rmr_tokenise`` function returns the actual number of
105 token pointers placed into *tokens*
107 The ``rmr_mk_ring`` function returns a void pointer which is
108 the *context* for the ring.
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.
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.
121 Not many of these functions set the value in ``errno,``
122 however the value may be one of the following:
131 Parameter(s) passed to the function were not valid.
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),