2004-11-03 13:51:07 +00:00
|
|
|
|
.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl)
|
2006-05-22 23:52:24 +00:00
|
|
|
|
.\" and Copyright (C) 2005 Michael Kerrisk (mtk-manpages@gmx.net)
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.\"
|
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
|
.\" preserved on all copies.
|
|
|
|
|
.\"
|
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
|
.\"
|
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
|
.\" professionally.
|
|
|
|
|
.\"
|
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
|
.\"
|
|
|
|
|
.\" Rewritten old page, 960210, aeb@cwi.nl
|
|
|
|
|
.\" Updated, added strtok_r. 2000-02-13 Nicol<6F>s Lichtmaier <nick@debian.org>
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.\" 2005-11-17, mtk: Substantial parts rewritten
|
|
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.TH STRTOK 3 2000-02-13 "GNU" "Linux Programmer's Manual"
|
|
|
|
|
.SH NAME
|
|
|
|
|
strtok, strtok_r \- extract tokens from strings
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
.nf
|
|
|
|
|
.B #include <string.h>
|
|
|
|
|
.sp
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.BI "char *strtok(char *" str ", const char *" delim );
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.sp
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.BI "char *strtok_r(char *" str ", const char *" delim ", char **" saveptr );
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.fi
|
|
|
|
|
.SH DESCRIPTION
|
2005-11-17 17:55:27 +00:00
|
|
|
|
The \fBstrtok\fP() function parses a string into a sequence of tokens.
|
|
|
|
|
On the first call to \fBstrtok\fP() the string to be parsed should be
|
|
|
|
|
specified in \fIstr\fP.
|
|
|
|
|
In each subsequent call that should parse the same string,
|
|
|
|
|
\fIstr\fP should be NULL.
|
|
|
|
|
|
|
|
|
|
The \fIdelim\fP argument specifies a set of characters that
|
|
|
|
|
delimit the tokens in the parsed string.
|
|
|
|
|
The caller may specify different strings in \fIdelim\fP in successive
|
|
|
|
|
calls that parse the same string.
|
|
|
|
|
|
|
|
|
|
Each call to \fBstrtok\fP() returns a pointer to a
|
|
|
|
|
null-terminated string containing the next token.
|
|
|
|
|
This string does not include the delimiting character.
|
|
|
|
|
If no more tokens are found, \fBstrtok\fP() returns NULL.
|
|
|
|
|
|
|
|
|
|
A sequence of two or more contiguous delimiter characters in
|
|
|
|
|
the parsed string is considered to be a single delimiter.
|
|
|
|
|
Delimiter characters at the start or end of the string are ignored.
|
|
|
|
|
Put another way: the tokens returned by \fBstrtok\fP()
|
|
|
|
|
are always non-empty strings.
|
|
|
|
|
|
|
|
|
|
The
|
|
|
|
|
.BR strtok_r ()
|
|
|
|
|
function is a reentrant version
|
|
|
|
|
.BR strtok ().
|
|
|
|
|
The \fIsaveptr\fP argument is a pointer to a
|
|
|
|
|
\fIchar *\fP variable that is used internally by
|
|
|
|
|
.BR strtok_r ()
|
|
|
|
|
in order to maintain context between successive calls that parse the
|
|
|
|
|
same string.
|
|
|
|
|
|
|
|
|
|
On the first call to
|
|
|
|
|
.BR strtok_r (),
|
|
|
|
|
.I str
|
|
|
|
|
should point to the string to be parsed, and the value of
|
|
|
|
|
.I saveptr
|
|
|
|
|
is ignored.
|
|
|
|
|
In subsequent calls, \fIstr\fP should be NULL, and
|
|
|
|
|
\fIsaveptr\fP should be unchanged since the previous call.
|
|
|
|
|
|
|
|
|
|
Different strings may be parsed concurrently using sequences of calls to
|
|
|
|
|
.BR strtok_r ()
|
|
|
|
|
that specify different \fIsaveptr\fP arguments.
|
2006-05-22 19:44:47 +00:00
|
|
|
|
.SH EXAMPLE
|
2005-11-17 17:55:27 +00:00
|
|
|
|
The following program uses nested loops that employ
|
|
|
|
|
.BR strtok_r ()
|
|
|
|
|
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 character(s)
|
|
|
|
|
to be used to separate that string into "major" tokens.
|
|
|
|
|
The third argument specifies the delimiter character(s)
|
|
|
|
|
to be used to separate the "major" tokens into subtokens.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.PP
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.nf
|
|
|
|
|
#include <stdio.h>
|
|
|
|
|
#include <stdlib.h>
|
|
|
|
|
#include <string.h>
|
|
|
|
|
|
|
|
|
|
int
|
|
|
|
|
main(int argc, char *argv[])
|
|
|
|
|
{
|
|
|
|
|
char *str1, *str2, *token, *subtoken;
|
|
|
|
|
char *saveptr1, *saveptr2;
|
|
|
|
|
int j;
|
|
|
|
|
|
|
|
|
|
if (argc != 4) {
|
|
|
|
|
fprintf(stderr, "Usage: %s string delim subdelim\\n",
|
|
|
|
|
argv[0]);
|
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
|
|
|
|
|
token = strtok_r(str1, argv[2], &saveptr1);
|
|
|
|
|
if (token == NULL)
|
|
|
|
|
break;
|
|
|
|
|
printf("%d: %s\n", j, token);
|
|
|
|
|
|
|
|
|
|
for (str2 = token; ; str2 = NULL) {
|
|
|
|
|
subtoken = strtok_r(str2, argv[3], &saveptr2);
|
|
|
|
|
if (subtoken == NULL)
|
|
|
|
|
break;
|
|
|
|
|
printf("\t --> %s\n", subtoken);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
exit(EXIT_SUCCESS);
|
|
|
|
|
} /* main */
|
|
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.PP
|
2005-11-17 17:55:27 +00:00
|
|
|
|
An example of the output produced by this program is the following:
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.PP
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.nf
|
|
|
|
|
$ ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/'
|
|
|
|
|
1: a/bbb///cc
|
|
|
|
|
--> a
|
|
|
|
|
--> bbb
|
|
|
|
|
--> cc
|
|
|
|
|
2: xxx
|
|
|
|
|
--> xxx
|
|
|
|
|
3: yyy
|
|
|
|
|
--> yyy
|
|
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.SH BUGS
|
2005-11-17 17:55:27 +00:00
|
|
|
|
Avoid using these functions.
|
|
|
|
|
If you do use them, note that:
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.PP
|
|
|
|
|
.RS
|
|
|
|
|
These functions modify their first argument.
|
|
|
|
|
.PP
|
|
|
|
|
These functions cannot be used on constant strings.
|
|
|
|
|
.PP
|
|
|
|
|
The identity of the delimiting character is lost.
|
|
|
|
|
.PP
|
|
|
|
|
The
|
|
|
|
|
.BR strtok ()
|
|
|
|
|
function uses a static buffer while parsing, so it's not thread safe. Use
|
|
|
|
|
.BR strtok_r ()
|
|
|
|
|
if this matters to you.
|
|
|
|
|
.RE
|
|
|
|
|
.SH "RETURN VALUE"
|
2005-11-21 08:52:27 +00:00
|
|
|
|
The \fBstrtok\fP() and \fBstrtok_r\fP() functions return a pointer to
|
2005-11-17 17:55:27 +00:00
|
|
|
|
the next token, or NULL if there are no more tokens.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.SH "CONFORMING TO"
|
|
|
|
|
.TP
|
2005-10-19 14:16:57 +00:00
|
|
|
|
.BR strtok ()
|
2006-08-03 13:57:30 +00:00
|
|
|
|
SVr4, POSIX.1-2001, 4.3BSD, C89.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.TP
|
2005-10-19 14:16:57 +00:00
|
|
|
|
.BR strtok_r ()
|
2005-11-17 17:55:27 +00:00
|
|
|
|
POSIX.1-2001
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
|
.BR index (3),
|
|
|
|
|
.BR memchr (3),
|
|
|
|
|
.BR rindex (3),
|
|
|
|
|
.BR strchr (3),
|
|
|
|
|
.BR strpbrk (3),
|
|
|
|
|
.BR strsep (3),
|
|
|
|
|
.BR strspn (3),
|
2006-02-09 20:57:44 +00:00
|
|
|
|
.BR strstr (3),
|
|
|
|
|
.BR wcstok (3)
|