getnetbyname.3socket (bbf215553c7233fbab8a0afdf1fac74c44781867) getnetbyname.3socket (c55633c3b85a97a093b3f79f341aee08eb6bd15b)
1'\" te
2.\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
3.\" Copyright 1989 AT&T
4.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution.
1'\" te
2.\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
3.\" Copyright 1989 AT&T
4.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution.
5.TH GETNETBYNAME 3SOCKET "Nov 4, 2004"
5.TH GETNETBYNAME 3SOCKET "March 30, 2022"
6.SH NAME
7getnetbyname, getnetbyname_r, getnetbyaddr, getnetbyaddr_r, getnetent,
8getnetent_r, setnetent, endnetent \- get network entry
9.SH SYNOPSIS
6.SH NAME
7getnetbyname, getnetbyname_r, getnetbyaddr, getnetbyaddr_r, getnetent,
8getnetent_r, setnetent, endnetent \- get network entry
9.SH SYNOPSIS
10.LP
11.nf
12\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
13#include <netdb.h>
14
15\fBstruct netent *\fR\fBgetnetbyname\fR(\fBconst char *\fR\fIname\fR);
16.fi
17
18.LP

--- 30 unchanged lines hidden (view full) ---

49.fi
50
51.LP
52.nf
53\fBint\fR \fBendnetent\fR(\fBvoid\fR);
54.fi
55
56.SH DESCRIPTION
10.nf
11\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
12#include <netdb.h>
13
14\fBstruct netent *\fR\fBgetnetbyname\fR(\fBconst char *\fR\fIname\fR);
15.fi
16
17.LP

--- 30 unchanged lines hidden (view full) ---

48.fi
49
50.LP
51.nf
52\fBint\fR \fBendnetent\fR(\fBvoid\fR);
53.fi
54
55.SH DESCRIPTION
57.sp
58.LP
59These functions are used to obtain entries for networks. An entry may come from
60any of the sources for \fBnetworks\fR specified in the \fB/etc/nsswitch.conf\fR
61file. See \fBnsswitch.conf\fR(5).
62.sp
63.LP
64\fBgetnetbyname()\fR searches for a network entry with the network name
65specified by the character string parameter \fIname\fR.
66.sp
67.LP
68\fBgetnetbyaddr()\fR searches for a network entry with the network address
69specified by \fInet\fR. The parameter \fBtype\fR specifies the family of the
70address. This should be one of the address families defined in
71<\fBsys/socket.h\fR>. See the \fBNOTES\fR section below for more information.
72.sp
73.LP
74Network numbers and local address parts are returned as machine format integer
56These functions are used to obtain entries for networks. An entry may come from
57any of the sources for \fBnetworks\fR specified in the \fB/etc/nsswitch.conf\fR
58file. See \fBnsswitch.conf\fR(5).
59.sp
60.LP
61\fBgetnetbyname()\fR searches for a network entry with the network name
62specified by the character string parameter \fIname\fR.
63.sp
64.LP
65\fBgetnetbyaddr()\fR searches for a network entry with the network address
66specified by \fInet\fR. The parameter \fBtype\fR specifies the family of the
67address. This should be one of the address families defined in
68<\fBsys/socket.h\fR>. See the \fBNOTES\fR section below for more information.
69.sp
70.LP
71Network numbers and local address parts are returned as machine format integer
75values, that is, in host byte order. See also \fBinet\fR(3SOCKET).
72values, that is, in host byte order. See also \fBinet\fR(3C).
76.sp
77.LP
78The \fBnetent.n_net\fR member in the \fBnetent\fR structure pointed to by the
79return value of the above functions is calculated by \fBinet_network()\fR. The
80\fBinet_network()\fR function returns a value in host byte order that is
81aligned based upon the input string. For example:
82.sp
83

--- 53 unchanged lines hidden (view full) ---

137.sp
138.LP
139\fBendnetent()\fR may be called to indicate that the caller expects to do no
140further network entry retrieval operations; the system may then deallocate
141resources it was using. It is still allowed, but possibly less efficient, for
142the process to call more network entry retrieval functions after calling
143\fBendnetent()\fR.
144.SS "Reentrant Interfaces"
73.sp
74.LP
75The \fBnetent.n_net\fR member in the \fBnetent\fR structure pointed to by the
76return value of the above functions is calculated by \fBinet_network()\fR. The
77\fBinet_network()\fR function returns a value in host byte order that is
78aligned based upon the input string. For example:
79.sp
80

--- 53 unchanged lines hidden (view full) ---

134.sp
135.LP
136\fBendnetent()\fR may be called to indicate that the caller expects to do no
137further network entry retrieval operations; the system may then deallocate
138resources it was using. It is still allowed, but possibly less efficient, for
139the process to call more network entry retrieval functions after calling
140\fBendnetent()\fR.
141.SS "Reentrant Interfaces"
145.sp
146.LP
147The functions \fBgetnetbyname()\fR, \fBgetnetbyaddr()\fR, and \fBgetnetent()\fR
148use static storage that is reused in each call, making these routines unsafe
149for use in multi-threaded applications.
150.sp
151.LP
152The functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and
153\fBgetnetent_r()\fR provide reentrant interfaces for these operations.
154.sp

--- 24 unchanged lines hidden (view full) ---

179for all threads. If multiple threads interleave calls to \fBgetnetent_r()\fR,
180the threads will enumerate disjointed subsets of the network database.
181.sp
182.LP
183Like their non-reentrant counterparts, \fBgetnetbyname_r()\fR and
184\fBgetnetbyaddr_r()\fR leave the enumeration position in an indeterminate
185state.
186.SH RETURN VALUES
142The functions \fBgetnetbyname()\fR, \fBgetnetbyaddr()\fR, and \fBgetnetent()\fR
143use static storage that is reused in each call, making these routines unsafe
144for use in multi-threaded applications.
145.sp
146.LP
147The functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and
148\fBgetnetent_r()\fR provide reentrant interfaces for these operations.
149.sp

--- 24 unchanged lines hidden (view full) ---

174for all threads. If multiple threads interleave calls to \fBgetnetent_r()\fR,
175the threads will enumerate disjointed subsets of the network database.
176.sp
177.LP
178Like their non-reentrant counterparts, \fBgetnetbyname_r()\fR and
179\fBgetnetbyaddr_r()\fR leave the enumeration position in an indeterminate
180state.
181.SH RETURN VALUES
187.sp
188.LP
189Network entries are represented by the \fBstruct netent\fR structure defined in
190\fB<netdb.h>\fR\&.
191.sp
192.LP
193The functions \fBgetnetbyname()\fR, \fBgetnetbyname_r\fR, \fBgetnetbyaddr\fR,
194and \fBgetnetbyaddr_r()\fR each return a pointer to a \fBstruct netent\fR if
195they successfully locate the requested entry; otherwise they return \fBNULL\fR.
196.sp

--- 11 unchanged lines hidden (view full) ---

208When the pointer returned by the reentrant functions \fBgetnetbyname_r()\fR,
209\fBgetnetbyaddr_r()\fR, and \fBgetnetent_r()\fR is non-\fBNULL\fR, it is always
210equal to the \fIresult\fR pointer that was supplied by the caller.
211.sp
212.LP
213The functions \fBsetnetent()\fR and \fBendnetent()\fR return \fB0\fR on
214success.
215.SH ERRORS
182Network entries are represented by the \fBstruct netent\fR structure defined in
183\fB<netdb.h>\fR\&.
184.sp
185.LP
186The functions \fBgetnetbyname()\fR, \fBgetnetbyname_r\fR, \fBgetnetbyaddr\fR,
187and \fBgetnetbyaddr_r()\fR each return a pointer to a \fBstruct netent\fR if
188they successfully locate the requested entry; otherwise they return \fBNULL\fR.
189.sp

--- 11 unchanged lines hidden (view full) ---

201When the pointer returned by the reentrant functions \fBgetnetbyname_r()\fR,
202\fBgetnetbyaddr_r()\fR, and \fBgetnetent_r()\fR is non-\fBNULL\fR, it is always
203equal to the \fIresult\fR pointer that was supplied by the caller.
204.sp
205.LP
206The functions \fBsetnetent()\fR and \fBendnetent()\fR return \fB0\fR on
207success.
208.SH ERRORS
216.sp
217.LP
218The reentrant functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r\fR and
219\fBgetnetent_r()\fR will return \fBNULL\fR and set \fIerrno\fR to \fBERANGE\fR
220if the length of the buffer supplied by caller is not large enough to store the
221result. See \fBIntro\fR(2) for the proper usage and interpretation of
222\fIerrno\fR in multi-threaded applications.
223.SH FILES
209The reentrant functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r\fR and
210\fBgetnetent_r()\fR will return \fBNULL\fR and set \fIerrno\fR to \fBERANGE\fR
211if the length of the buffer supplied by caller is not large enough to store the
212result. See \fBIntro\fR(2) for the proper usage and interpretation of
213\fIerrno\fR in multi-threaded applications.
214.SH FILES
224.sp
225.ne 2
226.na
227\fB\fB/etc/networks\fR\fR
228.ad
229.RS 22n
230network name database
231.RE
232
233.sp
234.ne 2
235.na
236\fB\fB/etc/nsswitch.conf\fR\fR
237.ad
238.RS 22n
239configuration file for the name service switch
240.RE
241
242.SH ATTRIBUTES
215.ne 2
216.na
217\fB\fB/etc/networks\fR\fR
218.ad
219.RS 22n
220network name database
221.RE
222
223.sp
224.ne 2
225.na
226\fB\fB/etc/nsswitch.conf\fR\fR
227.ad
228.RS 22n
229configuration file for the name service switch
230.RE
231
232.SH ATTRIBUTES
243.sp
244.LP
245See \fBattributes\fR(7) for descriptions of the following attributes:
246.sp
247
248.sp
249.TS
250box;
251c | c
252l | l .
253ATTRIBUTE TYPE ATTRIBUTE VALUE
254_
255MT-Level MT-Safe
256.TE
257
258.SH SEE ALSO
233See \fBattributes\fR(7) for descriptions of the following attributes:
234.sp
235
236.sp
237.TS
238box;
239c | c
240l | l .
241ATTRIBUTE TYPE ATTRIBUTE VALUE
242_
243MT-Level MT-Safe
244.TE
245
246.SH SEE ALSO
259.sp
260.LP
261.BR Intro (2),
262.BR Intro (3),
247.BR Intro (2),
248.BR Intro (3),
249.BR byteorder (3C),
250.BR inet (3C),
263.BR netdb.h (3HEAD),
251.BR netdb.h (3HEAD),
264.BR byteorder (3SOCKET),
265.BR inet (3SOCKET),
266.BR networks (5),
267.BR nsswitch.conf (5),
268.BR attributes (7)
269.sp
270.LP
271Fuller, V., Li, T., Yu, J., and Varadhan, K. \fIRFC 1519, Classless
272Inter-Domain Routing (CIDR): an Address Assignment and Aggregation Strategy\fR.
273Network Working Group. September 1993.
274.SH WARNINGS
252.BR networks (5),
253.BR nsswitch.conf (5),
254.BR attributes (7)
255.sp
256.LP
257Fuller, V., Li, T., Yu, J., and Varadhan, K. \fIRFC 1519, Classless
258Inter-Domain Routing (CIDR): an Address Assignment and Aggregation Strategy\fR.
259Network Working Group. September 1993.
260.SH WARNINGS
275.sp
276.LP
277The reentrant interfaces \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and
278\fBgetnetent_r()\fR are included in this release on an uncommitted basis only,
279and are subject to change or removal in future minor releases.
280.SH NOTES
261The reentrant interfaces \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and
262\fBgetnetent_r()\fR are included in this release on an uncommitted basis only,
263and are subject to change or removal in future minor releases.
264.SH NOTES
281.sp
282.LP
283The current implementation of these functions only return or accept network
284numbers for the Internet address family (type \fBAF_INET\fR). The functions
265The current implementation of these functions only return or accept network
266numbers for the Internet address family (type \fBAF_INET\fR). The functions
285described in \fBinet\fR(3SOCKET) may be helpful in constructing and
267described in \fBinet\fR(3C) may be helpful in constructing and
286manipulating addresses and network numbers in this form.
287.sp
288.LP
289When compiling multi-threaded applications, see \fBIntro\fR(3), \fINotes On
290Multithread Applications\fR, for information about the use of the
291\fB_REENTRANT\fR flag.
292.sp
293.LP
294Use of the enumeration interfaces \fBgetnetent()\fR and \fBgetnetent_r()\fR is
295discouraged; enumeration may not be supported for all database sources. The
296semantics of enumeration are discussed further in \fBnsswitch.conf\fR(5).
268manipulating addresses and network numbers in this form.
269.sp
270.LP
271When compiling multi-threaded applications, see \fBIntro\fR(3), \fINotes On
272Multithread Applications\fR, for information about the use of the
273\fB_REENTRANT\fR flag.
274.sp
275.LP
276Use of the enumeration interfaces \fBgetnetent()\fR and \fBgetnetent_r()\fR is
277discouraged; enumeration may not be supported for all database sources. The
278semantics of enumeration are discussed further in \fBnsswitch.conf\fR(5).