Copyright (c) 2004 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Christos Zoulas.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd September 15, 2025 .Dt SOCKADDR_SNPRINTF 3 .Os .Sh NAME .Nm sockaddr_snprintf .Nd formatting function for socket address structures .Sh LIBRARY .Lb libutil .Sh SYNOPSIS n util.h .Ft int .Fn sockaddr_snprintf "char *buf" "size_t buflen" "const char *fmt" "const struct sockaddr *sa" .Sh DESCRIPTION The .Fn sockaddr_snprintf function formats a socket address into a form suitable for printing.
p 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 .Xr 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 .Dq N/A is printed.
p The resulting formatted string is placed into .Fa buf . Up to .Fa buflen characters are placed in .Fa buf .
p The following formatting characters are supported (immediately after a percent
q Sq % sign): l -tag -width %a t a The node address portion of the socket address is printed numerically. For .Dv AF_INET the address is printed as: .Dq A.B.C.D and for AF_INET6 the address is printed as: .Dq A:B...[%if] using .Xr getnameinfo 3 internally with .Dv NI_NUMERICHOST . For .Dv AF_APPLETALK the address is printed as: .Dq A.B For .Dv AF_LOCAL
q Dv AF_UNIX the address is printed as: .Dq socket-path For .Dv AF_LINK the address is printed as: .Dq a.b.c.d.e.f using .Xr link_ntoa 3 , but the interface portion is skipped (see below). For .Dv AF_UNSPEC nothing is printed. t A The symbolic name of the address is printed. For .Dv AF_INET and .Dv AF_INET6 this is the hostname associated with the address. For all other address families, it is the same as the .Dq a format. t D Debugging output: For all addresses, print all their fields as .Dq field_name=value . t f The numeric value of the family of the address is printed. t l The length of the socket address is printed. t m The symbolic name of the address family is printed .Sq appletalk , .Sq inet , .Sq inet6 , .Sq link , or .Sq unix . t n The address is printed numerically. If the address supports a port, then %a:%p is printed except for inet6 where [%a]:%p is printed. Otherwise %a is printed. t N The address is printed symbolically. If the address supports a port, then %A:%P is printed except for inet6 where [%A]:%P is printed (because name resolution can fail, and also to differentiate from ipv4). Otherwise %A is printed. t p For .Dv AF_INET , .Dv AF_INET6 , and .Dv AF_APPLETALK the numeric value of the port portion of the address is printed. t P For .Dv AF_INET and .Dv 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 .Dq p format. t I For .Dv AF_LINK addresses, the interface name portion is printed. t F For .Dv AF_INET6 addresses, the flowinfo portion of the address is printed numerically. t R For .Dv AF_APPLETALK addresses, the netrange portion of the address is printed as: .Dq phase:[firstnet,lastnet] t S For .Dv AF_INET6 addresses, the scope portion of the address is printed numerically. t ? If present between .Dq % and the format character, and the selected format does not apply to the given address family, the .Dq N/A string is elided and no output results. .El .Sh RETURN VALUES The .Fn sockaddr_snprintf function returns the number of characters that are required to format the value .Fa val given the format string .Fa fmt excluding the terminating NUL. The returned string in .Fa buf is always NUL-terminated. If the address family is not supported, .Fn sockaddr_snprintf returns -1 and sets .Va errno to .Er EAFNOSUPPORT . For .Dv AF_INET and .Dv AF_INET6 addresses .Fn sockaddr_snprintf returns -1 if the .Xr getnameinfo 3 conversion failed, and .Fa errno is set to the error value from .Xr getnameinfo 3 . .Sh ERRORS If the buffer .Fa buf is too small to hold the formatted output, .Fn sockaddr_snprintf will still return the buffer, containing a truncated string. .Sh SEE ALSO .Xr getaddrinfo 3 , .Xr getnameinfo 3 , .Xr link_ntoa 3 , .Xr snprintf 3 .Sh HISTORY The .Fn sockaddr_snprintf first appeared in .Nx 3.0 . .Sh BUGS The .Fn sockaddr_snprintf interface is experimental and might change in the future.
p There is no way to specify different formatting styles for particular addresses. For example it would be useful to print .Dv AF_LINK addresses as .Dq %.2x:%.2x... instead of .Dq %x.%x...
p This function is supposed to be quick, but .Xr getnameinfo 3 might use system calls to convert the scope number to an interface name and the .Dq A and .Dq P format characters call .Xr getaddrinfo 3 which may block for a noticeable period of time.
p Not all formatting characters are supported by all address families and printing .Dq N/A is not very convenient. The .Dq ? character can suppress this, but other formatting (e.g., spacing or punctuation) will remain.
Indexes created Sat Sep 20 22:09:52 GMT 2025