lib/libutil/sockaddr_snprintf.3

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