manual: Document error codes of several socket functions (RHEL-57110)

Resolves: RHEL-57110
2025-06-11 11:42:31 +02:00 · 2025-06-11 11:42:31 +02:00 · 8656f60248
commit 8656f60248
parent c6e49bb8c7
6 changed files with 231 additions and 1 deletions
--- a/glibc-RHEL-57110-1.patch
+++ b/glibc-RHEL-57110-1.patch
@ -0,0 +1,67 @@
+commit 43afae31e0d7579deef13536c4c3704afaa017da
+Author: Maciej W. Rozycki <macro@redhat.com>
+Date:   Thu May 29 22:11:38 2025 +0100
+
+    manual: Document error codes missing for 'socket'
+    
+    Add missing EAFNOSUPPORT, ESOCKTNOSUPPORT, EPROTOTYPE, EINVAL, EPERM,
+    and ENOMEM error codes, and adjust existing descriptions accordingly.
+    
+    On Linux either ENOBUFS or ENOMEM is returned in the case of a memory
+    allocation failure, depending on the namespace requested, e.g. AF_INET
+    returns ENOMEM while AF_INET6 returns ENOBUFS, so document these codes
+    as alternatives.
+    
+    Similarly EPERM is returned rather than EACCES on Linux, so document
+    these codes as alternatives as well.  We might want to convert EPERM to
+    EACCES for POSIX compliance, but it is beyond the scope of this change,
+    and software has to expect either anyway, owing to the long-established
+    practice.
+    
+    Finally ESOCKTNOSUPPORT is returned rather than EPROTONOSUPPORT for an
+    unsupported style except for the AF_QIPCRTR namespace where EPROTOTYPE
+    is used, so document these codes as alternatives too.
+    
+    Reviewed-by: Florian Weimer <fweimer@redhat.com>
+
+diff --git a/manual/socket.texi b/manual/socket.texi
+index 63d550e9d484dc65..5199c3734be40136 100644
+--- a/manual/socket.texi
+++ b/manual/socket.texi
+@@ -2205,9 +2205,19 @@ socket, or @code{-1} in case of error.  The following @code{errno} error
+ conditions are defined for this function:
+ 
+ @table @code
+@item EAFNOSUPPORT
+The @var{namespace} requested is not supported.
+
+@item ESOCKTNOSUPPORT
+@itemx EPROTONOSUPPORT
+@itemx EPROTOTYPE
+The @var{style} is not supported by the @var{namespace} specified.
+
+ @item EPROTONOSUPPORT
+-The @var{protocol} or @var{style} is not supported by the
+-@var{namespace} specified.
+The @var{protocol} is not supported by the @var{namespace} specified.
+
+@item EINVAL
+The @var{style} or @var{protocol} requested is not valid.
+ 
+ @item EMFILE
+ The process already has too many file descriptors open.
+@@ -2216,11 +2226,13 @@ The process already has too many file descriptors open.
+ The system already has too many file descriptors open.
+ 
+ @item EACCES
+@itemx EPERM
+ The process does not have the privilege to create a socket of the specified
+ @var{style} or @var{protocol}.
+ 
+ @item ENOBUFS
+-The system ran out of internal buffer space.
+@itemx ENOMEM
+Insufficient memory was available.
+ @end table
+ 
+ The file descriptor returned by the @code{socket} function supports both
--- a/glibc-RHEL-57110-2.patch
+++ b/glibc-RHEL-57110-2.patch
@ -0,0 +1,36 @@
+commit 79b5febd762d6735ba8e878086a50ea04993e340
+Author: Maciej W. Rozycki <macro@redhat.com>
+Date:   Thu May 29 22:11:38 2025 +0100
+
+    manual: Document error codes missing for 'inet_ntop'
+    
+    Add documentation for EAFNOSUPPORT and ENOSPC error codes returned, and
+    the return value on failure.
+    
+    Reviewed-by: Florian Weimer <fweimer@redhat.com>
+
+diff --git a/manual/socket.texi b/manual/socket.texi
+index 5199c3734be40136..7a833360d91aa2a4 100644
+--- a/manual/socket.texi
+++ b/manual/socket.texi
+@@ -1211,7 +1211,19 @@ network (binary) to presentation (textual) form.  @var{af} should be
+ either @code{AF_INET} or @code{AF_INET6}, as appropriate.  @var{cp} is a
+ pointer to the address to be converted.  @var{buf} should be a pointer
+ to a buffer to hold the result, and @var{len} is the length of this
+-buffer.  The return value from the function will be this buffer address.
+buffer.
+
+The return value is @var{buf} on success.  On failure, the function's
+return value is a null pointer and @code{errno} is set accordingly.
+The following @code{errno} values are specific to this function:
+
+@table @code
+@item EAFNOSUPPORT
+The address family requested is neither @code{AF_INET} nor @code{AF_INET6}.
+
+@item ENOSPC
+Insufficient space available for the result in the buffer provided.
+@end table
+ @end deftypefun
+ 
+ @node Host Names
--- a/glibc-RHEL-57110-3.patch
+++ b/glibc-RHEL-57110-3.patch
@ -0,0 +1,47 @@
+commit 46acdf46cc1948187d6540cdf4abee5053cd8bcc
+Author: Maciej W. Rozycki <macro@redhat.com>
+Date:   Wed Jun 4 16:27:20 2025 +0100
+
+    manual: Document error codes missing for 'if_indextoname'
+    
+    Add documentation for ENXIO error code returned and refer to 'socket'
+    for further possible codes from the underlying function call.
+    
+    While changing the text clarify the description by mentioning 'ifname'
+    and replace @code tags with @var ones where referring to a function
+    parameter.
+    
+    Reviewed-by: Florian Weimer <fweimer@redhat.com>
+
+diff --git a/manual/socket.texi b/manual/socket.texi
+index 7a833360d91aa2a4..0f5ec07ede2a1949 100644
+--- a/manual/socket.texi
+++ b/manual/socket.texi
+@@ -505,11 +505,22 @@ name.  If no interface exists with the name given, it returns 0.
+ @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+ @c It opens a socket with opensock to use ioctl on the fd to get the
+ @c name from the index.
+-This function maps an interface index to its corresponding name.  The
+-returned name is placed in the buffer pointed to by @code{ifname}, which
+-must be at least @code{IFNAMSIZ} bytes in length.  If the index was
+-invalid, the function's return value is a null pointer, otherwise it is
+-@code{ifname}.
+This function maps an interface index @var{ifindex} to its corresponding
+name.  The returned name is placed in the buffer pointed to by @var{ifname},
+which must be at least @code{IFNAMSIZ} bytes in length.
+
+The return value is @var{ifname} on success.  On failure, the function's
+return value is a null pointer and @code{errno} is set accordingly.  The
+following @code{errno} values are specific to this function:
+
+@table @code
+@item ENXIO
+There is no interface at the index requested.
+@end table
+
+Additionally, since @code{if_indextoname} invokes @code{socket}
+internally, @code{errno} may also be set to a value listed for the
+@code{socket} function (@pxref{Creating a Socket}).
+ @end deftypefun
+ 
+ @deftp {Data Type} {struct if_nameindex}
--- a/glibc-RHEL-57110-4.patch
+++ b/glibc-RHEL-57110-4.patch
@ -0,0 +1,39 @@
+commit 5a9020eeb27eee88e7839ff5e9cea94892ec90ff
+Author: Maciej W. Rozycki <macro@redhat.com>
+Date:   Wed Jun 4 16:27:20 2025 +0100
+
+    manual: Document error codes missing for 'if_nametoindex'
+    
+    Add documentation for ENODEV error code returned and refer to 'socket'
+    for further possible codes from the underlying function call.
+    
+    While changing the text clarify the description by mentioning 'ifname'.
+    
+    Reviewed-by: Florian Weimer <fweimer@redhat.com>
+
+diff --git a/manual/socket.texi b/manual/socket.texi
+index 0f5ec07ede2a1949..e2f00b82a81fec6f 100644
+--- a/manual/socket.texi
+++ b/manual/socket.texi
+@@ -497,7 +497,20 @@ interface name, including its terminating zero byte.
+ @c takes a lock, which makes all callers AS- and AC-Unsafe.
+ @c  opensock @asulock @aculock @acsfd
+ This function yields the interface index corresponding to a particular
+-name.  If no interface exists with the name given, it returns 0.
+name specified with @var{ifname}.
+
+The return value is the interface index on success.  On failure, the
+function's return value is zero and @code{errno} is set accordingly.
+The following @code{errno} values are specific to this function:
+
+@table @code
+@item ENODEV
+There is no interface by the name requested.
+@end table
+
+Additionally, since @code{if_nametoindex} invokes @code{socket}
+internally, @code{errno} may also be set to a value listed for the
+@code{socket} function (@pxref{Creating a Socket}).
+ @end deftypefun
+ 
+ @deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname})
--- a/glibc-RHEL-57110-5.patch
+++ b/glibc-RHEL-57110-5.patch
@ -0,0 +1,33 @@
+commit 140b20e9716b51659a5223b182dcf07ac62b3f77
+Author: Maciej W. Rozycki <macro@redhat.com>
+Date:   Wed Jun 4 16:27:20 2025 +0100
+
+    manual: Document error codes missing for 'inet_pton'
+    
+    Add documentation for EAFNOSUPPORT error code returned, and the possible
+    return values on non-success.
+    
+    Reviewed-by: Florian Weimer <fweimer@redhat.com>
+
+diff --git a/manual/socket.texi b/manual/socket.texi
+index e2f00b82a81fec6f..ac7e9e8a93bd6ff5 100644
+--- a/manual/socket.texi
+++ b/manual/socket.texi
+@@ -1216,6 +1216,17 @@ either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
+ address being converted.  @var{cp} is a pointer to the input string, and
+ @var{buf} is a pointer to a buffer for the result.  It is the caller's
+ responsibility to make sure the buffer is large enough.
+
+The return value is @code{1} on success and @code{0} if @var{cp} does not
+point to a valid address string for the address family @var{af} requested.
+On failure, the function's return value is @code{-1} and @code{errno} is
+set accordingly.  The following @code{errno} values are specific to this
+function:
+
+@table @code
+@item EAFNOSUPPORT
+The address family requested is neither @code{AF_INET} nor @code{AF_INET6}.
+@end table
+ @end deftypefun
+ 
+ @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len})
--- a/glibc.spec
+++ b/glibc.spec
@ -157,7 +157,7 @@ end \
 Summary: The GNU libc libraries
 Name: glibc
 Version: %{glibcversion}
-Release: 203%{?dist}
+Release: 204%{?dist}

 # In general, GPLv2+ is used by programs, LGPLv2+ is used for
 # libraries.
@ -1232,6 +1232,11 @@ Patch923: glibc-RHEL-50546-3.patch
 Patch924: glibc-RHEL-50546-4.patch
 Patch925: glibc-RHEL-50546-5.patch
 Patch926: glibc-RHEL-50546-6.patch
+Patch927: glibc-RHEL-57110-1.patch
+Patch928: glibc-RHEL-57110-2.patch
+Patch929: glibc-RHEL-57110-3.patch
+Patch930: glibc-RHEL-57110-4.patch
+Patch931: glibc-RHEL-57110-5.patch

 ##############################################################################
 # Continued list of core "glibc" package information:
@ -3225,6 +3230,9 @@ update_gconv_modules_cache ()
 %endif

 %changelog
+* Wed Jun 11 2025 Arjun Shankar <arjun@redhat.com> - 2.34-204
+- manual: Document error codes of several socket functions (RHEL-57110)
+
 * Thu Jun 05 2025 Arjun Shankar <arjun@redhat.com> - 2.34-203
 - manual: Document several *at file system interface functions (RHEL-50546)