man3/strsep.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified Sat Jul 24 18:00:10 1993 by Rik Faith (faith@cs.unc.edu)
  10 .\" Modified Mon Jan 20 12:04:18 1997 by Andries Brouwer (aeb@cwi.nl)
  11 .\" Modified Tue Jan 23 20:23:07 2001 by Andries Brouwer (aeb@cwi.nl)
  12 .\"
  13 .TH strsep 3 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 strsep \- extract token from string
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <string.h>
  22 .PP
  23 .BI "char *strsep(char **restrict " stringp ", const char *restrict " delim );
  24 .fi
  25 .PP
  26 .RS -4
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .RE
  30 .PP
  31 .BR strsep ():
  32 .nf
  33     Since glibc 2.19:
  34         _DEFAULT_SOURCE
  35     Glibc 2.19 and earlier:
  36         _BSD_SOURCE
  37 .fi
  38 .SH DESCRIPTION
  39 If
  40 .I *stringp
  41 is NULL, the
  42 .BR strsep ()
  43 function returns NULL
  44 and does nothing else.
  45 Otherwise, this function finds the first token
  46 in the string
  47 .I *stringp
  48 that is delimited by one of the bytes in the string
  49 .IR delim .
  50 This token is terminated by overwriting the delimiter
  51 with a null byte (\(aq\e0\(aq),
  52 and
  53 .I *stringp
  54 is updated to point past the token.
  55 In case no delimiter was found, the token is taken to be
  56 the entire string
  57 .IR *stringp ,
  58 and
  59 .I *stringp
  60 is made NULL.
  61 .SH RETURN VALUE
  62 The
  63 .BR strsep ()
  64 function returns a pointer to the token,
  65 that is, it returns the original value of
  66 .IR *stringp .
  67 .SH ATTRIBUTES
  68 For an explanation of the terms used in this section, see
  69 .BR attributes (7).
  70 .ad l
  71 .nh
  72 .TS
  73 allbox;
  74 lbx lb lb
  75 l l l.
  76 Interface       Attribute       Value
  77 T{
  78 .BR strsep ()
  79 T}      Thread safety   MT-Safe
  80 .TE
  81 .hy
  82 .ad
  83 .sp 1
  84 .SH STANDARDS
  85 4.4BSD.
  86 .SH NOTES
  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:
 108 .PP
 109 .in +4n
 110 .EX
 111 .RB "$" " ./a.out \(aqa/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
 122 4:
 123          \-\->
 124 .EE
 125 .in
 126 .SS Program source
 127 \&
 128 .\" SRC BEGIN (strsep.c)
 129 .EX
 130 #include <stdio.h>
 131 #include <stdlib.h>
 132 #include <string.h>
 133
 134 int
 135 main(int argc, char *argv[])
 136 {
 137     char *token, *subtoken;
 138
 139     if (argc != 4) {
 140         fprintf(stderr, "Usage: %s string delim subdelim\en", argv[0]);
 141         exit(EXIT_FAILURE);
 142     }
 143
 144     for (unsigned int j = 1; (token = strsep(&argv[1], argv[2])); j++) {
 145         printf("%u: %s\en", j, token);
 146
 147         while ((subtoken = strsep(&token, argv[3])))
 148             printf("\et \-\-> %s\en", subtoken);
 149     }
 150
 151     exit(EXIT_SUCCESS);
 152 }
 153 .EE
 154 .\" SRC END
 155 .SH SEE ALSO
 156 .BR index (3),
 157 .BR memchr (3),
 158 .BR rindex (3),
 159 .BR strchr (3),
 160 .BR string (3),
 161 .BR strpbrk (3),
 162 .BR strspn (3),
 163 .BR strstr (3),
 164 .BR strtok (3)