Debian Codegraph @

upstream/mageia-cauldron/man3/strsep.3

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