gd_strtok(3) GETDATA gd_strtok(3)NAMEgd_strtok — tokenise a string using the GetData parser
SYNOPSIS
#include <getdata.h>
char *gd_strtok(DIRFILE *dirfile, const char *string);
DESCRIPTION
The gd_strtok() function parses a string into a series of tokens ac‐
cording to the rules of the Dirfile metadata syntax (see dirfile-for‐
mat(5)). The first time gd_strtok() is called, the string to be parsed
should be passed in string. The first token will be returned. In sub‐
sequent calls to parse the same string, string should be NULL (as with
strtok(3)). Each time gd_strtok() is called like this, the next token
is returned.
Operation of the Dirfile tokeniser varies between Dirfile Standards
Versions. The Standards Version used is the current Version of the
loaded DIRFILE dirfile. Use gd_dirfile_standards(3) to retrieve or
change this value. Changing the Standards Version of dirfile while
parsing a string will affect the parsing of subsequent tokens, but does
not affect tokens already returned. A copy of the string is cached in
the dirfile object. Calling gd_strtok() with different dirfiles will
parse different strings.
RETURN VALUE
Upon successful completion, gd_strtok() returns a copy of the first to‐
ken (if string is non-NULL), or the subsequent token. The token
strings returned are each allocated with malloc(3) and should be deal‐
located by the caller when no longer needed using free(3).
If no more tokens are available, or if an error occurred, NULL is re‐
turned. If an error has occurred, it will also set the dirfile error a
non-zero error value. Possible error values are:
GD_E_ALLOC
A memory allocation error occurred.
GD_E_ARGUMENT
There was no string to parse (i.e. string was NULL, but no
previous call specified a string to parse).
GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
GD_E_FORMAT
A syntax error was found in the string.
The dirfile error may be retrieved by calling gd_error(3). A descrip‐
tive error string for the last error encountered can be obtained from a
call to gd_error_string(3).
SEE ALSOgd_dirfile_standards(3), gd_open(3), dirfile-format(5)Version 0.8.0 28 June 2012 gd_strtok(3)
