strlen, , strnlen, strchr, strrchr, strpbrk, strspn, strcspn, strstr, strtok, or strsep Subroutine

Purpose

Determines the size, location, and existence of strings in memory.

Library

Standard C Library (libc.a)

Syntax

#include <string.h>

size_t strlen (String)
const char *String;

size_t strnlen (String, maxlen)
const char *String;
size_t maxlen;

char *strchr (String, Character)
const char *String;
int Character;

char *strrchr (String, Character)
const char *String;
int Character;

char *strpbrk (String1, String2)
const char *String1, String2;

size_t strspn (String1, String2)
const char *String1, * String2;

size_t strcspn (String1, String2)
const char *String1, *String2;

char *strstr (String1, String2)
const char *String1, *String2;

char *strtok (String1, String2)
char *String1;
const char *String2;

char *strsep (String1, String2)
char **String1;
const char *String2;

char *index (String, Character)
const char *String;
int Character;

char *rindex (String, Character)
const char *String;
int Character;

Description

The strlen, strnlen, strchr, strrchr, strpbrk, strspn, strcspn, strstr, and strtok subroutines determine such values as size, location, and the existence of strings in memory.

The String1, String2, and String parameters point to strings. A string is an array of characters terminated by a null character.

The strlen subroutine returns the number of bytes in the string pointed to by the String parameter, not including the terminating null bytes.

The strnlen function returns an integer containing the smaller of either the length of the string pointed to by String, or maxlen, not including the terminating null bytes.

The strchr subroutine returns a pointer to the first occurrence of the character specified by the Character (converted to an unsigned character) parameter in the string pointed to by the String parameter. A null pointer is returned if the character does not occur in the string. The null byte that terminates a string is considered to be part of the string.

The strrchr subroutine returns a pointer to the last occurrence of the character specified by the Character (converted to a character) parameter in the string pointed to by the String parameter. A null pointer is returned if the character does not occur in the string. The null byte that terminates a string is considered to be part of the string.

The strpbrk subroutine returns a pointer to the first occurrence in the string pointed to by the String1 parameter of any bytes from the string pointed to by the String2 parameter. A null pointer is returned if no bytes match.

The strspn subroutine returns the length of the initial segment of the string pointed to by the String1 parameter, which consists entirely of bytes from the string pointed to by the String2 parameter.

The strcspn subroutine returns the length of the initial segment of the string pointed to by the String1 parameter, which consists entirely of bytes not from the string pointed to by the String2 parameter.

The strstr subroutine finds the first occurrence in the string pointed to by the String1 parameter of the sequence of bytes specified by the string pointed to by the String2 parameter (excluding the terminating null character). It returns a pointer to the string found in the String1 parameter, or a null pointer if the string was not found. If the String2 parameter points to a string of 0 length, the strstr subroutine returns the value of the String1 parameter.

The strtok subroutine breaks the string pointed to by the String1 parameter into a sequence of tokens, each of which is delimited by a byte from the string pointed to by the String2 parameter. The first call in the sequence takes the String1 parameter as its first argument and is followed by calls that take a null pointer as their first argument. The separator string pointed to by the String2 parameter may be different from call to call.

The first call in the sequence searches the String1 parameter for the first byte that is not contained in the current separator string pointed to by the String2 parameter. If no such byte is found, no tokens exist in the string pointed to by the String1 parameter, and a null pointer is returned. If such a byte is found, it is the start of the first token.

The strtok subroutine then searches from the first token for a byte that is contained in the current separator string. If no such byte is found, the current token extends to the end of the string pointed to by the String1 parameter, and subsequent searches for a token return a null pointer. If such a byte is found, the strtok subroutine overwrites it with a null byte, which terminates the current token. The strtok subroutine saves a pointer to the following byte, from which the next search for a token will start. The subroutine returns a pointer to the first byte of the token.

Each subsequent call with a null pointer as the value of the first argument starts searching from the saved pointer, using it as the first token. Otherwise, the subroutine's behavior does not change.

The strsep subroutine returns the next token from the string String1 which is delimited by String2. The token is terminated with a \0 character and String1 is updated to point past the token. The strsep subroutine returns a pointer to the token, or NULL if String2 is not found in String1.

The index, rindex and strsep subroutines are included for compatibility with BSD and are not part of the ANSI C Library. The index subroutine is implemented as a call to the strchr subroutine. The rindex subroutine is implemented as a call to the strrchr subroutine.

Parameters

Error Codes

The strlen, strnlen, strchr, strrchr, strpbrk, strspn, strcspn, strstr, and strtok subroutines fail if the following occurs: