lib/libutil/sockaddr_snprintf.3

   1 .\"     $NetBSD: sockaddr_snprintf.3,v 1.7 2009/04/11 16:13:49 joerg 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 April 9, 2005
  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
  43 The
  44 .Fn sockaddr_snprintf
  45 function formats a socket address into a form suitable for printing.
  46 .Pp
  47 This function is convenient because it is protocol independent, i.e. one does
  48 not need to know the address family of the sockaddr in order to print it.
  49 The
  50 .Xr printf 3
  51 like format string specifies how the address is going to be printed.
  52 Some formatting characters are only supported by some address families.
  53 If a certain formatting character is not supported, then the string
  54 .Dq N/A
  55 is printed.
  56 .Pp
  57 The resulting formatted string is placed into
  58 .Fa buf .
  59 Up to
  60 .Fa buflen
  61 characters are placed in
  62 .Fa buf .
  63 .Pp
  64 The following formatting characters are supported (immediately
  65 after a percent
  66 .Pq Sq %
  67 sign):
  68 .Bl -tag -width %a
  69 .It a
  70 The node address portion of the socket address is printed numerically.
  71 For
  72 .Dv AF_INET
  73 the address is printed as:
  74 .Dq A.B.C.D
  75 and
  76 for AF_INET6
  77 the address is printed as:
  78 .Dq A:B...[%if]
  79 using
  80 .Xr getnameinfo 3
  81 internally with
  82 .Dv NI_NUMERICHOST .
  83 For
  84 .Dv AF_APPLETALK
  85 the address is printed as:
  86 .Dq A.B
  87 For
  88 .Dv AF_LOCAL
  89 .Pq Dv AF_UNIX
  90 the address is printed as:
  91 .Dq socket-path
  92 For
  93 .Dv AF_LINK
  94 the address is printed as:
  95 .Dq a.b.c.d.e.f
  96 using
  97 .Xr link_ntoa 3 ,
  98 but the interface portion is skipped (see below).
  99 For
 100 .Dv AF_UNSPEC
 101 nothing is printed.
 102 .It A
 103 The symbolic name of the address is printed.
 104 For
 105 .Dv AF_INET
 106 and
 107 .Dv AF_INET6
 108 this is the hostname associated with the address.
 109 For all other address families, it is the same as the
 110 .Dq a
 111 format.
 112 .It f
 113 The numeric value of the family of the address is printed.
 114 .It l
 115 The length of the socket address is printed.
 116 .It p
 117 For
 118 .Dv AF_INET ,
 119 .Dv AF_INET6 ,
 120 and
 121 .Dv AF_APPLETALK
 122 the numeric value of the port portion of the address is printed.
 123 .It P
 124 For
 125 .Dv AF_INET
 126 and
 127 .Dv AF_INET6
 128 this is the name of the service associated with the port number, if
 129 available.
 130 For all other address families, it is the same as the
 131 .Dq p
 132 format.
 133 .It I
 134 For
 135 .Dv AF_LINK
 136 addresses, the interface name portion is printed.
 137 .It F
 138 For
 139 .Dv AF_INET6
 140 addresses, the flowinfo portion of the address is printed numerically.
 141 .It R
 142 For
 143 .Dv AF_APPLETALK
 144 addresses, the netrange portion of the address is printed as:
 145 .Dq phase:[firstnet,lastnet]
 146 .It S
 147 For
 148 .Dv AF_INET6
 149 addresses, the scope portion of the address is printed numerically.
 150 .It ?
 151 If present between
 152 .Dq %
 153 and the format character, and the selected format does not apply to
 154 the given address family, the
 155 .Dq N/A
 156 string is elided and no output results.
 157 .El
 158 .Sh RETURN VALUES
 159 The
 160 .Fn sockaddr_snprintf
 161 function returns the number of characters that are required to format the
 162 value
 163 .Fa val
 164 given the format string
 165 .Fa fmt
 166 excluding the terminating NUL.
 167 The returned string in
 168 .Fa buf
 169 is always NUL-terminated.
 170 If the address family is not supported,
 171 .Fn sockaddr_snprintf
 172 returns \-1 and sets
 173 .Va errno
 174 to
 175 .Dv EAFNOSUPPORT .
 176 For
 177 .Dv AF_INET
 178 and
 179 .Dv AF_INET6
 180 addresses
 181 .Fn sockaddr_snprintf
 182 returns \-1 if the
 183 .Xr getnameinfo 3
 184 conversion failed, and
 185 .Fa errno
 186 is set to the error value from
 187 .Xr getnameinfo 3 .
 188 .Sh ERRORS
 189 If the buffer
 190 .Fa buf
 191 is too small to hold the formatted output,
 192 .Fn sockaddr_snprintf
 193 will still return the buffer, containing a truncated string.
 194 .Sh SEE ALSO
 195 .Xr getaddrinfo 3 ,
 196 .Xr getnameinfo 3 ,
 197 .Xr link_ntoa 3 ,
 198 .Xr snprintf 3
 199 .Sh HISTORY
 200 The
 201 .Fn sockaddr_snprintf
 202 first appeared in
 203 .Nx 3.0 .
 204 .Sh BUGS
 205 The
 206 .Fn sockaddr_snprintf
 207 interface is experimental and might change in the future.
 208 .Pp
 209 There is no way to specify different formatting styles for particular
 210 addresses.
 211 For example it would be useful to print
 212 .Dv AF_LINK
 213 addresses as
 214 .Dq %.2x:%.2x...
 215 instead of
 216 .Dq %x.%x...
 217 .Pp
 218 This function is supposed to be quick, but
 219 .Xr getnameinfo 3
 220 might use system calls to convert the scope number to an interface
 221 name and the
 222 .Dq A
 223 and
 224 .Dq P
 225 format characters call
 226 .Xr getaddrinfo 3
 227 which may block for a noticeable period of time.
 228 .Pp
 229 Not all formatting characters are supported by all address families and
 230 printing
 231 .Dq N/A
 232 is not very convenient.
 233 The
 234 .Dq \&?
 235 character can suppress this, but other formatting (e.g., spacing or
 236 punctuation) will remain.