]> Savannah Git Hosting - gnulib.git/commitdiff
doc: improve documentation for malloc, realloc etc
authorPaul Eggert <eggert@cs.ucla.edu>
Tue, 5 Nov 2024 23:57:20 +0000 (15:57 -0800)
committerPaul Eggert <eggert@cs.ucla.edu>
Tue, 5 Nov 2024 23:58:25 +0000 (15:58 -0800)
doc/posix-functions/calloc.texi
doc/posix-functions/malloc.texi
doc/posix-functions/realloc.texi
doc/posix-functions/reallocarray.texi
doc/posix-functions/strdup.texi

index ecd8b227c0ef8ae67ff638d0c5e47c5f42c77bdd..37e6e008b58ee6426fa5a99518fbf174bbc2ad2a 100644 (file)
@@ -10,9 +10,15 @@ Gnulib module: calloc-posix
 Portability problems fixed by Gnulib:
 @itemize
 @item
-Upon failure, the function does not set @code{errno} to @code{ENOMEM} on
-some platforms:
-mingw, MSVC 14, Solaris 11.4.
+On some platforms, when the function fails it does not set @code{errno}:
+mingw, MSVC 14.
+
+@item
+On some platforms, when the function fails it might set @code{errno}
+to @code{EAGAIN} instead of to @code{ENOMEM}. Although POSIX allows
+@code{EAGAIN}, the @code{calloc-posix} module insists on @code{ENOMEM}
+which also conforms to POSIX and is GNU-compatible:
+Solaris 11.4.
 
 @item
 On some platforms, @code{calloc (n, s)} can succeed even if
index 6a6f3c1059e4c49a21276fc4088efcfb53b2235e..0b552bdf677c310efd73add6fdd6f0d0b5e8d7ba 100644 (file)
@@ -10,9 +10,15 @@ Gnulib module: malloc-posix
 Portability problems fixed by Gnulib:
 @itemize
 @item
-Upon failure, the function does not set @code{errno} to @code{ENOMEM} on
-some platforms:
-mingw, MSVC 14, Solaris 11.4.
+On some platforms, when the function fails it does not set @code{errno}:
+mingw, MSVC 14.
+
+@item
+On some platforms, when the function fails it might set @code{errno}
+to @code{EAGAIN} instead of to @code{ENOMEM}. Although POSIX allows
+@code{EAGAIN}, the @code{malloc-posix} module insists on @code{ENOMEM}
+which also conforms to POSIX and is GNU-compatible:
+Solaris 11.4.
 
 @item
 On some platforms, @code{malloc (n)} can succeed even if @code{n}
index 0c7ab115d39d88b70a6cc74d58b81f623740d3ff..b08f76c5f14edbc17e0bbd401c2f976e70e664ea 100644 (file)
@@ -11,24 +11,33 @@ Portability problems fixed by Gnulib:
 
 @itemize
 @item
-Upon failure, the function does not set @code{errno} to @code{ENOMEM} on
-some platforms:
-mingw, MSVC 14, Solaris 11.4.
+On some platforms, when the function fails it does not set @code{errno}:
+mingw, MSVC 14.
+
+@item
+On some platforms, when the function fails it might set @code{errno}
+to @code{EAGAIN} instead of to @code{ENOMEM}. Although POSIX allows
+@code{EAGAIN}, the @code{realloc-posix} module insists on @code{ENOMEM}
+which also conforms to POSIX and is GNU-compatible:
+Solaris 11.4.
 
 @item
 On some platforms, @code{realloc (p, n)} can succeed even if @code{n}
 exceeds @code{PTRDIFF_MAX}.  Although this behavior is arguably
-allowed by POSIX it can lead to behavior not defined by POSIX later,
+allowed by POSIX it is not compatible with GNU and
+can lead to behavior not defined by POSIX later,
 so @code{realloc-posix} does not allow going over the limit.
 
 @item
-It is not portable to call @code{realloc} with a size of 0.  With a
-null pointer argument, this is the same ambiguity as @code{malloc (0)}
+It is not portable to call @code{realloc} with a size of 0.
+
+With a null pointer argument, this is the same ambiguity as @code{malloc (0)}
 as to whether a successful call returns a null pointer or a pointer to a
-new zero-sized memory region.  The @code{realloc-posix} module
-implements the latter behavior.
+new zero-sized memory region.  Although both behaviors conform to POSIX,
+@code{realloc-posix} insists on the latter behavior, which is
+compatible with GNU.
 
-Behavior is a real mess for @code{realloc (p, 0)} with non-null @code{p}.
+With non-null @code{p}, behavior is a real mess for @code{realloc (p, 0)}.
 C23 says behavior is undefined.
 C89 through C17 say a successful call returns either a null pointer
 or a pointer to a new zero-sized memory region.
@@ -51,7 +60,7 @@ glibc 2.33--2.40 by default, Android.
 Free @code{p}, possibly set @code{errno}, and return a null pointer:
 glibc 1--2.1 if specially built with @code{REALLOC_ZERO_BYTES_FREES=1},
 glibc 2.1.1--2.32 by default,
-mingw, MSVC.
+mingw, MSVC 14.
 
 @item
 Free @code{p}, set @code{errno} to @code{EINVAL}, and return a null pointer:
@@ -66,9 +75,9 @@ musl libc, macOS, FreeBSD, NetBSD, OpenBSD, Solaris, Cygwin.
 
 @noindent
 Behaviors (3) and (4) conform to POSIX; behaviors (1) and (2) do not.
-The @code{realloc-posix} module implements behavior (4) as it is more
+The @code{realloc-posix} module insists on behavior (4) as it is more
 popular than (3) and is more useful in practice.  Behavior (4) is the
-only one of the four in which returning a null pointer means failure,
+only one of the four in which returning a null pointer means failure,
 which is what non-expert programmers typically expect.
 
 A program not suspecting these variations in semantics will either:
@@ -84,6 +93,14 @@ Falsely respond to memory exhaustion (if it wisely checks for @code{realloc}
 failure), or have double-free bugs (if it unwisely does not check),
 when it assumes behavior (4) but the system implements (1), (2) or (3).
 @end itemize
+
+@item
+When @code{realloc (p, 0)} sets errno to @code{EINVAL} and returns null,
+a POSIX.1-2024 application cannot tell whether the call has succeeded
+and freed @code{p}, or has failed without freeing @code{p}.
+This is only a theoretical problem, though, as the only practical
+implementation with this behavior is AIX without @code{_LINUX_SOURCE_COMPAT},
+which behaves this way only when the call succeeds.
 @end itemize
 
 Portability problems not fixed by Gnulib:
index aa43596b6038e9d6b714a1f3c30291a445bbd8b8..318f7854cc49447de36f975901cd0a479e7519eb 100644 (file)
@@ -26,6 +26,13 @@ Portability problems fixed by Gnulib:
 This function is missing on many platforms:
 glibc 2.25, macOS 14, FreeBSD 10, NetBSD 7, OpenBSD 5.5, Minix 3.3.0, AIX 7.2, HP-UX 11, Solaris 11.4, Cygwin 1.7.x, mingw, MSVC 14, Android 9.0.
 
+@item
+On some platforms, when the function fails it might set @code{errno}
+to @code{EAGAIN} instead of to @code{ENOMEM}. Although POSIX allows
+@code{EAGAIN}, the @code{reallocarray} module insists on @code{ENOMEM}
+which also conforms to POSIX and is GNU-compatible:
+Solaris 11.4.
+
 @item
 On some platforms, @code{reallocarray (p, n, s)} can succeed even if
 multiplying @code{n} by @code{s} would exceed @code{PTRDIFF_MAX},
@@ -41,4 +48,8 @@ that @code{realloc} does.  @xref{realloc}.
 
 Portability problems not fixed by Gnulib:
 @itemize
+@item
+When not growing an already-allocated region,
+@code{reallocarray}, like @code{realloc}, can fail and return a null pointer:
+glibc 2.40 and probably other platforms.
 @end itemize
index 89bc78ee03c78e0fd40e8d83d451ad8fa974cf28..82fc1e517f2871e9d3309c2214465b6ca6802653 100644 (file)
@@ -17,9 +17,15 @@ This function has no prototype in @code{<string.h>} on some old platforms.
 Portability problems fixed by Gnulib module @code{strdup-posix}:
 @itemize
 @item
-Upon failure, the function does not set @code{errno} to @code{ENOMEM} on
-some platforms:
-mingw, MSVC 14, Solaris 11.4.
+On some platforms, when the function fails it does not set @code{errno}:
+mingw, MSVC 14.
+
+@item
+On some platforms, when the function fails it might set @code{errno}
+to @code{EAGAIN} instead of to @code{ENOMEM}. Although POSIX allows
+@code{EAGAIN}, the @code{strdup-posix} module insists on @code{ENOMEM}
+which also conforms to POSIX and is GNU-compatible:
+Solaris 11.4.
 @end itemize
 
 Portability problems not fixed by Gnulib: