0001 SYNOPSIS
0002 --------
0003
0004 #include <ubf.h>
0005
0006 int Bnext (UBFH *'p_ub', BFLDID *'bfldid', BFLDOCC *'occ', char *'buf', BFLDLEN *'len');
0007
0008 int Bnext2(Bnext_state_t \*'bnext_state', UBFH \*'p_ub', BFLDID \*'bfldid', BFLDOCC \*'occ', char \*'buf', BFLDLEN \*'len', char **'d_ptr');
0009
0010
0011 Link with '-lubf -lnstd -lm -lpthread'
0012
0013 DESCRIPTION
0014 -----------
0015 Iterate over the UBF buffer pointed by 'p_ub'. To start (or restart) loop over the buffer,
0016 'bfldid' value must be set to *BFIRSTFLDID*. If function succeeds it returns field id in
0017 'bfldid', occurrence in 'occ' and data value in 'buf'/'len' pair. 'buf' and 'len' both are
0018 optional fields. 'len' on input indicate the buffer length, on output it indicates the the
0019 length of data loaded. If 'len' is set to NULL, then it is assumed that on input buffer is
0020 large enough to store data. The state of iteration is stored in thread local storage (TLS).
0021
0022 When *Bnext()* and *Bnext2()* steps onto *BFLD_VIEW* type field, Bnext initializes the 'buf' as *BVIEWFLD*
0023 with trailing data. Thus the BVIEWFLD.data is set to memory address of
0024 'buf' + sizeof(BVIEWFLD). If 'len' was specified, before returning the data 'len' is
0025 reduced by sizeof(BVIEWFLD).
0026
0027 *Bnext()* is not reentrant, meaning that iteration state is kept in the thread local storage
0028 and while iterating one buffer, if attempt to iterate another buffer is done,
0029 the first buffer iteration state is lost.
0030
0031 To operate with two or more buffers at the same time, use *Bnext2()* version of the function,
0032 where the iteration state is stored at 'bnext_state' parameter. 'bnext_state' parameter is
0033 automatically initialized when iteration is stated by *BFIRSTFLDID*. This version of the
0034 function additionally returns pointer to the raw field data in 'd_ptr' parameter.
0035 The use of 'd_ptr' may give some performance boost as extra data copy is avoided during the
0036 data access.
0037 In case if current field is *BFLD_VIEW*, returned 'd_ptr' will return pointer to the
0038 initialized *BVIEWFLD* field. The *BVIEWFLD* initialization data is stored in thread
0039 local storage, meaning that if iterating two or more buffers with *BFLD_VIEW* fields, then
0040 'd_ptr' would be valid only for last result. If data shell be kept while accessing other
0041 UBF buffer with view fields, copy of 'd_ptr' to local variable of *BVIEWFLD* type
0042 may be done. Returned 'd_ptr' pointer is valid only while the UBF buffer is not
0043 modified (including no modifications to parent of the embedded buffer).
0044
0045 Functions are thread safe.
0046
0047 RETURN VALUE
0048 ------------
0049 On success, *Bnext()* and *Bnext2()* return *1*, if End Of Buffer reached, then *0* is returned; on error,
0050 -1 is returned, with *Berror* set to indicate the error.
0051
0052 ERRORS
0053 ------
0054 Note that *Bstrerror()* returns generic error message plus custom message with debug info
0055 from last function call.
0056
0057 *BALIGNERR* Corrupted buffer or pointing to not aligned memory area.
0058
0059 *BNOTFLD* Buffer not fielded, not correctly allocated or corrupted.
0060
0061 *BNOSPACE* No space in 'buf'.
0062
0063 EXAMPLE
0064 -------
0065 See *ubftest/test_bnext.c* for sample code.
0066
0067 BUGS
0068 ----
0069 Report bugs to support@mavimax.com
0070
0071 SEE ALSO
0072 --------
0073 *Bchg(3)* *Badd(3)* *CBadd(3)* *Bget(3)* *Boccur(3)*
0074
0075 COPYING
0076 -------
0077 (C) Mavimax, Ltd
0078
