1.\" $NetBSD: getipnodebyname.3,v 1.1.1.2 2012/09/09 16:07:43 christos Exp $ 2.\" 3.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") 4.\" 5.\" Permission to use, copy, modify, and/or distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15.\" PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" Id: getipnodebyname.3,v 1.3 2009/01/22 23:49:23 tbox Exp 18.\" 19.Dd September 17, 1999 20.Dt GETIPNODEBYNAME @LIB_NETWORK_EXT_U@ 21.Os BSD 4 22.Sh NAME 23.Nm getipnodebyname , 24.Nm getipnodebyaddr 25.Nd get network host entry 26.br 27.Nm freehostent 28.Nd free network host entry 29.Sh SYNOPSIS 30.Fd #include <netdb.h> 31.Pp 32.Ft struct hostent * 33.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error" 34.Ft struct hostent * 35.Fn getipnodebyaddr "const void *addr" "size_t len" "int af" "int *error" 36.Ft void 37.Fn freehostent "struct hostent *he" 38.Sh DESCRIPTION 39.Fn Getipnodebyname , 40and 41.Fn getipnodebyaddr 42each return a pointer to a 43.Ft hostent 44structure (see below) describing an internet host 45referenced by name or by address, as the function names indicate. 46This structure contains either the information obtained from the name server, 47or broken-out fields from a line in 48.Pa /etc/hosts . 49If the local name server is not running, these routines do a lookup in 50.Pa /etc/hosts . 51.Bd -literal -offset indent 52struct hostent { 53 char *h_name; /* official name of host */ 54 char **h_aliases; /* alias list */ 55 int h_addrtype; /* host address type */ 56 int h_length; /* length of address */ 57 char **h_addr_list; /* list of addresses from name server */ 58}; 59 60#define h_addr h_addr_list[0] /* address, for backward compatibility */ 61.Ed 62.Pp 63The members of this structure are: 64.Bl -tag -width "h_addr_list" 65.It h_name 66Official name of the host. 67.It h_aliases 68A zero-terminated array of alternate names for the host. 69.It h_addrtype 70The type of address being returned. 71.It h_length 72The length, in bytes, of the address. 73.It h_addr_list 74A zero-terminated array of network addresses for the host. 75Host addresses are returned in network byte order. 76.It h_addr 77The first address in 78.Li h_addr_list ; 79this is for backward compatibility. 80.El 81.Pp 82This structure should be freed after use by calling 83.Fn freehostent . 84.Pp 85When using the nameserver, 86.Fn getiphostbyaddr 87will search for the named host in each parent domain given in the 88.Dq Li search 89directive of 90.Xr resolv.conf @FORMAT_EXT@ 91unless the name contains a dot 92.Pq Dq \&. . 93If the name contains no dot, and if the environment variable 94.Ev HOSTALIASES 95contains the name of an alias file, the alias file will first be searched 96for an alias matching the input name. 97See 98.Xr hostname @DESC_EXT@ 99for the domain search procedure and the alias file format. 100.Pp 101.Fn Getiphostbyaddr 102can be told to look for IPv4 addresses, IPv6 addresses or both IPv4 and IPv6. 103If IPv4 addresses only are to be looked up then 104.Fa af 105should be set to 106.Dv AF_INET , 107otherwise it should be set to 108.Dv AF_INET6 . 109.Pp 110There are three flags that can be set 111.Bl -tag -width "AI_ADDRCONFIG" 112.It Dv AI_V4MAPPED 113Return IPv4 addresses if no IPv6 addresses are found. 114This flag is ignored unless 115.Fa af 116is 117.Dv AF_INET6 . 118.It Dv AI_ALL 119Return IPv4 addresses as well IPv6 addresses if 120.Dv AI_V4MAPPED 121is set. 122This flag is ignored unless 123.Fa af 124is 125.Dv AF_INET6 . 126.It Dv AI_ADDRCONFIG 127Only return addresses of a given type if the system has an active interface 128with that type. 129.El 130.Pp 131Also 132.Dv AI_DEFAULT 133is defined to be 134.Dv (AI_V4MAPPED|AI_ADDRCONFIG) . 135.Pp 136.Fn Getipnodebyaddr 137will lookup IPv4 mapped and compatible addresses in the IPv4 name 138space and IPv6 name space 139.Pp 140.Fn Freehostent 141frees the hostent structure allocated be 142.Fn getipnodebyname 143and 144.Fn getipnodebyaddr . 145The structures returned by 146.Fn gethostbyname , 147.Fn gethostbyname2 , 148.Fn gethostbyaddr 149and 150.Fn gethostent 151should not be passed to 152.Fn freehostent 153as they are pointers to static areas. 154.Sh ENVIRONMENT 155.Bl -tag -width "HOSTALIASES " -compact 156.It Ev HOSTALIASES 157Name of file containing 158.Pq Ar host alias , full hostname 159pairs. 160.El 161.Sh FILES 162.Bl -tag -width "HOSTALIASES " -compact 163.It Pa /etc/hosts 164See 165.Xr hosts @FORMAT_EXT@ . 166.El 167.Sh DIAGNOSTICS 168.Pp 169Error return status from 170.Fn getipnodebyname 171and 172.Fn getipnodebyaddr 173is indicated by return of a null pointer. 174In this case 175.Ft error 176may then be checked to see whether this is a temporary failure 177or an invalid or unknown host. 178.Ft errno 179can have the following values: 180.Bl -tag -width "HOST_NOT_FOUND " -offset indent 181.It Dv NETDB_INTERNAL 182This indicates an internal error in the library, unrelated to the network 183or name service. 184.Ft errno 185will be valid in this case; see 186.Xr perror @SYSCALL_EXT@ . 187.It Dv HOST_NOT_FOUND 188No such host is known. 189.It Dv TRY_AGAIN 190This is usually a temporary error 191and means that the local server did not receive 192a response from an authoritative server. 193A retry at some later time may succeed. 194.It Dv NO_RECOVERY 195Some unexpected server failure was encountered. 196This is a non-recoverable error, as one might expect. 197.It Dv NO_ADDRESS 198The requested name is valid but does not have an IP address; 199this is not a temporary error. 200This means that the name is known to the name server but there is no address 201associated with this name. 202Another type of request to the name server using this domain name 203will result in an answer; 204for example, a mail-forwarder may be registered for this domain. 205.El 206.Sh SEE ALSO 207.Xr hosts @FORMAT_EXT@ , 208.Xr hostname @DESC_EXT@ , 209.Xr resolver @LIB_NETWORK_EXT@ , 210.Xr resolver @FORMAT_EXT@ , 211.Xr gethostbyname @LIB_NETWORK_EXT@ , 212.Xr RFC2553 . 213