string(3C) string(3C) - HP

string(3C) 


NAME 

string: strcasecmp(), strcat(), strchr(), strcmp(), strcoll(), strcpy(), strcspn(), strdup(), strlen(), 

strncasecmp(), strncat(), strncmp(), strncpy(), strpbrk(), strrchr(), strrstr(), strspn(), strstr(), strtok(), 

strtok_r(), strxfrm(), index(), rindex() - character string operations 

SYNOPSIS 

#include 

#include 

char *strcat(char *__restrict s1, const char *__restrict s2); 

char *strncat(char *__restrict s1, const char *__restrict 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 *__restrict s1, const char *__restrict s2); 

char *strncpy(char *__restrict s1, const char *__restrict 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 *__restrict s1, const char *__restrict s2); 

char *strtok_r(char *s1, const char *s2, char **last); 

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

size_t strxfrm(char *__restrict s1, const char *__restrict s2, size_t n); 

char *index(const char *s, int c); 

char *rindex(const char *s, int c); 

s 

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 . They 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 

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 

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1



s 

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. 

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 strncpy() 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, ora 

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 nonnull 

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

strtok_r() is identical to strtok(), except that it expects to be passed the address of a character 

string pointer as the third argument. It will use this argument to keep track of the 

current position in the string being searched. It returns a pointer to the current token in 

the string or a NULL value if there are no more tokens. 

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

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 

2 Hewlett-Packard Company − 2 − HP-UX 11i Version 3: September 2010



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() and strxfrm() functions as single and/or multibyte characters. It also determines the 

case conversions to be done for the strcasecmp() and strncasecmp() functions. 

The LC_COLLATE category determines the collation ordering used by the strcoll() and strxfrm() 

functions. 

International Code Set Support 

Single- and multibyte character code sets are supported for the strcoll() and strxfrm() functions. 

Only single-byte character code sets are supported for the strcasecmp() and strncasecmp() functions. 

EXAMPLES 

The following sample piece of code finds the tokens, separated by blanks, that are in the string s (assuming 

that there are at most MAXTOK tokens): 

int i = 0; 

char *s, *last, *tok[MAXTOK]; 

tok[0] = strtok_r(s, " ", &last); 

while (tok[++i] = strtok_r(NULL, " ", &last)); 

WARNINGS 

The functions strcat(), strncat(), strcpy(), strncpy(), strtok(), and strtok_r() 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 multibyte code set (Asian 

languages) occupies three bytes in the transformed string. 

For functions strcoll() and strxfrm() results are undefined if the languages specified by the 

LC_COLLATE and LC_CTYPE categories use different code sets. 

Users of strtok_r() should also note that the prototype of this function will change in the next release 

for conformance with the new POSIX Threads standard. 

s 

AUTHOR 

string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. 

SEE ALSO 

conv(3C), malloc(3C), memory(3C), setlocale(3C), thread_safety(5), glossary(9). 

STANDARDS CONFORMANCE 

strcat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strchr(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strcmp(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strcoll(): AES, SVID3, XPG3, XPG4, ANSI C 

strcpy(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strcspn(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strdup(): SVID2, SVID3 

HP-UX 11i Version 3: September 2010 − 3 − Hewlett-Packard Company 3



strlen(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strncat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strncmp(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strncpy(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strpbrk(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strrchr(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strspn(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strstr(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strtok(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C 

strxfrm(): AES, SVID3, XPG3, XPG4, ANSI C 

s 

4 Hewlett-Packard Company − 4 − HP-UX 11i Version 3: September 2010

string(3C) string(3C) - HP

Create successful ePaper yourself

Delete template?

Save as template?