diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/strtok.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/strtok.3p | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/strtok.3p b/man-pages-posix-2017/man3p/strtok.3p new file mode 100644 index 0000000..78af67a --- /dev/null +++ b/man-pages-posix-2017/man3p/strtok.3p @@ -0,0 +1,232 @@ +'\" et +.TH STRTOK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strtok, +strtok_r +\(em split string into tokens +.SH SYNOPSIS +.LP +.nf +#include <string.h> +.P +char *strtok(char *restrict \fIs\fP, const char *restrict \fIsep\fP); +char *strtok_r(char *restrict \fIs\fP, const char *restrict \fIsep\fP, + char **restrict \fIstate\fP); +.fi +.SH DESCRIPTION +For +\fIstrtok\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +A sequence of calls to +\fIstrtok\fR() +breaks the string pointed to by +.IR s +into a sequence of tokens, each of which is delimited by a byte from +the string pointed to by +.IR sep . +The first call in the sequence has +.IR s +as its first argument, and is followed by calls with a null pointer as +their first argument. The separator string pointed to by +.IR sep +may be different from call to call. +.P +The first call in the sequence searches the string pointed to by +.IR s +for the first byte that is +.IR not +contained in the current separator string pointed to by +.IR sep . +If no such byte is found, then there are no tokens in the string +pointed to by +.IR s +and +\fIstrtok\fR() +shall return a null pointer. If such a byte is found, it is the +start of the first token. +.P +The +\fIstrtok\fR() +function then searches from there for a byte that +.IR is +contained in the current separator string. If no such byte is found, +the current token extends to the end of the string pointed to by +.IR s , +and subsequent searches for a token shall return a null pointer. If +such a byte is found, it is overwritten by a NUL character, which +terminates the current token. The +\fIstrtok\fR() +function saves a pointer to the following byte, from which the next +search for a token shall start. +.P +Each subsequent call, with a null pointer as the value of the first +argument, starts searching from the saved pointer and behaves as +described above. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 +calls +\fIstrtok\fR(). +.P +The +\fIstrtok\fR() +function need not be thread-safe. +.P +The +\fIstrtok_r\fR() +function shall be equivalent to +\fIstrtok\fR(), +except that +\fIstrtok_r\fR() +shall be thread-safe and the argument +.IR state +points to a user-provided pointer that allows +\fIstrtok_r\fR() +to maintain state between calls which scan the same string. The +application shall ensure that the pointer pointed to by +.IR state +is unique for each string (\c +.IR s ) +being processed concurrently by +\fIstrtok_r\fR() +calls. The application need not initialize the pointer pointed to by +.IR state +to any particular value. The implementation shall not update the +pointer pointed to by +.IR state +to point (directly or indirectly) to resources, other than within +the string +.IR s , +that need to be freed or released by the caller. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrtok\fR() +shall return a pointer to the first byte of a token. Otherwise, +if there is no token, +\fIstrtok\fR() +shall return a null pointer. +.P +The +\fIstrtok_r\fR() +function shall return a pointer to the token found, or a null pointer +when no token is found. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Searching for Word Separators" +.P +The following example searches for tokens separated by +<space> +characters. +.sp +.RS 4 +.nf + +#include <string.h> +\&... +char *token; +char line[] = "LINE TO BE SEPARATED"; +char *search = " "; +.P +/* Token will point to "LINE". */ +token = strtok(line, search); +.P +/* Token will point to "TO". */ +token = strtok(NULL, search); +.fi +.P +.RE +.SS "Find First two Fields in a Buffer" +.P +The following example uses +\fIstrtok\fR() +to find two character strings (a key and data associated with that key) +separated by any combination of +<space>, +<tab>, +or +<newline> +characters at the start of the array of characters pointed to by +.IR buffer . +.sp +.RS 4 +.nf + +#include <string.h> +\&... +char *buffer; +\&... +struct element { + char *key; + char *data; +} e; +\&... +// Load the buffer... +\&... +// Get the key and its data... +e.key = strtok(buffer, " \et\en"); +e.data = strtok(NULL, " \et\en"); +// Process the rest of the contents of the buffer... +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +Note that if +.IR sep +is the empty string, +\fIstrtok\fR() +and +\fIstrtok_r\fR() +return a pointer to the remainder of the string being tokenized. +.P +The +\fIstrtok_r\fR() +function is thread-safe and stores its state in a user-supplied buffer +instead of possibly using a static data area that may be overwritten +by an unrelated call from another thread. +.SH RATIONALE +The +\fIstrtok\fR() +function searches for a separator string within a larger string. It +returns a pointer to the last substring between separator strings. +This function uses static storage to keep track of the current string +position between calls. The new function, +\fIstrtok_r\fR(), +takes an additional argument, +.IR state , +to keep track of the current position in the string. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<string.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |