string(3C)string(3C)NAME
string: strcasecmp(), strcat(), strchr(), strcmp(), strcoll(), str‐
cpy(), strcspn(), strdup(), strlen(), strncasecmp(), strncat(),
strncmp(), strncpy(), strpbrk(), strrchr(), strrstr(), strspn(),
strstr(), strtok(), strtok_r(), strxfrm(), index(), rindex() - charac‐
ter string operations
SYNOPSIS
Remarks
All functions except and are declared in both headers, so only one of
the two headers needs to be included.
The functions and are declared only in They are provided solely for
portability of BSD applications, and are not recommended for new appli‐
cations where portability is important. For portable applications, use
and instead.
DESCRIPTION
Arguments s1, s2, and s point to strings (arrays of characters termi‐
nated by a null byte).
Definitions for all these functions, the type and the constant are pro‐
vided in the header.
Appends a copy of string
s2 to the end of string s1. appends a maximum of n
characters. It copies fewer if s2 is shorter than n
characters. Each returns a pointer to the null-termi‐
nated result (the value of s1).
Compares its arguments and returns an integer less than,
equal to, or greater than zero, depending on whether s1
is lexicographically less than, equal to, or greater
than s2. The comparison of corresponding characters is
done as if the type of the characters were Null pointer
values for s1 and s2 are treated the same as pointers to
empty strings. makes the same comparison but examines a
maximum of n characters (n less than or equal to zero
yields equality). and are identical in function to and
respectively, but characters are folded by (see
conv(3C)) prior to comparison. The returned lexico‐
graphic difference reflects the folding to lowercase.
Copies string s2 to s1, stopping after the null byte has been copied.
copies exactly n characters, truncating s2 or adding
null bytes to s1 if necessary, until a total of n have
been written. The result is not null-terminated if the
length of s2 is n or more. Each function returns s1.
Note that should not be used to copy n bytes of an arbi‐
trary structure. If that structure contains a null byte
anywhere, copies fewer than n bytes from the source to
the destination and fills the remainder with null bytes.
Use the function (see memory(3C)) to copy arbitrary
binary data.
Returns a pointer to a new string which is a
duplicate of the string to which s1 points. The space
for the new string is obtained using the function (see
malloc(3C)).
Returns the number of characters in
s, not including the terminating null byte.
Returns a pointer to the first (last) occurrence of character
c in string s, or a null pointer if c does not occur in
the string. The null byte terminating a string is con‐
sidered to be part of the string. is identical to and
is provided solely for portability of BSD applications.
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.
Returns the length of the maximum initial segment of string
s1, which consists entirely of characters from (not
from) string s2.
Returns a pointer to the first (last) occurrence of string
s2 in string s1, or a NULL pointer if s2 does not occur
in the string. If s2 points to a string of zero length,
returns s1.
Considers the string
s1 to consist of a sequence of zero or more text tokens
separated by spans of one or more characters from the
separator string s2. The first call (with a nonnull
pointer s1 specified) returns a pointer to the first
character of the first token, and writes a null byte
into s1 immediately following the returned token. The
function keeps track of its position in the string s1
between separate calls, so that subsequent calls made
with the first argument a null pointer work through the
string immediately following that token. In this way
subsequent calls work through the string s1 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.
is identical to
except that it expects to be passed the address of a
character string pointer as the third argument. It will
use this argument to keep track of the current position
in the string being searched. It returns a pointer to
the current token in the string or a NULL value if there
are no more tokens.
Returns an integer greater than, equal to, or less than zero,
according to whether the string pointed to by s1 is
greater than, equal to, or less than the string pointed
to by s2. The comparison is based on strings inter‐
preted as appropriate to the program's locale (see
Locale below). In the ``C'' locale works like
Transforms the string pointed to by
s2 and places the resulting string into the array
pointed to by s1. The transformation is such that if
the function is applied to two transformed strings, it
returns a value greater than, equal to, or less than
zero, corresponding to the result of the function
applied to the same two original strings. No more than
n bytes are placed into the resulting string, including
the terminating null character. If the transformed
string fits in no more than n bytes, the length of the
resulting string is returned (not including the termi‐
nating null character). Otherwise the return value is
the number of bytes that the s1 string would occupy (not
including the terminating null character), and the con‐
tents of the array are indeterminate.
has better performance with respect to in cases where a given string is
compared to other strings only a few times, or where the strings to be
compared are long but a difference in the strings that determines their
relative ordering usually comes among the first few characters. offers
better performance in, for example, a sorting routine where a number of
strings are each transformed just once and the transformed versions are
compared against each other many times.
EXTERNAL INFLUENCES
Locale
The category determines the interpretation of the bytes within the
string arguments to the and functions as single and/or multibyte char‐
acters. It also determines the case conversions to be done for the and
functions.
The category determines the collation ordering used by the and func‐
tions.
International Code Set Support
Single- and multibyte character code sets are supported for the and
functions. Only single-byte character code sets are supported for the
and functions.
EXAMPLES
The following sample piece of code finds the tokens, separated by
blanks, that are in the string s (assuming that there are at most
tokens):
int i = 0;
char *s, *last, *tok[MAXTOK];
tok[0] = strtok_r(s, " ", &last);
while (tok[++i] = strtok_r(NULL, " ", &last));
WARNINGS
The functions and alter the contents of the array to which s1 points.
They do not check for overflow of the array.
Null pointers for destination strings cause undefined behavior.
Character movement is performed differently in different implementa‐
tions, so moves involving overlapping source and destination strings
may yield surprises.
The transformed string produced by for a language using an 8-bit code
set is usually at least twice as large as the original string and may
be as much four times as large (ordinary characters occupy two bytes
each in the transformed string, 1-to-2 characters four bytes, 2-to-1
characters two bytes per original pair, and don't-care characters no
bytes). Each character of a multibyte code set (Asian languages) occu‐
pies three bytes in the transformed string.
For functions and results are undefined if the languages specified by
the and categories use different code sets.
Users of should also note that the prototype of this function will
change in the next release for conformance with the new POSIX Threads
standard.
AUTHOR
was developed by the University of California, Berkeley, AT&T, OSF, and
HP.
SEE ALSOconv(3C), malloc(3C), memory(3C), setlocale(3C), thread_safety(5),
glossary(9).
STANDARDS CONFORMANCEstring(3C)
