string(3C) string(3C)
NAME
string: strcat, strdup, strncat, strcmp, strncmp, strcpy, strncpy,
strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok, strstr -
manipulate strings
SYNOPSIS
#include <string.h>
char *strcat(char *s1, const char *s2);
char *strdup(const char *s1);
char *strncat(char *s1, const char *s2, sizet n);
int strcmp(const char *s1, const char *s2);
int strncmp(const char *s1, const char *s2, sizet n);
char *strcpy(char *s1, const char *s2);
char *strncpy(char *s1, const char *s2, sizet n);
sizet strlen(const char *s);
char *strchr(const char *s, int c);
char *strrchr(const char *s, int c);
char *strpbrk(const char *s1, const char *s2);
sizet strspn(const char *s1, const char *s2);
sizet strcspn(const char *s1, const char *s2);
char *strtok(char *s1, const char *s2);
char *strstr(const char *s1, const char *s2);
DESCRIPTION
The arguments s, s1, and s2 point to strings. The functions strcat(),
strncat(), strcpy(), strncpy(), and strtok() all alter s1. These func-
tions do not check for overflow of the array pointed to by s1.
strcat() appends a copy of string s2, including the terminating null
byte, to the end of string s1. strncat() appends at most n bytes. Each
returns a pointer to the result (including terminating null byte). The
initial byte of s2 overwrites the null byte at the end of s1.
Page 1 Reliant UNIX 5.44 Printed 11/98
string(3C) string(3C)
strcmp() compares its arguments and returns an integer less than,
equal to, or greater than 0, based upon whether s1 is lexicographi-
cally less than, equal to, or greater than s2. strncmp() makes the
same comparison but looks at, at most, n bytes. Bytes following a null
byte are not compared.
strcpy() copies string s2 to s1 including the terminating null byte,
stopping after the null byte has been copied. strncpy() copies exactly
n bytes, truncating s2 or adding null bytes to s1 if necessary. The
result will not be terminated with a null byte if the length of s2 is
n or more. Each function returns s1.
strdup() returns a pointer to a new string which is a duplicate of the
string pointed to by s1. The space for the new string is allocated
using malloc(3C). If the new string can not be created, a null pointer
is returned.
strlen() computes the number of bytes in the string to which s points,
not including the terminating null byte.
strchr() (or strrchr()) returns a pointer to the first (last) occur-
rence of c (converted to a char) in string s, or a null pointer if c
does not occur in the string. The null byte terminating a string is
considered to be part of the string.
strpbrk() returns a pointer to the first occurrence in string s1 of
any byte from string s2, or a null pointer if no byte from s2 exists
in s1.
strspn() returns the length of s1; no return value is reserved to
indicate an error.
strcspn() computes the length of the maximum initial segment of the
string pointed to by s1 which consists entirely of the bytes not from
the string pointed to by s2.
strtok() considers the string s1 to consist of a sequence of zero or
more text tokens separated by spans of one or more bytes from the
separator string s2. The first call, with pointer s1 specified,
returns a pointer to the first byte of the first token, and will have
written a null byte into s1 immediately following the returned token.
The function keeps track of its position in the string between sepa-
rate calls [a character string must therefore be processed completely
before strtok() can be called with a new character string], so that
subsequent calls (which must be made with the first argument a null
pointer) will work through the string s1 immediately following that
token. In this way subsequent calls will work through the string s1
until no tokens remain. The separator string s2 may be different from
call to call. When no token remains in s1, a null pointer is returned.
Page 2 Reliant UNIX 5.44 Printed 11/98
string(3C) string(3C)
strstr() locates the first occurrence in string s1 of the sequence of
characters (excluding the terminating null byte) in string s2.
strstr() 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
(i.e., the empty string), the function returns s1.
ERRORS
The strdup() function may fail if:
ENOMEM Storage space available is insufficient.
RETURN VALUES
The strcat() function returns s1; no return value is reserved to indi-
cate an error.
The strdup() function returns a pointer to a new string on success.
Otherwise it returns a null pointer and sets errno to indicate the
error.
The strncat() function returns s1; no return value is reserved to
indicate an error.
Upon completion, strcmp() 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.
Upon successful completion, strncmp() returns an integer greater than,
equal to or less than 0, if the possibly null-terminated array pointed
to by s1 is greater than, equal to or less than the possibly null-ter-
minated array pointed to by s2 respectively.
The strcpy() function returns s1; no return value is reserved to indi-
cate an error.
The strncpy() function returns s1; no return value is reserved to
indicate an error.
The strlen() function returns the length of s; no return value is
reserved to indicate an error.
Upon completion, strchr() returns a pointer to the byte, or a null
pointer if the byte was not found.
Upon successful completion, strrchr() returns a pointer to the byte or
a null pointer if c does not occur in the string.
Upon successful completion, strpbrk() returns a pointer to the byte or
a null pointer if no byte from s2 occurs in s1.
The strspn() function returns the length of s1; no return value is
reserved to indicate an error.
Page 3 Reliant UNIX 5.44 Printed 11/98
string(3C) string(3C)
The strcspn() function returns the length of s1; no return value is
reserved to indicate an error.
Upon successful completion, strtok() returns a pointer to the first
byte of a token. Otherwise, if there is no token, strtok() returns a
null pointer.
Upon successful completion, strstr() returns a pointer to the located
string or a null pointer if the string is not found.
NOTES
All of these functions assume the C locale by default. For some
locales, strxfrm() should be applied to the strings before they are
passed to the functions.
SEE ALSO
malloc(3C), setlocale(3C), strxfrm(3C), string(5).
Page 4 Reliant UNIX 5.44 Printed 11/98