[PATCH 5/5] manual: Document error codes missing for 'inet_pton'

[Maciej W. Rozycki]

On Tue, 27 May 2025, Florian Weimer wrote:

> >> Index: glibc/manual/socket.texi
> >> ===================================================================
> >> --- glibc.orig/manual/socket.texi
> >> +++ glibc/manual/socket.texi
> >> @@ -1222,6 +1222,17 @@ either @code{AF_INET} or @code{AF_INET6}
> >>  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.  On failure, the function's
> >> +return value is zero if @var{cp} does not point to a valid address string
> >> +for the address family @var{af} requested, or otherwise 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})
> >
> > This one is okay as well.
> >
> > Reviewed-by: Florian Weimer <fweimer@redhat.com>
> 
> So I need to walk back my Reviewed-By:.  Please spell out the tri-state
> -1/0/1 return values more clearly, as Andreas Schwab explained here:
> 
>   Bug 32998 - inet_pton does not set errno on parse failure
>   <https://sourceware.org/bugzilla/show_bug.cgi?id=32998>

 I think the description is as clear as POSIX is here, though it says a 0 
return value is a failure while POSIX refrains from classifying this case, 
leaving it up to the API user to conclude whether the result of passing an 
invalid address string constitutes a failure or success.  I'm happy to let 
this ambiguity through to our manual, so I've updated the description such 
as to avoid the classification as well.  I'll be posting the updates soon.

 FWIW, I think the API would be consistent if the return value was 0 for 
success, and -1 with `errno' set to EINVAL for an invalid address string. 
But there you go, it's been cast in stone decades ago in 6bone times.

  Maciej