Debian Codegraph @

upstream/fedora-44/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-07-23 "Linux man-pages 6.13"
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 BSD.
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 .SH CAVEATS
93 Be cautious when using this function.
94 If you do use it, note that:
95 .IP \[bu] 3
96 This function modifies its first argument.
97 .IP \[bu]
98 This function cannot be used on constant strings.
99 .IP \[bu]
100 The identity of the delimiting character is lost.
101 .SH EXAMPLES
102 The program below is a port of the one found in
103 .BR strtok (3),
104 which, however, doesn't discard multiple delimiters or empty tokens:
105 .P
106 .in +4n
107 .EX
108 .RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]"
109 1: a/bbb///cc
110 \-\-> a
111 \-\-> bbb
112 \-\->
113 \-\->
114 \-\-> cc
115 2: xxx
116 \-\-> xxx
117 3: yyy
118 \-\-> yyy
119 4:
120 \-\->
121 .EE
122 .in
123 .SS Program source
124 \&
125 .\" SRC BEGIN (strsep.c)
126 .EX
127 #include <stdio.h>
128 #include <stdlib.h>
129 #include <string.h>
130 \&
131 int
132 main(int argc, char *argv[])
133 {
134 char *token, *subtoken;
135 \&
136 if (argc != 4) {
137 fprintf(stderr, "Usage: %s string delim subdelim\[rs]n", argv[0]);
138 exit(EXIT_FAILURE);
139 }
140 \&
141 for (unsigned int j = 1; (token = strsep(&argv[1], argv[2])); j++) {
142 printf("%u: %s\[rs]n", j, token);
143 \&
144 while ((subtoken = strsep(&token, argv[3])))
145 printf("\[rs]t \-\-> %s\[rs]n", subtoken);
146 }
147 \&
148 exit(EXIT_SUCCESS);
149 }
150 .EE
151 .\" SRC END
152 .SH SEE ALSO
153 .BR memchr (3),
154 .BR strchr (3),
155 .BR string (3),
156 .BR strpbrk (3),
157 .BR strspn (3),
158 .BR strstr (3),
159 .BR strtok (3)