<string.h>


memchr · memcmp · memcpy · memmove · memset · NULL · size_t · strcat · strchr · strcmp · strcoll · strcpy · strcspn · strerror · strlen · strncat · strncmp · strncpy · strpbrk · strrchr · strspn · strstr · strtok · strxfrm

errno_t · memcpy_s · memmove_s · rsize_t · strcat_s · strcpy_s · strerror_s · strerrorlen_s · strncat_s · strncpy_s · strnlen_s · strtok_s


Include the standard header <string.h> to declare a number of functions that help you manipulate C strings and other arrays of characters.

    /* MACROS */
#define NULL <either 0, 0L, or (void *)0> [0 in C++]

    /* TYPES */
typedef ui-type size_t;

    /* FUNCTIONS */
int memcmp(const void *s1, const void *s2, size_t n);
void *memcpy(void *restrict s1, const void *restrict s2, size_t n);
void *memmove(void *s1, const void *s2, size_t n);
void *memset(void *s, int c, size_t n);
char *strcat(char *restrict s1, const char *restrict s2);
int strcmp(const char *s1, const char *s2);
int strcoll(const char *s1, const char *s2);
char *strcpy(char *restrict s1, const char *restrict s2);
size_t strcspn(const char *s1, const char *s2);
char *strerror(int errcode);
size_t strlen(const char *s);
char *strncat(char *restrict s1, const char *restrict s2, size_t n);
int strncmp(const char *s1, const char *s2, size_t n);
char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
size_t strspn(const char *s1, const char *s2);
char *strtok(char *restrict s1, const char *restrict s2);
size_t strxfrm(char *restrict s1, const char *restrict s2, size_t n);

void *memchr(const void *s, int c,
    size_t n); [not in C++]
const void *memchr(const void *s, int c,
    size_t n); [C++ only]
void *memchr(void *s, int c, size_t n); [C++ only]

char *strchr(const char *s, int c); [not in C++]
const char *strchr(const char *s, int c); [C++ only]
char *strchr(char *s, int c); [C++ only]

char *strpbrk(const char *s1,
    const char *s2); [not in C++]
const char *strpbrk(const char *s1,
    const char *s2); [C++ only]
char *strpbrk(char *s1, const char *s2); [C++ only]

char *strrchr(const char *s, int c); [not in C++]
const char *strrchr(const char *s, int c); [C++ only]
char *strrchr(char *s, int c); [C++ only]

char *strstr(const char *s1,
    const char *s2); [not in C++]
const char *strstr(const char *s1,
    const char *s2); [C++ only]
char *strstr(char *s1, const char *s2); [C++ only]

#if __STDC_WANT_LIB_EXT1__ [added with TR24731]
typedef int errno_t;
typedef size_t rsize_t;

errno_t memcpy_s(void *restrict s1, rsize_t maxsize,
    const void *restrict s2, rsize_t n);
errno_t memmove_s(void *s1, rsize_t maxsize,
    const void *s2, rsize_t n);

errno_t strcpy_s(char *restrict s1, rsize_t maxsize,
    const char *restrict s2);
errno_t strncpy_s(char *restrict s1, rsize_t maxsize,
    const char *restrict s2, rsize_t n);
errno_t strcat_s(char *restrict s1, rsize_t maxsize,
    const char *restrict s2);
errno_t strncat_s(char *restrict s1, rsize_t maxsize,
    const char *restrict s2, rsize_t n);
char *strtok_s(char *restrict s1, rsize_t *restrict psize1,
    const char *restrict s2, char **restrict pbuf1);

errno_t strerror_s(char *s, rsize_t maxsize,
    errno_t errcode);
size_t strerrorlen_s(errno_t errcode);

size_t strnlen_s(const char *restrict s, size_t maxsize);
#endif /* __STDC_WANT_LIB_EXT1__ */

errno_t

typedef int errno_t; [added with TR24731]

The type is a synonym for int, used to represent a value that can be stored in errno.

memchr

void *memchr(const void *s, int c,
    size_t n); [not in C++]
const void *memchr(const void *s, int c,
    size_t n); [C++ only]
void *memchr(void *s, int c, size_t n); [C++ only]

The function searches for the first element of an array of unsigned char, beginning at the address s with size n, that equals (unsigned char)c. If successful, it returns the address of the matching element; otherwise, it returns a null pointer.

memcmp

int memcmp(const void *s1, const void *s2, size_t n);

The function compares successive elements from two arrays of unsigned char, beginning at the addresses s1 and s2 (both of size n), until it finds elements that are not equal:

memcpy

void *memcpy(void *restrict s1, const void *restrict s2, size_t n);

The function copies the array of char beginning at the address s2 to the array of char beginning at the address s1 (both of size n). It returns s1. The elements of the arrays can be accessed and stored in any order.

memcpy_s

errno_t memcpy_s(void *restrict s1, rsize_t maxsize,
    const void *restrict s2, size_t n); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores null characters in the first maxsize elements of the array of char beginning at the address s1. It returns the error code it reported to the constraint handler.

Otherwise, the function copies the array of char beginning at the address s2 to the array of char beginning at the address s1 (both of size n). It returns zero.

memmove

void *memmove(void *s1, const void *s2, size_t n);

The function copies the array of char beginning at s2 to the array of char beginning at s1 (both of size n). It returns s1. If the arrays overlap, the function accesses each of the element values from s2 before it stores a new value in that element, so the copy is not corrupted.

memmove_s

errno_t memmove_s(void *s1, rsize_t maxsize,
    const void *s2, size_t n); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores null characters in the first maxsize elements of the array of char beginning at the address s1. It returns the error code it reported to the constraint handler.

Otherwise, the function copies the array of char beginning at s2 to the array of char beginning at s1 (both of size n). It returns zero. If the arrays overlap, the function accesses each of the element values from s2 before it stores a new value in that element, so the copy is not corrupted.

memset

void *memset(void *s, int c, size_t n);

The function stores (unsigned char)c in each of the elements of the array of unsigned char beginning at s, with size n. It returns s.

NULL

#define NULL <either 0, 0L, or (void *)0> [0 in C++]

The macro yields a null pointer constant that is usable as an address constant expression.

rsize_t

typedef size_t rsize_t; [added with TR24731]

The type is a synonym for size_t, used to represent a function argument to be checked on entry to a function. It is a runtime constraint violation for an argument of type rsize_t to be greater than RSIZE_MAX.

size_t

typedef ui-type size_t;

The type is the unsigned integer type ui-type of an object that you declare to store the result of the sizeof operator.

strcat

char *strcat(char *restrict s1, const char *restrict s2);

The function copies the string s2, including its terminating null character, to successive elements of the array of char that stores the string s1, beginning with the element that stores the terminating null character of s1. It returns s1.

strcat_s

errno_t strcat_s(char *restrict s1, rsize_t maxsize,
    const char *restrict s2); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null character in s1[0]. It returns the error code it reported to the constraint handler.

Otherwise, the function copies the string s2, including its terminating null character, to successive elements of the array of char that stores the string s1, beginning with the element that stores the terminating null character of s1. It returns zero.

strchr

char *strchr(const char *s, int c); [not in C++]
const char *strchr(const char *s, int c); [C++ only]
char *strchr(char *s, int c); [C++ only]

The function searches for the first element of the string s that equals (char)c. It considers the terminating null character as part of the string. If successful, the function returns the address of the matching element; otherwise, it returns a null pointer.

strcmp

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

The function compares successive elements from two strings, s1 and s2, until it finds elements that are not equal.

strcoll

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

The function compares two strings, s1 and s2, using a comparison rule that depends on the current locale. If s1 compares greater than s2 by this rule, the function returns a positive number. If the two strings compare equal, it returns zero. Otherwise, it returns a negative number.

strcpy

char *strcpy(char *restrict s1, const char *restrict s2);

The function copies the string s2, including its terminating null character, to successive elements of the array of char whose first element has the address s1. It returns s1.

strcpy_s

errno_t strcpy_s(char *restrict s1, rsize_t maxsize,
    const char *restrict s2); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null character in s1[0]. It returns the error code it reported to the constraint handler.

Otherwise, the function copies the string s2, including its terminating null character, to successive elements of the array of char whose first element has the address s1. It returns zero.

strcspn

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

The function searches for the first element s1[i] in the string s1 that equals any one of the elements of the string s2 and returns i. Each terminating null character is considered part of its string.

strerror

char *strerror(int errcode);

The function returns a pointer to an internal static-duration object containing the error message string corresponding to the error code errcode. The program must not alter any of the values stored in this object. A later call to strerror can alter the value stored in this object.

The function is not necessarily thread safe.

strerror_s

errno_t strerror_s(char *restrict s, rsize_t maxsize,
    errno_t errcode); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, the function returns the error code it reported to the constraint handler.

Otherwise, the function copies into s at most maxsize - 1 characters from the error message string corresponding to the error code errcode and appends a null character. If not all of the message string is copied, and if 3 < maxsize, then the string "..." overwrites the last three characters of the copied string.

The function returns zero.

strerrorlen_s

size_t strerrorlen_s(errno_t errcode); [added with TR24731]

The function returns the length of the error message string corresponding to the error code errcode.

strlen

size_t strlen(const char *s);

The function returns the number of characters in the string s, not including its terminating null character.

strncat

char *strncat(char *restrict s1, const char *restrict s2, size_t n);

The function copies the string s2, not including its terminating null character, to successive elements of the array of char that stores the string s1, beginning with the element that stores the terminating null character of s1. The function copies no more than n characters from s2. It then stores a null character, in the next element to be altered in s1, and returns s1.

strncat_s

errno_t strncat_s(char *restrict s1, rsize_t maxsize,
    const char *restrict s2, rsize_t n); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null character in s1[0]. It returns the error code it reported to the constraint handler.

Otherwise, the function copies the string s2, not including its terminating null character, to successive elements of the array of char that stores the string s1, beginning with the element that stores the terminating null character of s1. The function copies no more than n characters from s2. It then stores a null character, in the next element to be altered in s1, and returns zero.

strncmp

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

The function compares successive elements from two strings, s1 and s2, until it finds elements that are not equal or until it has compared the first n elements of the two strings.

strncpy

char *strncpy(char *restrict s1, const char *restrict s2, size_t n);

The function copies the string s2, not including its terminating null character, to successive elements of the array of char whose first element has the address s1. It copies no more than n characters from s2. The function then stores zero or more null characters in the next elements to be altered in s1 until it stores a total of n characters. It returns s1.

strncpy_s

errno_t strncpy_s(char *restrict s1, rsize_t maxsize,
    const char *restrict s2, rsize_t n); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null character in s1[0]. It returns the error code it reported to the constraint handler.

Otherwise, the function copies the string s2, not including its terminating null character, to successive elements of the array of char whose first element has the address s1. It copies no more than n characters from s2. The function then stores a null character in the next elements to be altered in s1. It returns zero.

strnlen_s

size_t strnlen_s(const char *s, size_t maxsize); [added with TR24731]

If s is a null pointer, the function returns zero. Otherwise, if a null character occurs in the first maxsize elements of the array beginning at s, the function returns the number of characters before the first null character. Otherwise, the function returns maxsize.

strpbrk

char *strpbrk(const char *s1,
    const char *s2); [not in C++]
const char *strpbrk(const char *s1,
    const char *s2); [C++ only]
char *strpbrk(char *s1,
    const char *s2); [C++ only]

The function searches for the first element s1[i] in the string s1 that equals any one of the elements of the string s2. It considers each terminating null character as part of its string. If s1[i] is not the terminating null character, the function returns &s1[i]; otherwise, it returns a null pointer.

strrchr

char *strrchr(const char *s, int c); [not in C++]
const char *strrchr(const char *s, int c); [C++ only]
char *strrchr(char *s, int c); [C++ only]

The function searches for the last element of the string s that equals (char)c. It considers the terminating null character as part of the string. If successful, the function returns the address of the matching element; otherwise, it returns a null pointer.

strspn

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

The function searches for the first element s1[i] in the string s1 that equals none of the elements of the string s2 and returns i. It considers the terminating null character as part of the string s1 only.

strstr

char *strstr(const char *s1,
    const char *s2); [not in C++]
const char *strstr(const char *s1,
    const char *s2); [C++ only]
char *strstr(char *s1, const char *s2); [C++ only]

The function searches for the first sequence of elements in the string s1 that matches the sequence of elements in the string s2, not including its terminating null character. If successful, the function returns the address of the matching first element; otherwise, it returns a null pointer.

strtok

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

If s1 is not a null pointer, the function begins a search of the string s1. If s1 is a null pointer, it begins a search of the string whose address was last stored in an internal static-duration object on an earlier call to the function, as described below. The search proceeds as follows:

  1. The function searches the string for begin, the address of the first element that equals none of the elements of the string s2 (a set of token separators). It considers the terminating null character as part of the search string only.
  2. If the search does not find an element, the function stores the address of the terminating null character in the internal static-duration object (so that a subsequent search beginning with that address will fail) and returns a null pointer. Otherwise, the function searches from begin for end, the address of the first element that equals any one of the elements of the string s2. It again considers the terminating null character as part of the search string only.
  3. If the search does not find an element, the function stores the address of the terminating null character in the internal static-duration object. Otherwise, it stores a null character in the element whose address is end. Then it stores the address of the next element after end in the internal static-duration object (so that a subsequent search beginning with that address will continue with the remaining elements of the string) and returns begin.

The function is not necessarily thread safe.

strtok_s

char 8strtok_s(char *restrict s1, rsize_t *restrict psize1,
    const char *restrict s2, char **restrict pbuf1); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, the function stores nothing and returns a null pointer.

Otherwise, if s1 is not a null pointer, the function begins a search of the string s1. If s1 is a null pointer, it begins a search of the string whose address was last stored in an internal static-duration object on an earlier call to the function, as described below. The search proceeds as follows:

  1. The function searches the string for begin, the address of the first element that equals none of the elements of the string s2 (a set of token separators). It considers the terminating null character as part of the search string only.
  2. If the search does not find an element, the function stores the address of the terminating null character in the internal static-duration object (so that a subsequent search beginning with that address will fail) and returns a null pointer. Otherwise, the function searches from begin for end, the address of the first element that equals any one of the elements of the string s2. It again considers the terminating null character as part of the search string only.
  3. If the search does not find an element, the function stores the address of the terminating null character in the internal static-duration object. Otherwise, it stores a null character in the element whose address is end. Then it stores the address of the next element after end in the internal static-duration object (so that a subsequent search beginning with that address will continue with the remaining elements of the string) and returns begin.

strxfrm

size_t strxfrm(char *restrict s1, const char *restrict s2, size_t n);

The function stores a string in the array of char whose first element has the address s1. It stores no more than n characters, including the terminating null character, and returns the number of characters needed to represent the entire string, not including the terminating null character. If the value returned is n or greater, the values stored in the array are indeterminate. (If n is zero, s1 can be a null pointer.)

strxfrm generates the string it stores from the string s2 by using a transformation rule that depends on the current locale. For example, if x is a transformation of s1 and y is a transformation of s2, then strcmp(x, y) returns the same value as strcoll(s1, s2).


See also the Table of Contents and the Index.

Copyright © 1992-2013 by P.J. Plauger and Jim Brodie. All rights reserved.