1getnetbyname(3SOCKET)      Sockets Library Functions     getnetbyname(3SOCKET)
2
3
4

NAME

6       getnetbyname,  getnetbyname_r, getnetbyaddr, getnetbyaddr_r, getnetent,
7       getnetent_r, setnetent, endnetent - get network entry
8

SYNOPSIS

10       cc [ flag ... ] file ... -lsocket  -lnsl  [ library ... ]
11       #include <netdb.h>
12
13       struct netent *getnetbyname(const char *name);
14
15
16       struct netent *getnetbyname_r(const char *name, struct netent *result,
17            char *buffer, int buflen);
18
19
20       struct netent *getnetbyaddr(long net, int type);
21
22
23       struct netent *getnetbyaddr_r(long net, int type, struct netent *result,
24            char *buffer, int buflen);
25
26
27       struct netent *getnetent(void);
28
29
30       struct netent *getnetent_r(struct netent *result, char *buffer,
31            int buflen);
32
33
34       int setnetent(int stayopen);
35
36
37       int endnetent(void);
38
39

DESCRIPTION

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
45
46       getnetbyname() searches for a network entry with the network name spec‐
47       ified by the character string parameter name.
48
49
50       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
55
56       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
59
60       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
65
66
67
68                  Text                          Value
69       "10"                          0x0000000a
70       "10.0"                        0x00000a00
71       "10.0.1"                      0a000a0001
72       "10.0.1.28"                   0x0a000180
73
74
75
76       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
80         in_addr_t addr, mask;
81
82         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
91
92
93       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
98
99       The  functions  setnetent(),  getnetent(),  and endnetent() are used to
100       enumerate network entries from the database.
101
102
103       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
110
111       Successive  calls  to  getnetent()  return either successive entries or
112       NULL, indicating the end of the enumeration.
113
114
115       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
121   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
126
127       The functions  getnetbyname_r(),  getnetbyaddr_r(),  and  getnetent_r()
128       provide reentrant interfaces for these operations.
129
130
131       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
137
138       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
150
151       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
158
159       Like their non-reentrant  counterparts,  getnetbyname_r()  and  getnet‐
160       byaddr_r() leave the enumeration position in an indeterminate state.
161

RETURN VALUES

163       Network  entries are represented by the struct netent structure defined
164       in <netdb.h>.
165
166
167       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
171
172       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
176
177       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
181
182       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
186
187       The functions setnetent() and endnetent() return 0 on success.
188

ERRORS

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

FILES

197       /etc/networks         network name database
198
199
200       /etc/nsswitch.conf    configuration file for the name service switch
201
202

ATTRIBUTES

204       See attributes(5) for descriptions of the following attributes:
205
206
207
208
209       ┌─────────────────────────────┬─────────────────────────────┐
210       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
211       ├─────────────────────────────┼─────────────────────────────┤
212       │MT-Level                     │MT-Safe                      │
213       └─────────────────────────────┴─────────────────────────────┘
214

SEE ALSO

216       Intro(2), Intro(3), byteorder(3SOCKET), inet(3SOCKET),  netdb.h(3HEAD),
217       networks(4), nsswitch.conf(4), attributes(5)
218
219
220       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

WARNINGS

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

NOTES

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
235
236       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
240
241       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).
244
245
246
247SunOS 5.11                        4 Nov 2004             getnetbyname(3SOCKET)
Impressum