# strtok

## 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 _s_ , const char *restrict _sep_);
           char *strtok_r(char *restrict _s_ , const char *restrict _sep_ ,
               char **restrict _state_);
    


## 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‐2017 defers to the ISO C
           standard.
    
           A sequence of calls to _strtok_() breaks the string pointed to by _s_
           into a sequence of tokens, each of which is delimited by a byte
           from the string pointed to by _sep_.  The first call in the sequence
           has _s_ as its first argument, and is followed by calls with a null
           pointer as their first argument. The separator string pointed to
           by _sep_ may be different from call to call.
    
           The first call in the sequence searches the string pointed to by _s_
           for the first byte that is _not_ contained in the current separator
           string pointed to by _sep_.  If no such byte is found, then there
           are no tokens in the string pointed to by _s_ 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 _s_ , 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‐2017 calls _strtok_().
    
           The _strtok_() function need not be thread-safe.
    
           The _strtok_r_() function shall be equivalent to _strtok_(), except
           that _strtok_r_() shall be thread-safe and the argument _state_ points
           to a user-provided pointer that allows _strtok_r_() to maintain
           state between calls which scan the same string. The application
           shall ensure that the pointer pointed to by _state_ is unique for
           each string (_s_) being processed concurrently by _strtok_r_() calls.
           The application need not initialize the pointer pointed to by
           _state_ to any particular value. The implementation shall not update
           the pointer pointed to by _state_ to point (directly or indirectly)
           to resources, other than within the string _s_ , that need to be
           freed or released by the caller.
    


## 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



           Note that if _sep_ is the empty string, _strtok_() and _strtok_r_()
           return a pointer to the remainder of the string being tokenized.
    
           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, _state_ , to keep
           track of the current position in the string.
    


## FUTURE DIRECTIONS



           None.
    


* * *