README: Update links
[man-pages.git] / man3 / strsep.3
blobbaef0facdc434af3b3e2ff32dbf16048e10e9b19
1 '\" t
2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
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 (faith@cs.unc.edu)
11 .\" Modified Mon Jan 20 12:04:18 1997 by Andries Brouwer (aeb@cwi.nl)
12 .\" Modified Tue Jan 23 20:23:07 2001 by Andries Brouwer (aeb@cwi.nl)
13 .\"
14 .TH strsep 3 (date) "Linux man-pages (unreleased)"
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>
24 .BI "char *strsep(char **restrict " stringp ", const char *restrict " delim );
25 .fi
27 .RS -4
28 Feature Test Macro Requirements for glibc (see
29 .BR feature_test_macros (7)):
30 .RE
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
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]\e0\[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
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.
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:
109 .in +4n
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
123          \-\->
126 .SS Program source
128 .\" SRC BEGIN (strsep.c)
130 #include <stdio.h>
131 #include <stdlib.h>
132 #include <string.h>
135 main(int argc, char *argv[])
137     char *token, *subtoken;
139     if (argc != 4) {
140         fprintf(stderr, "Usage: %s string delim subdelim\en", argv[0]);
141         exit(EXIT_FAILURE);
142     }
144     for (unsigned int j = 1; (token = strsep(&argv[1], argv[2])); j++) {
145         printf("%u: %s\en", j, token);
147         while ((subtoken = strsep(&token, argv[3])))
148             printf("\et \-\-> %s\en", subtoken);
149     }
151     exit(EXIT_SUCCESS);
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)