Commit | Line | Data |
---|---|---|
984263bc MD |
1 | .\" Copyright (c) 1983, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
dc71b7ab | 12 | .\" 3. Neither the name of the University nor the names of its contributors |
984263bc MD |
13 | .\" may be used to endorse or promote products derived from this software |
14 | .\" without specific prior written permission. | |
15 | .\" | |
16 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
17 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
18 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
19 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
20 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
21 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
22 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
23 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
24 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
25 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
26 | .\" SUCH DAMAGE. | |
27 | .\" | |
28 | .\" @(#)getnetent.3 8.1 (Berkeley) 6/4/93 | |
12b71966 | 29 | .\" $FreeBSD: src/lib/libc/net/getnetent.3,v 1.23 2007/01/09 00:28:02 imp Exp $ |
984263bc | 30 | .\" |
6516125a | 31 | .Dd May 6, 2019 |
984263bc MD |
32 | .Dt GETNETENT 3 |
33 | .Os | |
34 | .Sh NAME | |
35 | .Nm getnetent , | |
6516125a | 36 | .Nm getnetent_r , |
984263bc | 37 | .Nm getnetbyaddr , |
6516125a | 38 | .Nm getnetbyaddr_r , |
984263bc | 39 | .Nm getnetbyname , |
6516125a | 40 | .Nm getnetbyname_r , |
984263bc MD |
41 | .Nm setnetent , |
42 | .Nm endnetent | |
43 | .Nd get network entry | |
44 | .Sh LIBRARY | |
45 | .Lb libc | |
46 | .Sh SYNOPSIS | |
47 | .In netdb.h | |
48 | .Ft struct netent * | |
49 | .Fn getnetent void | |
6516125a SW |
50 | .Ft int |
51 | .Fn getnetent_r "struct netent *ne" "char *buffer" "size_t buflen" "struct netent **result" "int *h_errnop" | |
984263bc MD |
52 | .Ft struct netent * |
53 | .Fn getnetbyname "const char *name" | |
6516125a SW |
54 | .Ft int |
55 | .Fn getnetbyname_r "const char *name" "struct netent *ne" "char *buffer" "size_t buflen" "struct netent **result" "int *h_errnop" | |
984263bc | 56 | .Ft struct netent * |
12b71966 | 57 | .Fn getnetbyaddr "uint32_t net" "int type" |
6516125a SW |
58 | .Ft int |
59 | .Fn getnetbyaddr_r "uint32_t addr" "int af" "struct netent *ne" "char *buffer" "size_t buflen" "struct netent **result" "int *h_errnop" | |
984263bc MD |
60 | .Ft void |
61 | .Fn setnetent "int stayopen" | |
62 | .Ft void | |
63 | .Fn endnetent void | |
64 | .Sh DESCRIPTION | |
65 | The | |
66 | .Fn getnetent , | |
67 | .Fn getnetbyname , | |
68 | and | |
69 | .Fn getnetbyaddr | |
70 | functions | |
71 | each return a pointer to an object with the | |
ed5d5720 PA |
72 | following structure describing an internet network. |
73 | This structure contains either the information obtained | |
74 | from the nameserver, | |
75 | .Xr named 8 , | |
76 | broken-out fields of a line in the network data base | |
77 | .Pa /etc/networks , | |
78 | or entries supplied by the | |
430d1728 | 79 | .Xr yp 8 |
12b71966 PA |
80 | system. |
81 | The order of the lookups is controlled by the | |
ed5d5720 PA |
82 | `networks' entry in |
83 | .Xr nsswitch.conf 5 . | |
984263bc MD |
84 | .Bd -literal -offset indent |
85 | struct netent { | |
86 | char *n_name; /* official name of net */ | |
87 | char **n_aliases; /* alias list */ | |
88 | int n_addrtype; /* net number type */ | |
12b71966 | 89 | uint32_t n_net; /* net number */ |
984263bc MD |
90 | }; |
91 | .Ed | |
92 | .Pp | |
93 | The members of this structure are: | |
94 | .Bl -tag -width n_addrtype | |
95 | .It Fa n_name | |
96 | The official name of the network. | |
97 | .It Fa n_aliases | |
98 | A zero terminated list of alternate names for the network. | |
99 | .It Fa n_addrtype | |
cea736a1 SW |
100 | The type of the network number returned; currently only |
101 | .Dv AF_INET . | |
984263bc | 102 | .It Fa n_net |
12b71966 PA |
103 | The network number. |
104 | Network numbers are returned in machine byte | |
984263bc MD |
105 | order. |
106 | .El | |
107 | .Pp | |
108 | The | |
109 | .Fn getnetent | |
110 | function | |
111 | reads the next line of the file, opening the file if necessary. | |
112 | .Pp | |
113 | The | |
114 | .Fn setnetent | |
115 | function | |
12b71966 PA |
116 | opens and rewinds the file. |
117 | If the | |
984263bc MD |
118 | .Fa stayopen |
119 | flag is non-zero, | |
120 | the net data base will not be closed after each call to | |
121 | .Fn getnetbyname | |
122 | or | |
123 | .Fn getnetbyaddr . | |
124 | .Pp | |
125 | The | |
126 | .Fn endnetent | |
127 | function | |
128 | closes the file. | |
129 | .Pp | |
130 | The | |
131 | .Fn getnetbyname | |
132 | function | |
133 | and | |
134 | .Fn getnetbyaddr | |
135 | sequentially search from the beginning | |
136 | of the file until a matching | |
137 | net name or | |
138 | net address and type is found, | |
139 | or until | |
140 | .Dv EOF | |
141 | is encountered. | |
142 | The | |
143 | .Fa type | |
12b71966 | 144 | argument |
984263bc MD |
145 | must be |
146 | .Dv AF_INET . | |
147 | Network numbers are supplied in host order. | |
6516125a SW |
148 | .Pp |
149 | The | |
150 | .Fn getnetent_r , | |
151 | .Fn getnetbyaddr_r , | |
152 | and | |
153 | .Fn getnetbyname_r | |
154 | functions are reentrant versions of the above functions that take a | |
155 | pointer to a | |
156 | .Vt netent | |
157 | structure which is used to store state information. | |
158 | The structure must be zero-filled before it is used | |
159 | and should be considered opaque for the sake of portability. | |
160 | These functions also take a pointer to another | |
161 | .Vt netent | |
162 | structure which is used to store the results of the database lookup. | |
fdf79913 | 163 | .Sh RETURN VALUES |
6516125a SW |
164 | The |
165 | .Fn getnetent , | |
166 | .Fn getnetbyaddr , | |
167 | and | |
168 | .Fn getnetbyname | |
169 | functions return a pointer to a | |
170 | .Vt netent | |
171 | structure on success or a null pointer if end-of-file | |
172 | is reached or an error occurs. | |
173 | .Pp | |
174 | The | |
175 | .Fn getnetent_r , | |
176 | .Fn getnetbyaddr_r , | |
177 | and | |
178 | .Fn getnetbyname_r | |
179 | functions return 0 on success or \-1 if end-of-file | |
180 | is reached or an error occurs. | |
984263bc | 181 | .Sh FILES |
6516125a | 182 | .Bl -tag -width ".Pa /etc/nsswitch.conf" -compact |
984263bc | 183 | .It Pa /etc/networks |
ed5d5720 PA |
184 | .It Pa /etc/nsswitch.conf |
185 | .It Pa /etc/resolv.conf | |
984263bc | 186 | .El |
984263bc MD |
187 | .Sh SEE ALSO |
188 | .Xr networks 5 | |
189 | .Pp | |
190 | .%T RFC 1101 | |
6516125a SW |
191 | .Sh STANDARDS |
192 | The | |
193 | .Fn getnetent , | |
194 | .Fn getnetbyaddr , | |
195 | .Fn getnetbyname , | |
196 | .Fn setnetent , | |
197 | and | |
198 | .Fn endnetent | |
199 | functions conform to | |
200 | .St -p1003.1-2004 . | |
201 | .Pp | |
202 | The | |
203 | .Fn getnetent_r , | |
204 | .Fn getnetbyaddr_r , | |
205 | and | |
206 | .Fn getnetbyname_r | |
207 | functions are not currently standardized. | |
984263bc MD |
208 | .Sh HISTORY |
209 | The | |
210 | .Fn getnetent , | |
211 | .Fn getnetbyaddr , | |
212 | .Fn getnetbyname , | |
213 | .Fn setnetent , | |
214 | and | |
215 | .Fn endnetent | |
216 | functions appeared in | |
217 | .Bx 4.2 . | |
6516125a SW |
218 | .Pp |
219 | The | |
220 | .Fn getnetent_r , | |
221 | .Fn getnetbyaddr_r , | |
222 | and | |
223 | .Fn getnetbyname_r | |
224 | functions appeared in | |
225 | .Dx 2.1 . | |
984263bc MD |
226 | .Sh BUGS |
227 | The data space used by | |
12b71966 | 228 | these functions is thread-specific; if future use requires the data, it should be |
984263bc MD |
229 | copied before any subsequent calls to these functions overwrite it. |
230 | Only Internet network | |
231 | numbers are currently understood. | |
232 | Expecting network numbers to fit | |
233 | in no more than 32 bits is probably | |
234 | naive. |