STRING(3C)

NAME

strcat, strncat, strcmp, strncmp, strcpy, strncpy, strdup, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strstr, strtok, strcoll, strxfrm, nl_strcmp, nl_strncmp − character string operations

SYNOPSIS

#include <string.h>

char ∗strcat (s1, s2)
char ∗s1;
const char ∗s2;

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;

char ∗strcpy (s1, s2)
char ∗s1;
const char ∗s2;

char ∗strncpy (s1, s2, n)
char ∗s1;
const char ∗s2;
size_t n;

char ∗strdup (s)
const char ∗s;

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 ∗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 ∗strstr (s1, s2)
const char ∗s1, ∗s2;

char ∗strtok (s1, s2)
char ∗s1;
const char ∗s2;

int strcoll (s1, s2)
const char ∗s1, ∗s2;

size_t strxfrm (s1, s2, n)
char ∗s1;
const char ∗s2;
size_t n;

int nl_strcmp (s1, s2)
const char ∗s1, ∗s2;

int nl_strncmp (s1, s2, n)
const char ∗s1, ∗s2;
size_t n;

DESCRIPTION

The 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).

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 n characters in all have been written. The result will not be null-terminated if the length of s2 is n or more. Each function returns s1. Note that strncpy should not be used to copy n bytes of an arbitrary structure. If that structure contains a null byte anywhere, strncpy will copy fewer than n bytes from the source to the destination, and fill the remainder with null bytes. Use the memcpy function (described on 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(3C) or malloc(3X) function (depending on which is linked with the program).

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.

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 returns a pointer to the first 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 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 will have written 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 argument a null pointer will work through the string 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.

Strcoll returns an integer greater than, equal to, or less than zero, according as 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.

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. 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 will usually be 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) will occupy three bytes in the transformed string.

For the strcoll, strxfrm, nl_strcmp and nl_strncmp functions, the 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 and HP.

STANDARDS CONFORMANCE

nl_strcmp: XPG2

nl_strncmp: XPG2

strcat: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strchr: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strcmp: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strcoll: XPG3, ANSI C

strcpy: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strcspn: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strdup: SVID2

strlen: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strncat: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strncmp: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strncpy: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strpbrk: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strrchr: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strspn: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strstr: XPG3, POSIX.1, FIPS 151-1, ANSI C

strtok: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

strxfrm: XPG3, ANSI C

Hewlett-Packard Company — HP-UX Release 7.0: Sept 1989

Museum

Related Articles