usr/src/lib/libc/net/gethostbyname.3

.\" Copyright (c) 1983 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"     @(#)gethostbyname.3     6.3 (Berkeley) %G%
.\"
.TH GETHOSTENT 3N ""
.UC 5
.SH NAME
gethostent, gethostbyaddr, gethostbyname, sethostent, endhostent, sethostfile \- get network host entry
.SH SYNOPSIS
.B "#include <netdb.h>
.PP
.B "struct hostent *gethostent()
.PP
.B "struct hostent *gethostbyname(name)
.br
.B "char *name;
.PP
.B "struct hostent *gethostbyaddr(addr, len, type)
.br
.B "char *addr; int len, type;
.PP
.B "sethostent(stayopen)
.br
.B "int stayopen;
.PP
.B "endhostent()
.PP
.B "sethostfile(name)
.br
.B "char *name;
.SH DESCRIPTION
.IR Gethostent ,
.IR gethostbyname ,
and
.I gethostbyaddr
each return a pointer to an object with the
following structure.
Depending on how the library is configured,
this structure contains either the broken-out
fields of a line in the network host data base,
.IR /etc/hosts ,
or similar information obtained from the name server,
.IR named (8).
.RS
.PP
.nf
struct  hostent {
        char    *h_name;        /* official name of host */
        char    **h_aliases;    /* alias list */
        int     h_addrtype;     /* address type */
        int     h_length;       /* length of address */
        char    *h_addr;        /* address */
};
.ft R
.ad
.fi
.RE
.PP
The members of this structure are:
.TP \w'h_addrtype'u+2n
h_name
Official name of the host.
.TP \w'h_addrtype'u+2n
h_aliases
A zero terminated array of alternate names for the host.
.TP \w'h_addrtype'u+2n
h_addrtype
The type of address being returned; currently always AF_INET.
.TP \w'h_addrtype'u+2n
h_length
The length, in bytes, of the address.
.TP \w'h_addrtype'u+2n
h_addr
A pointer to the network address for the host.
Host addresses are returned
in network byte order.
.PP
.I Gethostent
reads the next line of the file, opening the file if necessary.
.PP
.I Sethostent
opens and rewinds the file.  If the
.I stayopen
flag is non-zero,
the host data base will not be closed after each call to
.I gethostbyname
or
.IR gethostbyaddr .
.PP
.I Endhostent
closes the file.
.PP
.I Sethostfile
changes the default host table file to
.I name
thus allowing these routines to be used with alternate host tables.
Note that it does
.I not
close the previous file.
If this is desired,
.I endhostent
should be called prior to it.
.PP
.I Gethostbyname
and
.I gethostbyaddr
sequentially search from the beginning
of the file until a matching
host name or
host address is found,
or until EOF is encountered.
Host addresses are supplied in network order.
.SH FILES
/etc/hosts
.SH "SEE ALSO"
hosts(5), resolver(3), named(8)
.SH DIAGNOSTICS
Null pointer
(0) returned on EOF or error.
.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.
.PP
On sites configured to use the name server
.IR named (8)
instead of
.IR /etc/hosts ,
.I gethostent
is not available
and
.I sethostfile
is a no-op.