STRING(3C) Standard C Library Functions STRING(3C)

NAME

string, strcasecmp, strcasecmp_l, strncasecmp, strncasecmp_l, strcat,
strncat, strlcat, strchr, strchrnul, strrchr, strcmp, strncmp,
stpcpy, stpncpy, strcpy, strncpy, strlcpy, strcspn, strspn, strdup,
strndup, strdupa, strndupa, strlen, strnlen, strpbrk, strsep, strstr,
strnstr, strcasestr, strtok, strtok_r - string operations

SYNOPSIS

#include <strings.h>

int strcasecmp(const char *s1, const char *s2);

int strcasecmp_l(const char *s1, const char *s2, locale_t loc);

int strncasecmp(const char *s1, const char *s2, size_t n);

int strncasecmp_l(const char *s1, const char *s2, size_t n, locale_t loc);

#include <string.h>

char *strcat(char *restrict s1, const char *restrict s2);

char *strncat(char *restrict s1, const char *restrict s2, size_t n);

size_t strlcat(char *dst, const char *src, size_t dstsize);

char *strchr(const char *s, int c);

char *strrchr(const char *s, int c);

int strcmp(const char *s1, const char *s2);

int strncmp(const char *s1, const char *s2, size_t n);

char *stpcpy(char *restrict s1, const char *restrict s2);

char *stpncpy(char *restrict s1, const char *restrict s2, size_t n);

char *strcpy(char *restrict s1, const char *restrict s2);

char *strncpy(char *restrict s1, const char *restrict s2, size_t n);

size_t strlcpy(char *dst, const char *src, size_t dstsize);

size_t strcspn(const char *s1, const char *s2);

size_t strspn(const char *s1, const char *s2);

char *strdup(const char *s1);

char *strndup(const char *s1, size_t n);

char *strdupa(const char *s1);

char *strndupa(const char *s1, size_t n);

size_t strlen(const char *s);

size_t strnlen(const char *s, size_t n);

char *strpbrk(const char *s1, const char *s2);

char *strsep(char **stringp, const char *delim);

char *strstr(const char *s1, const char *s2);

char *strnstr(const char *s1, const char *s2, size_t n);

char *strcasestr(const char *s1, const char *s2);

char *strcasestr_l(const char *s1, const char *s2, locale_t loc);

char *strtok(char *restrict s1, const char *restrict s2);

char *strtok_r(char *restrict s1, const char *restrict s2,
char **restrict lasts);

ISO C++
#include <string.h>

const char *strchr(const char *s, int c);

const char *strchrnul(const char *s, int c);

const char *strpbrk(const char *s1, const char *s2);

const char *strrchr(const char *s, int c);

const char *strstr(const char *s1, const char *s2);

#include <cstring>

char *std::strchr(char *s, int c);

char *std::strpbrk(char *s1, const char *s2);

char *std::strrchr(char *s, int c);

char *std::strstr(char *s1, const char *s2);

DESCRIPTION

The arguments s, s1, and s2 point to strings (arrays of characters
terminated by a null character). The strcat(), strncat(), strlcat(),
strcpy(), stpcpy(), stpncpy(), strncpy(), strlcpy(), strsep(),
strtok(), and strtok_r() functions all alter their first argument.
Additionally, the strcat(), stpcpy(), 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.

The strcasecmp() and strncasecmp() functions compare two strings
byte-by-byte, after converting each upper-case character to lower-
case (as determined by the LC_CTYPE category of the current locale).
Note that neither the contents pointed to by s1 nor s2 are modified.

The functions return 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

The strncasecmp() function examines at most n bytes from each string.

strcasecmp_l(), strncasecmp_l()
The strcasecmp_l() and strncasecmp_l() functions behave identically
to strcasecmp() and strncasecmp(), except instead of operating in the
current locale, they instead operate in the locale specified by loc.

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 of s2 to s1, not including any
terminating null character, and then appends a null character. 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 behaves
similarly to strchr(), except when the character c is not found, it
returns a pointer to the null terminator of the string s and not a
null pointer.

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(), strncpy(), strlcpy()
The strcpy() function copies string s2 to s1, including the
terminating null character, stopping after the null character has
been copied. The strncpy() function copies exactly n bytes,
truncating s2 or adding null characters to s1 if necessary. The
result will not be null-terminated if the length of s2 is n or more.
Both the strcpy() and strncpy() functions return s1. If copying takes
place between objects that overlap, the behavior of strcpy(),
strncpy(), and strlcpy() is undefined.

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;

stpcpy(), stpncpy()
The stpcpy() and stpncpy() functions behave identically to strcpy()
and strncpy() respectively; however, instead of returning a pointer
to the beginning of s1, they return a pointer to the terminating null
character.

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 s1. 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 identical
to strdup(), except it copies at most n bytes from s1 and ensures the
copied string is always null terminated.

The functions strdupa() and strndupa() behave identically to strdup()
and strndup() respectively; however, instead of allocating memory
using malloc(3C), they use alloca(3C). These functions are provided
for compatibility only, their use is strongly discouraged due to
their use of alloca(3C).

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(), strcasestr_l()
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 performs the
same search as strstr(), but only considers up to n bytes of s1.
Bytes following a null byte are not compared.


The strcasestr() and strcasestr_l() functions are similar to
strstr(), but both functions ignore the case of both s1 and s2. Where
as the strcasestr() function operates in the current locale, the
strcasestr_l() function operates in the locale specified by loc.

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.


#include <string.h>
...
char *token;
char line[] = "LINE TO BE SEPARATED";
char *search = " ";

/* Token will point to "LINE". */
token = strtok(line, search);

/* Token will point to "TO". */
token = strtok(NULL, search);

Example 2: Break a Line.

The following example uses strtok to break a line into two character
strings separated by any combination of SPACEs, TABs, or NEWLINEs.


#include <string.h>
...
struct element {
char *key;
char *data;
};
...
char line[LINE_MAX];
char *key, *data;
...
key = strtok(line, " \n");
data = strtok(NULL, " \n");

Example 3: Search for tokens.

The following example uses both strtok() and strtok_r() to search for
tokens separated by one or more characters from the string pointed to
by the second argument, "/".


#define __EXTENSIONS__
#include <stdio.h>
#include <string.h>

int
main() {
char *buf="5/90/45";
char *token;
char *lasts;

printf("tokenizing \"%s\" with strtok():\n", buf);
if ((token = strtok(buf, "/")) != NULL) {
printf("token = "%s\"\n", token);
while ((token = strtok(NULL, "/")) != NULL) {
printf("token = \"%s\"\n", token);
}
}

buf = "//5//90//45//";
printf("\ntokenizing \"%s\" with strtok_r():\n", buf);
if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
printf("token = \"%s\"\n", token);
while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
printf("token = \"%s\"\n", token);
}
}
}


When compiled and run, this example produces the following output:


tokenizing "5/90/45" with strtok():
token = "5"
token = "90"
token = "45"

tokenizing "//5//90//45//" with strtok_r():
token = "5"
token = "90"
token = "45"

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:

+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | See below. |
+--------------------+-----------------+
|MT-Level | See below. |
+--------------------+-----------------+
|Standard | See below. |
+--------------------+-----------------+

The strlcat(), strlcpy(), and strsep() functions are Committed. All
the rest are Standard.

The strtok(), strdup(), and strndup() functions are MT-Safe. The
remaining functions are Async-Signal-Safe.

For all except strlcat(), strlcpy(), and strsep(), see standards(7).

SEE ALSO

malloc(3C), newlocale(3C), setlocale(3C), strxfrm(3C), uselocale(3C),
attributes(7), standards(7)

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.

Except where noted otherwise, 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 Sun Studio compilers
when the -xstrconst flag is used) 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.

March 23, 2016 STRING(3C)