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