[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;
}

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

[Alejandro Colomar]

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

Hi Jan,

> Date: 2026-10-20 18:01:02+0200
> From: Jan Engelhardt <ej@inai.de>
>
> 
> 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.)

Thanks!  It'd be very useful to have this test program in the commit
message.  Would you mind sending v2 and incorporating it?  Please indent
the program with one tab, so the #include lines are not removed by
git(1).


Have a lovely night!
Alex

> 
> 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;
> }

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

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