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_1, const char *restrict _s_2);
       char *strtok_r(char *restrict _s, const char *restrict _s_e_p,
           char **restrict _l_a_s_t_s);

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-2008 defers to the ISO C standard.

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

       The first call in the sequence searches the string pointed to by _s_1 for
       the first byte that is _n_o_t contained in the current separator string
       pointed to by _s_2.  If no such byte is found, then there are no tokens
       in the string pointed to by _s_1 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_1,
       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-2008 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 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 _s_e_p.  The argument _l_a_s_t_s points to
       a user-provided pointer which points to stored information necessary
       for _s_t_r_t_o_k___r() to continue scanning the same string.

       In the first call to _s_t_r_t_o_k___r(), _s points to a null-terminated string,
       _s_e_p to a null-terminated string of separator characters, and the value
       pointed to by _l_a_s_t_s is ignored. The _s_t_r_t_o_k___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 _l_a_s_t_s points.

       In subsequent calls, _s is a null pointer and _l_a_s_t_s 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 _s_e_p may be different from call to call. When no token
       remains in _s, a null pointer shall be returned.

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.

           ##iinncclluuddee <<ssttrriinngg..hh>>
           ......
           cchhaarr **ttookkeenn;;
           cchhaarr lliinnee[[]] == ""LLIINNEE TTOO BBEE SSEEPPAARRAATTEEDD"";;
           cchhaarr **sseeaarrcchh == "" "";;

           /* 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.

           ##iinncclluuddee <<ssttrriinngg..hh>>
           ......
           cchhaarr    **bbuuffffeerr;;
           ......
           ssttrruucctt eelleemmeenntt {{
               cchhaarr **kkeeyy;;
               cchhaarr **ddaattaa;;
           }} ee;;
           ......
           //// LLooaadd tthhee bbuuffffeerr......
           ......
           //// GGeett tthhee kkeeyy aanndd iittss ddaattaa......
           ee..kkeeyy == ssttrrttookk((bbuuffffeerr,, "" \\tt\\nn""));;
           ee..ddaattaa == ssttrrttookk((NNUULLLL,, "" \\tt\\nn""));;
           //// PPrroocceessss tthhee rreesstt ooff tthhee ccoonntteennttss ooff tthhee bbuuffffeerr......
           ......

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       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, _l_a_s_t_s, to keep track of the current
       position in the string.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

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

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



IEEE/The Open Group                  2013                            STRTOK(3)
