1getnetbyname(3SOCKET) Sockets Library Functions getnetbyname(3SOCKET)
2
6 getnetbyname, getnetbyname_r, getnetbyaddr, getnetbyaddr_r, getnetent,
7 getnetent_r, setnetent, endnetent - get network entry
8
10 cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
11 #include <netdb.h>
12 struct netent *getnetbyname(const char *name);
14 struct netent *getnetbyname_r(const char *name, struct netent *result,
17 char *buffer, int buflen);
18 struct netent *getnetbyaddr(long net, int type);
21 struct netent *getnetbyaddr_r(long net, int type, struct netent *result,
24 char *buffer, int buflen);
25 struct netent *getnetent(void);
28 struct netent *getnetent_r(struct netent *result, char *buffer,
31 int buflen);
32 int setnetent(int stayopen);
35 int endnetent(void);
38
41 These functions are used to obtain entries for networks. An entry may
42 come from any of the sources for networks specified in the /etc/nss‐
43 witch.conf file. See nsswitch.conf(4).
44 getnetbyname() searches for a network entry with the network name spec‐
47 ified by the character string parameter name.
48 getnetbyaddr() searches for a network entry with the network address
51 specified by net. The parameter type specifies the family of the
52 address. This should be one of the address families defined in
53 <sys/socket.h>. See the NOTES section below for more information.
54 Network numbers and local address parts are returned as machine format
57 integer values, that is, in host byte order. See also inet(3SOCKET).
58 The netent.n_net member in the netent structure pointed to by the
61 return value of the above functions is calculated by inet_network().
62 The inet_network() function returns a value in host byte order that is
63 aligned based upon the input string. For example:
64 Text Value
69 "10" 0x0000000a
70 "10.0" 0x00000a00
71 "10.0.1" 0a000a0001
72 "10.0.1.28" 0x0a000180
73 Commonly, the alignment of the returned value is used as a crude
77 approximate of pre-CIDR (Classless Inter-Domain Routing) subnet mask.
78 For example:
79 in_addr_t addr, mask;
81 addr = inet_network(net_name);
83 mask= ~(in_addr_t)0;
84 if ((addr & IN_CLASSA_NET) == 0)
85 addr <<= 8, mask <<= 8;
86 if ((addr & IN_CLASSA_NET) == 0)
87 addr <<= 8, mask <<= 8;
88 if ((addr & IN_CLASSA_NET) == 0)
89 addr <<= 8, mask <<= 8;
90 This usage is deprecated by the CIDR requirements. See Fuller, V., Li,
94 T., Yu, J., and Varadhan, K. RFC 1519, Classless Inter-Domain Routing
95 (CIDR): an Address Assignment and Aggregation Strategy. Network Working
96 Group. September 1993.
97 The functions setnetent(), getnetent(), and endnetent() are used to
100 enumerate network entries from the database.
101 setnetent() sets (or resets) the enumeration to the beginning of the
104 set of network entries. This function should be called before the first
105 call to getnetent(). Calls to getnetbyname() and getnetbyaddr() leave
106 the enumeration position in an indeterminate state. If the stayopen
107 flag is non-zero, the system may keep allocated resources such as open
108 file descriptors until a subsequent call to endnetent().
109 Successive calls to getnetent() return either successive entries or
112 NULL, indicating the end of the enumeration.
113 endnetent() may be called to indicate that the caller expects to do no
116 further network entry retrieval operations; the system may then deallo‐
117 cate resources it was using. It is still allowed, but possibly less
118 efficient, for the process to call more network entry retrieval func‐
119 tions after calling endnetent().
120 Reentrant Interfaces
122 The functions getnetbyname(), getnetbyaddr(), and getnetent() use
123 static storage that is reused in each call, making these routines
124 unsafe for use in multi-threaded applications.
125 The functions getnetbyname_r(), getnetbyaddr_r(), and getnetent_r()
128 provide reentrant interfaces for these operations.
129 Each reentrant interface performs the same operation as its non-reen‐
132 trant counterpart, named by removing the ``_r'' suffix. The reentrant
133 interfaces, however, use buffers supplied by the caller to store
134 returned results, and are safe for use in both single-threaded and
135 multi-threaded applications.
136 Each reentrant interface takes the same parameters as its non-reentrant
139 counterpart, as well as the following additional parameters. The param‐
140 eter result must be a pointer to a struct netent structure allocated by
141 the caller. On successful completion, the function returns the network
142 entry in this structure. The parameter buffer must be a pointer to a
143 buffer supplied by the caller. This buffer is used as storage space for
144 the network entry data. All of the pointers within the returned struct
145 netent result point to data stored within this buffer. See RETURN VAL‐
146 UES. The buffer must be large enough to hold all of the data associated
147 with the network entry. The parameter buflen should give the size in
148 bytes of the buffer indicated by buffer.
149 For enumeration in multi-threaded applications, the position within the
152 enumeration is a process-wide property shared by all threads. setne‐
153 tent() may be used in a multi-threaded application but resets the enu‐
154 meration position for all threads. If multiple threads interleave calls
155 to getnetent_r(), the threads will enumerate disjointed subsets of the
156 network database.
157 Like their non-reentrant counterparts, getnetbyname_r() and getnet‐
160 byaddr_r() leave the enumeration position in an indeterminate state.
161
163 Network entries are represented by the struct netent structure defined
164 in <netdb.h>.
165 The functions getnetbyname(), getnetbyname_r, getnetbyaddr, and getnet‐
168 byaddr_r() each return a pointer to a struct netent if they success‐
169 fully locate the requested entry; otherwise they return NULL.
170 The functions getnetent() and getnetent_r() each return a pointer to a
173 struct netent if they successfully enumerate an entry; otherwise they
174 return NULL, indicating the end of the enumeration.
175 The functions getnetbyname(), getnetbyaddr(), and getnetent() use
178 static storage, so returned data must be copied before a subsequent
179 call to any of these functions if the data is to be saved.
180 When the pointer returned by the reentrant functions getnetbyname_r(),
183 getnetbyaddr_r(), and getnetent_r() is non-NULL, it is always equal to
184 the result pointer that was supplied by the caller.
185 The functions setnetent() and endnetent() return 0 on success.
188
190 The reentrant functions getnetbyname_r(), getnetbyaddr_r and getne‐
191 tent_r() will return NULL and set errno to ERANGE if the length of the
192 buffer supplied by caller is not large enough to store the result. See
193 Intro(2) for the proper usage and interpretation of errno in multi-
194 threaded applications.
195
197 /etc/networks network name database
198 /etc/nsswitch.conf configuration file for the name service switch
201
204 See attributes(5) for descriptions of the following attributes:
205 ┌─────────────────────────────┬─────────────────────────────┐
210 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
211 ├─────────────────────────────┼─────────────────────────────┤
212 │MT-Level │MT-Safe │
213 └─────────────────────────────┴─────────────────────────────┘
214
216 Intro(2), Intro(3), byteorder(3SOCKET), inet(3SOCKET), netdb.h(3HEAD),
217 networks(4), nsswitch.conf(4), attributes(5)
218 Fuller, V., Li, T., Yu, J., and Varadhan, K. RFC 1519, Classless Inter-
221 Domain Routing (CIDR): an Address Assignment and Aggregation Strategy.
222 Network Working Group. September 1993.
223
225 The reentrant interfaces getnetbyname_r(), getnetbyaddr_r(), and getne‐
226 tent_r() are included in this release on an uncommitted basis only, and
227 are subject to change or removal in future minor releases.
228
230 The current implementation of these functions only return or accept
231 network numbers for the Internet address family (type AF_INET). The
232 functions described in inet(3SOCKET) may be helpful in constructing and
233 manipulating addresses and network numbers in this form.
234 When compiling multi-threaded applications, see Intro(3), Notes On Mul‐
237 tithread Applications, for information about the use of the _REENTRANT
238 flag.
239 Use of the enumeration interfaces getnetent() and getnetent_r() is dis‐
242 couraged; enumeration may not be supported for all database sources.
243 The semantics of enumeration are discussed further in nsswitch.conf(4).
244SunOS 5.11 4 Nov 2004 getnetbyname(3SOCKET)