1 .TH GETFIELDS 3
2 .SH NAME
3 getfields, gettokens, tokenize \- break a string into fields
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .ta \w'\fLchar* \fP'u
10 .B
11 int	getfields(char *str, char **args, int maxargs, int multiflag,
12 .br
13 .B
14 	    char *delims)
15 .PP
16 .B
17 int	gettokens(char *str, char **args, int maxargs, char *delims)
18 .PP
19 .B
20 int	tokenize(char *str, char **args, int maxargs)
21 .SH DESCRIPTION
22 .I Getfields
23 places into the array
24 .I args
25 pointers to the first
26 .I maxargs
27 fields of the null terminated
28 .SM UTF
29 string
30 .IR str .
31 Delimiters between these fields are set to null.
32 .PP
33 Fields are substrings of
34 .I str
35 whose definition depends on the value of
36 .IR multiflag.
37 If
38 .I multiflag
39 is zero,
40 adjacent fields are separated by exactly one delimiter.
41 For example
42 .EX
43 
44 	getfields("#alice#bob##charles###", arg, 3, 0, "#");
45 
46 .EE
47 yields three substrings:
48 null-string ,
49 .BR "alice" ,
50 and
51 .BR "bob##charles###" .
52 If the
53 .I multiflag
54 argument is not zero,
55 a field is a non-empty string of non-delimiters.
56 For example
57 .EX
58 
59 	getfields("#alice#bob##charles###", arg, 3, 1, "#");
60 
61 .EE
62 yields the three substrings:
63 .BR "alice" ,
64 .BR "bob" ,
65 and
66 .BR "charles###" .
67 .PP
68 Getfields returns the number of fields pointed to.
69 .PP
70 .I Gettokens
71 is the same as
72 .I getfields
73 with
74 .I multiflag
75 non-zero,
76 except that fields may be quoted using single quotes, in the manner
77 of
78 .MR rc (1) .
79 See
80 .MR quote (3)
81 for related quote-handling software.
82 .PP
83 .I Tokenize
84 is
85 .I gettokens
86 with 
87 .I delims
88 set to \f5"\et\er\en "\fP.
89 .SH SOURCE
90 .B \*9/src/lib9/tokenize.c
91 .SH SEE ALSO
92 .I strtok
93 in
94 .MR strcat (3) ,
95 .MR quote (3) .