X-Git-Url: https://git.distorted.org.uk/~mdw/misc/blobdiff_plain/99acf5cd9f964d9d42eebed4a27215cda3c57178..d3fafed3ea3c8937802eaae33ae3f5b8f2b45a62:/gai.1

diff --git a/gai.1 b/gai.1
new file mode 100644
index 0000000..6f0ddf1
--- /dev/null
+++ b/gai.1
@@ -0,0 +1,221 @@
+.\" -*-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>