chiark - git - mdw - misc/blob - gai.1

   1 .\" -*-nroff-*-
   2 .ie t .ds o \(bu
   3 .el .ds o *
   4 .de hP
   5 .IP
   6 \fB\h'-\w'\\$1'u-1m'\\$1\h'1m'\fP\c
   7 ..
   8 .TH gai 1 "13 September 2017" "Straylight/Edgeware"
   9 .SH NAME
  10 gai \- look up names using getaddrinfo
  11 .SH SYNOPSIS
  12 .B gai
  13 .RB [ \-CNacgimnsuv ]
  14 .RB [ \-f
  15 .IR family ]
  16 .RB [ \-p
  17 .IR protocol ]
  18 .RB [ \-t
  19 .IR type ]
  20 .I name
  21 .RI [ service ]
  22 .SH DESCRIPTION
  23 The
  24 .B gai
  25 program looks up host and/or service names
  26 using the
  27 .BR getaddrinfo (3)
  28 C-library function,
  29 and reports the results in a machine-readable manner.
  30 .PP
  31 The following command-line options are recognized.
  32 .TP
  33 .B \-h
  34 Give a short help message describing the options available.
  35 .TP
  36 .B \-a
  37 If
  38 .B \-m
  39 is set,
  40 report plain IPv4 address
  41 .I in addition to
  42 the corresponding v6-mapped addresses.
  43 Sets the
  44 .B AI_ALL
  45 flag.
  46 See also
  47 .BR \-m .
  48 .TP
  49 .B \-c
  50 Report the canonical name of the host.
  51 Sets the
  52 .B AI_CANONNAME
  53 flag.
  54 See also
  55 .BR \-C .
  56 .TP
  57 .B \-C
  58 If the canonical name is an IDN,
  59 then convert it back into the local character set before display.
  60 Sets the
  61 .B AI_CANONIDN
  62 flag.
  63 See also
  64 .BR \-c .
  65 .TP
  66 .BI "\-f " family
  67 Return only addresses for the given address
  68 .IR family ,
  69 which may be one of
  70 .B unspec
  71 (any address family is acceptable; the default),
  72 .B inet
  73 (IPv4), or
  74 .B inet6
  75 (IPv6).
  76 Sets the
  77 .B ai_family
  78 hint.
  79 .TP
  80 .B \-g
  81 Return only addresses of families
  82 for which the host has a configured address.
  83 This is less useful than it sounds
  84 because of IPv6 link-local addresses.
  85 Sets the
  86 .B AI_ADDRCONFIG
  87 flag.
  88 .TP
  89 .B \-i
  90 Convert hostnames containing unusual characters to IDNs.
  91 Sets the
  92 .B AI_IDN
  93 flag.
  94 .TP
  95 .B \-m
  96 Return IPv4 addresses as their v6-mapped equivalents.
  97 Sets the
  98 .B AI_V4MAPPED
  99 flag.
 100 See also
 101 .BR \-a .
 102 .TP
 103 .B \-n
 104 Accept only numeric host addresses;
 105 do not attempt to resolve hostnames.
 106 (Scope ids on link-local IPv6 addresses are still accepted.)
 107 Sets the
 108 .B AI_NUMERICHOST
 109 flag.
 110 See also
 111 .BR \-N .
 112 .TP
 113 .B \-n
 114 Accept only numeric port numbers;
 115 do not attempt to resolve service names.
 116 Sets the
 117 .B AI_NUMERICSERV
 118 flag.
 119 See also
 120 .BR \-n .
 121 .TP
 122 .BI "\-p " protocol
 123 Return only addresses suitable for use with the given
 124 .I protocol ,
 125 which may be a protocol number
 126 or a name to be looked up in
 127 .BR /etc/protocols .
 128 Sets the
 129 .B ai_protocol
 130 hint.
 131 .TP
 132 .B \-s
 133 Allow unassigned Unicode code points in IDNs.
 134 Sets the
 135 .B AI_IDN_ALLOW_UNASSIGNED
 136 flag.
 137 See also
 138 .B \-C
 139 and
 140 .BR \-i .
 141 .TP
 142 .BI "\-t " type
 143 Return only addresses for the given socket
 144 .I type ,
 145 which may be one of
 146 .B any
 147 (no restriction; the default),
 148 .BR stream ,
 149 .BR dgram ,
 150 or
 151 .BR raw .
 152 Sets the
 153 .B ai_socktype
 154 hint.
 155 .TP
 156 .B \-u
 157 Check that the result of IDN conversion is a valid STD3 host name.
 158 Sets the
 159 .B AI_IDN_USE_STD3_ASCII_RULES
 160 flag.
 161 See also
 162 .B \-C
 163 and
 164 .BR \-i .
 165 .TP
 166 .B \-v
 167 Default the host address suitably for use for receiving connections;
 168 if
 169 .I name
 170 is
 171 .RB ` \- '
 172 then return appropriate wildcard addresses rather than loopback
 173 addresses.
 174 Sets the
 175 .B AI_PASSIVE
 176 flag.
 177 .PP
 178 The
 179 .I name
 180 may be
 181 .RB ` \- '
 182 to indicate that a service-only lookup should be performed.
 183 The
 184 .I service
 185 may be omitted to indicate that a hostname-only lookup should be
 186 performed.
 187 .PP
 188 The output is as follows.
 189 Firstly, if
 190 .B \-c
 191 is set, then a line
 192 .IP
 193 .BI [ canon ]
 194 .PP
 195 is written showing the canonical host name.
 196 Following this (if it's present) are one or more lines of the form
 197 .IP
 198 .IR family " " type " " address " " port
 199 .PP
 200 The
 201 .I family
 202 shows the address family of the given address, as either
 203 .B inet
 204 or
 205 .BR inet6 .
 206 The
 207 .I type
 208 shows the socket type, as
 209 .BR stream ,
 210 .BR dgram ,
 211 or
 212 .BR raw .
 213 The
 214 .I address
 215 and
 216 .I port
 217 are the numeric address and service,
 218 as produced by
 219 .BR getnameinfo (3).
 220 .SH AUTHOR
 221 Mark Wooding, <mdw@distorted.org.uk>