diff options
Diffstat (limited to 'manual/string.texi')
| -rw-r--r-- | manual/string.texi | 154 |
1 files changed, 136 insertions, 18 deletions
diff --git a/manual/string.texi b/manual/string.texi index 0b667bd..24004f1 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -1081,7 +1081,7 @@ issues. @xref{Concatenating Strings}. @end deftypefun @deftypefun size_t strlcpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX-1.2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies the string @var{from} to the destination array @var{to}, limiting the result's size (including the null terminator) @@ -1114,21 +1114,23 @@ processing strings. Also, this function has a performance issue, as its time cost is proportional to the length of @var{from} even when @var{size} is small. -This function is derived from OpenBSD 2.4. +This function was originally derived from OpenBSD 2.4, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t wcslcpy (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX.1-2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is a variant of @code{strlcpy} for wide strings. The @var{size} argument counts the length of the destination buffer in wide characters (and not bytes). -This function is derived from BSD. +This function was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t strlcat (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX-1.2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function appends the string @var{from} to the string @var{to}, limiting the result's total size (including the null @@ -1156,17 +1158,19 @@ As noted below, this function is generally a poor choice for processing strings. Also, this function has significant performance issues. @xref{Concatenating Strings}. -This function is derived from OpenBSD 2.4. +This function was originally derived from OpenBSD 2.4, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t wcslcat (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size}) -@standards{BSD, string.h} +@standards{POSIX.1-2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is a variant of @code{strlcat} for wide strings. The @var{size} argument counts the length of the destination buffer in wide characters (and not bytes). -This function is derived from BSD. +This function was originally a BSD extension, but was added in +POSIX.1-2024. @end deftypefun Because these functions can abruptly truncate strings or wide strings, @@ -1798,6 +1802,15 @@ This function finds the first occurrence of the byte @var{c} (converted to an @code{unsigned char}) in the initial @var{size} bytes of the object beginning at @var{block}. The return value is a pointer to the located byte, or a null pointer if no match was found. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{block} has a type +that is a pointer to a @code{const}-qualified object type, +@code{memchr} returns @code{const void *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{void *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wmemchr (const wchar_t *@var{block}, wchar_t @var{wc}, size_t @var{size}) @@ -1807,6 +1820,15 @@ This function finds the first occurrence of the wide character @var{wc} in the initial @var{size} wide characters of the object beginning at @var{block}. The return value is a pointer to the located wide character, or a null pointer if no match was found. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{block} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wmemchr} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {void *} rawmemchr (const void *@var{block}, int @var{c}) @@ -1865,6 +1887,15 @@ When @code{strchr} returns a null pointer, it does not let you know the position of the terminating null byte it has found. If you need that information, it is better (but less portable) to use @code{strchrnul} than to search for it a second time. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{string} has a type +that is a pointer to a @code{const}-qualified object type, +@code{strchr} returns @code{const char *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{char *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcschr (const wchar_t *@var{wstring}, wchar_t @var{wc}) @@ -1880,6 +1911,15 @@ string, so you can use this function get a pointer to the end of a wide string by specifying a null wide character as the value of the @var{wc} argument. It would be better (but less portable) to use @code{wcschrnul} in this case, though. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{wstring} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wcschr} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {char *} strchrnul (const char *@var{string}, int @var{c}) @@ -1939,6 +1979,15 @@ For example, strrchr ("hello, world", 'l') @result{} "ld" @end smallexample + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{string} has a type +that is a pointer to a @code{const}-qualified object type, +@code{strrchr} returns @code{const char *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{char *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcsrchr (const wchar_t *@var{wstring}, wchar_t @var{wc}) @@ -1947,6 +1996,15 @@ strrchr ("hello, world", 'l') The function @code{wcsrchr} is like @code{wcschr}, except that it searches backwards from the end of the string @var{wstring} (instead of forwards from the front). + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{wstring} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wcsrchr} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {char *} strstr (const char *@var{haystack}, const char *@var{needle}) @@ -1965,6 +2023,15 @@ strstr ("hello, world", "l") strstr ("hello, world", "wo") @result{} "world" @end smallexample + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{haystack} has a type +that is a pointer to a @code{const}-qualified object type, +@code{strstr} returns @code{const char *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{char *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcsstr (const wchar_t *@var{haystack}, const wchar_t *@var{needle}) @@ -1975,6 +2042,15 @@ substring @var{needle} rather than just a single wide character. It returns a pointer into the string @var{haystack} that is the first wide character of the substring, or a null pointer if no match was found. If @var{needle} is an empty string, the function returns @var{haystack}. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{haystack} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wcsstr} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcswcs (const wchar_t *@var{haystack}, const wchar_t *@var{needle}) @@ -2008,14 +2084,15 @@ strcasestr ("hello, World", "wo") @deftypefun {void *} memmem (const void *@var{haystack}, size_t @var{haystack-len},@*const void *@var{needle}, size_t @var{needle-len}) -@standards{GNU, string.h} +@standards{POSIX.1-2024, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{strstr}, but @var{needle} and @var{haystack} are byte arrays rather than strings. @var{needle-len} is the length of @var{needle} and @var{haystack-len} is the length of @var{haystack}. -This function is a GNU extension. +This function was originally a GNU extension, but was added in +POSIX.1-2024. @end deftypefun @deftypefun size_t strspn (const char *@var{string}, const char *@var{skipset}) @@ -2099,6 +2176,15 @@ strpbrk ("hello, world", " \t\n,.;!?") In a multibyte string, characters consisting of more than one byte are not treated as single entities. Each byte is treated separately. The function is not locale-dependent. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{string} has a type +that is a pointer to a @code{const}-qualified object type, +@code{strpbrk} returns @code{const char *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{char *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @deftypefun {wchar_t *} wcspbrk (const wchar_t *@var{wstring}, const wchar_t *@var{stopset}) @@ -2109,6 +2195,15 @@ related to @code{wcscspn}, except that it returns a pointer to the first wide character in @var{wstring} that is a member of the set @var{stopset} instead of the length of the initial substring. It returns a null pointer if no such wide character from @var{stopset} is found. + +In ISO C23 and later, this function is qualifier-generic: +that is, it is also implemented as a function-like macro, +and when the macro is used and @var{wstring} has a type +that is a pointer to a @code{const}-qualified object type, +@code{wcspbrk} returns @code{const wchar_t *}. +As an obsolescent feature, if the macro is suppressed +the external function returns @code{wchar_t *} regardless. +The function is also qualifier-generic in C++. @end deftypefun @@ -2431,8 +2526,8 @@ heap object containing the sensitive data after it's deallocated. Since erasure is a precaution against bugs, this optimization is inappropriate. -The function @code{explicit_bzero} erases a block of memory, and -guarantees that the compiler will not remove the erasure as +The functions @code{explicit_bzero} and @code{memset_explicit} erase a +block of memory, and guarantee that the compiler will not remove the erasure as ``unnecessary.'' @smallexample @@ -2458,16 +2553,18 @@ void encrypt_with_phrase (const char *phrase, const char *in, In this example, if @code{memset}, @code{bzero}, or a hand-written loop had been used, the compiler might remove them as ``unnecessary.'' -@strong{Warning:} @code{explicit_bzero} does not guarantee that +@strong{Warning:} @code{explicit_bzero} and @code{memset_explicit} do +not guarantee that sensitive data is @emph{completely} erased from the computer's memory. There may be copies in temporary storage areas, such as registers and ``scratch'' stack space; since these are invisible to the source code, a library function cannot erase them. -Also, @code{explicit_bzero} only operates on RAM. If a sensitive data -object never needs to have its address taken other than to call -@code{explicit_bzero}, it might be stored entirely in CPU registers -@emph{until} the call to @code{explicit_bzero}. Then it will be +Also, @code{explicit_bzero} and @code{memset_explicit} only operate on +RAM. If a sensitive data object never needs to have its address taken +other than to call @code{explicit_bzero} or @code{memset_explicit}, it +might be stored entirely in CPU registers @emph{until} the call to +@code{explicit_bzero} or @code{memset_explicit}. Then it will be copied into RAM, the copy will be erased, and the original will remain intact. Data in RAM is more likely to be exposed by a bug than data in registers, so this creates a brief window where the data is at @@ -2484,10 +2581,12 @@ variable itself is not @code{volatile}, some compilers will ignore the qualification on the pointer and remove the erasure anyway. Having said all that, in most situations, using @code{explicit_bzero} +or @code{memset_explicit} is better than not using it. At present, the only way to do a more thorough job is to write the entire sensitive operation in assembly language. We anticipate that future compilers will recognize calls to -@code{explicit_bzero} and take appropriate steps to erase all the +@code{explicit_bzero} or @code{memset_explicit} and take appropriate +steps to erase all the copies of the affected data, wherever they may be. @deftypefun void explicit_bzero (void *@var{block}, size_t @var{len}) @@ -2515,6 +2614,25 @@ functionality under a different name, such as @code{explicit_memset}, systems it may be in @file{strings.h} instead. @end deftypefun +@deftypefun {void *} memset_explicit (void *@var{block}, int @var{c}, size_t @var{size}) +@standards{C23, string.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +This function copies the value of @var{c} (converted to an +@code{unsigned char}) into each of the first @var{size} bytes of the +object beginning at @var{block}, just as @code{memset} would. It +returns the value of @var{block}. The bytes are always written, even +if the compiler could determine that this is ``unnecessary'' because +no correct program could read them back. + +@strong{Note:} The @emph{only} optimization that @code{memset_explicit} +disables is removal of ``unnecessary'' writes to memory. The compiler +can perform all the other optimizations that it could for a call to +@code{memset}. For instance, it may replace the function call with +inline memory writes, and it may assume that @var{block} cannot be a +null pointer. +@end deftypefun + @node Shuffling Bytes @section Shuffling Bytes |