strtok.3p (6387B)
- '\" 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 .