usr.bin/getaddrinfo/getaddrinfo.1

   1 .\"     $FreeBSD$
   2 .\"     $NetBSD: getaddrinfo.1,v 1.5 2014/04/22 06:02:06 wiz Exp $
   3 .\"
   4 .\" Copyright (c) 2013 The NetBSD Foundation, Inc.
   5 .\" All rights reserved.
   6 .\"
   7 .\" This documentation is derived from text contributed to The NetBSD
   8 .\" Foundation by Taylor R. Campbell.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  21 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  22 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  23 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  25 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  26 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  27 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  29 .\" POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .Dd March 20, 2017
  32 .Dt GETADDRINFO 1
  33 .Os
  34 .Sh NAME
  35 .Nm getaddrinfo
  36 .Nd resolve names to socket addresses
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl cNnP
  40 .Op Fl f Ar family
  41 .Op Fl p Ar protocol
  42 .Op Fl s Ar service Ns Op Ns / Ns Ar protocol
  43 .Op Fl t Ar socktype
  44 .Op Ar hostname
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility resolves host and service names to socket addresses with
  49 .Xr getaddrinfo 3
  50 and prints them to standard output in a user-friendly format.
  51 .Pp
  52 The output is a sequence of lines with space-separated fields:
  53 .Pp
  54 .Dl socket-type address-family protocol [af-specific data ...]
  55 .Pp
  56 For the
  57 .Dq inet
  58 and
  59 .Dq inet6
  60 address families, the af-specific data are the IP/IPv6 address and port
  61 number.
  62 .Pp
  63 Depending on the settings in
  64 .Xr nsswitch.conf 5 ,
  65 .Nm
  66 might query DNS for answers.
  67 However, it is not intended to be a general-purpose DNS query utility.
  68 Use
  69 .Xr drill 1
  70 for that.
  71 .Pp
  72 These options are available:
  73 .Bl -tag -width Ds
  74 .It Fl c
  75 Look up a canonical name as if with the
  76 .Dv AI_CANONNAME
  77 flag to
  78 .Xr getaddrinfo 3
  79 and print it on the first line before the socket addresses.
  80 .It Fl f Ar family
  81 Specify an address family.
  82 Address families are named like the
  83 .Dv AF_...
  84 constants for address family numbers in the
  85 .Aq Pa sys/socket.h
  86 header file but without the
  87 .Dv AF_
  88 prefix and lowercase.
  89 For example,
  90 .Dq inet
  91 corresponds with
  92 .Dv AF_INET .
  93 .It Fl N
  94 Treat the service as numeric and do not attempt service name
  95 resolution, as if with the
  96 .Dv AI_NUMERICSERV
  97 flag to
  98 .Xr getaddrinfo 3 .
  99 .It Fl n
 100 Treat the hostname as a numeric address and do not attempt name
 101 resolution, as if with the
 102 .Dv AI_NUMERICHOST
 103 flag to
 104 .Xr getaddrinfo 3 .
 105 .It Fl P
 106 Return socket addresses intended for use with
 107 .Xr bind 2 ,
 108 as if with the
 109 .Dv AI_PASSIVE
 110 flag to
 111 .Xr getaddrinfo 3 .
 112 By default, the socket addresses are intended for use with
 113 .Xr connect 2 ,
 114 .Xr sendto 2 ,
 115 or
 116 .Xr sendmsg 2 .
 117 .It Fl p Ar protocol
 118 Specify a protocol.
 119 Protocols are numeric or symbolic as listed in
 120 .Xr protocols 5 .
 121 .It Fl s Ar service Ns Op Ns / Ns Ar protocol
 122 Specify a service to look up.
 123 Services are symbolic or numeric with an optional
 124 protocol suffix as listed in
 125 .Xr services 5 .
 126 If a service is not specified, a hostname is required.
 127 .It Fl t Ar socktype
 128 Specify a socket type.
 129 Socket types are named like the
 130 .Dv SOCK_...
 131 constants for socket type numbers in the
 132 .Aq Pa sys/socket.h
 133 header file but without the
 134 .Dv SOCK_
 135 prefix and lowercase.
 136 For example,
 137 .Dq dgram
 138 corresponds with
 139 .Dv SOCK_DGRAM .
 140 .El
 141 .Sh EXIT STATUS
 142 .Ex -std getaddrinfo
 143 .Sh EXAMPLES
 144 Look up
 145 .Dq www.NetBSD.org :
 146 .Bd -literal -offset indent
 147 $ getaddrinfo www.NetBSD.org
 148 dgram inet6 udp 2001:4f8:3:7:2e0:81ff:fe52:9ab6 0
 149 dgram inet udp 149.20.53.67 0
 150 stream inet6 tcp 2001:4f8:3:7:2e0:81ff:fe52:9ab6 0
 151 stream inet tcp 149.20.53.67 0
 152 .Ed
 153 .Pp
 154 The port number here is zero because no service was specified.
 155 .Pp
 156 Look up
 157 .Dq morden.NetBSD.org
 158 for stream sockets on port 80, and show the canonical name:
 159 .Bd -literal -offset indent
 160 $ getaddrinfo -c -t stream -s 80 morden.NetBSD.org
 161 canonname ftp.NetBSD.org
 162 stream inet6 tcp 2001:470:1f05:3d::21 80
 163 stream inet tcp 199.233.217.249 80
 164 .Ed
 165 .Sh SEE ALSO
 166 .Xr drill 1 ,
 167 .Xr getent 1 ,
 168 .Xr getaddrinfo 3 ,
 169 .Xr getnameinfo 3 ,
 170 .Xr resolver 3 ,
 171 .Xr hosts 5 ,
 172 .Xr nsswitch.conf 5 ,
 173 .Xr protocols 5 ,
 174 .Xr resolv.conf 5 ,
 175 .Xr services 5
 176 .Sh HISTORY
 177 The
 178 .Nm
 179 command first appeared in
 180 .Nx 7.0 .