NAME
sockaddr_snprintf —
formatting function
for socket address structures
LIBRARY
System Utilities Library (libutil, -lutil)
SYNOPSIS
#include <util.h>
int
sockaddr_snprintf(
char
*buf,
size_t buflen,
const char *fmt,
const struct sockaddr *sa);
DESCRIPTION
The
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):
-
-
- a
- The node address portion of the socket address is printed
numerically. For
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.
-
-
- A
- The symbolic name of the address is printed. For
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.
-
-
- D
- Debugging output: For all addresses, print all their fields
as “field_name=value”.
-
-
- f
- The numeric value of the family of the address is
printed.
-
-
- l
- The length of the socket address is printed.
-
-
- p
- For
AF_INET
,
AF_INET6
, and AF_APPLETALK
the numeric value of the port portion of the address is printed.
-
-
- P
- For
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.
-
-
- I
- For
AF_LINK
addresses, the
interface name portion is printed.
-
-
- F
- For
AF_INET6
addresses, the
flowinfo portion of the address is printed numerically.
-
-
- R
- For
AF_APPLETALK
addresses, the
netrange portion of the address is printed as:
“phase:[firstnet,lastnet]”
-
-
- S
- For
AF_INET6
addresses, the scope
portion of the address is printed numerically.
-
-
- ?
- If present between “%” and the format
character, and the selected format does not apply to the given address
family, the “N/A” string is elided and no output results.
RETURN VALUES
The
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).
ERRORS
If the buffer
buf is too small to hold the formatted
output,
sockaddr_snprintf() will still return the buffer,
containing a truncated string.
SEE ALSO
getaddrinfo(3),
getnameinfo(3),
link_ntoa(3),
snprintf(3)
HISTORY
The
sockaddr_snprintf() first appeared in
NetBSD 3.0.
BUGS
The
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.