Debian Codegraph @

upstream/debian-unstable/man3/strtok_r.3

raw
1 '\" t
2 .\" Copyright 2005-2013, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH strtok_r 3 2026-02-25 "Linux man-pages 6.18"
8 .SH NAME
9 strtok_r \- string tokenize reentrant
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <string.h>
16 .P
17 .BI "char *strtok_r(char *_Nullable restrict " str \
18 ", const char *restrict " delim ,
19 .BI " char **restrict " saveptr );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR strtok_r ():
28 .nf
29 _POSIX_C_SOURCE
30 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
31 .fi
32 .SH DESCRIPTION
33 The
34 .BR strtok_r ()
35 function is a reentrant version of
36 .BR strtok (3).
37 .P
38 The
39 .I saveptr
40 argument is a pointer to a
41 .I char\~*
42 variable that is used internally by
43 .BR strtok_r ()
44 in order to maintain context between successive calls that parse the
45 same string.
46 .P
47 On the first call to
48 .BR strtok_r (),
49 .I str
50 should point to the string to be parsed, and the value of
51 .I *saveptr
52 is ignored (but see VERSIONS).
53 In subsequent calls,
54 .I str
55 should be NULL, and
56 .I saveptr
57 (and the buffer that it points to)
58 should be unchanged since the previous call.
59 .P
60 Different strings may be parsed concurrently using sequences of calls to
61 .BR strtok_r ()
62 that specify different
63 .I saveptr
64 arguments.
65 .SH RETURN VALUE
66 .BR strtok_r ()
67 returns a pointer to the next token,
68 or NULL if there are no more tokens.
69 .SH ATTRIBUTES
70 For an explanation of the terms used in this section, see
71 .BR attributes (7).
72 .TS
73 allbox;
74 lbx lb lb
75 l l l.
76 Interface Attribute Value
77 T{
78 .na
79 .nh
80 .BR strtok_r ()
81 T} Thread safety MT-Safe
82 .TE
83 .SH VERSIONS
84 On some implementations,
85 .\" Tru64, according to its manual page
86 .I *saveptr
87 is required to be NULL on the first call to
88 .BR strtok_r ()
89 that is being used to parse
90 .IR str .
91 .SH STANDARDS
92 POSIX.1-2008.
93 .SH HISTORY
94 POSIX.1-2001.
95 .SH EXAMPLES
96 The program below uses nested loops that employ
97 .BR strtok_r ()
98 to break a string into a two-level hierarchy of tokens.
99 The first command-line argument specifies the string to be parsed.
100 The second argument specifies the delimiter byte(s)
101 to be used to separate that string into "major" tokens.
102 The third argument specifies the delimiter byte(s)
103 to be used to separate the "major" tokens into subtokens.
104 .P
105 An example of the output produced by this program is the following:
106 .P
107 .in +4n
108 .EX
109 .RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]"
110 1: a/bbb///cc
111 \-\-> a
112 \-\-> bbb
113 \-\-> cc
114 2: xxx
115 \-\-> xxx
116 3: yyy
117 \-\-> yyy
118 .EE
119 .in
120 .SS Program source
121 \&
122 .\" SRC BEGIN (strtok.c)
123 .EX
124 #include <stdio.h>
125 #include <stdlib.h>
126 #include <string.h>
127 \&
128 int
129 main(int argc, char *argv[])
130 {
131 char *str1, *str2, *token, *subtoken;
132 char *saveptr1, *saveptr2;
133 int j;
134 \&
135 if (argc != 4) {
136 fprintf(stderr, "Usage: %s string delim subdelim\[rs]n",
137 argv[0]);
138 exit(EXIT_FAILURE);
139 }
140 \&
141 for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
142 token = strtok_r(str1, argv[2], &saveptr1);
143 if (token == NULL)
144 break;
145 printf("%d: %s\[rs]n", j, token);
146 \&
147 for (str2 = token; ; str2 = NULL) {
148 subtoken = strtok_r(str2, argv[3], &saveptr2);
149 if (subtoken == NULL)
150 break;
151 printf("\[rs]t \-\-> %s\[rs]n", subtoken);
152 }
153 }
154 \&
155 exit(EXIT_SUCCESS);
156 }
157 .EE
158 .\" SRC END
159 .SH SEE ALSO
160 .BR strtok (3)