sockaddr_snprintf(3) - NetBSD Manual Pages

SOCKADDR_SNPRINTF(3)    NetBSD Library Functions Manual   SOCKADDR_SNPRINTF(3)


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 sup-
     ported, then the string ``N/A'' is printed.

     The resulting formatted string is placed into buf.  Up to buflen charac-
     ters 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 numeri-
         cally.  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 exclud-
     ing the terminating NUL.  The returned string in buf is always NUL-termi-
     nated.  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 sys-
     tem 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 sup-
     press this, but other formatting (e.g., spacing or punctuation) will
     remain.

NetBSD 9.2                       June 7, 2013                       NetBSD 9.2