diff options
Diffstat (limited to 'man3/strtok.3')
| -rw-r--r-- | man3/strtok.3 | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/man3/strtok.3 b/man3/strtok.3 new file mode 100644 index 0000000..6f01530 --- /dev/null +++ b/man3/strtok.3 @@ -0,0 +1,289 @@ +'\" t +.\" Copyright (C) 2005, 2013 Michael Kerrisk <mtk.manpages@gmail.com> +.\" a few fragments from an earlier (1996) version by +.\" Andries Brouwer (aeb@cwi.nl) remain. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Rewritten old page, 960210, aeb@cwi.nl +.\" Updated, added strtok_r. 2000-02-13 Nicolás Lichtmaier <nick@debian.org> +.\" 2005-11-17, mtk: Substantial parts rewritten +.\" 2013-05-19, mtk: added much further detail on the operation of strtok() +.\" +.TH strtok 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +strtok, strtok_r \- extract tokens from strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.PP +.BI "char *strtok(char *restrict " str ", const char *restrict " delim ); +.BI "char *strtok_r(char *restrict " str ", const char *restrict " delim , +.BI " char **restrict " saveptr ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR strtok_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR strtok () +function breaks a string into a sequence of zero or more nonempty tokens. +On the first call to +.BR strtok (), +the string to be parsed should be +specified in +.IR str . +In each subsequent call that should parse the same string, +.I str +must be NULL. +.PP +The +.I delim +argument specifies a set of bytes that +delimit the tokens in the parsed string. +The caller may specify different strings in +.I delim +in successive +calls that parse the same string. +.PP +Each call to +.BR strtok () +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, +.BR strtok () +returns NULL. +.PP +A sequence of calls to +.BR strtok () +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 +.BR strtok () +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 +.IR str . +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 +.BR strtok () +returns NULL. +(A string that is empty or that contains only delimiters +will thus cause +.BR strtok () +to return NULL on the first call.) +.PP +The end of each token is found by scanning forward until either +the next delimiter byte is found or until the +terminating null byte (\[aq]\e0\[aq]) is encountered. +If a delimiter byte is found, it is overwritten with +a null byte to terminate the current token, and +.BR strtok () +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, +.BR strtok () +returns a pointer to the start of the found token. +.PP +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 +.BR strtok () +are always nonempty strings. +Thus, for example, given the string "\fIaaa;;bbb,\fP", +successive calls to +.BR strtok () +that specify the delimiter string "\fI;,\fP" +would return the strings "\fIaaa\fP" and "\fIbbb\fP", +and then a null pointer. +.PP +The +.BR strtok_r () +function is a reentrant version of +.BR strtok (). +The +.I saveptr +argument is a pointer to a +.I char\~* +variable that is used internally by +.BR strtok_r () +in order to maintain context between successive calls that parse the +same string. +.PP +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 (but see NOTES). +In subsequent calls, +.I str +should be NULL, and +.I saveptr +(and the buffer that it points to) +should be unchanged since the previous call. +.PP +Different strings may be parsed concurrently using sequences of calls to +.BR strtok_r () +that specify different +.I saveptr +arguments. +.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 ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtok () +T} Thread safety MT-Unsafe race:strtok +T{ +.na +.nh +.BR strtok_r () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH VERSIONS +On some implementations, +.\" Tru64, according to its manual page +.I *saveptr +is required to be NULL on the first call to +.BR strtok_r () +that is being used to parse +.IR str . +.SH STANDARDS +.TP +.BR strtok () +C11, POSIX.1-2008. +.TP +.BR strtok_r () +POSIX.1-2008. +.SH HISTORY +.TP +.BR strtok () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR strtok_r () +POSIX.1-2001. +.SH BUGS +Be cautious when using these functions. +If you do use them, note that: +.IP \[bu] 3 +These functions modify their first argument. +.IP \[bu] +These functions cannot be used on constant strings. +.IP \[bu] +The identity of the delimiting byte is lost. +.IP \[bu] +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. +.SH EXAMPLES +The program below 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 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. +.PP +An example of the output produced by this program is the following: +.PP +.in +4n +.EX +.RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]" +1: a/bbb///cc + \-\-> a + \-\-> bbb + \-\-> cc +2: xxx + \-\-> xxx +3: yyy + \-\-> yyy +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strtok.c) +.EX +#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\en", + 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\en", j, token); +\& + for (str2 = token; ; str2 = NULL) { + subtoken = strtok_r(str2, argv[3], &saveptr2); + if (subtoken == NULL) + break; + printf("\et \-\-> %s\en", subtoken); + } + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.PP +Another example program using +.BR strtok () +can be found in +.BR getaddrinfo_a (3). +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR wcstok (3) |