[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , Volume 2


strlen, strchr, strrchr, strpbrk, strspn, strcspn, strstr, or strtok 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;

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 *index (String, Character)
const char *String;
int Character;

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

Description

Attention: Do not use the strtok subroutine in a multithreaded environment.

The strlen, 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 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.

Parameters


Character Specifies a character for which to return a pointer.
String Points to a string from which data is returned.
String1 Points to a string from which an operation returns results.
String2 Points to a string which contains source for an operation.

Error Codes

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

EFAULT A string parameter is an invalid address.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

The index and rindex 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.

Related Information

The memccpy, memchr, memcmp, memcpy, or memmove subroutine, setlocale (setlocale Subroutine) subroutine, strcat, strncat, strxfrm, strcpy, strncpy, or strdup (strcat, strncat, strxfrm, strcpy, strncpy, or strdup Subroutine) subroutine, strcmp, strncmp, strcasecmp, strncasecmp, or strcoll (strcmp, strncmp, strcasecmp, strncasecmp, or strcoll Subroutine) subroutine, swab (swab Subroutine) subroutine.

List of String Manipulation Services in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview for Programming in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]