./_Man_NeXT_html/html3/string.3.html

Manual page for STRING(3)

index, rindex, strcasecmp, strcat, strncasecmp, strncat, strcmp, strncmp, strcpy, strncpy, strchr, strrchr, strspn, strcspn, strpbrk, strstr, strtok, strlen - string operations

SYNOPSIS

#include <string.h>

char *strcat(char *s, const char *append);

char *strncat(char *s, const char *append, size_t count);

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

int strncmp(const char *s1, const char *s2, size_t count);

char *strcpy(char *to, const char *from);

char *strncpy(char *to, const char *from, size_t count);

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

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

size_t strspn(const char *s1, const char *s2);

size_t strcspn(const char *s1, const char *s2);

char *strpbrk(const char *s1, const char *s2);

char *strstr(const char *s1, const char *s2);

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

size_t strlen(const char *s);

(ALSO AVAILABLE IN BSD)

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

int strncasecmp(const char *s1, const char *s2, size_t n);

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

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

DESCRIPTION

These functions operate on null-terminated strings. They do not check for overflow of any receiving string.

Strcat appends a copy of string append to the end of string s. Strncat appends at most count characters. Both return a pointer to the null-terminated result.

Strcmp compares its arguments and returns an integer greater than, equal to, or less than 0, according as s1 is lexicographically greater than, equal to, or less than s2. Strncmp makes the same comparison but looks at at most count characters.

Strcpy copies string from to to, stopping after the null character has been copied. Strncpy copies exactly count characters, appending nulls if from is less than count characters in length; the target may not be null-terminated if the length of from is count or more. Both return to.

Strchr locates the first occurrence of c in the string pointed to by s. The terminating null character is not considered to be part of the string. Strchr returns a pointer to the located character, or a null pointer if the character does not occur in the string.

Strrchr locates the last occurrence of c in the string pointed to by s. The terminating null character is not considered to be part of the string. Strrchr returns a pointer to the located character, or a null pointer if the character does not occur in the string.

Strspn computes the length of the maximum initial segment of the string pointed to by s1 which consists entirely of characters from the string pointed to by s2. Strspn returns the length of the segment.

Strcspn computes the length of the maximum initial segment of the string pointed to by s1 which consists entirely of characters not from the string pointed to by s2. Strcspn returns the length of the segment.

Strpbrk returns a pointer to the first occurrence in string s1 of any character from the string s2, or a NULL pointer if no character from s2 exists in s1.

Strstr returns a pointer to the first occurrence of the pattern string s2 in string s1. For example, if s1 is ``string thing'' and s2 is ``ing'', strstr returns ``ing thing''. If s2 does not appear in s1, strstr returns NULL.

A sequence of calls to strtok breaks the string pointed to by s1 into a sequence of tokens, each of which is delimited by a character from the string pointed to by s2. The first call in the sequence has s1 as its first argument, and is followed by calls with a null pointer as their first argument. The separator string pointed to by s2 may be different from call to call.

The first call in the sequence searches the string pointed to by s1 for the first character that is not contained in the current separator string pointed to by s2. If no such character is found, then there are no tokens in the string pointed to by s1 and strtok returns a null pointer. If such a character is found, it is the start of the first token.

Strtok then searches from there for a character that is contained in the current separator string. If no such character is found, the current token extends to the end of the string pointed to by s1, and subsequent searches for a token will return a null pointer. If such a character is found, it is overwritten by a null character, which terminates the current token. Strtok saves a pointer to the following character, from which the next search for a token will start.

Each subsequent call, with a null pointer as the value of the first argument, starts searching from the saved pointer and behaves as described above.

Strtok returns a pointer to the first character of a token, or a null pointer if there is no token.

Strlen returns the number of characters in string s, not including the null-terminating character.

BSD ADDITIONS

The strcasecmp and strncasecmp functions perform as strcmp and strncmp, but are case-insensitive (that is, they convert characters in each string to lowercase before comparing them).

The index and rindex functions are equivalent to strchr and strrchr, respectively.

These routines assume the ASCII character set when equating lower and upper case characters.

WARNINGS

Strcmp and strncmp use native character comparison, which is signed on some machines, but may be unsigned on other machines. Thus the sign of the value returned when one of the characters has its high-order bit set is implementation-dependent.

Strcasecmp and strncasecmp use native character comparison as above and assume the ASCII character set.

On many machines you cannot use a NULL pointer to indicate a null string. A NULL pointer is an error and results in an abort of the program. If you wish to indicate a null string, you must have a pointer that points to an explicit null string. On some implementations of the C language on some machines, a NULL pointer, if dereferenced, would yield a null string; this highly non-portable trick was used in some programs. Programmers using a NULL pointer to represent an empty string should be aware of this portability issue; even on machines where dereferencing a pointer does not cause an abort of the program, it does not necessarily yield a null string. Character movement is performed differently in different implementations. Thus overlapping moves may yield surprises.