[unix-history] / 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.1 (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
containing the broken-out
fields of a line in the network host data base,
.IR /etc/hosts .
.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 gethostent
(either directly, or indirectly through one of the other
\*(lqgethost\*(rq calls).
.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)
.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.
Commit	Line	Data
b9a6fdfb KM	1	.\" Copyright (c) 1983 Regents of the University of California.
	2	.\" All rights reserved. The Berkeley software License Agreement
	3	.\" specifies the terms and conditions for redistribution.
	4	.\"
92953539	5	.\" @(#)gethostbyname.3 6.1 (Berkeley) %G%
b9a6fdfb	6	.\"
92953539	7	.TH GETHOSTENT 3N ""
b9a6fdfb KM	8	.UC 5
b9a6fdfb KM	9	.SH NAME
92953539	10	gethostent, gethostbyaddr, gethostbyname, sethostent, endhostent, sethostfile \- get network host entry
b9a6fdfb KM	11	.SH SYNOPSIS
	12	.B "#include <netdb.h>
	13	.PP
	14	.B "struct hostent *gethostent()
	15	.PP
	16	.B "struct hostent *gethostbyname(name)
	17	.br
	18	.B "char *name;
	19	.PP
	20	.B "struct hostent *gethostbyaddr(addr, len, type)
	21	.br
	22	.B "char *addr; int len, type;
	23	.PP
	24	.B "sethostent(stayopen)
	25	.br
92953539	26	.B "int stayopen;
b9a6fdfb KM	27	.PP
b9a6fdfb KM	28	.B "endhostent()
92953539 KM	29	.PP
	30	.B "sethostfile(name)
	31	.br
	32	.B "char *name;
b9a6fdfb KM	33	.SH DESCRIPTION
	34	.IR Gethostent ,
	35	.IR gethostbyname ,
	36	and
	37	.I gethostbyaddr
	38	each return a pointer to an object with the
	39	following structure
	40	containing the broken-out
	41	fields of a line in the network host data base,
	42	.IR /etc/hosts .
	43	.RS
	44	.PP
	45	.nf
	46	struct hostent {
	47	char h_name; / official name of host */
	48	char *h_aliases; / alias list */
	49	int h_addrtype; /* address type */
	50	int h_length; /* length of address */
	51	char h_addr; / address */
	52	};
	53	.ft R
	54	.ad
	55	.fi
	56	.RE
	57	.PP
	58	The members of this structure are:
	59	.TP \w'h_addrtype'u+2n
	60	h_name
	61	Official name of the host.
	62	.TP \w'h_addrtype'u+2n
	63	h_aliases
	64	A zero terminated array of alternate names for the host.
	65	.TP \w'h_addrtype'u+2n
	66	h_addrtype
	67	The type of address being returned; currently always AF_INET.
	68	.TP \w'h_addrtype'u+2n
	69	h_length
	70	The length, in bytes, of the address.
	71	.TP \w'h_addrtype'u+2n
	72	h_addr
	73	A pointer to the network address for the host.
	74	Host addresses are returned
	75	in network byte order.
	76	.PP
	77	.I Gethostent
	78	reads the next line of the file, opening the file if necessary.
	79	.PP
	80	.I Sethostent
	81	opens and rewinds the file. If the
	82	.I stayopen
	83	flag is non-zero,
	84	the host data base will not be closed after each call to
	85	.I gethostent
	86	(either directly, or indirectly through one of the other
	87	\(lqgethost\(rq calls).
	88	.PP
	89	.I Endhostent
	90	closes the file.
	91	.PP
92953539 KM	92	.I Sethostfile
	93	changes the default host table file to
	94	.I name
	95	thus allowing these routines to be used with alternate host tables.
	96	Note that it does
	97	.I not
	98	close the previous file.
	99	If this is desired,
	100	.I endhostent
	101	should be called prior to it.
	102	.PP
b9a6fdfb KM	103	.I Gethostbyname
	104	and
	105	.I gethostbyaddr
	106	sequentially search from the beginning
	107	of the file until a matching
	108	host name or
	109	host address is found,
	110	or until EOF is encountered.
	111	Host addresses are supplied in network order.
	112	.SH FILES
	113	/etc/hosts
	114	.SH "SEE ALSO"
	115	hosts(5)
	116	.SH DIAGNOSTICS
	117	Null pointer
	118	(0) returned on EOF or error.
	119	.SH BUGS
	120	All information
	121	is contained in a static area
	122	so it must be copied if it is
	123	to be saved. Only the Internet
	124	address format is currently understood.