man-pages/man3/strtok.3.html
2021-03-31 01:06:50 +01:00

404 lines
11 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of STRTOK</TITLE>
</HEAD><BODY>
<H1>STRTOK</H1>
Section: Linux Programmer's Manual (3)<BR>Updated: 2019-10-10<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
strtok, strtok_r - extract tokens from strings
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>
<PRE>
<B>#include &lt;<A HREF="file:///usr/include/string.h">string.h</A>&gt;</B>
<B>char *strtok(char *</B><I>str</I><B>, const char *</B><I>delim</I><B>);</B>
<B>char *strtok_r(char *</B><I>str</I><B>, const char *</B><I>delim</I><B>, char **</B><I>saveptr</I><B>);</B>
</PRE>
<P>
Feature Test Macro Requirements for glibc (see
<B><A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A></B>(7)):
<P>
<B>strtok_r</B>():
_POSIX_C_SOURCE
<BR>&nbsp;&nbsp;&nbsp;&nbsp;||&nbsp;/*&nbsp;Glibc&nbsp;versions&nbsp;&lt;=&nbsp;2.19:&nbsp;*/&nbsp;_BSD_SOURCE&nbsp;||&nbsp;_SVID_SOURCE
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>
The
<B>strtok</B>()
function breaks a string into a sequence of zero or more nonempty tokens.
On the first call to
<B>strtok</B>(),
the string to be parsed should be
specified in
<I>str</I>.
In each subsequent call that should parse the same string,
<I>str</I>
must be NULL.
<P>
The
<I>delim</I>
argument specifies a set of bytes that
delimit the tokens in the parsed string.
The caller may specify different strings in
<I>delim</I>
in successive
calls that parse the same string.
<P>
Each call to
<B>strtok</B>()
returns a pointer to a
null-terminated string containing the next token.
This string does not include the delimiting byte.
If no more tokens are found,
<B>strtok</B>()
returns NULL.
<P>
A sequence of calls to
<B>strtok</B>()
that operate on the same string maintains a pointer
that determines the point from which to start searching for the next token.
The first call to
<B>strtok</B>()
sets this pointer to point to the first byte of the string.
The start of the next token is determined by scanning forward
for the next nondelimiter byte in
<I>str</I>.
If such a byte is found, it is taken as the start of the next token.
If no such byte is found,
then there are no more tokens, and
<B>strtok</B>()
returns NULL.
(A string that is empty or that contains only delimiters
will thus cause
<B>strtok</B>()
to return NULL on the first call.)
<P>
The end of each token is found by scanning forward until either
the next delimiter byte is found or until the
terminating null byte ('\0') is encountered.
If a delimiter byte is found, it is overwritten with
a null byte to terminate the current token, and
<B>strtok</B>()
saves a pointer to the following byte;
that pointer will be used as the starting point
when searching for the next token.
In this case,
<B>strtok</B>()
returns a pointer to the start of the found token.
<P>
From the above description,
it follows that a sequence of two or more contiguous delimiter bytes in
the parsed string is considered to be a single delimiter, and that
delimiter bytes at the start or end of the string are ignored.
Put another way: the tokens returned by
<B>strtok</B>()
are always nonempty strings.
Thus, for example, given the string &quot;<I>aaa;;bbb,</I>&quot;,
successive calls to
<B>strtok</B>()
that specify the delimiter string &quot;<I>;,</I>&quot;
would return the strings &quot;<I>aaa</I>&quot; and &quot;<I>bbb</I>&quot;,
and then a null pointer.
<P>
The
<B>strtok_r</B>()
function is a reentrant version of
<B>strtok</B>().
The
<I>saveptr</I>
argument is a pointer to a
<I>char&nbsp;*</I>
variable that is used internally by
<B>strtok_r</B>()
in order to maintain context between successive calls that parse the
same string.
<P>
On the first call to
<B>strtok_r</B>(),
<I>str</I>
should point to the string to be parsed, and the value of
<I>*saveptr</I>
is ignored (but see NOTES).
In subsequent calls,
<I>str</I>
should be NULL, and
<I>saveptr</I>
(and the buffer that it points to)
should be unchanged since the previous call.
<P>
Different strings may be parsed concurrently using sequences of calls to
<B>strtok_r</B>()
that specify different
<I>saveptr</I>
arguments.
<A NAME="lbAE">&nbsp;</A>
<H2>RETURN VALUE</H2>
The
<B>strtok</B>()
and
<B>strtok_r</B>()
functions return a pointer to
the next token, or NULL if there are no more tokens.
<A NAME="lbAF">&nbsp;</A>
<H2>ATTRIBUTES</H2>
For an explanation of the terms used in this section, see
<B><A HREF="/cgi-bin/man/man2html?7+attributes">attributes</A></B>(7).
<TABLE BORDER>
<TR VALIGN=top><TD><B>Interface</B></TD><TD><B>Attribute</B></TD><TD><B>Value</B><BR></TD></TR>
<TR VALIGN=top><TD>
<B>strtok</B>()
</TD><TD>Thread safety</TD><TD>MT-Unsafe race:strtok<BR></TD></TR>
<TR VALIGN=top><TD>
<B>strtok_r</B>()
</TD><TD>Thread safety</TD><TD>MT-Safe<BR></TD></TR>
</TABLE>
<A NAME="lbAG">&nbsp;</A>
<H2>CONFORMING TO</H2>
<DL COMPACT>
<DT id="1"><B>strtok</B>()
<DD>
POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
<DT id="2"><B>strtok_r</B>()
<DD>
POSIX.1-2001, POSIX.1-2008.
</DL>
<A NAME="lbAH">&nbsp;</A>
<H2>NOTES</H2>
On some implementations,
<I>*saveptr</I>
is required to be NULL on the first call to
<B>strtok_r</B>()
that is being used to parse
<I>str</I>.
<A NAME="lbAI">&nbsp;</A>
<H2>BUGS</H2>
Be cautious when using these functions.
If you do use them, note that:
<DL COMPACT>
<DT id="3">*<DD>
These functions modify their first argument.
<DT id="4">*<DD>
These functions cannot be used on constant strings.
<DT id="5">*<DD>
The identity of the delimiting byte is lost.
<DT id="6">*<DD>
The
<B>strtok</B>()
function uses a static buffer while parsing, so it's not thread safe.
Use
<B>strtok_r</B>()
if this matters to you.
</DL>
<A NAME="lbAJ">&nbsp;</A>
<H2>EXAMPLE</H2>
The program below uses nested loops that employ
<B>strtok_r</B>()
to break a string into a two-level hierarchy of tokens.
The first command-line argument specifies the string to be parsed.
The second argument specifies the delimiter byte(s)
to be used to separate that string into &quot;major&quot; tokens.
The third argument specifies the delimiter byte(s)
to be used to separate the &quot;major&quot; tokens into subtokens.
<P>
An example of the output produced by this program is the following:
<P>
$<B> ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/'</B>
1: a/bbb///cc
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&gt;&nbsp;a
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&gt;&nbsp;bbb
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&gt;&nbsp;cc
2: xxx
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&gt;&nbsp;xxx
3: yyy
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&gt;&nbsp;yyy
<A NAME="lbAK">&nbsp;</A>
<H3>Program source</H3>
#include &lt;<A HREF="file:///usr/include/stdio.h">stdio.h</A>&gt;
#include &lt;<A HREF="file:///usr/include/stdlib.h">stdlib.h</A>&gt;
#include &lt;<A HREF="file:///usr/include/string.h">string.h</A>&gt;
<P>
int
main(int argc, char *argv[])
{
<BR>&nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;*str1,&nbsp;*str2,&nbsp;*token,&nbsp;*subtoken;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;*saveptr1,&nbsp;*saveptr2;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;j;
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(argc&nbsp;!=&nbsp;4)&nbsp;{
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;&quot;Usage:&nbsp;%s&nbsp;string&nbsp;delim&nbsp;subdelim\n&quot;,
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;argv[0]);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(EXIT_FAILURE);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;}
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;for&nbsp;(j&nbsp;=&nbsp;1,&nbsp;str1&nbsp;=&nbsp;argv[1];&nbsp;;&nbsp;j++,&nbsp;str1&nbsp;=&nbsp;NULL)&nbsp;{
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;token&nbsp;=&nbsp;strtok_r(str1,&nbsp;argv[2],&nbsp;&amp;saveptr1);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(token&nbsp;==&nbsp;NULL)
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;break;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf(&quot;%d:&nbsp;%s\n&quot;,&nbsp;j,&nbsp;token);
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;for&nbsp;(str2&nbsp;=&nbsp;token;&nbsp;;&nbsp;str2&nbsp;=&nbsp;NULL)&nbsp;{
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;subtoken&nbsp;=&nbsp;strtok_r(str2,&nbsp;argv[3],&nbsp;&amp;saveptr2);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(subtoken&nbsp;==&nbsp;NULL)
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;break;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf(&quot; &nbsp;--&gt;&nbsp;%s\n&quot;,&nbsp;subtoken);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}
<BR>&nbsp;&nbsp;&nbsp;&nbsp;}
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;exit(EXIT_SUCCESS);
}
<P>
Another example program using
<B>strtok</B>()
can be found in
<B><A HREF="/cgi-bin/man/man2html?3+getaddrinfo_a">getaddrinfo_a</A></B>(3).
<A NAME="lbAL">&nbsp;</A>
<H2>SEE ALSO</H2>
<B><A HREF="/cgi-bin/man/man2html?3+index">index</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+memchr">memchr</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+rindex">rindex</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+strchr">strchr</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+string">string</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+strpbrk">strpbrk</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+strsep">strsep</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+strspn">strspn</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+strstr">strstr</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+wcstok">wcstok</A></B>(3)
<A NAME="lbAM">&nbsp;</A>
<H2>COLOPHON</H2>
This page is part of release 5.05 of the Linux
<I>man-pages</I>
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="7"><A HREF="#lbAB">NAME</A><DD>
<DT id="8"><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT id="9"><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT id="10"><A HREF="#lbAE">RETURN VALUE</A><DD>
<DT id="11"><A HREF="#lbAF">ATTRIBUTES</A><DD>
<DT id="12"><A HREF="#lbAG">CONFORMING TO</A><DD>
<DT id="13"><A HREF="#lbAH">NOTES</A><DD>
<DT id="14"><A HREF="#lbAI">BUGS</A><DD>
<DT id="15"><A HREF="#lbAJ">EXAMPLE</A><DD>
<DL>
<DT id="16"><A HREF="#lbAK">Program source</A><DD>
</DL>
<DT id="17"><A HREF="#lbAL">SEE ALSO</A><DD>
<DT id="18"><A HREF="#lbAM">COLOPHON</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 00:05:58 GMT, March 31, 2021
</BODY>
</HTML>