STRTOK(3)                  POSIX Programmer's Manual                 STRTOK(3)



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

NNAAMMEE
       strtok, strtok_r -- split string into tokens

SSYYNNOOPPSSIISS
       #include <string.h>

       char *strtok(char *restrict _s, const char *restrict _s_e_p);
       char *strtok_r(char *restrict _s, const char *restrict _s_e_p,
           char **restrict _s_t_a_t_e);

DDEESSCCRRIIPPTTIIOONN
       For _s_t_r_t_o_k(): 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 _s_t_r_t_o_k() 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 _s_e_p.  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 _s_e_p 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 _n_o_t contained in the current separator string
       pointed to by _s_e_p.  If no such byte is found, then there are no tokens
       in the string pointed to by _s and _s_t_r_t_o_k() shall return a null pointer.
       If such a byte is found, it is the start of the first token.

       The _s_t_r_t_o_k() function then searches from there for a byte that _i_s
       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 _s_t_r_t_o_k() 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 _s_t_r_t_o_k().

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

       The _s_t_r_t_o_k___r() function shall be equivalent to _s_t_r_t_o_k(), except that
       _s_t_r_t_o_k___r() shall be thread-safe and the argument _s_t_a_t_e points to a
       user-provided pointer that allows _s_t_r_t_o_k___r() to maintain state between
       calls which scan the same string. The application shall ensure that the
       pointer pointed to by _s_t_a_t_e is unique for each string (_s) being
       processed concurrently by _s_t_r_t_o_k___r() calls. The application need not
       initialize the pointer pointed to by _s_t_a_t_e to any particular value. The
       implementation shall not update the pointer pointed to by _s_t_a_t_e to
       point (directly or indirectly) to resources, other than within the
       string _s, that need to be freed or released by the caller.

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

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

EERRRROORRSS
       No errors are defined.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   SSeeaarrcchhiinngg ffoorr WWoorrdd SSeeppaarraattoorrss
       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);

   FFiinndd FFiirrsstt ttwwoo FFiieellddss iinn aa BBuuffffeerr
       The following example uses _s_t_r_t_o_k() 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 _b_u_f_f_e_r.


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

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Note that if _s_e_p is the empty string, _s_t_r_t_o_k() and _s_t_r_t_o_k___r() return a
       pointer to the remainder of the string being tokenized.

       The _s_t_r_t_o_k___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.

RRAATTIIOONNAALLEE
       The _s_t_r_t_o_k() 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, _s_t_r_t_o_k___r(),
       takes an additional argument, _s_t_a_t_e, to keep track of the current
       position in the string.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       The Base Definitions volume of POSIX.1-2017, <<ssttrriinngg..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  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.opengroup.org/unix/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 .



IEEE/The Open Group                  2017                            STRTOK(3)
