| blob | cc251a2252b038d2150163a3eabf82dbd231e4f3 |
1 '\" te
2 .\" Copyright (c) 1983, Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright 1989 AT&T. Copyright (c) 2007, Sun Microsystems, Inc.
3 .\" All Rights Reserved.
4 .TH GETSERVBYNAME 3SOCKET "Jan 31, 2007"
5 .SH NAME
6 getservbyname, getservbyname_r, getservbyport, getservbyport_r, getservent,
7 getservent_r, setservent, endservent \- get service entry
8 .SH SYNOPSIS
9 .LP
10 .nf
11 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
12 #include <netdb.h>
14 \fBstruct servent *\fR\fBgetservbyname\fR(\fBconst char *\fR\fIname\fR, \fBconst char *\fR\fIproto\fR);
15 .fi
17 .LP
18 .nf
19 \fBstruct servent *\fR\fBgetservbyname_r\fR(\fBconst char *\fR\fIname\fR, \fBconst char *\fR\fIproto\fR,
20 \fBstruct servent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
21 .fi
23 .LP
24 .nf
25 \fBstruct servent *\fR\fBgetservbyport\fR(\fBint\fR \fIport\fR, \fBconst char *\fR\fIproto\fR);
26 .fi
28 .LP
29 .nf
30 \fBstruct servent *\fR\fBgetservbyport_r\fR(\fBint\fR \fIport\fR, \fBconst char *\fR\fIproto\fR,
31 \fBstruct servent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
32 .fi
34 .LP
35 .nf
36 \fBstruct servent *\fR\fBgetservent\fR(\fBvoid\fR);
37 .fi
39 .LP
40 .nf
41 \fBstruct servent *\fR\fBgetservent_r\fR(\fBstruct servent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR,
42 \fBint\fR \fIbuflen\fR);
43 .fi
45 .LP
46 .nf
47 \fBint\fR \fBsetservent\fR(\fBint\fR \fIstayopen\fR);
48 .fi
50 .LP
51 .nf
52 \fBint\fR \fBendservent\fR(\fBvoid\fR);
53 .fi
55 .SH DESCRIPTION
56 .sp
57 .LP
58 These functions are used to obtain entries for Internet services. An entry may
59 come from any of the sources for \fBservices\fR specified in the
60 \fB/etc/nsswitch.conf\fR file. See \fBnsswitch.conf\fR(4).
61 .sp
62 .LP
63 The \fBgetservbyname()\fR and \fBgetservbyport()\fR functions sequentially
64 search from the beginning of the file until a matching protocol name or port
65 number is found, or until end-of-file is encountered. If a protocol name is
66 also supplied (non-null), searches must also match the protocol.
67 .sp
68 .LP
69 The \fBgetservbyname()\fR function searches for an entry with the Internet
70 service name specified by the \fIname\fR parameter.
71 .sp
72 .LP
73 The \fBgetservbyport()\fR function searches for an entry with the Internet port
74 number \fIport\fR.
75 .sp
76 .LP
77 All addresses are returned in network order. In order to interpret the
78 addresses, \fBbyteorder\fR(3SOCKET) must be used for byte order conversion. The
79 string \fIproto\fR is used by both \fBgetservbyname()\fR and
80 \fBgetservbyport()\fR to restrict the search to entries with the specified
81 protocol. If \fIproto\fR is \fINULL\fR, entries with any protocol can be
82 returned.
83 .sp
84 .LP
85 The functions \fBsetservent()\fR, \fBgetservent()\fR, and \fBendservent()\fR
86 are used to enumerate entries from the services database.
87 .sp
88 .LP
89 The \fBsetservent()\fR function sets (or resets) the enumeration to the
90 beginning of the set of service entries. This function should be called before
91 the first call to \fBgetservent()\fR. Calls to the functions
92 \fBgetservbyname()\fR and \fBgetservbyport()\fR leave the enumeration position
93 in an indeterminate state. If the \fIstayopen\fR flag is non-zero, the system
94 may keep allocated resources such as open file descriptors until a subsequent
95 call to \fBendservent()\fR.
96 .sp
97 .LP
98 The \fBgetservent()\fR function reads the next line of the file, opening the
99 file if necessary. \fBgetservent()\fR opens and rewinds the file. If the
100 \fIstayopen\fR flag is non-zero, the net data base will not be closed after
101 each call to \fBgetservent()\fR (either directly, or indirectly through one of
102 the other "getserv"calls).
103 .sp
104 .LP
105 Successive calls to \fBgetservent()\fR return either successive entries or
106 \fINULL\fR, indicating the end of the enumeration.
107 .sp
108 .LP
109 The \fBendservent()\fR function closes the file. The \fBendservent()\fR
110 function can be called to indicate that the caller expects to do no further
111 service entry retrieval operations; the system can then deallocate resources it
112 was using. It is still allowed, but possibly less efficient, for the process
113 to call more service entry retrieval functions after calling
114 \fBendservent()\fR.
115 .SS "Reentrant Interfaces"
116 .sp
117 .LP
118 The functions \fBgetservbyname()\fR, \fBgetservbyport()\fR, and
119 \fBgetservent()\fR use static storage that is re-used in each call, making
120 these functions unsafe for use in multithreaded applications.
121 .sp
122 .LP
123 The functions \fBgetservbyname_r()\fR, \fBgetservbyport_r()\fR, and
124 \fBgetservent_r()\fR provide reentrant interfaces for these operations.
125 .sp
126 .LP
127 Each reentrant interface performs the same operation as its non-reentrant
128 counterpart, named by removing the "\fB_r\fR" suffix. The reentrant
129 interfaces, however, use buffers supplied by the caller to store returned
130 results, and are safe for use in both single-threaded and multithreaded
131 applications.
132 .sp
133 .LP
134 Each reentrant interface takes the same parameters as its non-reentrant
135 counterpart, as well as the following additional parameters. The parameter
136 \fIresult\fR must be a pointer to a \fBstruct servent\fR structure allocated by
137 the caller. On successful completion, the function returns the service entry
138 in this structure. The parameter \fIbuffer\fR must be a pointer to a buffer
139 supplied by the caller. This buffer is used as storage space for the service
140 entry data. All of the pointers within the returned \fBstruct servent\fR
141 \fIresult\fR point to data stored within this buffer. See the RETURN VALUES
142 section of this manual page. The buffer must be large enough to hold all of the
143 data associated with the service entry. The parameter \fIbuflen\fR should give
144 the size in bytes of the buffer indicated by \fIbuffer\fR.
145 .sp
146 .LP
147 For enumeration in multithreaded applications, the position within the
148 enumeration is a process-wide property shared by all threads. The
149 \fBsetservent()\fR function can be used in a multithreaded application but
150 resets the enumeration position for all threads. If multiple threads
151 interleave calls to \fBgetservent_r()\fR, the threads will enumerate disjoint
152 subsets of the service database.
153 .sp
154 .LP
155 Like their non-reentrant counterparts, \fBgetservbyname_r()\fR and
156 \fBgetservbyport_r()\fR leave the enumeration position in an indeterminate
157 state.
158 .SH RETURN VALUES
159 .sp
160 .LP
161 Service entries are represented by the \fBstruct servent\fR structure defined
162 in <\fBnetdb.h\fR>:
163 .sp
164 .in +2
165 .nf
166 struct servent {
167 char *s_name; /* official name of service */
168 char **s_aliases; /* alias list */
169 int s_port; /* port service resides at */
170 char *s_proto; /* protocol to use */
171 };
172 .fi
173 .in -2
175 .sp
176 .LP
177 The members of this structure are:
178 .sp
179 .ne 2
180 .na
181 \fB\fBs_name\fR\fR
182 .ad
183 .RS 13n
184 The official name of the service.
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fBs_aliases\fR\fR
191 .ad
192 .RS 13n
193 A zero terminated list of alternate names for the service.
194 .RE
196 .sp
197 .ne 2
198 .na
199 \fB\fBs_port\fR\fR
200 .ad
201 .RS 13n
202 The port number at which the service resides. Port numbers are
203 returned in network byte order.
204 .RE
206 .sp
207 .ne 2
208 .na
209 \fB\fBs_proto\fR\fR
210 .ad
211 .RS 13n
212 The name of the protocol to use when contacting the service
213 .RE
215 .sp
216 .LP
217 The functions \fBgetservbyname()\fR, \fBgetservbyname_r()\fR,
218 \fBgetservbyport()\fR, and \fBgetservbyport_r()\fR each return a pointer to a
219 \fBstruct servent\fR if they successfully locate the requested entry; otherwise
220 they return \fINULL\fR.
221 .sp
222 .LP
223 The functions \fBgetservent()\fR and \fBgetservent_r()\fR each return a pointer
224 to a \fBstruct servent\fR if they successfully enumerate an entry; otherwise
225 they return \fINULL,\fR indicating the end of the enumeration.
226 .sp
227 .LP
228 The functions \fBgetservbyname()\fR, \fBgetservbyport()\fR, and
229 \fBgetservent()\fR use static storage, so returned data must be copied before a
230 subsequent call to any of these functions if the data is to be saved.
231 .sp
232 .LP
233 When the pointer returned by the reentrant functions \fBgetservbyname_r()\fR,
234 \fBgetservbyport_r()\fR, and \fBgetservent_r()\fR is non-null, it is always
235 equal to the \fIresult\fR pointer that was supplied by the caller.
236 .SH ERRORS
237 .sp
238 .LP
239 The reentrant functions \fBgetservbyname_r()\fR, \fBgetservbyport_r()\fR, and
240 \fBgetservent_r()\fR return \fINULL\fR and set \fBerrno\fR to \fBERANGE\fR if
241 the length of the buffer supplied by caller is not large enough to store the
242 result. See \fBIntro\fR(2) for the proper usage and interpretation of
243 \fBerrno\fR in multithreaded applications.
244 .SH FILES
245 .sp
246 .ne 2
247 .na
248 \fB\fB/etc/services\fR\fR
249 .ad
250 .RS 22n
251 Internet network services
252 .RE
254 .sp
255 .ne 2
256 .na
257 \fB\fB/etc/netconfig\fR\fR
258 .ad
259 .RS 22n
260 network configuration file
261 .RE
263 .sp
264 .ne 2
265 .na
266 \fB\fB/etc/nsswitch.conf\fR\fR
267 .ad
268 .RS 22n
269 configuration file for the name-service switch
270 .RE
272 .SH ATTRIBUTES
273 .sp
274 .LP
275 See \fBattributes\fR(5) for descriptions of the following attributes:
276 .sp
278 .sp
279 .TS
280 box;
281 c | c
282 l | l .
283 ATTRIBUTE TYPE ATTRIBUTE VALUE
284 _
285 MT-Level T{
286 See "Reentrant Interfaces" in \fBDESCRIPTION\fR.
287 T}
288 .TE
290 .SH SEE ALSO
291 .sp
292 .LP
293 \fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBnetdir\fR(3NSL),
294 \fBnetconfig\fR(4), \fBnsswitch.conf\fR(4), \fBservices\fR(4),
295 \fBattributes\fR(5), \fBnetdb.h\fR(3HEAD)
296 .SH WARNINGS
297 .sp
298 .LP
299 The reentrant interfaces \fBgetservbyname_r()\fR, \fBgetservbyport_r()\fR, and
300 \fBgetservent_r()\fR are included in this release on an uncommitted basis only,
301 and are subject to change or removal in future minor releases.
302 .SH NOTES
303 .sp
304 .LP
305 The functions that return \fBstruct servent\fR return the least significant
306 16-bits of the \fIs_port\fR field in \fInetwork byte order\fR.
307 \fBgetservbyport()\fR and \fBgetservbyport_r()\fR also expect the input
308 parameter \fIport\fR in the \fInetwork byte order\fR. See \fBhtons\fR(3SOCKET)
309 for more details on converting between host and network byte orders.
310 .sp
311 .LP
312 To ensure that they all return consistent results, \fBgetservbyname()\fR,
313 \fBgetservbyname_r()\fR, and \fBnetdir_getbyname()\fR are implemented in terms
314 of the same internal library function. This function obtains the system-wide
315 source lookup policy based on the \fBinet\fR family entries in
316 \fBnetconfig\fR(4) and the \fBservices:\fR entry in \fBnsswitch.conf\fR(4).
317 Similarly, \fBgetservbyport()\fR, \fBgetservbyport_r()\fR, and
318 \fBnetdir_getbyaddr()\fR are implemented in terms of the same internal library
319 function. If the \fBinet\fR family entries in \fBnetconfig\fR(4) have a ``-''
320 in the last column for nametoaddr libraries, then the entry for \fBservices\fR
321 in \fBnsswitch.conf\fR will be used; otherwise the nametoaddr libraries in that
322 column will be used, and \fBnsswitch.conf\fR will not be consulted.
323 .sp
324 .LP
325 There is no analogue of \fBgetservent()\fR and \fBgetservent_r()\fR in the
326 netdir functions, so these enumeration functions go straight to the
327 \fBservices\fR entry in \fBnsswitch.conf\fR. Thus enumeration may return
328 results from a different source than that used by \fBgetservbyname()\fR,
329 \fBgetservbyname_r()\fR, \fBgetservbyport()\fR, and \fBgetservbyport_r()\fR.
330 .sp
331 .LP
332 When compiling multithreaded applications, see \fBIntro\fR(3), \fINotes On
333 Multithread Applications\fR, for information about the use of the
334 \fB_REENTRANT\fR flag.
335 .sp
336 .LP
337 Use of the enumeration interfaces \fBgetservent()\fR and \fBgetservent_r()\fR
338 is discouraged; enumeration may not be supported for all database sources. The
339 semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4).