Last modified on 18 October 2011, at 19:37

C Programming/C Reference/string.h

string.h is the header in the C standard library for the C programming language which contains macro definitions, constants, and declarations of functions and types used not only for string handling but also various memory handling functions; the name is thus something of a misnomer.

Functions declared in string.h are extremely popular, since as a part of the C standard library, they are guaranteed to work on any platform which supports C. However, some security issues exist with these functions, such as buffer overflows, leading programmers to prefer safer, possibly less portable variants. Also, the string functions only work with characters encodings made of bytes, such as ASCII and UTF-8. In historical documentation the term "character" was often used instead of "byte", which if followed literally would mean that multi-byte encodings such as UTF-8 were not supported. The BSD documentation has been fixed to make this clear, but POSIX, Linux, and Windows documentation still uses "character" in many places. Functions to handle character encodings made up of larger code units than bytes, such as UTF-16 is generally achieved through wchar.h.

Constants and typesEdit

Name Notes
NULL macro expanding to the null pointer constant; that is, a constant representing a pointer value which is guaranteed not to be a valid address of an object in memory.
size_t an unsigned integer type which is the type of the result of the sizeof operator.

FunctionsEdit

Name Notes
void *memcpy(void *dest, const void *src, size_t n); copies n bytes between two memory areas; if there is overlap, the behavior is undefined
void *memmove(void *dest, const void *src, size_t n); copies n bytes between two memory areas; unlike with memcpy the areas may overlap
void *memchr(const void *s, int c, size_t n); returns a pointer to the first occurrence of c in the first n bytes of s, or NULL if not found
int memcmp(const void *s1, const void *s2, size_t n); compares the first n bytes of two memory areas
void *memset(void *, int c, size_t n); overwrites a memory area with n copies of c
char *strcat(char *dest, const char *src); appends the string src to dest
char *strncat(char *dest, const char *src, size_t n); appends at most n bytes of the string src to dest
char *strchr(const char *, int c); locates byte c in a string, searching from the beginning
char *strrchr(const char *, int c); locates byte c in a string, searching from the end
int strcmp(const char *, const char *); compares two strings lexicographically
int strncmp(const char *, const char *, size_t n); compares up to the first n bytes of two strings lexicographically
int strcoll(const char *, const char *); compares two strings using the current locale's collating order
char *strcpy(char *dest, const char *src); copies a string from one location to another
char *strncpy(char *dest, const char *src, size_t n); write exactly n bytes to dest, copying from src or add 0's
char *strerror(int); returns the string representation of an error number e.g. errno (not thread-safe)
size_t strlen(const char *); finds the length of a C string
size_t strspn(const char *, const char *accept); determines the length of the maximal initial substring consisting entirely of bytes in accept
size_t strcspn(const char *, const char *reject); determines the length of the maximal initial substring consisting entirely of bytes not in reject
char *strpbrk(const char *, const char *accept); finds the first occurrence of any byte in accept
char *strstr(const char *haystack, const char *needle); finds the first occurrence of the string "needle" in the longer string "haystack"
char *strtok(char *, const char * delim); parses a string into a sequence of tokens; non-thread safe in the spec, non-reentrant[1]
size_t strxfrm(char *dest, const char *src, size_t n); transforms src into a collating form, such that the numerical sort order of the transformed string is equivalent to the collating order of src

Extensions to ISO CEdit

Name Notes Specification
void *memccpy(void *dest, const void *src, int c, size_t n); copies up to n bytes between two memory areas, which must not overlap, stopping when the byte c is found SVID, POSIX[2]
void *mempcpy(void *dest, const void *src, size_t n); variant of memcpy returning a pointer to the byte following the last written byte GNU
errno_t strcat_s(char *dest, size_t n, const char *src); bounds-checked variant of strcat ISO/IEC WDTR 24731
errno_t strcpy_s(char *dest, size_t n, const char *src); bounds-checked variant of strcpy ISO/IEC WDTR 24731
char *strdup(const char *src); allocates and duplicates a string into memory POSIX; originally a BSD extension
int strerror_r(int, char *, size_t); Puts the result of strerror() into the provided buffer in a thread-safe way. POSIX:2001
char *strerror_r(int, char *, size_t); Return strerror() in a thread-safe way. The provided buffer is used only if necessary (incompatible with POSIX version). GNU
size_t strlcat(char *dest, const char *src, size_t n); bounds-checked variant of strcat originally OpenBSD, now also FreeBSD, Solaris, Mac OS X
size_t strlcpy(char *dest, const char *src, size_t n); bounds-checked variant of strcpy originally OpenBSD, now also FreeBSD, Solaris, Mac OS X
char *strsignal(int sig); by analogy to strerror, returns string representation of the signal sig (not thread safe) POSIX:2008[3]
char *strtok_r(char *, const char *delim, char **saveptr); thread-safe and reentrant version of strtok[1] POSIX

ReferencesEdit

External linksEdit