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)