diff options
Diffstat (limited to 'contrib/bind/man/gethostbyname.3')
| -rw-r--r-- | contrib/bind/man/gethostbyname.3 | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/contrib/bind/man/gethostbyname.3 b/contrib/bind/man/gethostbyname.3 new file mode 100644 index 0000000..23432a0 --- /dev/null +++ b/contrib/bind/man/gethostbyname.3 @@ -0,0 +1,226 @@ +.\" Copyright (c) 1983, 1987 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms are permitted provided +.\" that: (1) source distributions retain this entire copyright notice and +.\" comment, and (2) distributions including binaries display the following +.\" acknowledgement: ``This product includes software developed by the +.\" University of California, Berkeley and its contributors'' in the +.\" documentation or other materials provided with the distribution and in +.\" all advertising materials mentioning features or use of this software. +.\" 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED +.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" +.\" @(#)gethostbyname.3 6.12 (Berkeley) 6/23/90 +.\" +.TH GETHOSTBYNAME @LIB_NETWORK_EXT_U@ "June 23, 1990" +.UC 5 +.SH NAME +gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry +.SH SYNOPSIS +.B "#include <netdb.h> +.PP +.B "extern int h_errno; +.PP +.B "struct hostent *gethostbyname(name) +.br +.B "char *name; +.PP +.B "struct hostent *gethostbyname2(name, af) +.br +.B "char *name; int af; +.PP +.B "struct hostent *gethostbyaddr(addr, len, type) +.br +.B "char *addr; int len, type; +.PP +.B "struct hostent *gethostent() +.PP +.B "sethostent(stayopen) +.br +.B "int stayopen; +.PP +.B "endhostent() +.PP +.B "herror(string) +.br +.B "char *string; +.PP +.SH DESCRIPTION +.IR Gethostbyname , +.IR gethostbyname2 , +and +.I gethostbyaddr +each return a pointer to an object with the +following structure describing an internet host +referenced by name or by address, respectively. +This structure contains either the information obtained from the name server, +.IR @INDOT@named (@SYS_OPS_EXT@), +or broken-out fields from a line in +.IR /etc/hosts . +If the local name server is not running these routines do a lookup in +.IR /etc/hosts . +.RS +.PP +.nf +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 */ +.ft R +.ad +.fi +.RE +.PP +The members of this structure are: +.TP \w'h_addr_list'u+2n +h_name +Official name of the host. +.TP \w'h_addr_list'u+2n +h_aliases +A zero terminated array of alternate names for the host. +.TP \w'h_addr_list'u+2n +h_addrtype +The type of address being returned; usually AF_INET. +.TP \w'h_addr_list'u+2n +h_length +The length, in bytes, of the address. +.TP \w'h_addr_list'u+2n +h_addr_list +A zero terminated array of network addresses for the host. +Host addresses are returned in network byte order. +.TP \w'h_addr_list'u+2n +h_addr +The first address in h_addr_list; this is for backward compatibility. +.PP +When using the nameserver, +.I gethostbyname +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 ``HOSTALAIASES'' +contains the name of an alias file, the alias file will first be searched +for an alias matching the input name. +See +.IR hostname (@DESC_EXT@) +for the domain search procedure and the alias file format. +.PP +.I Gethostbyname2 +is an evolution of +.I gethostbyname +intended to allow lookups in address families other than AF_INET, for example +AF_INET6. Currently the +.I af +argument must be specified as +.I AF_INET +else the function will return \s-2NULL\s+2 after having set +.I h_errno +to \s-2NETDB_INTERNAL\s+2. +.PP +.I Sethostent +may be used to request the use of a connected TCP socket for queries. +If the +.I stayopen +flag is non-zero, +this sets the option to send all queries to the name server using TCP +and to retain the connection after each call to +.I gethostbyname +or +.IR gethostbyaddr . +Otherwise, queries are performed using UDP datagrams. +.PP +.I Endhostent +closes the TCP connection. +.SH DIAGNOSTICS +.PP +Error return status from +.I gethostbyname +and +.I gethostbyaddr +is indicated by return of a null pointer. +The external integer +.IR h_errno +may then be checked to see whether this is a temporary failure +or an invalid or unknown host. +The routine +.I herror +can be used to print an error message describing the failure. +If its argument +.I string +is non-NULL, it is printed, followed by a colon and a space. +The error message is printed with a trailing newline. +.PP +.IR h_errno +can have the following values: +.RS +.IP NETDB_INTERNAL \w'HOST_NOT_FOUND'u+2n +This indicates an internal error in the library, unrelated to the network +or name service. +.I errno +will be valid in this case; see +.IR perror (3). +.IP HOST_NOT_FOUND \w'HOST_NOT_FOUND'u+2n +No such host is known. +.IP TRY_AGAIN \w'HOST_NOT_FOUND'u+2n +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. +.IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n +Some unexpected server failure was encountered. +This is a non-recoverable error. +.IP NO_DATA \w'HOST_NOT_FOUND'u+2n +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. +.RE +.SH FILES +/etc/hosts +.SH "SEE ALSO" +resolver(@LIB_NETWORK_EXT@), hosts(@FORMAT_EXT@), hostname(@DESC_EXT@), @INDOT@named(@SYS_OPS_EXT@) +.SH CAVEAT +.PP +.I Gethostent +is defined, and +.I sethostent +and +.I endhostent +are redefined, +when +.IR libc +is built to use only the routines to lookup in +.IR /etc/hosts +and not the name server. +.PP +.I Gethostent +reads the next line of +.IR /etc/hosts , +opening the file if necessary. +.PP +.I Sethostent +is redefined to open and rewind the file. If the +.I stayopen +argument is non-zero, +the hosts data base will not be closed after each call to +.I gethostbyname +or +.IR gethostbyaddr . +.I Endhostent +is redefined to close the file. +.SH BUGS +All information +is contained in a static area +so it must be copied if it is +to be saved. Only the Internet +address format is currently understood. |
