[PATCH] man/man3/getnameinfo.3: Mention behavior for AF_UNIX

[PATCH] man/man3/getnameinfo.3: Mention behavior for AF_UNIX

[Jan Engelhardt]

Signed-off-by: Jan Engelhardt <jengelh@inai.de>
---
 man/man3/getnameinfo.3 | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/man/man3/getnameinfo.3 b/man/man3/getnameinfo.3
index 7db812948..6c2a08275 100644
--- a/man/man3/getnameinfo.3
+++ b/man/man3/getnameinfo.3
@@ -121,6 +121,14 @@ cannot be determined.)
 If set, then the numeric form of the service address is returned.
 (When not set, this will still happen in case the service's name
 cannot be determined.)
+.P
+Behavior for passing other sockaddr types to getnameinfo is unspecified by
+POSIX.
+Portable programs should not expect any particular behavior.
+For e.g. AF_UNIX/sockaddr_un,
+many libc implementations fail such a call,
+some succeed but provide zero-length strings in \fIhost\fP and \fIserv\fP,
+and some fill these buffers with pseudo values.
 .SS Extensions to getnameinfo() for Internationalized Domain Names
 Starting with glibc 2.3.4,
 .BR getnameinfo ()
-- 
2.56.0

Re: [PATCH] man/man3/getnameinfo.3: Mention behavior for AF_UNIX

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2026 bytes --]

Hi Jan,

> Date: 2026-10-20 13:51:43+0200
> From: Jan Engelhardt <jengelh@inai.de>
>
> Signed-off-by: Jan Engelhardt <jengelh@inai.de>
> ---
>  man/man3/getnameinfo.3 | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/man/man3/getnameinfo.3 b/man/man3/getnameinfo.3
> index 7db812948..6c2a08275 100644
> --- a/man/man3/getnameinfo.3
> +++ b/man/man3/getnameinfo.3
> @@ -121,6 +121,14 @@ cannot be determined.)
>  If set, then the numeric form of the service address is returned.
>  (When not set, this will still happen in case the service's name
>  cannot be determined.)
> +.P
> +Behavior for passing other sockaddr types to getnameinfo is unspecified by

This 'other' seems out of context.  I don't see a recent earlier mention
that the address family of the socket should be AF_INET/6.  There's one
at the top, but that seems far enough that a reader might get confused.

Perhaps we could have this text in a VERSIONS section, and instead of
assuming the reader remembers, we could be explicit about it.

> +POSIX.
> +Portable programs should not expect any particular behavior.
> +For e.g. AF_UNIX/sockaddr_un,
> +many libc implementations fail such a call,
> +some succeed but provide zero-length strings in \fIhost\fP and \fIserv\fP,
> +and some fill these buffers with pseudo values.

I'd rewrite a little bit:

	.SH VERSIONS
	POSIX only specifies the behavior for sockets of the
	.B AF_INET
	and
	.B AF_INET6
	address families.
	Other address families are non-portable;
	for example, for
	.BR AF_UNIX ,
	many libc implementations fail,
	some succeed but provide zero-length strings in
	.I host
	and
	.IR serv ,
	and some fill these buffers with pseudo-values.

BTW, out of curiosity, what do those pseudo-values look like?


Have a lovely day!
Alex

>  .SS Extensions to getnameinfo() for Internationalized Domain Names
>  Starting with glibc 2.3.4,
>  .BR getnameinfo ()
> -- 
> 2.56.0
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] man/man3/getnameinfo.3: Mention behavior for AF_UNIX

[Jan Engelhardt]

On Tuesday 2026-10-20 16:27, Alejandro Colomar wrote:
>
>I'd rewrite a little bit:
>
>	.SH VERSIONS
>	POSIX only specifies the behavior for sockets of the
>	.B AF_INET
>	and
>	.B AF_INET6
>	address families.
>	Other address families are non-portable;
>	for example, for
>	.BR AF_UNIX ,
>	many libc implementations fail,
>	some succeed but provide zero-length strings in
>	.I host
>	and
>	.IR serv ,
>	and some fill these buffers with pseudo-values.
>
>BTW, out of curiosity, what do those pseudo-values look like?

(Something must have gone wrong seeing zero-length output.
So I redid the test program and runs.)

getnameinfo:

* FreeBSD 15: fills host="/path", serv="", returns success(0).

* glibc 2.44: fills host=<utsname> (flags=0) or host="localhost"
  (flags=NI_NUMERICHOST), and serv="/path", returns success(0).

* OpenBSD 7.9: signals EAI_FAMILY. Upon seeing NI_NUMERICHOST,
  signals EAI_SYSTEM instead (odd).

* OmniOS r151046 (Solaris): signals EAI_FAMILY.

* musl-libc 1.2.6 (Alpine Linux): signals EAI_FAMILY.

* cygwin 3.6.11: signals EAI_FAMILY.

getaddrinfo:

* FreeBSD: getaddrinfo("/the/socket/path", nullptr,
  hints_with_AF_UNIX, ...) succeeds.

* the rest: signals EAI_FAMILY.


---
#include <sys/un.h>
#include <netdb.h>
#include <sys/socket.h>
#include <cstdio>
#include <cstring>

int main()
{
	struct sockaddr_un u{};
	u.sun_family = AF_UNIX;
	strcpy(u.sun_path, "/pa");
	char host[320] = "!", serv[320] = "!";

	auto ret = getnameinfo(reinterpret_cast<struct sockaddr *>(&u),
	           sizeof(u), host, sizeof(host), serv, sizeof(serv), 0);
	printf("GNI %d %s\n", ret, gai_strerror(ret));
	if (ret == 0)
		printf("GNI <%s> <%s>\n", host, serv);

	ret = getnameinfo(reinterpret_cast<struct sockaddr *>(&u),
	      sizeof(u), host, sizeof(host), serv, sizeof(serv), NI_NUMERICHOST | NI_NUMERICSERV);
	printf("GNI %d %s\n", ret, gai_strerror(ret));
	if (ret == 0)
		printf("GNI <%s> <%s>\n", host, serv);

	struct addrinfo hints{};
	hints.ai_family = AF_UNIX;
	hints.ai_socktype = 0;
	struct addrinfo *res = nullptr;
	ret = getaddrinfo(host, serv, &hints, &res);
	printf("GAI %d %s\n", ret, gai_strerror(ret));
	if (ret == 0)
		for (; res != nullptr; res = res->ai_next)
			printf("GAI fam %u %u %u\n", res->ai_family,
				res->ai_socktype, res->ai_protocol);
	return 0;
}