SOCKADDR_SNPRINTF(3) | Library Functions Manual | SOCKADDR_SNPRINTF(3) |
sockaddr_snprintf
—
#include <util.h>
int
sockaddr_snprintf
(char
*buf, size_t
buflen, const char
*fmt, const struct
sockaddr *sa);
sockaddr_snprintf
() function formats a socket
address into a form suitable for printing.
This function is convenient because it is protocol independent, i.e. one does not need to know the address family of the sockaddr in order to print it. The printf(3) like format string specifies how the address is going to be printed. Some formatting characters are only supported by some address families. If a certain formatting character is not supported, then the string “N/A” is printed.
The resulting formatted string is placed into buf. Up to buflen characters are placed in buf.
The following formatting characters are supported (immediately after a percent (‘%’) sign):
AF_INET
the address is printed as:
“A.B.C.D” and for AF_INET6 the address is printed as:
“A:B...[%if]” using
getnameinfo(3)
internally with NI_NUMERICHOST
. For
AF_APPLETALK
the address is printed as:
“A.B” For AF_LOCAL
(AF_UNIX
) the address is printed as:
“socket-path” For AF_LINK
the
address is printed as: “a.b.c.d.e.f” using
link_ntoa(3), but the
interface portion is skipped (see below). For
AF_UNSPEC
nothing is printed.AF_INET
and AF_INET6
this
is the hostname associated with the address. For all other address
families, it is the same as the “a” format.AF_INET
, AF_INET6
, and
AF_APPLETALK
the numeric value of the port portion
of the address is printed.AF_INET
and AF_INET6
this is the name of the service associated with the port number, if
available. For all other address families, it is the same as the
“p” format.AF_LINK
addresses, the interface name portion
is printed.AF_INET6
addresses, the flowinfo portion of
the address is printed numerically.AF_APPLETALK
addresses, the netrange portion
of the address is printed as:
“phase:[firstnet,lastnet]”AF_INET6
addresses, the scope portion of the
address is printed numerically.sockaddr_snprintf
() function returns the number of
characters that are required to format the value val
given the format string fmt excluding the terminating
NUL. The returned string in buf is always
NUL-terminated. If the address family is not supported,
sockaddr_snprintf
() returns -1 and sets
errno to EAFNOSUPPORT
. For
AF_INET
and AF_INET6
addresses
sockaddr_snprintf
() returns -1 if the
getnameinfo(3) conversion
failed, and errno is set to the error value from
getnameinfo(3).
sockaddr_snprintf
() will still return the
buffer, containing a truncated string.
sockaddr_snprintf
() first appeared in
NetBSD 3.0.
sockaddr_snprintf
() interface is experimental and
might change in the future.
There is no way to specify different formatting styles for
particular addresses. For example it would be useful to print
AF_LINK
addresses as “%.2x:%.2x...”
instead of “%x.%x...”
This function is supposed to be quick, but getnameinfo(3) might use system calls to convert the scope number to an interface name and the “A” and “P” format characters call getaddrinfo(3) which may block for a noticeable period of time.
Not all formatting characters are supported by all address families and printing “N/A” is not very convenient. The “?” character can suppress this, but other formatting (e.g., spacing or punctuation) will remain.
June 7, 2013 | NetBSD 9.0 |