From the Linux Programmer's Manual: string
STRING
NAME
strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, strdup, strfry,
strlen, strncat, strncmp, strncpy, strncasecmp, strpbrk, strrchr, strsep,
strspn, strstr, strtok, strxfrm, index, rindex - string operations
SYNOPSIS
#include <string.h>
char *index(const char *s, int c);
char *rindex(const char *s, int c);
DESCRIPTION
The string functions perform string operations on NULL-terminated strings.
See the individual man pages for descriptions of each function.
SEE ALSO
index(3), rindex(3), strcasecmp(3), strcat(3), strchr(3), strcmp(3), strcoll(3),
strcpy(3), strcspn(3), strdup(3), strfry(3), strlen(3), strncat(3), strncmp(3),
strncpy(3), strncasecmp(3), strpbrk(3), strrchr(3), strsep(3), strspn(3),
strstr(3), strtok(3), strxfrm(3)
INDEX
NAME
index, rindex - locate character in string
SYNOPSIS
#include <string.h>
char *index(const char *s, int c);
char *rindex(const char *s, int c);
DESCRIPTION
The index() function returns a pointer to the first occurrence of the character
c in the string s.
The rindex() function returns a pointer to the last occurrence of the
character c in the string s.
The terminating NULL character is considered to be a part of the strings.
RETURN VALUE
The index() and rindex() functions return a pointer to the matched character
or NULL if the character is not found.
STRCASECMP
NAME
strcasecmp, strncasecmp - compare two strings ignoring case
SYNOPSIS
#include <string.h>
int strcasecmp(const char *s1, const char *s2);
int strncasecmp(const char *s1, const char *s2, size_t n);
DESCRIPTION
The strcasecmp() function compares the two strings s1 and s2, ignoring
the case of the characters. It returns an integer less than, equal to,
or greater than zero if s1 is found, respectively, to be less than, to
match, or be greater than s2.
The strncasecmp() function is similar, except it only compares the first
n characters of s1.
RETURN VALUE
The strcasecmp() and strncasecmp() functions return an integer less than,
equal to, or greater than zero if s1 (or the first n bytes thereof) is
found, respectively, to be less than, to match, or be greater than s2.
STRCAT
NAME
strcat, strncat - concatenate two strings
SYNOPSIS
#include <string.h>
char *strcat(char *dest, const char *src);
char *strncat(char *dest, const char *src, size_t n);
DESCRIPTION
The strcat() function appends the src string to the dest string overwriting
the `\0' character at the end of dest, and then adds a terminating `\0'
character. The strings may not overlap, and the dest string must have enough
space for the result.
The strncat() function is similar, except that only the first n characters
of src are appended to dest.
RETURN VALUE
The strcat() and strncat() functions return a pointer to the resulting
string dest.
STRCHR
NAME
strchr, strrchr - locate character in string
SYNOPSIS
#include <string.h>
char *strchr(const char *s, int c);
char *strrchr(const char *s, int c);
DESCRIPTION
The strchr() function returns a pointer to the first occurrence of the
character c in the string s.
The strrchr() function returns a pointer to the last occurrence of the
character c in the string s.
Here "character" means "byte" - these functions do not work with wide
or multi-byte characters.
RETURN VALUE
The strchr() and strrchr() functions return a pointer to the matched character
or NULL if the character is not found.
STRCMP
NAME
strcmp, strncmp - compare two strings
SYNOPSIS
#include <string.h>
int strcmp(const char *s1, const char *s2);
int strncmp(const char *s1, const char *s2, size_t n);
DESCRIPTION
The strcmp() function compares the two strings s1 and s2. It returns an
integer less than, equal to, or greater than zero if s1 is found, respectively,
to be less than, to match, or be greater than s2.
The strncmp() function is similar, except it only compares the first
(at most) n characters of s1 and s2.
RETURN VALUE
The strcmp() and strncmp() functions return an integer less than, equal
to, or greater than zero if s1 (or the first n bytes thereof) is found,
respectively, to be less than, to match, or be greater than s2.
STRCOLL
NAME
strcoll - compare two strings using the current locale
SYNOPSIS
#include <string.h>
int strcoll(const char *s1, const char *s2);
DESCRIPTION
The strcoll() function compares the two strings s1 and s2. It returns an
integer less than, equal to, or greater than zero if s1 is found, respectively,
to be less than, to match, or be greater than s2. The comparison is based
on strings interpreted as appropriate for the program's current locale
for category LC_COLLATE. (See setlocale(3)).
RETURN VALUE
The strcoll() function returns an integer less than, equal to, or greater
than zero if s1 is found, respectively, to be less than, to match, or be
greater than s2, when both are interpreted as appropriate for the current
locale.
STRCPY
NAME
strcpy, strncpy - copy a string
SYNOPSIS
#include <string.h>
char *strcpy(char *dest, const char *src);
char *strncpy(char *dest, const char *src, size_t n);
DESCRIPTION
The strcpy() function copies the string pointed to by src (including the
terminating `\0' character) to the array pointed to by dest. The strings
may not overlap, and the destination string dest must be large enough to
receive the copy.
The strncpy() function is similar, except that not more than n bytes
of src are copied. Thus, if there is no null byte among the first n bytes
of src, the result will not be null-terminated.
In the case where the length of src is less than that of n, the remainder
of dest will be padded with nulls.
RETURN VALUE
The strcpy() and strncpy() functions return a pointer to the destination
string dest.
BUGS
If the destination string of a strcpy() is not large enough (that is, if
the programmer was stupid/lazy, and failed to check the size before copying)
then anything might happen. Overflowing fixed length strings is a favourite
cracker technique.
STRSPN
NAME
strspn, strcspn - search a string for a set of characters
SYNOPSIS
#include <string.h>
size_t strspn(const char *s, const char *accept);
size_t strcspn(const char *s, const char *reject);
DESCRIPTION
The strspn() function calculates the length of the initial segment of s
which consists entirely of characters in accept.
The strcspn() function calculates the length of the initial segment
of s which consists entirely of characters not in reject.
RETURN VALUE
The strspn() function returns the number of characters in the initial segment
of s which consist only of characters from accept.
The strcspn() function returns the number of characters in the initial
segment of s which are not in the string reject.
STRDUP
NAME
strdup, strndup, strdupa, strndupa - duplicate a string
SYNOPSIS
#include <string.h>
char *strdup(const char *s);
#define _GNU_SOURCE
#include <string.h>
char *strndup(const char *s, size_t n);
char *strdupa(const char *s);
char *strndupa(const char *s, size_t n);
DESCRIPTION
The strdup() function returns a pointer to a new string which is a duplicate
of the string s. Memory for the new string is obtained with malloc(3),
and can be freed with free(3).
The strndup() function is similar, but only copies at most n characters.
If s is longer than n, only n characters are copied, and a terminating
NUL is added.
strdupa and strndupa are similar, but use alloca(3) to allocate the
buffer. They are only available when using the GNU GCC suite, and suffer
from the same limitations described in alloca(3).
RETURN VALUE
The strdup() function returns a pointer to the duplicated string, or NULL
if insufficient memory was available.
ERRORS
ENOMEM
Insufficient memory available to allocate duplicate string.
STRFRY
NAME
strfry - randomize a string
SYNOPSIS
#include <string.h>
char *strfry(char *string);
DESCRIPTION
The strfry() function randomizes the contents of string by using rand(3)
to randomly swap characters in the string. The result is an anagram of
string.
RETURN VALUE
The strfry() functions returns a pointer to the randomized string.
STRLEN
NAME
strlen - calculate the length of a string
SYNOPSIS
#include <string.h>
size_t strlen(const char *s);
DESCRIPTION
The strlen() function calculates the length of the string s, not including
the terminating `\0' character.
RETURN VALUE
The strlen() function returns the number of characters in s.
STRCAT
NAME
strcat, strncat - concatenate two strings
SYNOPSIS
#include <string.h>
char *strcat(char *dest, const char *src);
char *strncat(char *dest, const char *src, size_t n);
DESCRIPTION
The strcat() function appends the src string to the dest string overwriting
the `\0' character at the end of dest, and then adds a terminating `\0'
character. The strings may not overlap, and the dest string must have enough
space for the result.
The strncat() function is similar, except that only the first n characters
of src are appended to dest.
RETURN VALUE
The strcat() and strncat() functions return a pointer to the resulting
string dest.
STRCMP
NAME
strcmp, strncmp - compare two strings
SYNOPSIS
#include <string.h>
int strcmp(const char *s1, const char *s2);
int strncmp(const char *s1, const char *s2, size_t n);
DESCRIPTION
The strcmp() function compares the two strings s1 and s2. It returns an
integer less than, equal to, or greater than zero if s1 is found, respectively,
to be less than, to match, or be greater than s2.
The strncmp() function is similar, except it only compares the first
(at most) n characters of s1 and s2.
RETURN VALUE
The strcmp() and strncmp() functions return an integer less than, equal
to, or greater than zero if s1 (or the first n bytes thereof) is found,
respectively, to be less than, to match, or be greater than s2.
STRCPY
NAME
strcpy, strncpy - copy a string
SYNOPSIS
#include <string.h>
char *strcpy(char *dest, const char *src);
char *strncpy(char *dest, const char *src, size_t n);
DESCRIPTION
The strcpy() function copies the string pointed to by src (including the
terminating `\0' character) to the array pointed to by dest. The strings
may not overlap, and the destination string dest must be large enough to
receive the copy.
The strncpy() function is similar, except that not more than n bytes
of src are copied. Thus, if there is no null byte among the first n bytes
of src, the result will not be null-terminated.
In the case where the length of src is less than that of n, the remainder
of dest will be padded with nulls.
RETURN VALUE
The strcpy() and strncpy() functions return a pointer to the destination
string dest.
BUGS
If the destination string of a strcpy() is not large enough (that is, if
the programmer was stupid/lazy, and failed to check the size before copying)
then anything might happen. Overflowing fixed length strings is a favourite
cracker technique.
STRCASECMP
NAME
strcasecmp, strncasecmp - compare two strings ignoring case
SYNOPSIS
#include <string.h>
int strcasecmp(const char *s1, const char *s2);
int strncasecmp(const char *s1, const char *s2, size_t n);
DESCRIPTION
The strcasecmp() function compares the two strings s1 and s2, ignoring
the case of the characters. It returns an integer less than, equal to,
or greater than zero if s1 is found, respectively, to be less than, to
match, or be greater than s2.
The strncasecmp() function is similar, except it only compares the first
n characters of s1.
RETURN VALUE
The strcasecmp() and strncasecmp() functions return an integer less than,
equal to, or greater than zero if s1 (or the first n bytes thereof) is
found, respectively, to be less than, to match, or be greater than s2.
STRPBRK
NAME
strpbrk - search a string for any of a set of characters
SYNOPSIS
#include <string.h>
char *strpbrk(const char *s, const char *accept);
DESCRIPTION
The strpbrk() function locates the first occurrence in the string s of
any of the characters in the string accept.
RETURN VALUE
The strpbrk() function returns a pointer to the character in s that matches
one of the characters in accept, or NULL if no such character is found.
STRCHR
NAME
strchr, strrchr - locate character in string
SYNOPSIS
#include <string.h>
char *strchr(const char *s, int c);
char *strrchr(const char *s, int c);
DESCRIPTION
The strchr() function returns a pointer to the first occurrence of the
character c in the string s.
The strrchr() function returns a pointer to the last occurrence of the
character c in the string s.
Here "character" means "byte" - these functions do not work with wide
or multi-byte characters.
RETURN VALUE
The strchr() and strrchr() functions return a pointer to the matched character
or NULL if the character is not found.
STRSEP
NAME
strsep - extract token from string
SYNOPSIS
#include <string.h>
char *strsep(char **stringp, const char *delim);
DESCRIPTION
If *stringp is NULL, the strsep() function returns NULL and does nothing
else. Otherwise, this function finds the first token in the string *stringp,
where tokens are delimited by symbols in the string delim. This token is
terminated with a `\0' character (by overwriting the delimiter) and *stringp
is updated to point past the token. In case no delimiter was found, the
token is taken to be the entire string *stringp, and *stringp is made NULL.
RETURN VALUE
The strsep() function returns a pointer to the token, that is, it returns
the original value of *stringp.
NOTES
The strsep() function was introduced as a replacement for strtok(), since
the latter cannot handle empty fields. However, strtok() conforms to ANSI-C
and hence is more portable.
BUGS
This function suffers from the same problems as strtok(). In particular,
it modifies the original string. Avoid it.
STRSPN
NAME
strspn, strcspn - search a string for a set of characters
SYNOPSIS
#include <string.h>
size_t strspn(const char *s, const char *accept);
size_t strcspn(const char *s, const char *reject);
DESCRIPTION
The strspn() function calculates the length of the initial segment of s
which consists entirely of characters in accept.
The strcspn() function calculates the length of the initial segment
of s which consists entirely of characters not in reject.
RETURN VALUE
The strspn() function returns the number of characters in the initial segment
of s which consist only of characters from accept.
The strcspn() function returns the number of characters in the initial
segment of s which are not in the string reject.
STRSTR
NAME
strstr - locate a substring
SYNOPSIS
#include <string.h>
char *strstr(const char *haystack, const char *needle);
DESCRIPTION
The strstr() function finds the first occurrence of the substring needle
in the string haystack. The terminating `\0' characters are not compared.
RETURN VALUE
The strstr() function returns a pointer to the beginning of the substring,
or NULL if the substring is not found.
BUGS
Early versions of Linux libc (like 4.5.26) would not allow an empty argument.
Later versions (like 4.6.27) work correctly, and return haystack when needle
is empty.
STRTOK
NAME
strtok, strtok_r - extract tokens from strings
SYNOPSIS
#include <string.h>
char *strtok(char *s, const char *delim);
char *strtok_r(char *s, const char *delim, char **ptrptr);
DESCRIPTION
A `token' is a nonempty string of characters not occurring in the string
delim, followed by \0 or by a character occurring in delim.
The strtok() function can be used to parse the string s into tokens.
The first call to strtok() should have s as its first argument. Subsequent
calls should have the first argument set to NULL. Each call returns a pointer
to the next token, or NULL when no more tokens are found.
If a token ends with a delimiter, this delimiting character is overwritten
with a \0 and a pointer to the next character is saved for the next call
to strtok(). The delimiter string delim may be different for each call.
The strtok_r() function works the same as the strtok() function, but
instead of using a static buffer it uses a pointer to a user allocated
char* pointer. This pointer, the ptrptr parameter, must be the same while
parsing the same string.
BUGS
Never use these functions. If you do, note that:
These functions modify their first argument.
The identity of the delimiting character is lost.
These functions cannot be used on constant strings.
The strtok() function uses a static buffer while
parsing, so it's not thread safe. Use strtok_r() if this matters to you.
RETURN VALUE
The strtok() function returns a pointer to the next token, or NULL if there
are no more tokens.
STRXFRM
NAME
strxfrm - string transformation
SYNOPSIS
#include <string.h>
size_t strxfrm(char *dest, const char *src, size_t n);
DESCRIPTION
The strxfrm() function transforms the src string into a form such that
the result of strcmp() on two strings that have been transformed with strxfrm()
is the same as the result of strcoll() on the two strings before their
transformation. The first n characters of the transformed string are placed
in dest. The transformation is based on the program's current locale for
category LC_COLLATE. (See setlocale(3)).
RETURN VALUE
The strxfrm() function returns the number of bytes required to store the
transformed string in dest excluding the terminating `\0' character. If
the value returned is n or more, the contents of dest are indeterminate.