.\"	$NetBSD: getnetent.3,v 1.1.1.2 2012/09/09 16:07:43 christos Exp $
.\"
.\" Copyright (C) 2009  Internet Systems Consortium, Inc. ("ISC")
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
.\" Id: getnetent.3,v 1.3 2009/01/22 23:49:23 tbox Exp 
.\"
.Dd May 20, 1996
.Dt GETNETENT @LIB_NETWORK_EXT_U@
.Os BSD 4
.Sh NAME
.Nm getnetent ,
.Nm getnetbyaddr ,
.Nm getnetbyname ,
.Nm setnetent ,
.Nm endnetent 
.Nd get networks entry
.Sh SYNOPSIS
.Fd #include <netdb.h>
.Ft struct netent *
.Fn getnetent
.Ft struct netent *
.Fn getnetbyname "char name"
.Ft struct netent *
.Fn getnetbyaddr "unsigned long net" "int type"
.Ft void 
.Fn setnetent "int stayopen"
.Ft void 
.Fn endnetent
.Sh DESCRIPTION
The
.Fn getnetent ,
.Fn getnetbyname ,
and
.Fn getnetbyaddr
subroutines
each return a pointer to an object with the following structure
containing the broken-out fields of a line in the 
.Pa networks 
database.
.Bd -literal -offset indent
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 */
};
.Ed
.Pp
The members of this structure are:
.Bl -tag -width "n_addrtype" 
.It n_name
The official name of the network.
.It n_aliases
A zero-terminated list of alternate names for the network.
.It n_addrtype
The type of the network number returned: 
.Dv AF_INET .
.It n_net
The network number.  Network numbers are returned in machine byte
order.
.El
.Pp
If the
.Fa stayopen
flag on a 
.Fn setnetent
subroutine is NULL, the
.Pa networks
database is opened.  Otherwise, the
.Fn setnetent
has the effect of rewinding the 
.Pa networks 
database.
The
.Fn endnetent
subroutine may be called to
close the 
.Pa networks 
database when processing is complete.
.Pp
The
.Fn getnetent
subroutine simply reads the next
line while
.Fn getnetbyname
and
.Fn getnetbyaddr
search until a matching
.Fa name
or
.Fa net
number is found
(or until 
.Dv EOF 
is encountered).  The 
.Fa type must be 
.Dv AF_INET .
The
.Fn getnetent
subroutine keeps a pointer in the database, allowing
successive calls to be used to search the entire file.
.Pp
Before a
.Ic while
loop using
.Fn getnetent ,
a call to
.Fn setnetent
must be made 
in order to perform initialization; a call to 
.Fn endnetent
must be used after the loop.  Both
.Fn getnetbyname
and
.Fn getnetbyaddr
make calls to
.Fn setnetent
and
.Fn endnetent .
.Sh FILES
.Pa /etc/networks
.Sh DIAGNOSTICS
Null pointer (0) returned on 
.Dv EOF 
or error.
.Sh SEE ALSO
.Xr networks @FORMAT_EXT@ ,
RFC 1101.
.Sh HISTORY
The 
.Fn "getnetent" , 
.Fn "getnetbyaddr" , 
.Fn "getnetbyname" , 
.Fn "setnetent" , 
and
.Fn "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.