'\"macro stdmacro
.if n .pH g3c.string $W$ of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} string 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} string 3C "C Programming Language Utilities"
.if \nX=2 .ds x} string 3C "" "\&"
.if \nX=3 .ds x} string "" "" "\&"
.TH \*(x}
.SH NAME
\f4string\f2: \f4strcat\f1, \f4strdup\f1, \f4strncat\f1, \f4strcmp\f1, \f4strncmp\f1, \f4strcpy\f1, \f4strncpy\f1, \f4strlen\f1, \f4strchr\f1, \f4strrchr\f1, \f4strpbrk\f1, \f4strspn\f1, \f4strcspn\f1, \f4strtok\f1, \f4strstr\f1 \- string operations
.SH SYNOPSIS
.nf
\f4#include <string.h>\f1
.PP
\f4char \(**strcat (char \(**s1, const char \(**s2);\f1
.PP
\f4char \(**strdup (const char \(**s1);\f1
.PP
\f4char \(**strncat (char \(**s1, const char \(**s2, size_t n);\f1
.PP
\f4int strcmp (const char \(**s1, const char \(**s2);\f1
.PP
\f4int strncmp (const char \(**s1, const char \(**s2, size_t n);\f1
.PP
\f4char \(**strcpy (char \(**s1, const char \(**s2);\f1
.PP
\f4char \(**strncpy (char \(**s1, const char \(**s2, size_t n);\f1
.PP
\f4size_t strlen (const char \(**s);\f1
.PP
\f4char \(**strchr (const char \(**s, int c);\f1
.PP
\f4char \(**strrchr (const char \(**s, int c);\f1
.PP
\f4char \(**strpbrk (const char \(**s1, const char \(**s2);\f1
.PP
\f4size_t strspn (const char \(**s1, const char \(**s2);\f1
.PP
\f4size_t strcspn (const char \(**s1, const char \(**s2);\f1
.PP
\f4char \(**strtok (char \(**s1, const char \(**s2);\f1
.PP
\f4char \(**strstr (const char \(**s1, const char \(**s2);\f1
.SH DESCRIPTION
The arguments
.IR s ,
.IR s1 ,
and
.I s2\^
point to strings (arrays of characters terminated by a
null character).
The functions
\f4strcat\fP,
\f4strncat\fP,
\f4strcpy\fP,
\f4strncpy\fP,
and
\f4strtok\fP.
all alter
.IR s1 .
These functions do not check for overflow of
the array pointed to by
.IR s1 .
.PP
\f4strcat\fP
appends a copy of string
.I s2\^,
including the terminating null character,
to the end of string
.IR s1 .
\f4strncat\fP
appends at most
.I n\^
characters.
Each returns a pointer to the null-terminated result.
The initial character of \f2s2\f1 overrides the null character at the
end of \f2s1\f1.
.PP
\f4strcmp\fP
compares its arguments and returns an integer
less than, equal to, or greater than 0,
based upon whether
.I s1\^
is lexicographically less than, equal to, or
greater than
.IR s2 .
\f4strncmp\fP
makes the same comparison but looks at at most
.I n\^
characters.
Characters following a null character are not compared.
.PP
\f4strcpy\fP
copies string
.I s2\^
to
.IR s1 
including the terminating null character,
stopping after the null character has been copied.
\f4strncpy\fP
copies exactly
.I n\^
characters,
truncating
.I s2\^
or adding
null characters to 
.I s1\^
if necessary.
The result will not be null-terminated if the length
of
.I s2\^
is
.I n\^
or more.
Each function returns
.IR s1 .
.PP
\f4strdup\fP
returns a pointer to a new string which is a duplicate of the string
pointed to by 
.I s1.
The space for the new string is obtained using
\f4malloc\fP(3C)\^.
If the new string can not be created, a
.SM NULL
pointer is returned.
.PP
\f4strlen\fP
returns the number of characters in
.IR s ,
not including the terminating null character.
.PP
\f4strchr\fP
(or \f4strrchr\fP)
returns a pointer to the first (last)
occurrence of
.I c\^
(converted to a \f4char\fP)
in string
.IR s ,
or a
.SM NULL
pointer if
.I c\^
does not occur in the string.
The null character terminating a string is considered to
be part of the string.
.PP
\f4strpbrk\fP
returns a pointer to the first occurrence in string
.I s1\^
of any character from string
.IR s2 ,
or a
.SM NULL
pointer if no character from
.I s2\^
exists in
.IR s1 .
.PP
\f4strspn\fP
(or \f4strcspn\fP)
returns the length of the initial segment of string
.I s1\^
which consists entirely of characters from (not from) string
.IR s2 .
.PP
\f4strtok\fP
considers the string
.I s1\^
to consist of a sequence of zero or more text tokens separated
by spans of one or more characters from the separator string
.IR s2 .
The first call (with pointer
.I s1\^
specified) returns a pointer to the first character of the first
token, and will have written a
null character into
.I s1\^
immediately following the returned token. The function
keeps track of its position in the string
between separate calls, so that subsequent calls
(which must be made with the first 
argument a
.SM NULL
pointer) will work through the string
.I s1\^
immediately following that token.
In this way subsequent calls
will work through the string
.I s1\^
until no tokens remain.
The separator string
.I s2\^
may be different from call to call.
When no token remains in
.IR s1 ,
a
.SM NULL
pointer is returned.
.PP
\f4strstr\fP locates the first occurrence in string \f2s1\f1 of the sequence
of characters (excluding the terminating null character) in string \f2s2\f1.
\f4strstr\fP returns a pointer to the located string, or a null pointer
if the string is not found. If \f2s2\f1 points to a string with
zero length (i.e., the string ""), the function returns \f2s1\f1.
.SH "SEE ALSO"
\f4malloc\fP(3C), \f4setlocale\fP(3C), \f4strxfrm\f1(3C).
.SH NOTES
All of these functions assume the default locale ``C.''
For some locales, \f4strxfrm\f1 should be applied to the
strings before they are passed to the functions.
.\"	@(#)string.3c	6.4 of 10/20/83
.Ee
