1.\" $NetBSD: sockaddr_snprintf.3,v 1.3 2004/12/01 00:06:46 peter 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 November 19, 2004 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 f 110The numeric value of the family of the address is printed. 111.It l 112The length of the socket address is printed. 113.It p 114For 115.Dv AF_INET , 116.Dv AF_INET6 , 117and 118.Dv AF_APPLETALK 119the numeric value of the port portion of the address is printed. 120.It I 121For 122.Dv AF_LINK 123addresses, the interface name portion is printed. 124.It F 125For 126.Dv AF_INET6 127addresses, the flowinfo portion of the address is printed numerically. 128.It R 129For 130.Dv AF_APPLETALK 131addresses, the netrange portion of the address is printed as: 132.Dq phase:[firstnet,lastnet] 133.It S 134For 135.Dv AF_INET6 136addresses, the scope portion of the address is printed numerically. 137.El 138.Sh RETURN VALUES 139The 140.Fn sockaddr_snprintf 141function returns the number of characters that are required to format the 142value 143.Fa val 144given the format string 145.Fa fmt 146excluding the terminating NUL. 147The returned string in 148.Fa buf 149is always NUL-terminated. 150If the address family is not supported, 151.Fn sockaddr_snprintf 152returns \-1 and sets 153.Va errno 154to 155.Dv EAFNOSUPPORT . 156For 157.Dv AF_INET 158and 159.DV AF_INET6 160addresses 161.Fn sockaddr_snprintf 162returns \-1 if the 163.Xr getnameinfo 3 164conversion failed, and 165.Fa errno 166is set to the error value from 167.Xr getnameinfo 3 . 168.Sh ERRORS 169If the buffer 170.Fa buf 171is too small to hold the formatted output, 172.Fn sockaddr_snprintf 173will still return the buffer, containing a truncated string. 174.Sh SEE ALSO 175.Xr getnameinfo 3 , 176.Xr link_ntoa 3 , 177.Xr snprintf 3 178.Sh HISTORY 179The 180.Fn sockaddr_snprintf 181first appeared in 182.Nx 3.0 . 183.Sh BUGS 184The 185.Fn sockaddr_snprintf 186interface is experimental and might change in the future. 187.Pp 188There is no way to specify different formatting styles for particular 189addresses. 190For example it would be useful to print 191.Dv AF_LINK 192addresses as 193.Dq %.2x:%.2x... 194instead of 195.Dq %x.%x... 196.Pp 197This function is supposed to be quick, but 198.Xr getnameinfo 3 199might use system calls to convert the scope number to an interface name. 200.Pp 201Not all formatting characters are supported by all address families and 202printing 203.Dq N/A 204is not very convenient. 205