404 lines
11 KiB
HTML
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"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
strtok, strtok_r - extract tokens from strings
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/string.h">string.h</A>></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> || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
|
|
|
|
<A NAME="lbAD"> </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 "<I>aaa;;bbb,</I>",
|
|
successive calls to
|
|
<B>strtok</B>()
|
|
|
|
that specify the delimiter string "<I>;,</I>"
|
|
would return the strings "<I>aaa</I>" and "<I>bbb</I>",
|
|
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 *</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"> </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"> </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"> </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"> </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"> </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"> </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 "major" tokens.
|
|
The third argument specifies the delimiter byte(s)
|
|
to be used to separate the "major" 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> --> a
|
|
<BR> --> bbb
|
|
<BR> --> cc
|
|
2: xxx
|
|
<BR> --> xxx
|
|
3: yyy
|
|
<BR> --> yyy
|
|
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Program source</H3>
|
|
|
|
|
|
|
|
#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
|
|
#include <<A HREF="file:///usr/include/stdlib.h">stdlib.h</A>>
|
|
#include <<A HREF="file:///usr/include/string.h">string.h</A>>
|
|
<P>
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
<BR> char *str1, *str2, *token, *subtoken;
|
|
<BR> char *saveptr1, *saveptr2;
|
|
<BR> int j;
|
|
<P>
|
|
<BR> if (argc != 4) {
|
|
<BR> fprintf(stderr, "Usage: %s string delim subdelim\n",
|
|
<BR> argv[0]);
|
|
<BR> exit(EXIT_FAILURE);
|
|
<BR> }
|
|
<P>
|
|
<BR> for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
|
|
<BR> token = strtok_r(str1, argv[2], &saveptr1);
|
|
<BR> if (token == NULL)
|
|
<BR> break;
|
|
<BR> printf("%d: %s\n", j, token);
|
|
<P>
|
|
<BR> for (str2 = token; ; str2 = NULL) {
|
|
<BR> subtoken = strtok_r(str2, argv[3], &saveptr2);
|
|
<BR> if (subtoken == NULL)
|
|
<BR> break;
|
|
<BR> printf(" --> %s\n", subtoken);
|
|
<BR> }
|
|
<BR> }
|
|
<P>
|
|
<BR> 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"> </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"> </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"> </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>
|