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 77.Dv AF_INET6 78the address is printed as 79.Dq A:B...[%if] 80using 81.Xr getnameinfo 3 82internally with 83.Dv NI_NUMERICHOST . 84For 85.Dv AF_LOCAL 86.Pq Dv AF_UNIX 87the address is printed as 88.Dq socket-path . 89For 90.Dv AF_LINK 91the address is printed as 92.Dq a.b.c.d.e.f 93using 94.Xr link_ntoa 3 , 95but the interface portion is skipped (see below). 96For 97.Dv AF_UNSPEC 98nothing is printed. 99.It A 100The symbolic name of the address is printed. 101For 102.Dv AF_INET 103and 104.Dv AF_INET6 105this is the hostname associated with the address. 106For all other address families, it is the same as the 107.Dq a 108format. 109.It D 110Debugging output: 111For all addresses, print all their fields as 112.Dq field_name=value . 113.It f 114The numeric value of the family of the address is printed. 115.It l 116The length of the socket address is printed. 117.It p 118For 119.Dv AF_INET 120and 121.Dv AF_INET6 122the numeric value of the port portion of the address is printed. 123.It P 124For 125.Dv AF_INET 126and 127.Dv AF_INET6 128this is the name of the service associated with the port number, if 129available. 130For all other address families, it is the same as the 131.Dq p 132format. 133.It I 134For 135.Dv AF_LINK 136addresses, the interface name portion is printed. 137.It F 138For 139.Dv AF_INET6 140addresses, the flowinfo portion of the address is printed numerically. 141.It R 142For 143.Dv AF_APPLETALK 144addresses, 145always prints 146.Dq N/A , 147because not supported on 148.Dx . 149.It S 150For 151.Dv AF_INET6 152addresses, the scope portion of the address is printed numerically. 153.It ? 154If present between 155.Dq % 156and the format character, and the selected format does not apply to 157the given address family, the 158.Dq N/A 159string is elided and no output results. 160.El 161.Sh RETURN VALUES 162The 163.Fn sockaddr_snprintf 164function returns the number of characters that are required to format the 165value 166.Fa val 167given the format string 168.Fa fmt 169excluding the terminating NUL. 170The returned string in 171.Fa buf 172is always NUL-terminated. 173If the address family is not supported, 174.Fn sockaddr_snprintf 175returns \-1 and sets 176.Va errno 177to 178.Er EAFNOSUPPORT . 179For 180.Dv AF_INET 181and 182.Dv AF_INET6 183addresses 184.Fn sockaddr_snprintf 185returns \-1 if the 186.Xr getnameinfo 3 187conversion failed, and 188.Fa errno 189is set to the error value from 190.Xr getnameinfo 3 . 191.Sh ERRORS 192If the buffer 193.Fa buf 194is too small to hold the formatted output, 195.Fn sockaddr_snprintf 196will still return the buffer, containing a truncated string. 197.Sh SEE ALSO 198.Xr getaddrinfo 3 , 199.Xr getnameinfo 3 , 200.Xr link_ntoa 3 , 201.Xr snprintf 3 202.Sh HISTORY 203The 204.Fn sockaddr_snprintf 205first appeared in 206.Nx 3.0 . 207.Sh BUGS 208The 209.Fn sockaddr_snprintf 210interface is experimental and might change in the future. 211.Pp 212There is no way to specify different formatting styles for particular 213addresses. 214For example it would be useful to print 215.Dv AF_LINK 216addresses as 217.Dq %.2x:%.2x... 218instead of 219.Dq %x.%x... 220.Pp 221This function is supposed to be quick, but 222.Xr getnameinfo 3 223might use system calls to convert the scope number to an interface 224name and the 225.Dq A 226and 227.Dq P 228format characters call 229.Xr getaddrinfo 3 230which may block for a noticeable period of time. 231.Pp 232Not all formatting characters are supported by all address families and 233printing 234.Dq N/A 235is not very convenient. 236The 237.Dq \&? 238character can suppress this, but other formatting (e.g., spacing or 239punctuation) will remain. 240