From 8656f602485508bf1420e66285c0e031cde391d8 Mon Sep 17 00:00:00 2001 From: Arjun Shankar Date: Wed, 11 Jun 2025 11:42:31 +0200 Subject: [PATCH] manual: Document error codes of several socket functions (RHEL-57110) Resolves: RHEL-57110 --- glibc-RHEL-57110-1.patch | 67 ++++++++++++++++++++++++++++++++++++++++ glibc-RHEL-57110-2.patch | 36 +++++++++++++++++++++ glibc-RHEL-57110-3.patch | 47 ++++++++++++++++++++++++++++ glibc-RHEL-57110-4.patch | 39 +++++++++++++++++++++++ glibc-RHEL-57110-5.patch | 33 ++++++++++++++++++++ glibc.spec | 10 +++++- 6 files changed, 231 insertions(+), 1 deletion(-) create mode 100644 glibc-RHEL-57110-1.patch create mode 100644 glibc-RHEL-57110-2.patch create mode 100644 glibc-RHEL-57110-3.patch create mode 100644 glibc-RHEL-57110-4.patch create mode 100644 glibc-RHEL-57110-5.patch diff --git a/glibc-RHEL-57110-1.patch b/glibc-RHEL-57110-1.patch new file mode 100644 index 0000000..b14c557 --- /dev/null +++ b/glibc-RHEL-57110-1.patch @@ -0,0 +1,67 @@ +commit 43afae31e0d7579deef13536c4c3704afaa017da +Author: Maciej W. Rozycki +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 + +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 diff --git a/glibc-RHEL-57110-2.patch b/glibc-RHEL-57110-2.patch new file mode 100644 index 0000000..f162010 --- /dev/null +++ b/glibc-RHEL-57110-2.patch @@ -0,0 +1,36 @@ +commit 79b5febd762d6735ba8e878086a50ea04993e340 +Author: Maciej W. Rozycki +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 + +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 diff --git a/glibc-RHEL-57110-3.patch b/glibc-RHEL-57110-3.patch new file mode 100644 index 0000000..bc1e2ae --- /dev/null +++ b/glibc-RHEL-57110-3.patch @@ -0,0 +1,47 @@ +commit 46acdf46cc1948187d6540cdf4abee5053cd8bcc +Author: Maciej W. Rozycki +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 + +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} diff --git a/glibc-RHEL-57110-4.patch b/glibc-RHEL-57110-4.patch new file mode 100644 index 0000000..85135ac --- /dev/null +++ b/glibc-RHEL-57110-4.patch @@ -0,0 +1,39 @@ +commit 5a9020eeb27eee88e7839ff5e9cea94892ec90ff +Author: Maciej W. Rozycki +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 + +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}) diff --git a/glibc-RHEL-57110-5.patch b/glibc-RHEL-57110-5.patch new file mode 100644 index 0000000..881862c --- /dev/null +++ b/glibc-RHEL-57110-5.patch @@ -0,0 +1,33 @@ +commit 140b20e9716b51659a5223b182dcf07ac62b3f77 +Author: Maciej W. Rozycki +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 + +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}) diff --git a/glibc.spec b/glibc.spec index e2c7b47..e33ecdc 100644 --- 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 - 2.34-204 +- manual: Document error codes of several socket functions (RHEL-57110) + * Thu Jun 05 2025 Arjun Shankar - 2.34-203 - manual: Document several *at file system interface functions (RHEL-50546)