Debian Codegraph @

upstream/debian-trixie/man3/strsep.3

raw
1 '\" t
2 .\" Copyright 1993 David Metcalfe ([email protected])
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" References consulted:
7 .\" Linux libc source code
8 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
9 .\" 386BSD man pages
10 .\" Modified Sat Jul 24 18:00:10 1993 by Rik Faith ([email protected])
11 .\" Modified Mon Jan 20 12:04:18 1997 by Andries Brouwer ([email protected])
12 .\" Modified Tue Jan 23 20:23:07 2001 by Andries Brouwer ([email protected])
13 .\"
14 .TH strsep 3 2024-06-15 "Linux man-pages 6.9.1"
15 .SH NAME
16 strsep \- extract token from string
17 .SH LIBRARY
18 Standard C library
19 .RI ( libc ", " \-lc )
20 .SH SYNOPSIS
21 .nf
22 .B #include <string.h>
23 .P
24 .BI "char *strsep(char **restrict " stringp ", const char *restrict " delim );
25 .fi
26 .P
27 .RS -4
28 Feature Test Macro Requirements for glibc (see
29 .BR feature_test_macros (7)):
30 .RE
31 .P
32 .BR strsep ():
33 .nf
34 Since glibc 2.19:
35 _DEFAULT_SOURCE
36 glibc 2.19 and earlier:
37 _BSD_SOURCE
38 .fi
39 .SH DESCRIPTION
40 If
41 .I *stringp
42 is NULL, the
43 .BR strsep ()
44 function returns NULL
45 and does nothing else.
46 Otherwise, this function finds the first token
47 in the string
48 .I *stringp
49 that is delimited by one of the bytes in the string
50 .IR delim .
51 This token is terminated by overwriting the delimiter
52 with a null byte (\[aq]\[rs]0\[aq]),
53 and
54 .I *stringp
55 is updated to point past the token.
56 In case no delimiter was found, the token is taken to be
57 the entire string
58 .IR *stringp ,
59 and
60 .I *stringp
61 is made NULL.
62 .SH RETURN VALUE
63 The
64 .BR strsep ()
65 function returns a pointer to the token,
66 that is, it returns the original value of
67 .IR *stringp .
68 .SH ATTRIBUTES
69 For an explanation of the terms used in this section, see
70 .BR attributes (7).
71 .TS
72 allbox;
73 lbx lb lb
74 l l l.
75 Interface Attribute Value
76 T{
77 .na
78 .nh
79 .BR strsep ()
80 T} Thread safety MT-Safe
81 .TE
82 .SH STANDARDS
83 None.
84 .SH HISTORY
85 4.4BSD.
86 .P
87 The
88 .BR strsep ()
89 function was introduced as a replacement for
90 .BR strtok (3),
91 since the latter cannot handle empty fields.
92 However,
93 .BR strtok (3)
94 conforms to C89/C99 and hence is more portable.
95 .SH BUGS
96 Be cautious when using this function.
97 If you do use it, note that:
98 .IP \[bu] 3
99 This function modifies its first argument.
100 .IP \[bu]
101 This function cannot be used on constant strings.
102 .IP \[bu]
103 The identity of the delimiting character is lost.
104 .SH EXAMPLES
105 The program below is a port of the one found in
106 .BR strtok (3),
107 which, however, doesn't discard multiple delimiters or empty tokens:
108 .P
109 .in +4n
110 .EX
111 .RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]"
112 1: a/bbb///cc
113 \-\-> a
114 \-\-> bbb
115 \-\->
116 \-\->
117 \-\-> cc
118 2: xxx
119 \-\-> xxx
120 3: yyy
121 \-\-> yyy
122 4:
123 \-\->
124 .EE
125 .in
126 .SS Program source
127 \&
128 .\" SRC BEGIN (strsep.c)
129 .EX
130 #include <stdio.h>
131 #include <stdlib.h>
132 #include <string.h>
133 \&
134 int
135 main(int argc, char *argv[])
136 {
137 char *token, *subtoken;
138 \&
139 if (argc != 4) {
140 fprintf(stderr, "Usage: %s string delim subdelim\[rs]n", argv[0]);
141 exit(EXIT_FAILURE);
142 }
143 \&
144 for (unsigned int j = 1; (token = strsep(&argv[1], argv[2])); j++) {
145 printf("%u: %s\[rs]n", j, token);
146 \&
147 while ((subtoken = strsep(&token, argv[3])))
148 printf("\[rs]t \-\-> %s\[rs]n", subtoken);
149 }
150 \&
151 exit(EXIT_SUCCESS);
152 }
153 .EE
154 .\" SRC END
155 .SH SEE ALSO
156 .BR memchr (3),
157 .BR strchr (3),
158 .BR string (3),
159 .BR strpbrk (3),
160 .BR strspn (3),
161 .BR strstr (3),
162 .BR strtok (3)