.\"	$OpenBSD: getnetent.3,v 1.4 1999/06/05 22:17:36 aaron Exp $
.\" $From: getnetent.3,v 8.2 1996/05/09 05:59:10 vixie Exp $
.TH getnetent 3
.SH NAME
getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent \- get networks
entry
.SH SYNTAX
.nf
.B #include <netdb.h>
.PP
.B struct netent *getnetent()
.PP
.B struct netent *getnetbyname(\fIname\fP)
.B char *\fIname\fP;
.PP
.B struct netent *getnetbyaddr(\fInet\fP, \fItype\fP)
.B unsigned long \fInet\fP; int \fItype\fP;
.PP
.B void setnetent(\fIstayopen\fP)
.B int \fIstayopen\fP;
.PP
.B void endnetent()
.fi
.SH DESCRIPTION
The
.IR getnetent ,
.IR getnetbyname ,
and
.I getnetbyaddr
subroutines
each return a pointer to an object with the
following structure
containing the broken-out
fields of a line in the
.I networks
database.
.RS
.PP
.nf
struct	netent {
	char	*n_name;	/* official name of net */
	char	**n_aliases;	/* alias list */
	int	n_addrtype;	/* net number type */
	long	n_net;		/* net number */
};
.ft R
.ad
.fi
.RE
.PP
The members of this structure are:
.TP \w'n_addrtype'u+2n
n_name
The official name of the network.
.TP \w'n_addrtype'u+2n
n_aliases
A zero terminated list of alternate names for the network.
.TP \w'n_addrtype'u+2n
n_addrtype
The type of the network number returned: AF_INET.
.TP \w'n_addrtype'u+2n
n_net
The network number.  Network numbers are returned in machine byte
order.
.PP
If the
.I stayopen
flag on a
.I setnetent
subroutine is NULL, the
.I networks
database is opened.  Otherwise the
.I setnetent
has the effect of rewinding the
.I networks
database.
The
.I endnetent
may be called to
close the
.I networks
database when processing is complete.
.PP
The
.I getnetent
subroutine simply reads the next
line while
.I getnetbyname
and
.I getnetbyaddr
search until a matching
.I name
or
.I net
number is found
(or until EOF is encountered).  The \fItype\fP must be AF_INET.
The
.I getnetent
subroutine keeps a pointer in the database, allowing
successive calls to be used
to search the entire file.
.PP
A call to
.I setnetent
must be made before a
.I while
loop using
.I getnetent
in order to perform initialization and an
.I endnetent
must be used after the loop.  Both
.I getnetbyname
and
.I getnetbyaddr
make calls to
.I setnetent
and
.I endnetent .
.SH FILES
.I /etc/networks
.SH DIAGNOSTICS
Null pointer (0) returned on EOF or error.
.SH SEE ALSO
.nf
networks(5)
RFC 1101
.SH HISTORY
The getnetent(), getnetbyaddr(), getnetbyname(), setnetent(), and
endnetent() functions appeared in
.Bx 4.2 .
.SH BUGS
The data space used by these functions is static; if future use requires the
data, it should be copied before any subsequent calls to these functions
overwrite it.  Only Internet network numbers are currently understood.
Expecting network numbers to fit in no more than 32 bits is probably naive.