302 lines
7.5 KiB
Plaintext
302 lines
7.5 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3c.string $W$ of 5/22/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} string 3C "C Development Set" "\&"
|
|
.if \nX=1 .ds x} string 3C "C Development Set"
|
|
.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 \f4strcasecmp\f1, \f4strncasecmp\f1, \f4index\f1, \f4rindex\f1, \f4strtok_r\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
|
|
\f4int strcasecmp (const char \(**s1, const char \(**s2);\f1
|
|
.PP
|
|
\f4int strncasecmp (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 \(**strtok_r (char \(**s1, const char \(**s2, char \(**\(**lasts);\f1
|
|
.PP
|
|
\f4char \(**strstr (const char \(**s1, const char \(**s2);\f1
|
|
.PP
|
|
\f4#include <strings.h>\f1
|
|
.PP
|
|
\f4char \(**index (const char \(**s, int c);\f1
|
|
.PP
|
|
\f4char \(**rindex (const char \(**s, int c);\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,
|
|
\f4strtok_r\fP,
|
|
and
|
|
\f4strtok\fP,
|
|
all alter
|
|
.IR s1 .
|
|
These functions do not check for overflow of
|
|
the array pointed to by
|
|
.IR s1 ,
|
|
or for overlap between
|
|
.I s1\^
|
|
and
|
|
.IR s2 .
|
|
If overflow of
|
|
.IR s1\^
|
|
occurs, or
|
|
copying takes place when
|
|
.I s1\^
|
|
and
|
|
.I s2\^
|
|
overlap, the
|
|
behavior is undefined.
|
|
.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.
|
|
\f4strcasecmp\fP
|
|
and
|
|
\f4strncasecmp\fP
|
|
are case-insensitive versions of \f4strcmp\fP and \f4strncmp\fP,
|
|
respectively.
|
|
Case-insensitive comparison is implemented by converting upper-case
|
|
ASCII characters to lower-case before comparison.
|
|
Thus \f4strcasecmp\fP and \f4strncasecmp\fP
|
|
only give meaningful results for the "C" locale (7 bit ASCII).
|
|
.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 (ie. if the length of
|
|
.IR n
|
|
is greater than the length of
|
|
.IR s2
|
|
).
|
|
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
|
|
\f4index\fP
|
|
.RB ( rindex )
|
|
are included as duplicates of
|
|
\f4strchr\fp
|
|
.RB ( strrchr )
|
|
for compatibility (see Notes).
|
|
.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.
|
|
Note that a string consisting entirely of non-separator characters
|
|
is considered a single token.
|
|
For example, if the initial call to \f4strtok\fP
|
|
is made with
|
|
.I s1
|
|
pointing to a string consisting entirely of non-separator characters,
|
|
then the return value from \f4strtok\fP
|
|
will be the value of
|
|
.I s1
|
|
passed to \f4strtok\fP.
|
|
.PP
|
|
\f4strtok_r\fP is a reentrant version of \f4strtok\fP.
|
|
The current location in the string is kept track of in \f2lasts\fP.
|
|
On the first call to \f4strtok_r\fP, \f2lasts\fP should be a pointer to a
|
|
.SM NULL
|
|
pointer. It is kept updated on each successive call to \f4strtok_r\fP
|
|
to point into \f2s1\fP directly after the null character.
|
|
\f2lasts\fP must not be changed between calls to \f4strtok_r\fP.
|
|
The feature test macro
|
|
.SM
|
|
\f4_SGI_REENTRANT_FUNCTIONS\fP
|
|
should be defined to make this function visible.
|
|
.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),
|
|
\f4memory\fP(3C),
|
|
\f4setlocale\fP(3C),
|
|
\f4strcoll\fP(3C),
|
|
\f4strerror\fP(3C),
|
|
\f4strxfrm\fP(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.
|
|
.PP
|
|
Declarations for \f4index\f1 and \f4rindex\f1 are specifically omitted
|
|
from \f4<string.h>\f1 due to possible naming conflicts. Instead, they are
|
|
declared in \f4<strings.h>\f1.
|
|
.PP
|
|
The
|
|
.BR index ,
|
|
.BR rindex ,
|
|
.BR strcasecmp ,
|
|
.BR strncasecmp
|
|
routines are from the 4.3BSD or 4.3BSD-tahoe standard C library.
|
|
.\" @(#)string.3c 6.4 of 10/20/83
|
|
.Ee
|