SYNOPSIS
#include <getdata.h>- char *gd_strtok(DIRFILE *dirfile, const char *string);
DESCRIPTION
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 the subsequent token. The token strings returned are each allocated with malloc(3) and should be deallocated by the caller when no longer needed using free(3).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).