Provided by: manpages-posix-dev_2013a-2_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult the corresponding Linux  manual  page  for  details  of
       Linux behavior), or the interface may not be implemented on Linux.

NAME

       strtok, strtok_r — split string into tokens

SYNOPSIS

       #include <string.h>

       char *strtok(char *restrict s1, const char *restrict s2);
       char *strtok_r(char *restrict s, const char *restrict sep,
           char **restrict lasts);

DESCRIPTION

       For strtok(): The functionality described on this reference page is aligned with the ISO C
       standard. Any conflict between the requirements described here and the ISO C  standard  is
       unintentional. This volume of POSIX.1‐2008 defers to the ISO C standard.

       A  sequence  of  calls  to  strtok() breaks the string pointed to by s1 into a sequence of
       tokens, each of which is delimited by a byte from the string pointed to by s2.  The  first
       call  in  the  sequence has s1 as its first argument, and is followed by calls with a null
       pointer as their first argument. The separator string pointed to by s2  may  be  different
       from call to call.

       The  first  call  in  the sequence searches the string pointed to by s1 for the first byte
       that is not contained in the current separator string pointed to by s2.  If no  such  byte
       is  found,  then  there  are  no  tokens in the string pointed to by s1 and strtok() shall
       return a null pointer. If such a byte is found, it is the start of the first token.

       The strtok() function then searches from there for a byte that is contained in the current
       separator  string.  If  no such byte is found, the current token extends to the end of the
       string pointed to by s1, and subsequent searches for a token shall return a null  pointer.
       If  such  a  byte  is  found,  it  is overwritten by a NUL character, which terminates the
       current token. The strtok() function saves a pointer to the following byte, from which the
       next search for a token shall start.

       Each  subsequent  call,  with  a  null  pointer as the value of the first argument, starts
       searching from the saved pointer and behaves as described above.

       The implementation shall behave as if no function defined in this volume  of  POSIX.1‐2008
       calls strtok().

       The strtok() function need not be thread-safe.

       The  strtok_r()  function  considers the null-terminated string s as a sequence of zero or
       more text tokens separated by spans of one or more characters from  the  separator  string
       sep.   The  argument  lasts  points  to  a  user-provided  pointer  which points to stored
       information necessary for strtok_r() to continue scanning the same string.

       In the first call to strtok_r(), s points to a null-terminated  string,  sep  to  a  null-
       terminated  string  of separator characters, and the value pointed to by lasts is ignored.
       The strtok_r() function shall return a pointer to the first character of the first  token,
       write  a  null  character  into s immediately following the returned token, and update the
       pointer to which lasts points.

       In subsequent calls, s is a null pointer and lasts shall be unchanged  from  the  previous
       call so that subsequent calls shall move through the string s, returning successive tokens
       until no tokens remain. The separator string sep may be different from call to call.  When
       no token remains in s, a null pointer shall be returned.

RETURN VALUE

       Upon  successful completion, strtok() shall return a pointer to the first byte of a token.
       Otherwise, if there is no token, strtok() shall return a null pointer.

       The strtok_r() function shall return a pointer to the token found, or a null pointer  when
       no token is found.

ERRORS

       No errors are defined.

       The following sections are informative.

EXAMPLES

   Searching for Word Separators
       The following example searches for tokens separated by <space> characters.

           #include <string.h>
           ...
           char *token;
           char line[] = "LINE TO BE SEPARATED";
           char *search = " ";

           /* Token will point to "LINE". */
           token = strtok(line, search);

           /* Token will point to "TO". */
           token = strtok(NULL, search);

   Find First two Fields in a Buffer
       The  following  example  uses  strtok()  to  find  two  character  strings (a key and data
       associated with that key) separated by any combination of  <space>,  <tab>,  or  <newline>
       characters at the start of the array of characters pointed to by buffer.

           #include <string.h>
           ...
           char    *buffer;
           ...
           struct element {
               char *key;
               char *data;
           } e;
           ...
           // Load the buffer...
           ...
           // Get the key and its data...
           e.key = strtok(buffer, " \t\n");
           e.data = strtok(NULL, " \t\n");
           // Process the rest of the contents of the buffer...
           ...

APPLICATION USAGE

       The  strtok_r()  function  is  thread-safe  and stores its state in a user-supplied buffer
       instead of possibly using a static data area that may be overwritten by an unrelated  call
       from another thread.

RATIONALE

       The strtok() function searches for a separator string within a larger string. It returns a
       pointer to the last substring  between  separator  strings.   This  function  uses  static
       storage  to  keep  track  of  the current string position between calls. The new function,
       strtok_r(), takes an additional argument, lasts, to keep track of the current position  in
       the string.

FUTURE DIRECTIONS

       None.

SEE ALSO

       The Base Definitions volume of POSIX.1‐2008, <string.h>

COPYRIGHT

       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2013 Edition, Standard for Information Technology  --  Portable  Operating  System
       Interface  (POSIX),  The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc  and  The  Open  Group.   (This  is
       POSIX.1-2008  with  the  2013  Technical  Corrigendum  1  applied.)  In  the  event of any
       discrepancy between this version and the original IEEE and The Open  Group  Standard,  the
       original  IEEE  and The Open Group Standard is the referee document. The original Standard
       can be obtained online at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are most  likely  to  have
       been  introduced  during  the conversion of the source files to man page format. To report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .