Description

The arguments s, s1, and s2 point to strings (arrays of characters terminated by a null character). The strcat(), strncat(), strlcat(), strcpy(),
strncpy(), strlcpy(), strsep(), strtok(), and strtok_r() functions all alter their first argument. Additionally, the strcat() and strcpy() functions do not check for overflow
of the array.

strcasecmp(), strncasecmp()

The strcasecmp() and strncasecmp() functions are case-insensitive versions of strcmp() and strncmp() respectively, described below. They ignore differences in case when comparing lower and upper case characters,
using the current locale of the process to determine the case of the characters.

strcat(), strncat(), strlcat()

The strcat() function appends a copy of string s2, including the terminating null character, to the end of string s1. The strncat() function appends at most n characters. Each returns
a pointer to the null-terminated result. The initial character of s2 overrides the null character at the end of s1. If copying takes place between objects that overlap, the behavior of strcat(), strncat(), and
strlcat() is undefined.

The strlcat() function appends at most (dstsize-strlen(dst)-1) characters of src to dst (dstsize being the size of the string buffer
dst). If the string pointed to by dst contains a null-terminated string that fits into dstsize bytes when strlcat() is called, the string pointed to by dst will be a null-terminated string that
fits in dstsize bytes (including the terminating null character) when it completes, and the initial character of src will override the null character at the end of dst. If the string pointed to by dst is
longer than dstsize bytes when strlcat() is called, the string pointed to by dst will not be changed. The function returns min{dstsize,strlen(dst)}+
strlen(src). Buffer overflow can be checked as follows:

if (strlcat(dst, src, dstsize) >= dstsize)
return −1;

strchr(), strrchr(), strchrnul()

The strchr() function returns a pointer to the first occurrence of c (converted to a char) in string s, or a null pointer if c does not occur in the string.

The strrchr() function returns a pointer to the last occurrence of c. The null character terminating a string is considered to be part of the string.

The strchrnul() function is similar to strchr() except that if c is not found in s, it returns a pointer to the null byte at the end of s, rather than NULL.

strcmp(), strncmp()

The strcmp() function compares two strings byte-by-byte, according to the ordering of your machine's character set. The function returns an integer greater than, equal to, or less than 0, if the string pointed to by s1 is greater than, equal to,
or less than the string pointed to by s2 respectively. The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes that differ in the strings being compared. The strncmp() function makes
the same comparison but looks at a maximum of n bytes. Bytes following a null byte are not compared.

strcpy(), stpcpy(), strncpy(), stpncpy(), strlcpy()

The strcpy() and stpcpy() functions copy string s2 to s1, including the terminating null character, stopping after the null character has been copied. The strcpy() function returns
s1. The stpcpy() function returns a pointer to the terminating null character copied into the s1 array.

The strncpy()stpncpy() and functions copy not more than n bytes (bytes that follow a null byte are not copied) from the array pointed to by s2 to the array pointed to by s1. If the
array pointed to by s2 is a string that is shorter than n bytes, null bytes are appended to the copy in the array pointed to by s1, until n bytes in all are written. The stpcpy() function
returns s1. If s1 contains null bytes, stpncpy() returns a pointer to the first such null byte. Otherwise, it returns &s1[n].

The strlcpy() function copies at most dstsize−1 characters (dstsize being the size of the string buffer dst) from src to dst, truncating src
if necessary. The result is always null-terminated. The function returns strlen(src). Buffer overflow can be checked as follows:

if (strlcpy(dst, src, dstsize) >= dstsize)
return −1;

If copying takes place between objects that overlap, the behavior of these functions is undefined.

strcspn(), strspn()

The strcspn() function returns the length of the initial segment of string s1 that consists entirely of characters not from string s2. The strspn() function returns the length of the initial segment of string
s1 that consists entirely of characters from string s2.

strdup(), strndup(), strdupa(), strndupa()

The strdup() function returns a pointer to a new string that is a duplicate of the string pointed to by s. The returned pointer can be passed to free(). The space for the new string is obtained using malloc(3C). If the new string cannot be created, a null pointer is returned and errno may be set to ENOMEM to indicate that the storage space
available is insufficient.

The strndup() function is similar to strdup(), except that it copies at most size bytes. If the length of s is larger than size, only size bytes are copied and
a terminating null byte is added. If size is larger than the length of s, all bytes in s are copied, including the terminating null character.

The strdupa() and strndupa() functions are similar to strdup() and strndup(), respectively, but use alloca(3C) to allocate the buffer.

strlen(), strnlen()

The strlen() function returns the number of bytes in s, not including the terminating null character.

The strnlen() function returns the smaller of n or the number of bytes in s, not including the terminating null character. The strnlen() function never examines more than n bytes of
the string pointed to by s.

strpbrk()

The strpbrk() function returns a pointer to the first occurrence in string s1 of any character from string s2, or a null pointer if no character from s2 exists in s1.

strsep()

The strsep() function locates, in the null-terminated string referenced by *stringp, the first occurrence of any character in the string delim (or the terminating `\0' character) and replaces it with a `\0'. The
location of the next character after the delimiter character (or NULL, if the end of the string was reached) is stored in *stringp. The original value of *stringp is returned.

An ``empty'' field (one caused by two adjacent delimiter characters) can be detected by comparing the location referenced by the pointer returned by strsep() to `\0'.

If *stringp is initially NULL, strsep() returns NULL.

strstr(), strnstr(), strcasestr()

The strstr() function locates the first occurrence of the string s2 (excluding the terminating null character) in string s1 and returns a pointer to the located string, or a null pointer if the string is not found. If s2
points to a string with zero length (that is, the string ""), the function returns s1.

The strnstr() function locates the first occurrence of the null-terminated string s2 in the string s1, where not more than n characters are searched. Characters that appear after a `\0' character
are not searched.

The strcasestr() function is similar to strstr(), but ignores the case of both strings.

strtok()

A sequence of calls to strtok() breaks the string pointed to by s1 into a sequence of tokens, each of which is delimited by a byte from the string pointed to by s2. The first call in the sequence has s1 as
its first argument, and is followed by calls with a null pointer as their first argument. The separator string pointed to by s2 can be different from call to call.

The first call in the sequence searches the string pointed to by s1 for the first byte that is not contained in the current separator string pointed to by s2. If no such byte is found, then there are no tokens in the string pointed to by
s1 and strtok() returns a null pointer. If such a byte is found, it is the start of the first token.

The strtok() function then searches from there for a byte that 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 s1, and subsequent searches for a token return
a null pointer. If such a byte is found, it is overwritten by a null byte that terminates the current token. The strtok() function saves a pointer to the following byte in thread-specific data, from which the next search for a token starts.

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.

See Example 1, 2, and 3 in the EXAMPLES section for examples of strtok() usage and the explanation in NOTES.

strtok_r()

The strtok_r() function considers the null-terminated string s1 as a sequence of zero or more text tokens separated by spans of one or more characters from the separator string s2. The argument lasts points
to a user-provided pointer which points to stored information necessary for strtok_r() to continue scanning the same string.

In the first call to strtok_r(), s1 points to a null-terminated string, s2 to a null-terminated string of separator characters, and the value pointed to by lasts is ignored. The strtok_r() function
returns a pointer to the first character of the first token, writes a null character into s1 immediately following the returned token, and updates the pointer to which lasts points.

In subsequent calls, s1 is a null pointer and lasts is unchanged from the previous call so that subsequent calls move through the string s1, returning successive tokens until no tokens remain. The separator string s2
can be different from call to call. When no token remains in s1, a null pointer is returned.

See Example 3 in the EXAMPLES section for an example of strtok_r() usage and the explanation in NOTES.

Examples

Example 1 Search for word separators.

The following example searches for tokens separated by space characters.

See also

Notes

When compiling multithreaded applications, the _REENTRANT flag must be defined on the compile line. This flag should only be used in multithreaded applications.

A single-threaded application can gain access to strtok_r() only by defining __EXTENSIONS__ or by defining _POSIX_C_SOURCE to a value greater than or equal to 199506L.

All of these functions assume the default locale ``C.'' For some locales, strxfrm(3C) should be applied to the strings before they are passed to the functions.

The strtok() function is safe to use in multithreaded applications because it saves its internal state in a thread-specific data area. However, its use is discouraged, even for single-threaded applications. The strtok_r() function should be used instead.

Do not pass the address of a character string literal as the argument s1 to either strtok() or strtok_r(). Similarly, do not pass a pointer to the address of a character string literal as the argument stringp to
strsep(). These functions can modify the storage pointed to by s1 in the case of strtok() and strtok_r() or *stringp in the case of strsep(). The C99 standard specifies that attempting
to modify the storage occupied by a string literal results in undefined behavior. This allows compilers (including gcc and the Oracle Solaris Studio compilers) to place string literals in read-only memory. Note that in Example 1 above, this problem is avoided because the variable
line is declared as a writable array of type char that is initialized by a string literal rather than a pointer to char that points to a string literal.