1.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
2.\" Copyright (c) 1995,1996,1999 by Internet Software Consortium
3.\"
4.\" Permission to use, copy, modify, and distribute this software for any
5.\" purpose with or without fee is hereby granted, provided that the above
6.\" copyright notice and this permission notice appear in all copies.
7.\"
8.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
14.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15.\"
16.\" Id: getnetent.man3,v 1.2 2009/01/21 00:12:34 each Exp
17.\"
18.Dd May 20, 1996
19.Dt GETNETENT 3
20.Os BSD 4
21.Sh NAME
22.Nm getnetent ,
23.Nm getnetbyaddr ,
24.Nm getnetbyname ,
25.Nm setnetent ,
26.Nm endnetent
27.Nd get networks entry
28.Sh SYNOPSIS
29.Fd #include <netdb.h>
30.Ft struct netent *
31.Fn getnetent
32.Ft struct netent *
33.Fn getnetbyname "char name"
34.Ft struct netent *
35.Fn getnetbyaddr "unsigned long net" "int type"
36.Ft void
37.Fn setnetent "int stayopen"
38.Ft void
39.Fn endnetent
40.Sh DESCRIPTION
41The
42.Fn getnetent ,
43.Fn getnetbyname ,
44and
45.Fn getnetbyaddr
46subroutines
47each return a pointer to an object with the following structure
48containing the broken-out fields of a line in the
49.Pa networks
50database.
51.Bd -literal -offset indent
52struct	netent {
53	char	*n_name;	/* official name of net */
54	char	**n_aliases;	/* alias list */
55	int	n_addrtype;	/* net number type */
56	long	n_net;		/* net number */
57};
58.Ed
59.Pp
60The members of this structure are:
61.Bl -tag -width "n_addrtype"
62.It n_name
63The official name of the network.
64.It n_aliases
65A zero-terminated list of alternate names for the network.
66.It n_addrtype
67The type of the network number returned:
68.Dv AF_INET .
69.It n_net
70The network number.  Network numbers are returned in machine byte
71order.
72.El
73.Pp
74If the
75.Fa stayopen
76flag on a
77.Fn setnetent
78subroutine is NULL, the
79.Pa networks
80database is opened.  Otherwise, the
81.Fn setnetent
82has the effect of rewinding the
83.Pa networks
84database.
85The
86.Fn endnetent
87subroutine may be called to
88close the
89.Pa networks
90database when processing is complete.
91.Pp
92The
93.Fn getnetent
94subroutine simply reads the next
95line while
96.Fn getnetbyname
97and
98.Fn getnetbyaddr
99search until a matching
100.Fa name
101or
102.Fa net
103number is found
104(or until
105.Dv EOF
106is encountered).  The
107.Fa type must be
108.Dv AF_INET .
109The
110.Fn getnetent
111subroutine keeps a pointer in the database, allowing
112successive calls to be used to search the entire file.
113.Pp
114Before a
115.Ic while
116loop using
117.Fn getnetent ,
118a call to
119.Fn setnetent
120must be made
121in order to perform initialization; a call to
122.Fn endnetent
123must be used after the loop.  Both
124.Fn getnetbyname
125and
126.Fn getnetbyaddr
127make calls to
128.Fn setnetent
129and
130.Fn endnetent .
131.Sh FILES
132.Pa /etc/networks
133.Sh DIAGNOSTICS
134Null pointer (0) returned on
135.Dv EOF
136or error.
137.Sh SEE ALSO
138.Xr networks 5 ,
139RFC 1101.
140.Sh HISTORY
141The
142.Fn "getnetent" ,
143.Fn "getnetbyaddr" ,
144.Fn "getnetbyname" ,
145.Fn "setnetent" ,
146and
147.Fn "endnetent"
148functions appeared in
149.Bx 4.2 .
150.Sh BUGS
151The data space used by these functions is static; if future use requires the
152data, it should be copied before any subsequent calls to these functions
153overwrite it.  Only Internet network numbers are currently understood.
154Expecting network numbers to fit in no more than 32 bits is probably naive.
155