NAME
sockaddr_snprintf —
formatting function for socket address
structures
LIBRARY
library “libutil”
SYNOPSIS
#include
<util.h>
int
sockaddr_snprintf(char
*buf, size_t
buflen, const char
*fmt, const struct
sockaddr *sa);
DESCRIPTION
Thesockaddr_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_INETthe address is printed as: “A.B.C.D” and for AF_INET6 the address is printed as: “A:B...[%if]” using getnameinfo(3) internally withNI_NUMERICHOST. ForAF_APPLETALKthe address is printed as: “A.B” ForAF_LOCAL(AF_UNIX) the address is printed as: “socket-path” ForAF_LINKthe address is printed as: “a.b.c.d.e.f” using link_ntoa(3), but the interface portion is skipped (see below). ForAF_UNSPECnothing is printed. - A
- The symbolic name of the address is printed. For
AF_INETandAF_INET6this 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, andAF_APPLETALKthe numeric value of the port portion of the address is printed. - P
- For
AF_INETandAF_INET6this 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_LINKaddresses, the interface name portion is printed. - F
- For
AF_INET6addresses, the flowinfo portion of the address is printed numerically. - R
- For
AF_APPLETALKaddresses, the netrange portion of the address is printed as: “phase:[firstnet,lastnet]” - S
- For
AF_INET6addresses, 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
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.