.\" -*-nroff-*-
.ie t .ds o \(bu
.el .ds o *
.de hP
.IP
\fB\h'-\w'\\$1'u-1m'\\$1\h'1m'\fP\c
..
.TH space 1 "13 September 2017" "Straylight/Edgeware"
.SH NAME
gai \- look up names using getaddrinfo
.SH SYNOPSIS
.B gai
.RB [ \-CNacgimnsuv ]
.RB [ \-f
.IR family ]
.RB [ \-p
.IR protocol ]
.RB [ \-t
.IR type ]
.I name
.RI [ service ]
.SH DESCRIPTION
The
.B gai
program looks up host and/or service names
using the
.BR getaddrinfo (3)
C-library function,
and reports the results in a machine-readable manner.
.PP
The following command-line options are recognized.
.TP
.B \-h
Give a short help message describing the options available.
.TP
.B \-a
If
.B \-m
is set,
report plain IPv4 address
.I in addition to
the corresponding v6-mapped addresses.
Sets the
.B AI_ALL
flag.
See also
.BR \-m .
.TP
.B \-c
Report the canonical name of the host.
Sets the
.B AI_CANONNAME
flag.
See also
.BR \-C .
.TP
.B \-C
If the canonical name is an IDN,
then convert it back into the local character set before display.
Sets the
.B AI_CANONIDN
flag.
See also
.BR \-c .
.TP
.BI "\-f " family
Return only addresses for the given address
.IR family ,
which may be one of
.B unspec
(any address family is acceptable; the default),
.B inet
(IPv4), or
.B inet6
(IPv6).
Sets the
.B ai_family
hint.
.TP
.B \-g
Return only addresses of families
for which the host has a configured address.
This is less useful than it sounds
because of IPv6 link-local addresses.
Sets the
.B AI_ADDRCONFIG
flag.
.TP
.B \-i
Convert hostnames containing unusual characters to IDNs.
Sets the
.B AI_IDN
flag.
.TP
.B \-m
Return IPv4 addresses as their v6-mapped equivalents.
Sets the
.B AI_V4MAPPED
flag.
See also
.BR \-a .
.TP
.B \-n
Accept only numeric host addresses;
do not attempt to resolve hostnames.
(Scope ids on link-local IPv6 addresses are still accepted.)
Sets the
.B AI_NUMERICHOST
flag.
See also
.BR \-N .
.TP
.B \-n
Accept only numeric port numbers;
do not attempt to resolve service names.
Sets the
.B AI_NUMERICSERV
flag.
See also
.BR \-n .
.TP
.BI "\-p " protocol
Return only addresses suitable for use with the given
.I protocol ,
which may be a protocol number
or a name to be looked up in
.BR /etc/protocols .
Sets the
.B ai_protocol
hint.
.TP
.B \-s
Allow unassigned Unicode code points in IDNs.
Sets the
.B AI_IDN_ALLOW_UNASSIGNED
flag.
See also
.B \-C
and
.BR \-i .
.TP
.BI "\-t " type
Return only addresses for the given socket
.I type ,
which may be one of
.B any
(no restriction; the default),
.BR stream ,
.BR dgram ,
or
.BR raw .
Sets the
.B ai_socktype
hint.
.TP
.B \-u
Check that the result of IDN conversion is a valid STD3 host name.
Sets the
.B AI_IDN_USE_STD3_ASCII_RULES
flag.
See also
.B \-C
and
.BR \-i .
.TP
.B \-v
Default the host address suitably for use for receiving connections;
if
.I name
is
.RB ` \- '
then return appropriate wildcard addresses rather than loopback
addresses.
Sets the
.B AI_PASSIVE
flag.
.PP
The
.I name
may be
.RB ` \- '
to indicate that a service-only lookup should be performed.
The
.I service
may be omitted to indicate that a hostname-only lookup should be
performed.
.PP
The output is as follows.
Firstly, if
.B \-c
is set, then a line
.IP
.BI [ canon ]
.PP
is written showing the canonical host name.
Following this (if it's present) are one or more lines of the form
.IP
.IR family " " type " " address " " port
.PP
The
.I family
shows the address family of the given address, as either
.B inet
or
.BR inet6 .
The
.I type
shows the socket type, as
.BR stream ,
.BR dgram ,
or
.BR raw .
The
.I address
and
.I port
are the numeric address and service,
as produced by
.BR getnameinfo (3).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>