---
name: "gd_strtok"
section: "3"
platform: "linux"
package: "libgetdata-doc"
version: "0.11.0-15"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/gd_strtok"
---

# gd\_strtok(3)

tokenise a string using the GetData parser

## 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)](/dirfile-format/5.md)).  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)](/strtok/3.md)). 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)](/gd_dirfile_standards/3.md) 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 *dirfile*s 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)](/strdup/3.md) is used the allocate the buffers, but an alternate memory manager may be used by calling [**gd\_alloc\_funcs**(3)](/gd_alloc_funcs/3.md) 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:\
  .TP 8 **GD\_E\_ALLOC** A memory allocation error occurred.\
  .TP 8 **GD\_E\_ARGUMENT** There was no string to parse (i.e. *string* was NULL, but no previous call specified a string to parse).\
  .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid.\
  .TP 8 **GD\_E\_FORMAT** A syntax error was found in the string.

The dirfile error may be retrieved by calling [**gd\_error**(3)](/gd_error/3.md). A descriptive error string for the last error encountered can be obtained from a call to [**gd\_error\_string**(3)](/gd_error_string/3.md).

## HISTORY

The **gd\_strtok**() function appeared in GetData-0.8.0.

## SEE ALSO

[**gd\_dirfile\_standards**(3)](/gd_dirfile_standards/3.md), [**gd\_open**(3)](/gd_open/3.md), [dirfile-format(5)](/dirfile-format/5.md)