| C standard library (libc) |
|---|
| General topics |
| Miscellaneous headers |
TheC programming language has a set of functions implementing operations onstrings (character strings and byte strings) in itsstandard library. Various operations, such as copying,concatenation,tokenization and searching are supported. For character strings, the standard library uses the convention that strings arenull-terminated: a string ofn characters is represented as anarray ofn + 1 elements, the last of which is a "NUL character" with numeric value 0.
The only support for strings in the programming language proper is that the compiler translates quotedstring constants into null-terminated strings.
A string is defined as a contiguous sequence ofcode units terminated by the first zero code unit (often called theNUL code unit).[1] This means a string cannot contain the zero code unit, as the first one seen marks the end of the string. Thelength of a string is the number of code units before the zero code unit.[1] The memory occupied by a string is always one more code unit than the length, as space is needed to store the zero terminator.
Generally, the termstring means a string where the code unit is of typechar, which is exactly 8 bits on all modern machines.C90 defineswide strings[1] which use a code unit of typewchar_t, which is 16 or 32 bits on modern machines. This was intended forUnicode but it is increasingly common to useUTF-8 in normal strings for Unicode instead.
Strings are passed to functions by passing a pointer to the first code unit. Sincechar* andwchar_t* are different types, the functions that process wide strings are different than the ones processing normal strings and have different names.
String literals ("text" in the C source code) are converted to arrays (char[] in C, orconst char[] in C++) during compilation.[2] The result is an array of code units containing all the characters plus a trailing zero code unit. In C90L"text" produces a wide string. A string literal can contain the zero code unit (one way is to put\0 into the source), but this will cause the string to end at that point. The rest of the literal will be placed in memory (with another zero code unit added to the end) but it is impossible to know those code units were translated from the string literal, therefore such source code isnot a string literal.[3]
Each string ends at the first occurrence of the zero code unit of the appropriate kind (char orwchar_t). Consequently, a byte string (char*) can contain non-NUL characters inASCII or anyASCII extension, but not characters in encodings such asUTF-16 (even though a 16-bit code unit might be nonzero, its high or low byte might be zero). The encodings that can be stored in wide strings are defined by the width ofwchar_t. In most implementations,wchar_t is at least 16 bits, and so all 16-bit encodings, such asUCS-2, can be stored. Ifwchar_t is 32-bits, then 32-bit encodings, such asUTF-32, can be stored. (The standard requires a "type that holds any wide character", which on Windows no longer holds true since the UCS-2 to UTF-16 shift. This was recognized as a defect in the standard and fixed in C++.)[4] C++11 andC11 add two types with explicit widthschar16_t andchar32_t.[5]
Variable-width encodings can be used in both byte strings and wide strings. String length and offsets are measured in bytes orwchar_t, not in "characters", which can be confusing to beginning programmers.UTF-8 andShift JIS are often used in C byte strings, whileUTF-16 is often used in C wide strings whenwchar_t is 16 bits. Truncating strings with variable-width characters using functions likestrncpy can produce invalid sequences at the end of the string. This can be unsafe if the truncated parts are interpreted by code that assumes the input is valid.
Support for Unicode literals such ascharfoo[512]="φωωβαρ"; (UTF-8) orwchar_tfoo[512]=L"φωωβαρ"; (UTF-16 or UTF-32, depends onwchar_t) is implementation defined,[6] and may require that the source code be in the same encoding, especially forchar where compilers might just copy whatever is between the quotes. Some compilers or editors will require entering all non-ASCII characters as\xNN sequences for each byte of UTF-8, and/or\uNNNN for each word of UTF-16. Since C11 (and C++11), a new literal prefixu8 is available that guarantees UTF-8 for a bytestring literal, as incharfoo[512]=u8"φωωβαρ";.[7] SinceC++20 andC23, achar8_t type was added that is meant to store UTF-8 characters and the types of u8 prefixed character and string literals were changed tochar8_t andchar8_t[] respectively.
In historical documentation the term "character" was often used instead of "byte" for C strings, which leads many[who?] to believe that these functions somehow do not work forUTF-8. In fact all lengths are defined as being in bytes and this is true in all implementations, and these functions work as well with UTF-8 as with single-byte encodings. The BSD documentation has been fixed to make this clear, but POSIX, Linux, and Windows documentation still uses "character" in many places where "byte" or "wchar_t" is the correct term.
Functions for handling memory buffers can process sequences of bytes that include null-byte as part of the data. Names of these functions typically start withmem, as opposite to thestr prefix.
Most of the functions that operate on C strings are declared in thestring.h header (cstring in C++), while functions that operate on C wide strings are declared in thewchar.h header (cwchar in C++). These headers also contain declarations of functions used for handling memory buffers; the name is thus something of a misnomer.
Functions declared instring.h are extremely popular since, as a part of theC standard library, they are guaranteed to work on any platform which supports C. However, some security issues exist with these functions, such as potentialbuffer overflows when not used carefully and properly, causing the programmers to prefer safer and possibly less portable variants, out of which some popular ones are listed below. Some of these functions also violateconst-correctness by accepting aconst string pointer and returning a non-const pointer within the string. To correct this, some have been separated into twooverloaded functions in the C++ version of the standard library.
| Name | Notes |
|---|---|
| NULL | Macro expanding to thenull pointer constant; that is, a constant representing a pointer value which is guaranteednot to be a valid address of an object in memory. |
| wchar_t | Type used for acode unit in "wide" strings. The C standard only requires thatwchar_t be wide enough to hold the widest character set among the supported systemlocales[8] and be greater or equal in size tochar.[9] OnWindows, the only platform to usewchar_t extensively, it's defined as 16-bit[10] whichwas enough to represent anyUnicode (UCS-2) character, but is now only enough to represent aUTF-16 code unit, which can be half a code point. On other platforms it is defined as 32-bit and a Unicode code point always fits. This difference makes code usingwchar_t non-portable. |
| wint_t | Integer type that can hold any value of a wchar_t as well as the value of the macro WEOF. Usually a 32 bit signed value. |
| char8_t[11] | Part of the C standard since C23, in<uchar.h>, a type that is suitable for storing UTF-8 characters.[12] |
| char16_t[13] | Part of the C standard sinceC11,[14] in<uchar.h>, a type capable of holding 16 bits even ifwchar_t is another size. If the macro__STDC_UTF_16__ is defined as1, the type is used for UTF-16 on that system. This is always the case in C23.[15] C++ does not define such a macro, but the type is always used for UTF-16 in that language.[16] |
| char32_t[13] | Part of the C standard since C11,[17] in<uchar.h>, a type capable of holding 32 bits even ifwchar_t is another size. If the macro__STDC_UTF_32__ is defined as1, the type is used for UTF-32 on that system. This is always the case in C23.[15] C++ does not define such a macro, but the type is always used for UTF-32 in that language.[16] |
| mbstate_t | Contains all the information about the conversion state required from one call to a function to the other. |
| Byte string | Wide string | Description[note 1] | |
|---|---|---|---|
| String manipulation | strcpy[18] | wcscpy[19] | Copies one string to another |
| strncpy[20] | wcsncpy[21] | Writes exactlyn bytes, copying from source or adding nulls | |
| strcat[22] | wcscat[23] | Appends one string to another | |
| strncat[24] | wcsncat[25] | Appends no more thann bytes from one string to another | |
| strxfrm[26] | wcsxfrm[27] | Transforms a string according to the current locale | |
| String examination | strlen[28] | wcslen[29] | Returns the length of the string |
| strcmp[30] | wcscmp[31] | Compares two strings (three-way comparison) | |
| strncmp[32] | wcsncmp[33] | Compares a specific number of bytes in two strings | |
| strcoll[34] | wcscoll[35] | Compares two strings according to the current locale | |
| strchr[36] | wcschr[37] | Finds the first occurrence of a byte in a string | |
| strrchr[38] | wcsrchr[39] | Finds the last occurrence of a byte in a string | |
| strspn[40] | wcsspn[41] | Returns the number of initial bytes in a string that are in a second string | |
| strcspn[42] | wcscspn[43] | Returns the number of initial bytes in a string that are not in a second string | |
| strpbrk[44] | wcspbrk[45] | Finds in a string the first occurrence of a byte in a set | |
| strstr[46] | wcsstr[47] | Finds the first occurrence of a substring in a string | |
| strtok[48] | wcstok[49] | Splits a string into tokens | |
| Miscellaneous | strerror[50] | — | Returns a string containing a message derived from anerror code |
| Memory manipulation | memset[51] | wmemset[52] | Fills a buffer with a repeated byte. SinceC23,memset_explicit() was added to erase sensitive data. |
| memcpy[53] | wmemcpy[54] | Copies one buffer to another. SinceC23,memccpy() was added to efficiently concatenate strings. | |
| memmove[55] | wmemmove[56] | Copies one buffer to another, possibly overlapping, buffer | |
| memcmp[57] | wmemcmp[58] | Compares two buffers (three-way comparison) | |
| memchr[59] | wmemchr[60] | Finds the first occurrence of a byte in a buffer | |
| |||
| Name | Description |
|---|---|
| mblen[61] | Returns the number of bytes in the next multibyte character |
| mbtowc[62] | Converts the next multibyte character to a wide character |
| wctomb[63] | Converts a wide character to its multibyte representation |
| mbstowcs[64] | Converts a multibyte string to a wide string |
| wcstombs[65] | Converts a wide string to a multibyte string |
| btowc[66] | Converts a single-byte character to wide character, if possible |
| wctob[67] | Converts a wide character to a single-byte character, if possible |
| mbsinit[68] | Checks if a state object represents initial state |
| mbrlen[69] | Returns the number of bytes in the next multibyte character, given state |
| mbrtowc[70] | Converts the next multibyte character to a wide character, given state |
| wcrtomb[71] | Converts a wide character to its multibyte representation, given state |
| mbsrtowcs[72] | Converts a multibyte string to a wide string, given state |
| wcsrtombs[73] | Converts a wide string to a multibyte string, given state |
| mbrtoc8[74] | Converts the next multibyte character to a UTF-8 character, given state |
| c8rtomb[75] | Converts a single code point from UTF-8 to a narrow multibyte character representation, given state |
| mbrtoc16[76] | Converts the next multibyte character to a UTF-16 character, given state |
| c16rtomb[77] | Converts a single code point from UTF-16 to a narrow multibyte character representation, given state |
| mbrtoc32[78] | Converts the next multibyte character to a UTF-32 character, given state |
| c32rtomb[79] | Converts a single code point from UTF-32 to a narrow multibyte character representation, given state |
These functions all need ambstate_t object, originally in static memory (making the functions not be thread-safe) and in later additions the caller must maintain. This was originally intended to track shift states in themb encodings, but modern ones such as UTF-8 do not need this. However these functions were designed on the assumption that thewc encoding is not avariable-width encoding and thus are designed to deal with exactly onewchar_t at a time, passing it by value rather than using a string pointer. As UTF-16 is a variable-width encoding, thembstate_t has been reused to keep track of surrogate pairs in the wide encoding, though the caller must still detect and callmbtowc twice for a single character.[80][81][82] Later additions to the standard admit that the only conversion programmers are interested in is between UTF-8 and UTF-16 and directly provide this.
| Byte string | Wide string | Description[note 1] |
|---|---|---|
| atof[83] | — | converts a string to a floating-point value ('atof' means 'ASCII to float') |
| atoi atol atoll[84] | — | converts a string to an integer (C99) ('atoi' means 'ASCII to integer') |
| strtof (C99)[85] strtod[86] strtold (C99)[87] | wcstof (C99)[88] wcstod[89] wcstold (C99)[90] | converts a string to a floating-point value |
| strtol strtoll[91] | wcstol wcstoll[92] | converts a string to a signed integer |
| strtoul strtoull[93] | wcstoul wcstoull[94] | converts a string to an unsigned integer |
| ||
The C standard library contains several functions for numeric conversions. The functions that deal with byte strings are defined in thestdlib.h header (cstdlib header in C++). The functions that deal with wide strings are defined in thewchar.h header (cwchar header in C++).
The functionsstrchr,bsearch,strpbrk,strrchr,strstr,memchr and their wide counterparts are notconst-correct, since they accept aconst string pointer and return a non-const pointer within the string. This has been fixed inC23.[95]
Also, since the Normative Amendment 1 (C95),atoxx functions are considered subsumed bystrtoxxx functions, for which reason neither C95 nor any later standard provides wide-character versions of these functions. The argument againstatoxx is that they do not differentiate between an error and a0.[96]
| Name | Source | Description |
|---|---|---|
| bzero[97][98] | BSD | Fills a buffer with zero bytes, deprecated bymemset |
| memccpy[99] | SVID | Part of the C standard sinceC23, copies between two non-overlapping memory areas, stopping when a given byte is found. |
| mempcpy[100] | GNU | a variant ofmemcpy returning a pointer to the byte following the last written byte |
| strcasecmp[101] | BSD | case-insensitive version ofstrcmp |
| strcat_s[102] | Windows | a variant ofstrcat that checks the destination buffer size before concatenation |
| strcpy_s[103] | Windows | a variant ofstrcpy that checks the destination buffer size before copying |
| strdup &strndup[104] | POSIX | Part of the C standard since C23, allocates and duplicates a string |
| strerror_r[105] | POSIX 1, GNU | a variant ofstrerror that is thread-safe. The GNU version is incompatible with the POSIX one. |
| stricmp[106] | Windows | case-insensitive version ofstrcmp |
| strlcpy[107] | BSD | a variant ofstrcpy that truncates the result to fit in the destination buffer[108] |
| strlcat[107] | BSD | a variant ofstrcat that truncates the result to fit in the destination buffer[108] |
| strsignal[109] | POSIX:2008 | returns string representation of asignal code. Not thread safe. |
| strtok_r[110] | POSIX | a variant ofstrtok that is thread-safe |
Despitethe well-established need to replacestrcat[22] andstrcpy[18] with functions that do not allow buffer overflows, no accepted standard has arisen. This is partly due to the mistaken belief by many C programmers thatstrncat andstrncpy have the desired behavior; however, neither function was designed for this (they were intended to manipulate null-padded fixed-size string buffers, a data format less commonly used in modern software), and the behavior and arguments are non-intuitive and often written incorrectly even by expert programmers.[108]
The most popular[a] replacement are thestrlcat[111] andstrlcpy[112] functions, which appeared inOpenBSD 2.4 in December, 1998.[108] These functions always write one NUL to the destination buffer, truncating the result if necessary, and return the size of buffer that would be needed, which allows detection of the truncation and provides a size for creating a new buffer that will not truncate. For a long time they have not been included in theGNU C library (used by software on Linux), on the basis of allegedly being inefficient,[113] encouraging the use of C strings (instead of some superior alternative form of string),[114][115] and hiding other potential errors.[116][117] Even while glibc hadn't added support, strlcat and strlcpy have been implemented in a number of other C libraries including ones for OpenBSD,FreeBSD,NetBSD,Solaris,OS X, andQNX, as well as in alternative C libraries for Linux, such aslibbsd, introduced in 2008,[118] andmusl, introduced in 2011,[119][120] and the source code added directly to other projects such asSDL,GLib,ffmpeg,rsync, and even internally in theLinux kernel. This did change in 2024, theglibc FAQ notes that as of glibc 2.38, the code has been committed[121] and thereby added.[122] These functions were standardized as part of POSIX.1-2024,[123] the Austin Group Defect TrackerID 986 tracked some discussion about such plans for POSIX.
As part of its 2004Security Development Lifecycle, Microsoft introduced a family of "secure" functions includingstrcpy_s andstrcat_s (along with many others).[124] These functions were standardized with some minor changes as part of the optionalC11 (Annex K) proposed by ISO/IEC WDTR 24731.[125] These functions perform various checks including whether the string is too long to fit in the buffer. If the checks fail, a user-specified "runtime-constraint handler" function is called,[126] which usually aborts the program.[127][128] These functions attracted considerable criticism because initially they were implemented only on Windows and at the same time warning messages started to be produced byMicrosoft Visual C++ suggesting use of these functions instead of standard ones. This has been speculated by some to be an attempt by Microsoft to lock developers into its platform.[129] Experience with these functions has shown significant problems with their adoption and errors in usage, so the removal of Annex K was proposed for the next revision of the C standard.[130] Usage ofmemset_s has been suggested as a way to avoid unwanted compiler optimizations.[131][132]
strlcpy, versus 38,644 uses ofstrcpy_s (and 15,286,150 uses ofstrcpy).[citation needed]{{cite web}}: CS1 maint: location (link){{cite web}}: CS1 maint: location (link){{cite web}}: CS1 maint: location (link){{cite web}}: CS1 maint: location (link)This [strlcpy and strlcat] API has been adopted by most modern operating systems and many standalone software packages [...]. The notable exception is the GNU standard C library, glibc, whose maintainer steadfastly refuses to include these improved APIs, labelling them "horribly inefficient BSD crap", despite prior evidence that they are faster is most cases than the APIs they replace.
Correct string handling means that you always know how long your strings are and therefore you can you memcpy (instead of strcpy).
strlcpy(3) – Linux Library FunctionsManual from ManKier.com "However, one may question the validity of such optimizations, as they defeat the whole purpose of strlcpy() and strlcat(). As a matter of fact, the first version of this manual page got it wrong."{{cite web}}: CS1 maint: location (link){{cite web}}: CS1 maint: location (link)memset_s(3) – FreeBSD Library FunctionsManual
| Features | |||||
|---|---|---|---|---|---|
| Standard library |
| ||||
| Compilers | |||||
| IDEs | |||||
| Comparison with other languages | |||||
| Descendant languages | |||||
| Designer | |||||
