Debian Codegraph @

upstream/debian-unstable/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-25 "Linux man-pages 6.18"
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 The identity of the delimiting character is lost.
90 .SH EXAMPLES
91 The program below is a port of the one found in
92 .BR strtok (3),
93 which, however, doesn't discard multiple delimiters or empty tokens:
94 .P
95 .in +4n
96 .EX
97 .RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]"
98 1: a/bbb///cc
99 \-\-> a
100 \-\-> bbb
101 \-\->
102 \-\->
103 \-\-> cc
104 2: xxx
105 \-\-> xxx
106 3: yyy
107 \-\-> yyy
108 4:
109 \-\->
110 .EE
111 .in
112 .SS Program source
113 \&
114 .\" SRC BEGIN (strsep.c)
115 .EX
116 #include <stdio.h>
117 #include <stdlib.h>
118 #include <string.h>
119 \&
120 int
121 main(int argc, char *argv[])
122 {
123 char *token, *subtoken;
124 \&
125 if (argc != 4) {
126 fprintf(stderr, "Usage: %s string delim subdelim\[rs]n", argv[0]);
127 exit(EXIT_FAILURE);
128 }
129 \&
130 for (unsigned int j = 1; (token = strsep(&argv[1], argv[2])); j++) {
131 printf("%u: %s\[rs]n", j, token);
132 \&
133 while ((subtoken = strsep(&token, argv[3])))
134 printf("\[rs]t \-\-> %s\[rs]n", subtoken);
135 }
136 \&
137 exit(EXIT_SUCCESS);
138 }
139 .EE
140 .\" SRC END
141 .SH SEE ALSO
142 .BR memchr (3),
143 .BR strchr (3),
144 .BR string (3),
145 .BR strpbrk (3),
146 .BR strspn (3),
147 .BR strstr (3),
148 .BR strtok (3)