X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_support.3.rst;h=cc63e43152d2151825babc075493bf38c5ee9bb1;hb=8c6756d9d6f94beca0bc382f97383ca5e79d16c7;hp=648bedf7cc111138f5de1be9d68a9bdf70be618a;hpb=a3a121ca4a0426ec964fa684fb27c397f2ee9e24;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr_support.3.rst b/docs/rmr_support.3.rst index 648bedf..cc63e43 100644 --- a/docs/rmr_support.3.rst +++ b/docs/rmr_support.3.rst @@ -1,14 +1,14 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. - -============================================================================================ -Man Page: rmr_support -============================================================================================ - - +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. CAUTION: this document is generated from source in doc/src/rtd. +.. To make changes edit the source and recompile the document. +.. Do NOT make changes directly to .rst or .md files. + +============================================================================================ +Man Page: rmr_support +============================================================================================ + + RMR LIBRARY FUNCTIONS @@ -19,118 +19,118 @@ RMR LIBRARY FUNCTIONS NAME ---- -RMR support functions +RMR support functions SYNOPSIS -------- - -:: - - #include - #include - - char* rmr_fib( char* fname ); - int rmr_has_str( char const* buf, char const* str, char sep, int max ); - int rmr_tokenise( char* buf, char** tokens, int max, char sep ); - void* rmr_mk_ring( int size ); - void rmr_ring_free( void* vr ); - - static inline void* rmr_ring_extract( void* vr ) - static inline int rmr_ring_insert( void* vr, void* new_data ) - + +:: + + #include + #include + + char* rmr_fib( char* fname ); + int rmr_has_str( char const* buf, char const* str, char sep, int max ); + int rmr_tokenise( char* buf, char** tokens, int max, char sep ); + void* rmr_mk_ring( int size ); + void rmr_ring_free( void* vr ); + + static inline void* rmr_ring_extract( void* vr ) + static inline int rmr_ring_insert( void* vr, void* new_data ) + DESCRIPTION ----------- -These functions support the RMR library, and are made -available to user applications as some (e.g. route table -generators) might need and/or want to make use of them. The -``rmr_fib`` function accepts a file name and reads the entire -file into a single buffer. The intent is to provide an easy -way to load a static route table without a lot of buffered -I/O hoops. - -The ``rmr_has_str`` function accepts a *buffer* containing a -set of delimited tokens (e.g. foo,bar,goo) and returns true -if the target string, *str,* matches one of the tokens. The -*sep* parameter provides the separation character in the -buffer (e.g a comma) and *max* indicates the maximum number -of tokens to split the buffer into before checking. - -The ``rmr_tokenise`` function is a simple tokeniser which -splits *buf* into tokens at each occurrence of *sep*. -Multiple occurrences of the separator character (e.g. a,,b) -result in a nil token. Pointers to the tokens are placed into -the *tokens* array provided by the caller which is assumed to -have at least enough space for *max* entries. - -The ``rmr_mk_ring`` function creates a buffer ring with -*size* entries. - -The ``rmr_ring_free`` function accepts a pointer to a ring -context and frees the associated memory. - -The ``rmr_ring_insert`` and ``rmr_ring_extract`` functions -are provided as static inline functions via the -*rmr/ring_inline.h* header file. These functions both accept -the ring *context* returned by ``mk_ring,`` and either insert -a pointer at the next available slot (tail) or extract the -data at the head. +These functions support the RMR library, and are made +available to user applications as some (e.g. route table +generators) might need and/or want to make use of them. The +``rmr_fib`` function accepts a file name and reads the entire +file into a single buffer. The intent is to provide an easy +way to load a static route table without a lot of buffered +I/O hoops. + +The ``rmr_has_str`` function accepts a *buffer* containing a +set of delimited tokens (e.g. foo,bar,goo) and returns true +if the target string, *str,* matches one of the tokens. The +*sep* parameter provides the separation character in the +buffer (e.g a comma) and *max* indicates the maximum number +of tokens to split the buffer into before checking. + +The ``rmr_tokenise`` function is a simple tokeniser which +splits *buf* into tokens at each occurrence of *sep*. +Multiple occurrences of the separator character (e.g. a,,b) +result in a nil token. Pointers to the tokens are placed into +the *tokens* array provided by the caller which is assumed to +have at least enough space for *max* entries. + +The ``rmr_mk_ring`` function creates a buffer ring with +*size* entries. + +The ``rmr_ring_free`` function accepts a pointer to a ring +context and frees the associated memory. + +The ``rmr_ring_insert`` and ``rmr_ring_extract`` functions +are provided as static inline functions via the +*rmr/ring_inline.h* header file. These functions both accept +the ring *context* returned by ``mk_ring,`` and either insert +a pointer at the next available slot (tail) or extract the +data at the head. RETURN VALUES ------------- -The following are the return values for each of these -functions. - -The ``rmr_fib`` function returns a pointer to the buffer -containing the contents of the file. The buffer is terminated -with a single nil character (0) making it a legitimate C -string. If the file was empty or nonexistent, a buffer with -an immediate nil character. If it is important to the calling -programme to know if the file was empty or did not exist, the -caller should use the system stat function call to make that -determination. - -The ``rmr_has_str`` function returns 1 if *buf* contains the -token referenced by &ita and false (0) if it does not. On -error, a -1 value is returned and ``errno`` is set -accordingly. - -The ``rmr_tokenise`` function returns the actual number of -token pointers placed into *tokens* - -The ``rmr_mk_ring`` function returns a void pointer which is -the *context* for the ring. - -The ``rmr_ring_insert`` function returns 1 if the data was -successfully inserted into the ring, and 0 if the ring is -full and the pointer could not be deposited. - -The ``rmr_ring_extract`` will return the data which is at the -head of the ring, or NULL if the ring is empty. +The following are the return values for each of these +functions. + +The ``rmr_fib`` function returns a pointer to the buffer +containing the contents of the file. The buffer is terminated +with a single nil character (0) making it a legitimate C +string. If the file was empty or nonexistent, a buffer with +an immediate nil character. If it is important to the calling +programme to know if the file was empty or did not exist, the +caller should use the system stat function call to make that +determination. + +The ``rmr_has_str`` function returns 1 if *buf* contains the +token referenced by &ita and false (0) if it does not. On +error, a -1 value is returned and ``errno`` is set +accordingly. + +The ``rmr_tokenise`` function returns the actual number of +token pointers placed into *tokens* + +The ``rmr_mk_ring`` function returns a void pointer which is +the *context* for the ring. + +The ``rmr_ring_insert`` function returns 1 if the data was +successfully inserted into the ring, and 0 if the ring is +full and the pointer could not be deposited. + +The ``rmr_ring_extract`` will return the data which is at the +head of the ring, or NULL if the ring is empty. ERRORS ------ -Not many of these functions set the value in ``errno,`` -however the value may be one of the following: - - .. list-table:: - :widths: auto - :header-rows: 0 - :class: borderless - - * - **INVAL** - - - Parameter(s) passed to the function were not valid. - - +Not many of these functions set the value in ``errno,`` +however the value may be one of the following: + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid. + + EXAMPLE @@ -141,6 +141,6 @@ EXAMPLE SEE ALSO -------- -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), -rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), -rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), +rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),