STRING(3C) SysV STRING(3C)
NAME
string: strcat, strdup, strncat, strcmp, strncmp, strxfrm, strcoll,
strcpy, strncpy, strlen, strchr, strrchr, strstr, strpbrk, strspn,
strcspn, strtok, strtok_r - string operations
SYNOPSIS
#include <string.h>
char *strcat (s1, s2)
char *s1;
const char *s2;
char *strdup (s1)
char *s1;
char *strncat (s1, s2, n)
char *s1;
const char *s2;
size_t n;
int strcmp (s1, s2)
const char *s1, *s2;
int strncmp (s1, s2, n)
const char *s1, *s2;
size_t n;
size_t strxfrm(s1, s2, n)
char *s1;
const char*s2;
size_t n;
int strcoll(s1, s2)
const char *s1, *s2;
char *strcpy (s1, s2)
char *s1;
const char *s2;
char *strncpy (s1, s2, n)
char *s1;
const char *s2;
size_t n;
size_t strlen (s)
const char *s;
char *strchr (s, c)
const char *s;
int c;
char *strrchr (s, c)
const char *s;
int c;
char *strstr(s1, s2)
const char *s1, *s2;
char *strpbrk (s1, s2)
const char *s1, *s2;
size_t strspn (s1, s2)
const char *s1, *s2;
size_t strcspn (s1, s2)
const char *s1, *s2;
char *strtok (s1, s2)
char *s1;
const char *s2;
char *strtok_r (s1, s2, last_string)
char *s1;
const char *s2;
char **last_string;
DESCRIPTION
The arguments s1, s2 and s point to strings (arrays of characters
terminated by a null character). The functions strcat, strncat, strcpy,
and strncpy all alter s1. These functions do not check for overflow of
the array pointed to by s1.
The strcat function appends a copy of the string pointed to by the s2
parameter, including the terminating null character, to the end of the
string pointed to by the s1 parameter. The beginning character of the
string pointed to by the s2 parameter overwrites the null character at
the end of the string pointed to by the s1 parameter. When operating on
overlapping strings, the behavior of this function is unreliable.
The strchr function locates the first occurrence of the integer specified
by the c parameter, which is converted to a char, in the string pointed
to by the s parameter. The terminating null character is treated as part
of the string pointed to by the s parameter.
The strcmp function compares the string pointed to by the s1 parameter to
the string pointed to by the s2 parameter.
The sign of a nonzero value returned by strcmp is determined by the sign
of the difference between the values of the first pair of bytes (both
interpreted as unsigned char) that differ in the two compared objects.
The strcoll function compares the string pointed to by the s1 parameter
with the string pointed to by the s2 parameter, both interpreted as
appropriate to the LC_COLLATE category of the current locale. The sign
of a nonzero value returned by strcoll is determined by the relative
ordering within the current collating sequence of the first pair of
characters that differ in the objects under comparison.
The strcpy function copies the string pointed to by the s2 parameter,
including the terminating null character, to the location pointed to by
the s1 parameter. When operating on overlapping strings, the behavior of
this function is unreliable.
The strdup function returns a pointer to a new string that is an exact
duplicate of the string pointed to by the s1 parameter. The malloc
function is used to allocate space for the new string.
The strlen function returns the number of bytes in the string pointed to
by the s parameter. The string length value does not include the string
terminating null character.
The strcmp function compares the string pointed to by the s1 parameter
with the string pointed to by the s2 parameter. The sign of any nonzero
value returned by strcmp is determined by the sign resulting from the
difference in integer values of the first character-pair comparison (both
converted to unsigned char) in which the characters are different.
The strncat function appends n bytes in the string pointed to by the s2
parameter to the end of the string pointed to by the s1 parameter. The
initial character of the string pointed to by s2 overwrites the null
character at the end of the string pointed to by s1. The number of
characters specified by the n parameter and a terminating null character
are always appended to the string pointed to by the s1 parameter. When
operating on overlapping strings, the behavior of this function is
unreliable.
The strncpy function copies no more than the number of characters
specified by the n parameter from the location pointed to by the s2
parameter to the location pointed to by the s1 parameter. Characters
following a null character are not copied. When operating on overlapping
strings, the behavior of this function is unreliable. When the location
pointed to by the s2 parameter is a string whose character length is less
than the value specified by the n parameter, null characters are appended
to the s1 string until n characters are contained in the string.
The strpbrk function scans the string pointed to by the s1 parameter for
the first occurrence of any character in the string pointed to by the s2
parameter.
The strrchr function locates the last occurrence of the integer specified
by the c parameter, which is converted to a char value, in the string
pointed to by the s parameter. The terminating null character is treated
as a part of the string pointed to by the s parameter.
The strspn function computes the length of the maximum initial segment of
the string pointed to by the s1 parameter, which consists entirely of
characters from the string pointed to by the s2 parameter.
The strcspn function computes the byte length of the maximum initial
segment of the string pointed to by the s1 parameter, which consists
entirely of characters that are not from the string pointed to by the s2
parameter.
The strstr function locates the first occurrence in the string pointed to
by the s1 parameter of the sequence of bytes in the string pointed to by
the s2 parameter, excluding the terminating null character.
The strtok function expects that the string pointed to by the s1
parameter consists of multiple tokens separated by one or more characters
that match those in a separator string pointed to by the s2 parameter. A
sequence of calls to the strtok function breaks the s1 string into a
sequence of expected tokens, each of which is delimited by one or more
characters from the s2 string.
The initial call to function strtok in the token-sequence search
specifies the s1 parameter as the address of the token string. This call
is followed by subsequent calls that have a null pointer as the value of
the s1 parameter. The separator string pointed to by the s2 parameter may
be different in every call to this function.
The first call in the token-sequence search tests every character in the
s1 string for any character that is not contained in the current
separator string pointed to by the s2 parameter. When no matching
character is found, there are no tokens in that string and a null pointer
is returned. When a nonseparator character is found, it becomes the
starting character of the next token.
The strtok function then searches for a character that matches any
character in the current separator string pointed to by the s2 parameter.
When no matching character is found, the current token extends to the end
of the string pointed to by the s1 parameter and subsequent searches for
a token return a null pointer. When a matching separator-string
character is found, it is overwritten by the null character, which
terminates the current token. The strtok function saves a pointer to the
next character, which is the character from which the next search for a
token starts.
Each subsequent call having a null pointer as the value of the the s1
parameter begins a search at the character pointed to by the saved
pointer and behaves as described above.
The strtok_r function is the reentrant version of strtok. Upon
successful completion, the first character of the next token is stored in
**last_string, and a value of 0 (zero) is returned.
The strxfrm function transforms the string pointed to by the s2 parameter
and places the result in the address specified by s1. The transformation
is such that if the strcmp 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 strcoll function applied to the same
two original strings. No more than n bytes are placed into the resulting
array pointed to by s1, including the terminating mull character. If n is
zero, s1 is permitted to be a null pointer. If copying takes place
between objects that overlap, the behavior is undefined.
EXAMPLES
The following expression evaluates to the size of the array needed to
hold the transformation of the string pointed to by s:
1 + strxfrm(NULL, s, 0)
The following extracts tokens from a string using successive calls to
strtok.
#include <string.h>
static char str[] = "?a???b,,,#c";
char *t;
t = strtok(str, "?"); /* t points to the token "a" */
t = strtok(NULL, ","); /* t points to the token "??b" */
t = strtok(NULL, "#,"); /* t points to the token "c" */
t = strtok(NULL, "?"); /* t is a null pointer */
DIAGNOSTICS
Upon successful completion, the strcat, strcpy, strncat, and strncpy
functions return a pointer to the resulting string. Otherwise these
functions return a null pointer, and sets errno to indicate the error.
Upon successful completion, the strchr and strrchr functions return a
pointer to the matching character in the scanned string. When the
character specified by parameter c is not found, a null pointer is
returned errno is set to indicate the error.
Upon successful completion, the strcmp, strcoll, and strncmp functions
return an integer whose value is greater than, equal to, or less than 0
(zero), according to whether the s1 string is greater than, equal to, or
less than the s2 string. When a successful comparison can not be made,
these functions return 0 (zero), and set errno to indicate the error.
Upon successful completion, the strcspn, strnspn, and strxfrm functions
return the length of the string segment. Otherwise, (size_t)-1 is
returned and errno is set to indicate the error.
Upon successful completion, the strlen function returns the number of
characters in the string to which the s parameter points.
Otherwise, (size_t)-1 is returned and errno is set to indicate the
error.
Upon successful completion, the strpbrk function returns a pointer to the
matched character. When no character in the string pointed to by the s2
parameter occurs in the string pointed to by the s1 parameter, a null
pointer is returned and errno is set to indicate the error.
Upon successful completion, the strstr function returns a pointer to the
located string. When the s2 parameter points to a string having 0 (zero)
length, the strstr function returns the string pointed to by parameter
s1. On error, a null pointer is returned and errno is set to indicate
the error.
Upon successful completion, the strtok function returns a pointer to the
first character of the parsed token in the string. When there is no token
in the string, a null pointer is returned, and errno is set to indicate
the error.
SEE ALSO
intro(3), malloc(3C), malloc(3X), setlocale (3C).
NOTES
You may obtain in-line versions of strcpy, strncpy, strncat, strcat,
strcmp, strncmp, and strlen by adding the directive
#define _STRING_BUILTINS
or the directive
#define _BUILTINS
before any #include directives in your program. If you use the
#define _BUILTINS
directive, _MATH_BUILTINS gets defined, too. See intro(3).
Parts of this discussion are adapted from ANSI X3.159-1989.
CAVEATS
strcmp and strncmp are implemented by using the most natural character
comparison on the machine. Thus the sign of the value returned when one
of the characters has its high-order bit set not the same in all
implementations and should not be relied upon.
Character movement is performed differently in different implementations.
Thus overlapping moves may yield surprises.