> Date: 2026-07-31 23:18:54+0200 > From: Alejandro Colomar > > Hi! > > Here's a patch set for documenting mem*(3) and strn*(3) functions as > provided in . This should put a stop to the misunderstanding > and misuse of these functions as handling strings; they handle bytes and > nonstrings (and in some cases, strings can be used as nonstrings or as > byte arrays, but very carefully). > > This header is quite portable: {Free,Net,Open}BSD, glibc, and musl, at > least and since forever. > > The C Committee is discussing standardization of , so let's > give it a bump. Here's a draft of the proposal: --- Name alx-0097r1 - , the legitimate header for memcpy(3) et al. Principles - Avoid ambiguities - Codify existing practice to address evident deficiencies Category Revert regression; library Author Alejandro Colomar Cc: Mark Harris Cc: Nevin Liber Cc: JeanHeyd Meneide Cc: Joseph Myers Cc: Keith Bostic History r0 (2026-07-31): - Initial draft. r1 (2026-07-31): - Avoid cd(1). Rationale The standard mixes functions for handling strings, functions for handling bytes, and other hybrids, all in a single header file: . This has historically caused confusion, as for example leading to believe that strncpy(3) is appropriate to handle strings. Let's separate the standard clearly into three different header files that differentiate these APIs. System V It turns out that mem*() functions haven't been always in . These functions were first introduced in 1983 in System V, and were added in a separate file. Very soon, they were added to 4.3BSD in 1986 for compatibility to System V, also in . Most modern-day POSIX-compatible libc implementations still provide this header file for backwards compatibility reasons: $ find ~/src/bsd/freebsd/main/ | grep /include/memory.h /home/alx/src/bsd/freebsd/main/include/memory.h $ find ~/src/bsd/netbsd/trunk/ | grep /include/memory.h /home/alx/src/bsd/netbsd/trunk/include/memory.h $ find ~/src/bsd/openbsd/master/ | grep /include/memory.h /home/alx/src/bsd/openbsd/master/include/memory.h $ find ~/src/gnu/glibc/master/ | grep /include/memory.h /home/alx/src/gnu/glibc/master/include/memory.h $ find ~/src/musl/libc/master/ | grep /include/memory.h /home/alx/src/musl/libc/master/include/memory.h C89 It seems that it was C89 that moved the mem*() functions to , even though the Rationale document for C89 doesn't mention it at all. This was a huge mistake --we can see the consequences in the many misuses of these functions, and programmers that believe they are appropriate for uses that they are unappropriate-- that we can undo now. Design decisions To avoid breaking the world, let's provide the declarations of mem*() in both and the old-but-new . This will allow existing programs to continue working without changes. It will also allow new programs to use the more higienic header files. This is actually what is done by existing implementations, which provide the declarations in both header files. So, this is standardization of prior art. The strn*() functions didn't have their own separate header, but to avoid miususe, let's have a third header file for them. The name comes from the GCC [[gnu::nonstring]] attribute, which is used to refer to things that are somewhat similar to a string but aren't really a string (they are not necessarily NUL-terminated). Strings are valid nonstrings, but not the other way around. This is why some strn*() functions still work well on strings, such as strncmp(3). However, that shouldn't prevent moving them to this header file. Also, some strn*() functions work with strings in some parameters, while taking nonstrings in others. For example, strncat(3) takes a nonstring, and produces a string; and strncpy(3) takes a string (or a nonstring), and produces a nonstring. Let's put all of these in , so that will remain as a header file for functions that *exclusively* handle strings. Because is already more packed than , containing also stuff that would correspond to other headers (e.g., wcstol(3)), let's not split that one. A refactor of should entertain a much larger task, and create files such as , , , etc. Proposed wording Based on N3886. 7 Library @@ New subclause after 7.27 ("_Noreturn ") +7.<27+1> Memory handling +7.<27+1>.1 Memory function conventions @@ Copy 7.28.1p1 as 7.<27+1>.1p1, then: The header - + declares one type, several functions, -several type-generic functions, +one type-generic function, and defines two macros useful for manipulating -arrays of character type and other objects treated as arrays of character type. -328) +AAA) The type is size_t and one of the macros is NULL (both described in 7.22). Various methods are used for determining the lengths of the arrays, but in all cases a -char * or void * argument points to the initial (lowest addressed) character of the array. If an array is accessed beyond the end of an object, the behavior is undefined. + +AAA) + See "future library directions" (7.35.<17+1>) @@ p2 +2 + The macro + __STDC_VERSION_MEMORY_H__ + is an integer constant expression + with a value equivalent to 202ymmL. @@ ## Copy 7.28.1p3 as 7.<27+1>.1p3, verbatim. ## Copy 7.28.1p4 as 7.<27+1>.1p4, verbatim. +7.<27+1>.2 Copying functions ## Move 7.28.2.1 as 7.<27+1>.2.1 ("The memcpy function"). ## Move 7.28.2.2 as 7.<27+1>.2.2 ("The memccpy function"). ## Move 7.28.2.3 as 7.<27+1>.2.3 ("The memmove function"). +7.<27+1>.3 Comparison functions +7.<27+1>.3.1 General @@ Copy 7.28.4.1p1 as 7.<27+1>.3.1p1, then: The sign of a nonzero value returned by the comparison functions memcmp -, strcmp, and strncmp is determined by the sign of the difference between the values of the first pair of characters (both interpreted as unsigned char) that differ in the objects being compared. @@ ## Move 7.28.4.2 as 7.<27+1>.3.2 ("The memcmp function"). +7.<27+1>.4 Search functions +7.<27+1>.4.1 Introduction @@ Copy 7.28.5.1p1 as 7.<27+1>.4.1p1, then: The stateless search functions in this subclause (memchr -, strchr, strpbrk, strrchr, strstr ) are generic functions. These functions are generic in the qualification of the array to be searched and will return a result pointer to an element with the same qualification as the passed array. If the array to be searched is const-qualified, the result pointer will be to a const-qualified element. If the array to be searched is not const-qualified, -332) +BBB) the result pointer will be to an unqualified element. ## Copy footnote 332) as BBB), verbatim. @@ Copy 7.28.5.1p2 as 7.<27+1>.4.1p2, then: The external declarations of these generic functions have a concrete function type that returns a pointer to an unqualified element -( of type -char when specified as QChar, and void -when specified as QVoid -) , and accepts a pointer to a const-qualified array of the same type to search. This signature supports all correct uses. If the macro definition of any of these generic functions is suppressed to access an actual function, the external declaration with the corresponding concrete type is visible. -333) +CCC) @@ ## Copy footnote 333) as CCC), verbatim. ## Copy 7.28.5.1p3 as 7.<27+1>.4.1p3, verbatim. @@ ## Move 7.28.5.2 as 7.<27+1>.4.2 ("The memchr function"). +7.<27+1>.5 Miscellaneous functions ## Move 7.28.6.1 as 7.<27+1>.5.1 ("The memset function"). ## Move 7.28.6.2 as 7.<27+1>.5.2 ("The memset_explicit function"). 7.28 String handling @@ New subsection after title +7.28.<0+1> General +1 + The header + includes the headers and . @@ ## Move 7.28.1p2 as 7.28.<0+1>p2, verbatim. 7.28.1 String function conventions ## Delete p2 --moved elsewhere--. 7.28.2 Copying functions ## Delete 7.28.2.1 ("The memcpy function") --moved elsewhere--. ## Delete 7.28.2.2 ("The memccpy function") --moved elsewhere--. ## Delete 7.28.2.3 ("The memmove function") --moved elsewhere--. ## Delete 7.28.2.5 ("The strncpy function") --moved elsewhere--. ## Delete 7.28.2.7 ("The strndup function") --moved elsewhere--. 7.28.3 Concatenation functions @@ Title -Concatenation +Catenation @@ ## Delete 7.28.3.2 ("The strncat function") --moved elsewhere--. 7.28.4.1 Comparison functions :: General @@ p1 The sign of a nonzero value returned by the comparison functions +( -memcmp, strcmp -, and strncmp +) is determined by the sign of the difference between the values of the first pair of characters (both interpreted as unsigned char) that differ in the objects being compared. 7.28.4 Comparison functions ## Delete 7.28.4.2 ("The memcmp function") --moved elsewhere--. ## Delete 7.28.4.5 ("The strncmp function") --moved elsewhere--. 7.28.5.1 Search functions :: Introduction @@ p1 The stateless search functions in this subclause ( -memchr, strchr, strpbrk, strrchr, strstr ) are generic functions. These functions are generic in the qualification of the array to be searched and will return a result pointer to an element with the same qualification as the passed array. If the array to be searched is const-qualified, the result pointer will be to a const-qualified element. If the array to be searched is not const-qualified, 332) the result pointer will be to an unqualified element. @@ p2 The external declarations of these generic functions have a concrete function type that returns a pointer to an unqualified element -( of type char -when specified as QChar, -and void -when specified as QVoid -) , and accepts a pointer to a const-qualified array of the same type to search. This signature supports all correct uses. If the macro definition of any of these generic functions is suppressed to access an actual function, the external declaration with the corresponding concrete type is visible. 333) 7.28.5 Search functions ## Delete 7.28.5.2 ("The memchr function") --moved elsewhere--. 7.28.6 Miscellaneous functions ## Delete 7.28.6.1 ("The memset function") --moved elsewhere--. ## Delete 7.28.6.2 ("The memset_explicit function") --moved elsewhere--. ## Delete 7.28.6.5 ("The strnlen function") --moved elsewhere--. 7 Library @@ New subclause after 7.28 ("String handling "). +7.<28+1> Nonstring handling +7.<28+1>.1 Nonstring function conventions @@ Copy 7.28.1p1 as 7.<28+1>.1p1, then: The header - + declares one type, several functions, -several type-generic functions, and defines two macros useful for manipulating arrays of character type and other objects treated as arrays of character type. -328) +DDD) The type is size_t and one of the macros is NULL (both described in 7.22). Various methods are used for determining the lengths of the arrays, but in all cases a char * -or void * argument points to the initial (lowest addressed) character of the array. If an array is accessed beyond the end of an object, the behavior is undefined. + +DDD) + See "future library directions" (7.35.<18+1>) @@ p2 +2 + The macro + __STDC_VERSION_NONSTRING_H__ + is an integer constant expression + with a value equivalent to 202ymmL. @@ ## Copy 7.28.1p3 as 7.<28+1>.1p3, verbatim. ## Copy 7.28.1p4 as 7.<28+1>.1p4, verbatim. +7.<28+1>.2 Copying functions ## Move 7.28.2.5 as 7.<28+1>.2.1 ("The strncpy function"). ## Move 7.28.2.7 as 7.<28+1>.2.2 ("The strndup function"). +7.<28+1>.3 Catenation functions ## Move 7.28.3.2 as 7.<28+1>.3.1 ("The strncat function"). +7.<28+1>.4 Comparison functions +7.<28+1>.4.1 General @@ Copy 7.28.4.1p1 as 7.<28+1>.4.1p1, then: The sign of a nonzero value returned by the comparison functions -memcmp, strcmp, and +( strncmp +) is determined by the sign of the difference between the values of the first pair of characters (both interpreted as unsigned char) that differ in the objects being compared. @@ ## Move 7.28.4.5 as 7.<28+1>.4.2 ("The strncmp function"). +7.<28+1>.5 Miscellaneous functions ## Move 7.28.6.5 as 7.<28+1>.5.1 ("The strnlen function"). ## I've kept plurals in sections that only have one function. ## This is because we may add functions in the future, so it's ## better to keep the wording generic to avoid having to update ## it needlessly. --