1
2
3
4
5
6
7
8
9gd_strtok(3)                        GETDATA                       gd_strtok(3)
10
11
12

NAME

14       gd_strtok — tokenise a string using the GetData parser
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       char *gd_strtok(DIRFILE *dirfile, const char *string);
21
22

DESCRIPTION

24       The  gd_strtok()  function  parses a string into a series of tokens ac‐
25       cording to the rules of the Dirfile metadata syntax  (see  dirfile-for‐
26       mat(5)).  The first time gd_strtok() is called, the string to be parsed
27       should be passed in string.  The first token will be returned.  In sub‐
28       sequent  calls to parse the same string, string should be NULL (as with
29       strtok(3)).  Each time gd_strtok() is called like this, the next  token
30       is returned.
31
32       Operation  of  the  Dirfile  tokeniser varies between Dirfile Standards
33       Versions.  The Standards Version used is the  current  Version  of  the
34       loaded  DIRFILE  dirfile.   Use  gd_dirfile_standards(3) to retrieve or
35       change this value.  Changing the Standards  Version  of  dirfile  while
36       parsing a string will affect the parsing of subsequent tokens, but does
37       not affect tokens already returned.  A copy of the string is cached  in
38       the  dirfile  object.  Calling gd_strtok() with different dirfiles will
39       parse different strings.
40
41

RETURN VALUE

43       Upon successful completion, gd_strtok() returns a copy of the first to‐
44       ken,  if string is non-NULL, or else a subsequent token from the previ‐
45       ously specified string, if string is NULL.  Every non-NULL pointer  re‐
46       turned by gd_strtok() points to a new buffer allocated on the heap.  By
47       default, strdup(3) is used the allocate the buffers, but  an  alternate
48       memory  manager may be used by calling gd_alloc_funcs(3) before calling
49       this function.  The caller is responsible for  deallocating  all  these
50       buffers.
51
52       If  no  more tokens are available, or if an error occurred, NULL is re‐
53       turned.  If an error has occurred, it will also set the dirfile error a
54       non-zero error value.  Possible error values are:
55
56       GD_E_ALLOC
57               A memory allocation error occurred.
58
59       GD_E_ARGUMENT
60               There  was  no  string  to parse (i.e.  string was NULL, but no
61               previous call specified a string to parse).
62
63       GD_E_BAD_DIRFILE
64               The supplied dirfile was invalid.
65
66       GD_E_FORMAT
67               A syntax error was found in the string.
68
69       The dirfile error may be retrieved by calling gd_error(3).  A  descrip‐
70       tive error string for the last error encountered can be obtained from a
71       call to gd_error_string(3).
72
73

HISTORY

75       The gd_strtok() function appeared in GetData-0.8.0.
76
77

SEE ALSO

79       gd_dirfile_standards(3), gd_open(3), dirfile-format(5)
80
81
82
83Version 0.10.0                 25 December 2016                   gd_strtok(3)
Impressum