usr.bin/getaddrinfo/getaddrinfo.1

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