X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_support.3.rst;h=648bedf7cc111138f5de1be9d68a9bdf70be618a;hb=refs%2Fchanges%2F52%2F3652%2F11;hp=272fb399650f3716e7d62adbe884677a68ca71cc;hpb=2b3c393e660c5e1037191f43cc70537da8316b89;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr_support.3.rst b/docs/rmr_support.3.rst index 272fb39..648bedf 100644 --- a/docs/rmr_support.3.rst +++ b/docs/rmr_support.3.rst @@ -1,88 +1,93 @@ - - .. 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 -============================================================================================ - - -NAME --------------------------------------------------------------------------------------------- + + +RMR LIBRARY FUNCTIONS +===================== + + + +NAME +---- + RMR support functions - -SYNOPSIS --------------------------------------------------------------------------------------------- - + + +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 ) - - -DESCRIPTION --------------------------------------------------------------------------------------------- - + + +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 +``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 +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 +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_mk_ring`` function creates a buffer ring with +*size* entries. -The rmr_ring_free function accepts a pointer to a ring +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 +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 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 +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 @@ -91,42 +96,51 @@ 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 +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. +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_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_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 +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 +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: - - -INVAL - - Parameter(s) passed to the function were not valid. - - -EXAMPLE --------------------------------------------------------------------------------------------- - - -SEE ALSO --------------------------------------------------------------------------------------------- - + + +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. + + + + +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),