HPUX strcoll[3c]
string(3C) string(3C)
NAME
strcat(), strncat(), strcmp(), strncmp(), strcasecmp(), strncasecmp(),
strcpy(), strncpy(), strdup(), strlen(), strchr(), strrchr(),
strpbrk(), strspn(), strcspn(), strstr(), strrstr(), strtok(),
strcoll(), strxfrm(), nl_strcmp(), nl_strncmp(), index(), rindex() -
character string operations
SYNOPSIS
#include <string.h>
#include <strings.h>
char *strcat(char *s1, const char *s2);
char *strncat(char *s1, const char *s2, size_t n);
int strcmp(const char *s1, const char *s2);
int strncmp(const char *s1, const char *s2, size_t n);
int strcasecmp(const char *s1, const char *s2);
int strncasecmp(const char *s1, const char *s2, size_t n);
char *strcpy(char *s1, const char *s2);
char *strncpy(char *s1, const char *s2, size_t n);
char *strdup(const char *s);
size_t 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);
size_t strspn(const char *s1, const char *s2);
size_t strcspn(const char *s1, const char *s2);
char *strstr(const char *s1, const char *s2);
char *strrstr(const char *s1, const char *s2);
char *strtok(char *s1, const char *s2);
int strcoll(const char *s1, const char *s2);
size_t strxfrm(char *s1, const char *s2, size_t n);
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
string(3C) string(3C)
int nl_strcmp(const char *s1, const char *s2);
int nl_strncmp(const char *s1, const char *s2, size_t n);
char *index(const char *s, int c);
char *rindex(const char *s, int c);
Remarks:
All functions except index() and rindex() are declared in both headers,
so only one of the two headers needs to be included.
The functions index() and rindex() are declared only in <strings.h>,
They and <strings.h> are provided solely for portability of BSD
applications, and are not recommended for new applications where
portability is important. For portable applications, use <string.h>,
strchr(), and strrchr() instead.
index() and rindex() and <strings.h> are provided solely for
portability of BSD applications, and are not recommended for new
applications where portability is important. For portable
applications, use strchr() and strrchr() instead.
DESCRIPTION
Arguments s1, s2, and s point to strings (arrays of characters
terminated by a null byte).
Definitions for all these functions, the type size_t, and the constant
NULL are provided in the <string.h> header.
strcat() Appends a copy of string s2 to the end of string s1.
strncat() appends a maximum of n characters. It copies
fewer if s2 is shorter than n characters. Each returns
a pointer to the null-terminated result (the value of
s1).
strcmp() 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 unsigned char. Null pointer values for s1 and s2
are treated the same as pointers to empty strings.
strncmp() makes the same comparison but examines a
maximum of n characters (n less than or equal to zero
yields equality). strcasecmp() and strncasecmp() are
identical in function to strcmp() and strncmp()
respectively, but characters are folded by _tolower()
(see conv(3C)) prior to comparison. The returned
lexicographic difference reflects the folding to
lowercase.
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
string(3C) string(3C)
strcpy() Copies string s2 to s1, stopping after the null byte
has been copied. strncpy() 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 arbitrary structure.
If that structure contains a null byte anywhere,
strncpy() copies fewer than n bytes from the source to
the destination and fills the remainder with null
bytes. Use the memcpy() function (see memory(3C)) to
copy arbitrary binary data.
strdup() 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 malloc() function (see
malloc(3C)).
strlen() Returns the number of characters in s, not including
the terminating null byte.
strchr() (strrchr()) 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 considered to be part of
the string. index() (rindex()) is identical to
strchr() (strrchr()), and is provided solely for
portability of BSD applications.
strpbrk() 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.
strspn() (strcspn()) Returns the length of the maximum initial
segment of string s1, which consists entirely of
characters from (not from) string s2.
strstr() (strrstr()) 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, strstr() (strrstr()) returns s1.
strtok() 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 non-null 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
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
string(3C) string(3C)
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.
strcoll() 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
interpreted as appropriate to the program's locale (see
Locale below). In the ``C'' locale strcoll() works
like strcmp(). nl_strcmp() is provided for historical
reasons only and is equivalent to strcoll().
nl_strncmp(), also provided only for historical
reasons, makes the same comparisons as strcoll(), but
looks at a maximum of n characters (n less than or
equal to zero yields equality).
strxfrm() 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 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 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
terminating 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 contents of the array are indeterminate.
strcoll() has better performance with respect to strxfrm() 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. strxfrm() 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 LC_CTYPE category determines the interpretation of the bytes
within the string arguments to the strcoll(), strxfrm(), nl_strcmp(),
and nl_strncmp() functions as single and/or multi-byte characters. It
also determines the case conversions to be done for the strcasecmp()
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
string(3C) string(3C)
and strncasecmp() functions.
The LC_COLLATE category determines the collation ordering used by the
strcoll(), strxfrm(), nl_strcmp(), and nl_strncmp() functions. See
hpnls(5) for a description of supported collation features. Use
nlsinfo (see nlsinfo(1)) to view the collation used for a particular
locale.
International Code Set Support
Single- and multi-byte character code sets are supported for the
strcoll(), strxfrm(), nl_strcmp(), and nl_strncmp() functions. All
other functions support only single-byte character code sets.
WARNINGS
The functions strcat(), strncat(), strcpy(), strncpy(), and strtok()
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
implementations, so moves involving overlapping source and destination
strings may yield surprises.
The transformed string produced by strxfrm() 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 multi-byte code set
(Asian languages) occupies three bytes in the transformed string.
For functions strcoll(), strxfrm(), nl_strcmp(), and nl_strncmp(),
results are undefined if the languages specified by the LC_COLLATE and
LC_CTYPE categories use different code sets.
AUTHOR
string was developed by AT&T, HP, and the University of California,
Berkeley.
SEE ALSO
nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C),
setlocale(3C), hpnls(5).
STANDARDS CONFORMANCE
nl_strcmp(): XPG2
nl_strncmp(): XPG2
strcat(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strchr(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
string(3C) string(3C)
strcmp(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strcoll(): AES, XPG3, XPG4, ANSI C
strcpy(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strcspn(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strdup(): SVID2
strlen(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strncat(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strncmp(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strncpy(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strpbrk(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strrchr(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strspn(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strstr(): AES, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strtok(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strxfrm(): AES, XPG3, XPG4, ANSI C
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992