Commit | Line | Data |
---|---|---|
d3fafed3 MW |
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> |