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