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