gethostent.3n

<B>Digital的Unix操作系统VAX 4.2源码</B>

.TH gethostent 3n
.SH Name
gethostent, gethostbyaddr, gethostbyname, sethostent, endhostent \- get 
hosts entry
.SH Syntax
.B "#include <netdb.h>
.PP
.B "struct hostent *gethostent()
.PP
.B "struct hostent *gethostbyname(\fIname\fP)
.br
.B "char *\fIname\fP;
.PP
.B "struct hostent *gethostbyaddr(\fIaddr\fP, \fIlen\fP, \fItype\fP)
.br
.B "char *\fIaddr\fP; int \fIlen\fP, \fItype\fP;
.PP
.B void sethostent(\fIstayopen\fP)
.br
.B int \fIstayopen\fP;
.PP
.B "void endhostent()
.NXR "gethostent subroutine"
.NXR "gethostent subroutine" "svc.conf file and"
.SH Description
.NXR "gethostent subroutine"
.NXR "gethostbyaddr subroutine"
.NXR "gethostbyname subroutine"
.NXR "sethostent subroutine"
.NXR "endhostent subroutine"
.NXR "hosts file" "getting entry"
The
.PN gethostent ,
.PN gethostbyname ,
and
.PN gethostbyaddr
subroutines return a pointer to an object with the
following structure
containing the broken-out fields
reflecting information obtained from the
.PN hosts
database.
.EX 0
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_list; /* list of addresses from name server */
#define  h_addr h_addr_list[0] /* address for backward compatibility */
};
.EE
.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
If the 
.I stayopen
flag on a 
.PN sethostent
subroutine is NULL, the
hosts database is opened.  Otherwise the
.PN sethostent
has the effect of rewinding the 
.PN hosts
database.
The
.PN endhostent
may be called to
close the
.PN hosts 
database when processing is complete.
.PP
The
.PN gethostent
subroutine simply reads the next
line while
.PN gethostbyname
and
.PN gethostbyaddr
search until a matching
.I name,
or
.I addr,
.I len,
.I type
is found
(or until EOF is encountered).
The
.PN gethostent
subroutine keeps a pointer in the database, allowing
successive calls to be used 
to search the entire file.
.PP
The
.PN gethostbyname
and
.PN gethostbyaddr
subroutines query the 
.PN hosts 
database.
.PP
A call to
.PN sethostent
must be made before a
.PN while
loop using
.PN gethostent
in order to perform initialization and an
.PN endhostent
must be used after the loop.  Both
.PN gethostbyname
and
.PN gethostbyaddr
make calls to
.PN sethostent
and
.PN endhostent .
.SH Restrictions
.NXR "gethostent subroutine" "restrictions"
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
If YP is running, 
.PN gethostent
does not return the entries in any particular order.
See the 
.I Guide to the Yellow Pages Service
for setup information.
.PP
The 
.PN hosts
database may also be distributed via the BIND/Hesiod
naming service.  See the
.I Guide to the BIND/Hesiod Service
for more information.
.SH Return Values
Null pointer
(0) returned on EOF or error.
.SH Files
.PN /etc/hosts
.SH See Also
hosts(5), svc.conf(5)
.br
.I Guide to the BIND/Hesiod Service
.br
.I Guide to the Yellow Pages Service