2004-11-03 13:51:07 +00:00
|
|
|
|
.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl)
|
2007-09-20 06:52:22 +00:00
|
|
|
|
.\" and Copyright (C) 2005 Michael Kerrisk (mtk.manpages@gmail.com)
|
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.
|
2007-04-12 22:42:49 +00:00
|
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.\" 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
|
|
|
|
|
.\"
|
2010-09-27 05:48:04 +00:00
|
|
|
|
.TH STRTOK 3 2010-09-27 "GNU" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.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
|
2007-07-08 12:11:40 +00:00
|
|
|
|
.sp
|
|
|
|
|
.in -4n
|
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
|
.in
|
|
|
|
|
.sp
|
|
|
|
|
.ad l
|
|
|
|
|
.BR strtok_r ():
|
2008-08-29 15:50:13 +00:00
|
|
|
|
_SVID_SOURCE || _BSD_SOURCE || _POSIX_C_SOURCE\ >=\ 1 ||
|
|
|
|
|
_XOPEN_SOURCE || _POSIX_SOURCE
|
2007-07-08 12:11:40 +00:00
|
|
|
|
.ad b
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.SH DESCRIPTION
|
2007-05-12 09:06:04 +00:00
|
|
|
|
The
|
|
|
|
|
.BR strtok ()
|
|
|
|
|
function parses a string into a sequence of tokens.
|
|
|
|
|
On the first call to
|
|
|
|
|
.BR strtok ()
|
|
|
|
|
the string to be parsed should be
|
2005-11-17 17:55:27 +00:00
|
|
|
|
specified in \fIstr\fP.
|
2007-04-12 22:42:49 +00:00
|
|
|
|
In each subsequent call that should parse the same string,
|
2005-11-17 17:55:27 +00:00
|
|
|
|
\fIstr\fP should be NULL.
|
|
|
|
|
|
|
|
|
|
The \fIdelim\fP argument specifies a set of characters that
|
|
|
|
|
delimit the tokens in the parsed string.
|
2007-04-12 22:42:49 +00:00
|
|
|
|
The caller may specify different strings in \fIdelim\fP in successive
|
2005-11-17 17:55:27 +00:00
|
|
|
|
calls that parse the same string.
|
|
|
|
|
|
2007-05-12 09:06:04 +00:00
|
|
|
|
Each call to
|
|
|
|
|
.BR strtok ()
|
|
|
|
|
returns a pointer to a
|
2005-11-17 17:55:27 +00:00
|
|
|
|
null-terminated string containing the next token.
|
|
|
|
|
This string does not include the delimiting character.
|
2007-05-12 09:06:04 +00:00
|
|
|
|
If no more tokens are found,
|
|
|
|
|
.BR strtok ()
|
|
|
|
|
returns NULL.
|
2005-11-17 17:55:27 +00:00
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
|
A sequence of two or more contiguous delimiter characters in
|
2005-11-17 17:55:27 +00:00
|
|
|
|
the parsed string is considered to be a single delimiter.
|
|
|
|
|
Delimiter characters at the start or end of the string are ignored.
|
2007-05-12 09:06:04 +00:00
|
|
|
|
Put another way: the tokens returned by
|
|
|
|
|
.BR strtok ()
|
mbind.2, rename.2, sched_setscheduler.2, set_mempolicy.2, syslog.2, argz_add.3, dlopen.3, scanf.3, strtod.3, strtok.3, tcgetpgrp.3, hd.4, cpuset.7, regex.7, ld.so.8: Global fix: s/non-empty/nonempty/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:41:47 +00:00
|
|
|
|
are always nonempty strings.
|
2005-11-17 17:55:27 +00:00
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
|
The
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.BR strtok_r ()
|
|
|
|
|
function is a reentrant version
|
|
|
|
|
.BR strtok ().
|
2007-04-12 22:42:49 +00:00
|
|
|
|
The \fIsaveptr\fP argument is a pointer to a
|
2005-11-17 17:55:27 +00:00
|
|
|
|
\fIchar *\fP variable that is used internally by
|
|
|
|
|
.BR strtok_r ()
|
|
|
|
|
in order to maintain context between successive calls that parse the
|
|
|
|
|
same string.
|
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
|
On the first call to
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.BR strtok_r (),
|
|
|
|
|
.I str
|
2007-04-12 22:42:49 +00:00
|
|
|
|
should point to the string to be parsed, and the value of
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.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.
|
2007-05-19 04:30:20 +00:00
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
|
The
|
|
|
|
|
.BR strtok ()
|
|
|
|
|
and
|
|
|
|
|
.BR strtok_r ()
|
|
|
|
|
functions return a pointer to
|
|
|
|
|
the next token, or NULL if there are no more tokens.
|
|
|
|
|
.SH "CONFORMING TO"
|
|
|
|
|
.TP
|
|
|
|
|
.BR strtok ()
|
|
|
|
|
SVr4, POSIX.1-2001, 4.3BSD, C89, C99.
|
|
|
|
|
.TP
|
|
|
|
|
.BR strtok_r ()
|
2008-07-15 13:39:17 +00:00
|
|
|
|
POSIX.1-2001.
|
2007-05-19 04:30:20 +00:00
|
|
|
|
.SH BUGS
|
2009-01-14 17:30:33 +00:00
|
|
|
|
Be cautious when using these functions.
|
2007-05-19 04:30:20 +00:00
|
|
|
|
If you do use them, note that:
|
2009-01-14 17:20:17 +00:00
|
|
|
|
.IP * 2
|
2007-05-19 04:30:20 +00:00
|
|
|
|
These functions modify their first argument.
|
2009-01-14 17:20:17 +00:00
|
|
|
|
.IP *
|
2007-05-19 04:30:20 +00:00
|
|
|
|
These functions cannot be used on constant strings.
|
2009-01-14 17:20:17 +00:00
|
|
|
|
.IP *
|
2007-05-19 04:30:20 +00:00
|
|
|
|
The identity of the delimiting character is lost.
|
2009-01-14 17:20:17 +00:00
|
|
|
|
.IP *
|
2007-05-19 04:30:20 +00:00
|
|
|
|
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.
|
2006-05-22 19:44:47 +00:00
|
|
|
|
.SH EXAMPLE
|
2008-10-28 16:01:42 +00:00
|
|
|
|
The program below uses nested loops that employ
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.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
|
2008-10-28 16:01:42 +00:00
|
|
|
|
An example of the output produced by this program is the following:
|
|
|
|
|
.PP
|
|
|
|
|
.in +4n
|
|
|
|
|
.nf
|
|
|
|
|
.RB "$" " ./a.out \(aqa/bbb///cc;xxx:yyy:\(aq \(aq:;\(aq \(aq/\(aq"
|
|
|
|
|
1: a/bbb///cc
|
|
|
|
|
\-\-> a
|
|
|
|
|
\-\-> bbb
|
|
|
|
|
\-\-> cc
|
|
|
|
|
2: xxx
|
|
|
|
|
\-\-> xxx
|
|
|
|
|
3: yyy
|
|
|
|
|
\-\-> yyy
|
|
|
|
|
.fi
|
|
|
|
|
.in
|
|
|
|
|
.SS Program source
|
eventfd.2, getdents.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, getaddrinfo.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, strtok.3, strtol.3, core.5: srcfix
s/\.R " "/\\\&/ as a way of getting a blank line after a .SS heading.
(Suggested by Sam Varshavchik <mrsam@courier-mta.com>)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-11-05 01:42:45 +00:00
|
|
|
|
\&
|
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) {
|
2007-04-12 22:42:49 +00:00
|
|
|
|
fprintf(stderr, "Usage: %s string delim subdelim\\n",
|
2005-11-17 17:55:27 +00:00
|
|
|
|
argv[0]);
|
|
|
|
|
exit(EXIT_FAILURE);
|
2007-04-12 22:42:49 +00:00
|
|
|
|
}
|
2005-11-17 17:55:27 +00:00
|
|
|
|
|
|
|
|
|
for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
|
|
|
|
|
token = strtok_r(str1, argv[2], &saveptr1);
|
|
|
|
|
if (token == NULL)
|
|
|
|
|
break;
|
2006-12-16 06:12:03 +00:00
|
|
|
|
printf("%d: %s\\n", j, token);
|
2005-11-17 17:55:27 +00:00
|
|
|
|
|
|
|
|
|
for (str2 = token; ; str2 = NULL) {
|
|
|
|
|
subtoken = strtok_r(str2, argv[3], &saveptr2);
|
|
|
|
|
if (subtoken == NULL)
|
|
|
|
|
break;
|
2007-06-20 21:39:45 +00:00
|
|
|
|
printf("\t \-\-> %s\\n", subtoken);
|
2007-04-12 22:42:49 +00:00
|
|
|
|
}
|
|
|
|
|
}
|
2005-11-17 17:55:27 +00:00
|
|
|
|
|
|
|
|
|
exit(EXIT_SUCCESS);
|
2010-09-23 06:31:18 +00:00
|
|
|
|
}
|
2005-11-17 17:55:27 +00:00
|
|
|
|
.fi
|
2010-09-27 05:48:04 +00:00
|
|
|
|
.PP
|
|
|
|
|
Another example program using
|
|
|
|
|
.BR strtok ()
|
|
|
|
|
can be found in
|
|
|
|
|
.BR getaddrinfo_a (3).
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
|
.BR index (3),
|
|
|
|
|
.BR memchr (3),
|
|
|
|
|
.BR rindex (3),
|
|
|
|
|
.BR strchr (3),
|
index.3, stpcpy.3, strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strdup.3, strfry.3, strpbrk.3, strsep.3, strspn.3, strstr.3, strtok.3, strxfrm.3: SEE ALSO: Add reference to string(3)
The idea here is to provide a route to discover other
string functions.
Reported-by: Mark Hills <mark@pogo.org.uk>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-12 14:39:58 +00:00
|
|
|
|
.BR string (3),
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.BR strpbrk (3),
|
|
|
|
|
.BR strsep (3),
|
|
|
|
|
.BR strspn (3),
|
2006-02-09 20:57:44 +00:00
|
|
|
|
.BR strstr (3),
|
|
|
|
|
.BR wcstok (3)
|