229 lines
6.4 KiB
Groff
229 lines
6.4 KiB
Groff
.\" $NetBSD: gethostbyname.3,v 1.1 1996/02/02 15:27:23 mrg Exp $
|
|
.\"
|
|
.\" 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 3 "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 named (8),
|
|
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 (7)
|
|
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(3), hosts(5), hostname(7), named(8)
|
|
.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.
|