man3/strsep.3

   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>
  23 .PP
  24 .BI "char *strsep(char **restrict " stringp ", const char *restrict " delim );
  25 .fi
  26 .PP
  27 .RS -4
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .RE
  31 .PP
  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]\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 .ad l
  72 .nh
  73 .TS
  74 allbox;
  75 lbx lb lb
  76 l l l.
  77 Interface       Attribute       Value
  78 T{
  79 .BR strsep ()
  80 T}      Thread safety   MT-Safe
  81 .TE
  82 .hy
  83 .ad
  84 .sp 1
  85 .SH STANDARDS
  86 None.
  87 .SH HISTORY
  88 4.4BSD.
  89 .PP
  90 The
  91 .BR strsep ()
  92 function was introduced as a replacement for
  93 .BR strtok (3),
  94 since the latter cannot handle empty fields.
  95 However,
  96 .BR strtok (3)
  97 conforms to C89/C99 and hence is more portable.
  98 .SH BUGS
  99 Be cautious when using this function.
 100 If you do use it, note that:
 101 .IP \[bu] 3
 102 This function modifies its first argument.
 103 .IP \[bu]
 104 This function cannot be used on constant strings.
 105 .IP \[bu]
 106 The identity of the delimiting character is lost.
 107 .SH EXAMPLES
 108 The program below is a port of the one found in
 109 .BR strtok (3),
 110 which, however, doesn't discard multiple delimiters or empty tokens:
 111 .PP
 112 .in +4n
 113 .EX
 114 .RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]"
 115 1: a/bbb///cc
 116          \-\-> a
 117          \-\-> bbb
 118          \-\->
 119          \-\->
 120          \-\-> cc
 121 2: xxx
 122          \-\-> xxx
 123 3: yyy
 124          \-\-> yyy
 125 4:
 126          \-\->
 127 .EE
 128 .in
 129 .SS Program source
 130 \&
 131 .\" SRC BEGIN (strsep.c)
 132 .EX
 133 #include <stdio.h>
 134 #include <stdlib.h>
 135 #include <string.h>
 136 \&
 137 int
 138 main(int argc, char *argv[])
 139 {
 140     char *token, *subtoken;
 141 \&
 142     if (argc != 4) {
 143         fprintf(stderr, "Usage: %s string delim subdelim\en", argv[0]);
 144         exit(EXIT_FAILURE);
 145     }
 146 \&
 147     for (unsigned int j = 1; (token = strsep(&argv[1], argv[2])); j++) {
 148         printf("%u: %s\en", j, token);
 149 \&
 150         while ((subtoken = strsep(&token, argv[3])))
 151             printf("\et \-\-> %s\en", subtoken);
 152     }
 153 \&
 154     exit(EXIT_SUCCESS);
 155 }
 156 .EE
 157 .\" SRC END
 158 .SH SEE ALSO
 159 .BR memchr (3),
 160 .BR strchr (3),
 161 .BR string (3),
 162 .BR strpbrk (3),
 163 .BR strspn (3),
 164 .BR strstr (3),
 165 .BR strtok (3)