1
2
3
4
5
6
7
8
9gd_strtok(3) GETDATA gd_strtok(3)
10
11
12
14 gd_strtok — tokenise a string using the GetData parser
15
16
18 #include <getdata.h>
19
20 char *gd_strtok(DIRFILE *dirfile, const char *string);
21
22
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
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
75 The gd_strtok() function appeared in GetData-0.8.0.
76
77
79 gd_dirfile_standards(3), gd_open(3), dirfile-format(5)
80
81
82
83Version 0.10.0 25 December 2016 gd_strtok(3)