| 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 space 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> |