OSF

NAME

strcat, strchr, strcmp, strcoll, strcpy, strcspn, strdup, strerror, strlen, strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, strtok, strtok_r, strxfrm −  Performs operations on strings

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <string.h> char ∗strcat(
char ∗s1,
const char ∗s2) ; char ∗strchr(
const char ∗s,
int c) ; int strcmp(
const char ∗s1,
const char ∗s2) ; int strcoll(
const char ∗s1,
const char ∗s2) ; char ∗strcpy(
char ∗s1,
const char ∗s2) ; size_t strcspn(
const char ∗s1,
const char ∗s2) ; char ∗ strdup(
char ∗s1) ; char ∗strerror(
fint errnum) ; size_t strlen(
char ∗s) ; char ∗strncat(
char ∗s1,
const char ∗s2,
size_t n) ; int strncmp(
const char ∗s1,
const char ∗s2,
size_t n char ∗strncpy(
char ∗s1,
const char ∗s2,
size_t n) ; char ∗strpbrk(
const char ∗s1,
const char ∗s2) ; char ∗strrchr(
const char ∗s,
int c) ; size_t strspn(
const char ∗s1,
const char ∗s2) ; char ∗strstr(
const char ∗s1,
const char ∗s2) ; char ∗strtok(
char ∗s1,
const char ∗s2) ; char ∗strtok_r(
char ∗s1,
const char ∗s2,
char ∗∗last_string) ; size_t strxfrm(
char ∗s1,
const char ∗s2,
size_t n) ;

PARAMETERS

cSpecifies a character expressed as an int data type in functions strchr() and strrchr(). 

errnumSpecifies an error-number value in the strerror() function. 

nSpecifies the number of characters in a string referenced in the strncat(), strncmp(), strncpy(), and strncpy() functions. 

sSpecifies a string variable referenced in the strchr(), strlen(), and strrchr() functions. 

s1Points to a location containing one of two strings referenced in the strcat(), strcmp(), strcoll(), strcpy(), strcspn(), strncat(), strncmp(), strncpy(), strpbrk(), strspn(), strstr(), strtok(), and strxfrm() functions. 

s2Points to a location containing the second of two strings referenced in the same functions that use the s1 parameter. 

last_stringPoints to the first character of the next token. 

DESCRIPTION

The string functions copy, compare, and append strings in memory, and determine such values as location, size, and the existence of strings in memory. 

The strcat() function appends a copy of the string pointed to by the s2 parameter, including the terminating null character, to the end of the string pointed to by the s1 parameter.  The beginning character of the string pointed to by the s2 parameter overwrites the null character at the end of the string pointed to by the s1 parameter.  When operating on overlapping strings, the behavior of this function is unreliable. 

The strchr() function locates the first occurrence of the integer specified by the c parameter, which is converted to a char, in the string pointed to by the s parameter.  The terminating null character is treated as part of the string pointed to by the s parameter. 

The strcmp() function compares the string pointed to by the s1 parameter to the string pointed to by the s2 parameter.  The sign of a nonzero value returned by strcmp() is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as unsigned char) that differ in the two compared objects. 

The strcoll() function compares the string pointed to by the s1 parameter with the string pointed to by the s2 parameter, both interpreted as appropriate to the LC_COLLATE category of the current locale.  The sign of a nonzero value returned by strcoll() is determined by the relative ordering within the current collating sequence of the first pair of characters that differ in the objects under comparison. 

The strcpy() function copies the string pointed to by the s2 parameter, including the terminating null character, to the location pointed to by the s1 parameter.  When operating on overlapping strings, the behavior of this function is unreliable. 

The strdup() function returns a pointer to a new string that is an exact duplicate of the string pointed to by the s1 parameter.  The malloc() function is used to allocate space for the new string. 

The strerror() function maps the error number specified by the errnum parameter to a language-dependent error message string, and returns a pointer to the string.  The string pointed to by the return value is not modified by the program, but may be overwritten by a subsequent call to this function.  The implementation behaves as though no other function calls the strerror() function. 

The strlen() function returns the number of bytes in the string pointed to by the s parameter. The string length value does not include the string terminating null character. 

The strcmp() function compares the string pointed to by the s1 parameter with the string pointed to by the s2 parameter. The sign of any nonzero value returned by strcmp() is determined by the sign resulting from the difference in integer values of the first character-pair comparison (both converted to unsigned char) in which the characters are different. 

The strncat() function appends n bytes in the string pointed to by the s2 parameter to the end of the string pointed to by the s1 parameter. The initial character of the string pointed to by s2 overwrites the null character at the end of the string pointed to by s1.  The number of characters specified by the n parameter and a terminating null character are always appended to the string pointed to by the s1 parameter.  When operating on overlapping strings, the behavior of this function is unreliable. 

The strncpy() function copies no more than the number of characters specified by the n parameter from the location pointed to by the s2 parameter to the location pointed to by the s1 parameter.  Characters following a null character are not copied.  When operating on overlapping strings, the behavior of this function is unreliable.  When the location pointed to by the s2 parameter is a string whose character length is less than the value specified by the n parameter, null characters are appended to the s1 string until n characters are contained in the string. 

The strpbrk() function scans the string pointed to by the s1 parameter for the first occurrence of any character in the string pointed to by the s2 parameter. 

The strrchr() function locates the last occurrence of the integer specified by the c parameter, which is converted to a char value, in the string pointed to by the s parameter.  The terminating null character is treated as a part of the string pointed to by the s parameter. 

The strspn() function computes the length of the maximum initial segment of the string pointed to by the s1 parameter, which consists entirely of characters from the string pointed to by the s2 parameter. 

The strcspn() function computes the byte length of the maximum initial segment of the string pointed to by the s1 parameter, which consists entirely of characters that are not from the string pointed to by the s2 parameter. 

The strstr() function locates the first occurrence in the string pointed to by the s1 parameter of the sequence of bytes in the string pointed to by the s2 parameter, excluding the terminating null character. 

The strtok() function expects that the string pointed to by the s1 parameter consists of multiple tokens separated by one or more characters that match those in a separator string pointed to by the s2 parameter. A sequence of calls to the strtok() function breaks the s1 string into a sequence of expected tokens, each of which is delimited by one or more characters from the s2 string. 

The initial call to function strtok() in the token-sequence search specifies the s1 parameter as the address of the token string.  This call is followed by subsequent calls that have a null pointer as the value of the s1 parameter. The separator string pointed to by the s2 parameter may be different in every call to this function. 

The first call in the token-sequence search tests every character in the s1 string for any character that is not contained in the current separator string pointed to by the s2 parameter. When no matching character is found, there are no tokens in that string and a null pointer is returned.  When a nonseparator character is found, it becomes the starting character of the next token. 

The strtok() function then searches for a character that matches any character in the current separator string pointed to by the s2 parameter.  When no matching character is found, the current token extends to the end of the string pointed to by the s1 parameter and subsequent searches for a token return a null pointer.  When a matching separator-string character is found, it is overwritten by the null character, which terminates the current token.  The strtok() function saves a pointer to the next character, which is the character from which the next search for a token starts. 

Each subsequent call having a null pointer as the value of the the s1 parameter begins a search at the character pointed to by the saved pointer and behaves as described above. 

The implementation behaves as though no function calls the strtok() function. 

The strtok_r() function is the reentrant version of strtok().  Upon successful completion, the first character of the next token is stored in ∗∗last_string, and a value of 0 (zero) is returned. 

The strxfrm() function transforms the string pointed to by the s2 parameter and places the result in the address specified by s1.  When the strcmp() function is applied to two transformed strings, a value greater than, equal to, or less than 0 (zero) is returned. The returned value corresponds to the same value that is returned when the strcoll() function is applied to the same two original transformed strings.  No more than n characters are placed in the location pointed to by the s1 parameter, including the terminating null character.  When n is 0 (zero), the s1 parameter is a null pointer.  When operating on overlapping strings, the behavior of this function is unreliable. 

NOTES

AES Support Level:
Full use (strcat(), strchr(), strcmp(), strcoll(), strcpy(), strcspn(), strerror(), strlen(), strncat(), strncmp(), strncpy(), strpbrk(), strrchr(), strspn(), strstr(), strtok(), strxfrm())

RETURN VALUES

Upon successful completion, the strcat(), strcpy(), strncat(), and strncpy() functions return a pointer to the resulting string. Otherwise these functions return a null pointer. 

Upon successful completion, the strchr() and strrchr() functions return a pointer to the matching character in the scanned string, When the character specified by parameter c is not found, a null pointer is returned. 

Upon successful completion, the strcmp(), strcoll(), and strncmp() functions return an integer whose value is greater than, equal to, or less than 0 (zero), according to whether the s1 string is greater than, equal to, or less than the s2 string. When a successful comparison can not be made, these functions return 0 (zero). 

Upon successful completion, the strcspn(), strnspn(), and strxfrm() functions return the length of the string segment. Otherwise, (size_t)-1 is returned and errno is set to indicate the error. 

Upon successful completion, the strerror() function returns a pointer to the generated message string.  If the error number is not valid, errno is set to [EINVAL]. 

Upon successful completion, the strlen() function returns the number of characters in the string to which the s parameter points. Otherwise, (size_t)-1 is returned and errno is set to indicate the error. 

Upon successful completion, the strpbrk() function returns a pointer to the matched character. When no character in the string pointed to by the s2 parameter occurs in the string pointed to by the s1 parameter, a null pointer is returned and the value of errno remains unchanged. On error, the strpbrk() function returns a null pointer and sets errno to indicate the error. 

Upon successful completion, the strstr() function returns a pointer to the located string or a null pointer when the string is not found.  When the s2 parameter points to a string having 0 (zero) length, the strstr() function returns the string pointed to by parameter s1.  On error, a null pointer is returned and errno is set to indicate the error. 

Upon successful completion, the strtok() function returns a pointer to the first character of the parsed token in the string. When there is no token in the string, a null pointer is returned. 

ERRORS

If one of the string functions fails, errno may be set to the following value:

[EINVAL]The string pointed to by the s1 or s2 parameter contains characters outside the domain of the collating sequence, or the value of the errnum parameter used in the strerror() function is not a valid message number. 

RELATED INFORMATION

Functions: memccpy(3), setlocale(3), swab(3)