diff options
Diffstat (limited to 'lib/libc/net/gethostbyname.3')
| -rw-r--r-- | lib/libc/net/gethostbyname.3 | 379 |
1 files changed, 379 insertions, 0 deletions
diff --git a/lib/libc/net/gethostbyname.3 b/lib/libc/net/gethostbyname.3 new file mode 100644 index 0000000..7c83d02 --- /dev/null +++ b/lib/libc/net/gethostbyname.3 @@ -0,0 +1,379 @@ +.\" Copyright (c) 1983, 1987, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 +.\" $FreeBSD$ +.\" +.Dd May 25, 1995 +.Dt GETHOSTBYNAME 3 +.Os +.Sh NAME +.Nm gethostbyname , +.Nm gethostbyname2 , +.Nm gethostbyaddr , +.Nm gethostent , +.Nm sethostent , +.Nm endhostent , +.Nm herror , +.Nm hstrerror +.Nd get network host entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In netdb.h +.Vt extern int h_errno ; +.Ft struct hostent * +.Fn gethostbyname "const char *name" +.Ft struct hostent * +.Fn gethostbyname2 "const char *name" "int af" +.Ft struct hostent * +.Fn gethostbyaddr "const void *addr" "socklen_t len" "int type" +.Ft struct hostent * +.Fn gethostent void +.Ft void +.Fn sethostent "int stayopen" +.Ft void +.Fn endhostent void +.Ft void +.Fn herror "const char *string" +.Ft const char * +.Fn hstrerror "int err" +.Sh DESCRIPTION +.Bf -symbolic +The +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 +functions are preferred over the +.Fn gethostbyname , +.Fn gethostbyname2 , +and +.Fn gethostbyaddr +functions. +.Ef +.Pp +The +.Fn gethostbyname , +.Fn gethostbyname2 +and +.Fn gethostbyaddr +functions +each return a pointer to an object with the +following structure describing an internet host +referenced by name or by address, respectively. +.Pp +The +.Fa name +argument passed to +.Fn gethostbyname +or +.Fn gethostbyname2 +should point to a +.Dv NUL Ns -terminated +hostname. +The +.Fa addr +argument passed to +.Fn gethostbyaddr +should point to an address which is +.Fa len +bytes long, +in binary form +(i.e., not an IP address in human readable +.Tn ASCII +form). +The +.Fa type +argument specifies the address family +(e.g.\& +.Dv AF_INET , AF_INET6 , +etc.) of this address. +.Pp +The structure returned contains either the information obtained from the name +server, +.Xr named 8 , +broken-out fields from a line in +.Pa /etc/hosts , +or database entries supplied by the +.Xr yp 8 +system. +The order of the lookups is controlled by the +.Sq hosts +entry in +.Xr nsswitch.conf 5 . +.Bd -literal +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +.Ed +.Pp +The members of this structure are: +.Bl -tag -width h_addr_list +.It Va h_name +Official name of the host. +.It Va h_aliases +A +.Dv NULL Ns -terminated +array of alternate names for the host. +.It Va h_addrtype +The type of address being returned; usually +.Dv AF_INET . +.It Va h_length +The length, in bytes, of the address. +.It Va h_addr_list +A +.Dv NULL Ns -terminated +array of network addresses for the host. +Host addresses are returned in network byte order. +.It Va h_addr +The first address in +.Va h_addr_list ; +this is for backward compatibility. +.El +.Pp +When using the nameserver, +.Fn gethostbyname +and +.Fn gethostbyname2 +will search for the named host in the current domain and its parents +unless the name ends in a dot. +If the name contains no dot, and if the environment variable +.Dq Ev HOSTALIASES +contains the name of an alias file, the alias file will first be searched +for an alias matching the input name. +See +.Xr hostname 7 +for the domain search procedure and the alias file format. +.Pp +The +.Fn gethostbyname2 +function is an evolution of +.Fn gethostbyname +which is intended to allow lookups in address families other than +.Dv AF_INET , +for example +.Dv AF_INET6 . +.Pp +The +.Fn sethostent +function +may be used to request the use of a connected +.Tn TCP +socket for queries. +If the +.Fa stayopen +flag is non-zero, +this sets the option to send all queries to the name server using +.Tn TCP +and to retain the connection after each call to +.Fn gethostbyname , +.Fn gethostbyname2 +or +.Fn gethostbyaddr . +Otherwise, queries are performed using +.Tn UDP +datagrams. +.Pp +The +.Fn endhostent +function +closes the +.Tn TCP +connection. +.Pp +The +.Fn herror +function writes a message to the diagnostic output consisting of the +string argument +.Fa string , +the constant string +.Qq Li ":\ " , +and a message corresponding to the value of +.Va h_errno . +.Pp +The +.Fn hstrerror +function returns a string which is the message text corresponding to the +value of the +.Fa err +argument. +.Sh FILES +.Bl -tag -width /etc/nsswitch.conf -compact +.It Pa /etc/hosts +.It Pa /etc/nsswitch.conf +.It Pa /etc/resolv.conf +.El +.Sh EXAMPLES +Print out the hostname associated with a specific IP address: +.Bd -literal -offset indent +const char *ipstr = "127.0.0.1"; +struct in_addr ip; +struct hostent *hp; + +if (!inet_aton(ipstr, &ip)) + errx(1, "can't parse IP address %s", ipstr); + +if ((hp = gethostbyaddr((const void *)&ip, + sizeof ip, AF_INET)) == NULL) + errx(1, "no name associated with %s", ipstr); + +printf("name associated with %s is %s\en", ipstr, hp->h_name); +.Ed +.Sh DIAGNOSTICS +Error return status from +.Fn gethostbyname , +.Fn gethostbyname2 +and +.Fn gethostbyaddr +is indicated by return of a +.Dv NULL +pointer. +The external integer +.Va h_errno +may then be checked to see whether this is a temporary failure +or an invalid or unknown host. +The routine +.Fn herror +can be used to print an error message describing the failure. +If its argument +.Fa string +is +.Pf non- Dv NULL , +it is printed, followed by a colon and a space. +The error message is printed with a trailing newline. +.Pp +The variable +.Va h_errno +can have the following values: +.Bl -tag -width HOST_NOT_FOUND +.It Dv HOST_NOT_FOUND +No such host is known. +.It Dv TRY_AGAIN +This is usually a temporary error +and means that the local server did not receive +a response from an authoritative server. +A retry at some later time may succeed. +.It Dv NO_RECOVERY +Some unexpected server failure was encountered. +This is a non-recoverable error. +.It Dv NO_DATA +The requested name is valid but does not have an IP address; +this is not a temporary error. +This means that the name is known to the name server but there is no address +associated with this name. +Another type of request to the name server using this domain name +will result in an answer; +for example, a mail-forwarder may be registered for this domain. +.El +.Sh SEE ALSO +.Xr getaddrinfo 3 , +.Xr getnameinfo 3 , +.Xr inet_aton 3 , +.Xr resolver 3 , +.Xr hosts 5 , +.Xr hostname 7 , +.Xr named 8 +.Sh CAVEAT +The +.Fn gethostent +function +is defined, and +.Fn sethostent +and +.Fn endhostent +are redefined, +when +.Lb libc +is built to use only the routines to lookup in +.Pa /etc/hosts +and not the name server. +.Pp +The +.Fn gethostent +function +reads the next line of +.Pa /etc/hosts , +opening the file if necessary. +.Pp +The +.Fn sethostent +function +opens and/or rewinds the file +.Pa /etc/hosts . +If the +.Fa stayopen +argument is non-zero, +the file will not be closed after each call to +.Fn gethostbyname , +.Fn gethostbyname2 +or +.Fn gethostbyaddr . +.Pp +The +.Fn endhostent +function +closes the file. +.Sh HISTORY +The +.Fn herror +function appeared in +.Bx 4.3 . +The +.Fn endhostent , +.Fn gethostbyaddr , +.Fn gethostbyname , +.Fn gethostent , +and +.Fn sethostent +functions appeared in +.Bx 4.2 . +The +.Fn gethostbyname2 +function first appeared in +.Tn BIND +version 4.9.4. +.Sh BUGS +These functions use a thread-specific data storage; +if the data is needed for future use, it should be +copied before any subsequent calls overwrite it. +.Pp +Though these functions are thread-safe, +still it is recommended to use the +.Xr getaddrinfo 3 +family of functions, instead. +.Pp +Only the Internet +address format is currently understood. |
