NAME

       gd_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 according to the rules of the Dirfile
       metadata syntax (see dirfile-format(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 subsequent 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 token, if string is non-NULL, or else
       a subsequent token from the previously specified string, if  string  is  NULL.   Every  non-NULL  pointer
       returned  by gd_strtok() points to a new buffer allocated on the heap.  By default, strdup(3) is used the
       allocate the buffers, but an alternate memory manager may be used  by  calling  gd_alloc_funcs(3)  before
       calling this function.  The caller is responsible for deallocating all these buffers.

       If no more tokens are available, or if an error occurred, NULL is returned.  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 descriptive error string for the last error
       encountered can be obtained from a call to gd_error_string(3).

HISTORY

       The gd_strtok() function appeared in GetData-0.8.0.

SEE ALSO

       gd_dirfile_standards(3), gd_open(3), dirfile-format(5)