C Programming/string.h/Function reference

Synopsis
The memset copies c into each of the n first bytes of the object pointed to by s.

Return value
The function returns the pointer s. There is no defined value to return when an error occurs.

Source

 * | Definition of memset from OpenGroup

strcat
In computing, the C programming language offers a library function called strcat that allows one memory block to be appended to another memory block. Both memory blocks are required to be null-terminated. Since, in C, strings are not first-class datatypes, and are implemented as blocks of ASCII bytes in memory, strcat will effectively append one string to another given two pointers to blocks of allocated memory. The name strcat is an abbreviation of "string concatenate". strcat is found in the string.h header file.

For example:

Here is a possible implementation of strcat:

It can also be defined in terms of other string library functions:

Bounds errors
strcat can be dangerous because if the string to be appended is too long to fit in the destination buffer, it will overwrite adjacent memory, invoking undefined behavior. Usually the program will simply cause a segmentation fault when this occurs, but a skilled attacker can use such a buffer overflow to break into a system (see computer security).

Bounds checking variants
To prevent buffer overflows, several alternatives for strcat have been used. All of them take an extra argument which encodes the length of the destination buffer and will not write past that buffer end. All of them can still result in buffer overflows if an incorrect length is provided.

strncat
char* strncat(char* dst, const char* src, size_t n);

The most common bounded variant, <tt>strncat</tt>, only appends a specified number of bytes, plus a NULL byte. This allows each concatenated string to use no more than its "share" of a buffer and was perhaps intended to make tables. It is poorly suited to the more common need of getting the prefix of the concatenated string that fits in the buffer. For this the proper value to pass for the count is <tt>bufferSize-strlen(buffer)-1</tt>. Common mistakes are to pass <tt>bufferSize</tt>, <tt>bufferSize-1</tt>, and <tt>bufferSize-strlen(buffer)</tt>, all of which can still produce a buffer overflow.

strlcat
size_t strlcat(char* dst, const char* src, size_t size);

The <tt>strlcat</tt> function, created by OpenBSD developers Todd C. Miller and Theo de Raadt, is often regarded as a safer and more useful version of <tt>strncat</tt>. It takes the actual length of the buffer as an argument, and returns the number of bytes that would be needed allowing the caller to reallocate the buffer if possible. It has been ported to a number of operating systems, but notably rejected by glibc maintainers, who suggest that C programmers need to keep track of string length and that "using this function only leads to other errors."

strcat_s
errno_t strcat_s(char* dst, rsize_t size, const char* src);

The  function, proposed for standardisation in ISO/IEC TR 24731,  is supported by the Microsoft C Runtime Library. and some other C libraries. It returns non-zero if the source string does not fit, and sets the buffer to the empty string (a disastrous result if the original string is not stored elsewhere or if the caller ignores the return result). It is also explicitly unsupported by some libraries, including the GLibc library. Warning messages produced by Microsoft's compilers suggesting programmers change <tt>strcat</tt> and <tt>strncat</tt> to this function have been speculated by some to be a Microsoft attempt to lock developers to its platform.

strchr
Function name strchr for C and C++

Syntax

include <string.h>

char *strchr(const char *s, int c);

Description

The strchr function locates the first occurrence of c, cast to char, in the string pointed to by s. The terminating null character is considered a part of the string.

Parameters

s Points to the string to be searched.

c Is the character to search for in string s.

Return Values

The strchr function returns a pointer to the first occurrence of character c located within s. If character c does not occur in the string, strchr returns a null pointer.

strcmp
In POSIX and in the programming language C,  is a function in the C standard library (declared in  ) that compares two C strings.

The prototype according ISO/IEC 9899:1999, 7.21.4.2

returns 0 when the strings are equal, a negative integer when  is less than , or a positive integer if   is greater than  , according to the lexicographical order.

A variant of  exists called   that only compares the strings up to a certain offset.

Another variant,, conforming to POSIX.1-2001, works like  , but is case-insensitive. Some systems instead provide this functionality with functions named  or. To compare a subset of both strings with case-insensitivity, various systems may provide,   or.

Example
The above code is a working sample that prints whether the first argument is less than, equal to or greater than the second.

A possible implementation is (P.J. Plauger, The Standard C Library, 1992): However, most real-world implementations will have various optimization tricks to reduce the execution time of the function. One will notice, that strcmp not only returns -1, 0 and +1, but also other negative or positive values, resulting from optimizing away the branching introduced by the  operator:

strcpy
The C programming language offers a library function called <tt>strcpy</tt>, defined in the string.h header file, that allows null-terminated memory blocks to be copied from one location to another. Since strings in C are not first-class data types and are implemented instead as contiguous blocks of bytes in memory, <tt>strcpy</tt> will effectively copy strings given two pointers to blocks of allocated memory.

The prototype of the function is: The argument order mimics that of an assignment: destination "=" source. The return value is.

Usage and implementation
For example In the second line memory is allocated to hold the copy of the string, then the string is copied from one memory block into the other, then the first letter of that copy is modified.

Although the simple assignment <tt>str2 = str1</tt> might appear to do the same thing, it only copies the memory address of <tt>str1</tt> into <tt>str2</tt> but not the actual string. Both <tt>str1</tt> and <tt>str2</tt> would refer to the same memory block, and the allocated block that used to be pointed to by <tt>str2</tt> would be lost. The assignment to str2[0] would either also modify str1, or it would cause an access violation (as modern compilers often place the string constants in read-only memory).

The <tt>strcpy</tt> function performs a copy by iterating over the individual characters of the string and copying them one by one. An explicit implementation of <tt>strcpy</tt> is:

A common compact implementation is:

Modern versions provided by C libraries often copy far more than one byte at a time, relying on bit math to detect if the larger word has a null byte before writing it. Often a call compiles into an inline machine instruction specifically designed to do <tt>strcpy</tt>.

Unicode
<tt>strcpy</tt> will work for all common byte encodings of Unicode strings, including UTF-8. There is no need to actually know the encoding as long as the null byte is never used by it.

If Unicode is encoded in units larger than a byte, such as UTF-16, then a different function is needed, as null bytes will occur in parts of the larger code units. C99 defines the function <tt>wcscpy</tt>, which will copy <tt>wchar_t</tt>-sized objects and stop at the first one with a zero value. This is not as useful as it appears, as different computer platforms disagree on how large a <tt>wchar_t</tt> is (some use 16 bits and some 32 bits).

Buffer overflows
<tt>strcpy</tt> can be dangerous because if the string to be copied is too long to fit in the destination buffer, it will overwrite adjacent memory, invoking undefined behavior. Usually the program will simply cause a segmentation fault when this occurs, but a skilled attacker can use buffer overflow to break into a system. To prevent buffer overflows, several alternatives for <tt>strcpy</tt> have been used. All of them take an extra argument which is the length of the destination buffer and will not write past that buffer end. All of them can still result in buffer overflows if an incorrect length is provided.

strncpy
char* strncpy(char* dst, const char* src, size_t size);

<tt>strncpy</tt> writes exactly the given number of bytes, either only copying the start of the string if it is too long, or adding zeros to the end of the copy to fill the buffer. It was introduced into the C library to deal with fixed-length name fields in structures such as directory entries. Despite its name it is not a bounded version of <tt>strcpy</tt>; it does not guarantee that the result is a null-terminated string. The name of the function is misleading because <tt>strncat</tt> and <tt>snprintf</tt> are respectively bounded versions of <tt>strcat</tt> and <tt>sprintf</tt>.

The assumption that the result is a null-terminated string leads to two problems. If the source string is too long, the result is not null-terminated, making data after the end of the buffer appear to be part of the string. And if the source string is much shorter than the buffer, considerable time will be wasted filling the rest of the buffer with null bytes.

An alternative from the standard C library that will always append one null byte is to use strncat with an initially empty string as the destination.

strlcpy
size_t strlcpy(char* dst, const char* src, size_t size);

The <tt>strlcpy</tt> function, created by OpenBSD developers Todd C. Miller and Theo de Raadt, is often regarded as a safer version of <tt>strncpy</tt>. It always adds a single null byte, and returns the number of bytes that would be needed, allowing the caller to reallocate the buffer if possible. It has been ported to a number of operating systems, but notably rejected by Ulrich Drepper, the glibc maintainer, who suggests that C programmers need to keep track of string length and that "using this function only leads to other errors."

strcpy_s
errno_t strcpy_s(char* dst, rsize_t size, const char* src);

The  function, proposed for standardisation in ISO/IEC TR 24731,  is supported by the Microsoft C Runtime Library and some other C libraries. It returns non-zero if the source string does not fit, and sets the buffer to the empty string (not the prefix!). It is also explicitly unsupported by some libraries, including the GNU C library. Warning messages produced by Microsoft's compilers suggesting programmers change <tt>strcpy</tt> and <tt>strncpy</tt> to this function have been speculated by some to be a Microsoft attempt to lock developers to its platform.

strcspn
strcspn is the function from the C standard library (header file string.h).

It searches the string for certain set of characters.

The strcspn function calculates the length of initial segment of string 1 which does not contain any character from string 2.

Return Value
This function returns the index of first character in string 1 that matches with any character of string 2.

Example
Output:

The first decimal digit of s is at position: 10

strerror
The string-error function, strerror, is a C/C++ function which translates an error code, usually stored in the global variable errno, to a human-readable error message.

History
The strerror function is defined in IEEE Std 1003.1, also known as POSIX 1.

Reentrancy
The strerror function is not reentrant. For a reentrant version of the function, see strerror r.

Semantics
The function generates and reports a C-style string, containing an error message derived from the error code passed in with errnum.

strlen
In the C standard library, <tt>strlen</tt> is a string function that determines the length of a C character string.

Example usage
This program will print the value 11, which is the length of the string "Hello World". Character strings are stored in an array of a data type called <tt>char</tt>. The end of a string is found by searching for the first null character in the array.

Note importantly that this length does *NOT* include the array entry for the trailing null byte required for the ending character of C strings. Thus, if you need to copy the C string, you need to allocate a space of strlen + 1.

Implementation
FreeBSD 6.2 implements <tt>strlen</tt> like so:

It is possible to write faster versions in C that examines full machine word rather than byte-by-byte. Hacker's Delight has given an algorithm that makes use of bitwise operations to detect if any of these bytes is nul ('\0'). The current FreeBSD implementation does this.

Modern C compilers usually provide fast inline versions of <tt>strlen</tt> written in assembly, either using the bitwise operation technique or a special instruction provided by certain CISC processors. In addition, <tt>strlen</tt> of a quoted string constant is often optimized into a constant integer.

strrchr
strrchr is function in string.h. It is mainly used to locate last occurrence of character in string, searching from the end. It returns a pointer to the last occurrence of character in the C string str. The terminating null-character is considered part of the C string. Therefore, it can also be located to retrieve a pointer to the end of a string.

Syntax
In C, this function is declared as:

char *strrchr ( const char *, int );

str is a C string. character is the character to be located. It is passed as its int promotion, but it is internally converted back to char.

Return value
A pointer to the last occurrence of character in str. If the value is not found, the function returns a null pointer.

Example
Output : Last occurrence of 's' found at 18.

strspn
strspn function is used to find out the length of substring or length of maximum initial segment of the string pointed to by one string, let's say s1 containing all characters from another string pointed to by another string say s2., while strscpn is used to discover the length of initial segment containing all elements not in the reject list.

Syntax
size_t strspn(const char *s, const char *accept);

size_t strcspn(const char *s, const char *reject);

Parameters
s1- It points to null-terminated string to be searched.

s2- It points to null-terminated set of characters.

strstr
<tt>strstr</tt> is a C standard library string function as defined in <tt>string.h</tt>. <tt>strstr</tt> has the function signature <tt>char * strstr(const char *haystack, const char *needle);</tt> which returns a pointer to a character at the first index where <tt>needle</tt> is in <tt>haystack</tt>, or NULL if not present.

The <tt>strcasestr</tt> is a function much like <tt>strstr</tt> except that it ignores the case of both <tt>needle</tt> and <tt>haystack</tt>. <tt>strcasestr</tt> is a non-standard function while <tt>strstr</tt> conforms to C89 and C99.

Example
<tt>cptr</tt> is now a pointer to the sixth letter (<tt>e</tt>) in "wikipedia".

strtok
strtok is one of the C-library function. The syntax of strtok function is as follow: Syntax:

Description: The strtok function returns a pointer to the next "token" in str1, where str2 contains the delimiters that determine the token. strtok returns NULL if no token is found. In order to convert a string to tokens, the first call to strtok should have str1 point to the string to be tokenized. All calls after this should have str1 be NULL.

strxfrm
  is a C Standard Library string function declared in string.h. It transforms string according to the current locale setting.

The prototype of this function is: size_t strxfrm(char *str1, const char *str2 , size_t num);

str1
is the string which receives num characters of transformed string. If num is equal to zero then str1 contains only null character.

str2
is the string which is to be transformed.

num
is the maximum number of characters which to be copied into str1.

Description
strxfrm function transforms str2 according to the current locale setting.For that LC_COLLATE category is used which is defined in locale.h. After transformation, the first num characters of the transformed string is copied into str1. strxfrm function performs transformation in such a way that result of strcmp on two strings is the same as result of strcoll on two original strings.

Return Value
strxfrm function returns length of transformed string excluding terminating null character.

Output
The length of str2 = 11

The content of str1 = Hell

The content of str2 = Hello World