1.\" $NetBSD: sockaddr_snprintf.3,v 1.8 2013/06/07 17:23:26 christos Exp $ 2.\" 3.\" Copyright (c) 2004 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christos Zoulas. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 2, 2021 31.Dt SOCKADDR_SNPRINTF 3 32.Os 33.Sh NAME 34.Nm sockaddr_snprintf 35.Nd formatting function for socket address structures 36.Sh LIBRARY 37.Lb libutil 38.Sh SYNOPSIS 39.In util.h 40.Ft int 41.Fn sockaddr_snprintf "char *buf" "size_t buflen" "const char *fmt" "const struct sockaddr *sa" 42.Sh DESCRIPTION 43The 44.Fn sockaddr_snprintf 45function formats a socket address into a form suitable for printing. 46.Pp 47This function is convenient because it is protocol independent, i.e. one does 48not need to know the address family of the sockaddr in order to print it. 49The 50.Xr printf 3 51like format string specifies how the address is going to be printed. 52Some formatting characters are only supported by some address families. 53If a certain formatting character is not supported, then the string 54.Dq N/A 55is printed. 56.Pp 57The resulting formatted string is placed into 58.Fa buf . 59Up to 60.Fa buflen 61characters are placed in 62.Fa buf . 63.Pp 64The following formatting characters are supported (immediately 65after a percent 66.Pq Sq % 67sign): 68.Bl -tag -width %a 69.It a 70The node address portion of the socket address is printed numerically. 71For 72.Dv AF_INET 73the address is printed as 74.Dq A.B.C.D , 75and 76for AF_INET6 77the address is printed as 78.Dq A:B...[%if] 79using 80.Xr getnameinfo 3 81internally with 82.Dv NI_NUMERICHOST . 83For 84.Dv AF_LOCAL 85.Pq Dv AF_UNIX 86the address is printed as 87.Dq socket-path . 88For 89.Dv AF_LINK 90the address is printed as 91.Dq a.b.c.d.e.f 92using 93.Xr link_ntoa 3 , 94but the interface portion is skipped (see below). 95For 96.Dv AF_UNSPEC 97nothing is printed. 98.It A 99The symbolic name of the address is printed. 100For 101.Dv AF_INET 102and 103.Dv AF_INET6 104this is the hostname associated with the address. 105For all other address families, it is the same as the 106.Dq a 107format. 108.It D 109Debugging output: 110For all addresses, print all their fields as 111.Dq field_name=value . 112.It f 113The numeric value of the family of the address is printed. 114.It l 115The length of the socket address is printed. 116.It p 117For 118.Dv AF_INET 119and 120.Dv AF_INET6 121the numeric value of the port portion of the address is printed. 122.It P 123For 124.Dv AF_INET 125and 126.Dv AF_INET6 127this is the name of the service associated with the port number, if 128available. 129For all other address families, it is the same as the 130.Dq p 131format. 132.It I 133For 134.Dv AF_LINK 135addresses, the interface name portion is printed. 136.It F 137For 138.Dv AF_INET6 139addresses, the flowinfo portion of the address is printed numerically. 140.It R 141For 142.Dv AF_APPLETALK 143addresses, 144always prints 145.Dq N/A , 146because not supported on 147.Dx . 148.It S 149For 150.Dv AF_INET6 151addresses, the scope portion of the address is printed numerically. 152.It ? 153If present between 154.Dq % 155and the format character, and the selected format does not apply to 156the given address family, the 157.Dq N/A 158string is elided and no output results. 159.El 160.Sh RETURN VALUES 161The 162.Fn sockaddr_snprintf 163function returns the number of characters that are required to format the 164value 165.Fa val 166given the format string 167.Fa fmt 168excluding the terminating NUL. 169The returned string in 170.Fa buf 171is always NUL-terminated. 172If the address family is not supported, 173.Fn sockaddr_snprintf 174returns \-1 and sets 175.Va errno 176to 177.Er EAFNOSUPPORT . 178For 179.Dv AF_INET 180and 181.Dv AF_INET6 182addresses 183.Fn sockaddr_snprintf 184returns \-1 if the 185.Xr getnameinfo 3 186conversion failed, and 187.Fa errno 188is set to the error value from 189.Xr getnameinfo 3 . 190.Sh ERRORS 191If the buffer 192.Fa buf 193is too small to hold the formatted output, 194.Fn sockaddr_snprintf 195will still return the buffer, containing a truncated string. 196.Sh SEE ALSO 197.Xr getaddrinfo 3 , 198.Xr getnameinfo 3 , 199.Xr link_ntoa 3 , 200.Xr snprintf 3 201.Sh HISTORY 202The 203.Fn sockaddr_snprintf 204first appeared in 205.Nx 3.0 . 206.Sh BUGS 207The 208.Fn sockaddr_snprintf 209interface is experimental and might change in the future. 210.Pp 211There is no way to specify different formatting styles for particular 212addresses. 213For example it would be useful to print 214.Dv AF_LINK 215addresses as 216.Dq %.2x:%.2x... 217instead of 218.Dq %x.%x... 219.Pp 220This function is supposed to be quick, but 221.Xr getnameinfo 3 222might use system calls to convert the scope number to an interface 223name and the 224.Dq A 225and 226.Dq P 227format characters call 228.Xr getaddrinfo 3 229which may block for a noticeable period of time. 230.Pp 231Not all formatting characters are supported by all address families and 232printing 233.Dq N/A 234is not very convenient. 235The 236.Dq \&? 237character can suppress this, but other formatting (e.g., spacing or 238punctuation) will remain. 239