int
sockaddr_snprintf(
char *buf
, size_t buflen
, const char *fmt
, const struct sockaddr *sa
)
)
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.
)
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).
buf
is too small to hold the formatted output,
sockaddr_snprintf(
)
will still return the buffer, containing a truncated string.
)
first appeared in
NetBSD3.0.
)
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.