1getservbyname(3SOCKET) Sockets Library Functions getservbyname(3SOCKET)
2
6 getservbyname, getservbyname_r, getservbyport, getservbyport_r, getser‐
7 vent, getservent_r, setservent, endservent - get service entry
8
10 cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
11 #include <netdb.h>
12 struct servent *getservbyname(const char *name, const char *proto);
14 struct servent *getservbyname_r(const char *name, const char *proto,
17 struct servent *result, char *buffer, int buflen);
18 struct servent *getservbyport(int port, const char *proto);
21 struct servent *getservbyport_r(int port, const char *proto,
24 struct servent *result, char *buffer, int buflen);
25 struct servent *getservent(void);
28 struct servent *getservent_r(struct servent *result, char *buffer,
31 int buflen);
32 int setservent(int stayopen);
35 int endservent(void);
38
41 These functions are used to obtain entries for Internet services. An
42 entry may come from any of the sources for services specified in the
43 /etc/nsswitch.conf file. See nsswitch.conf(4).
44 The getservbyname() and getservbyport() functions sequentially search
47 from the beginning of the file until a matching protocol name or port
48 number is found, or until end-of-file is encountered. If a protocol
49 name is also supplied (non-null), searches must also match the proto‐
50 col.
51 The getservbyname() function searches for an entry with the Internet
54 service name specified by the name parameter.
55 The getservbyport() function searches for an entry with the Internet
58 port number port.
59 All addresses are returned in network order. In order to interpret the
62 addresses, byteorder(3SOCKET) must be used for byte order conversion.
63 The string proto is used by both getservbyname() and getservbyport() to
64 restrict the search to entries with the specified protocol. If proto is
65 NULL, entries with any protocol can be returned.
66 The functions setservent(), getservent(), and endservent() are used to
69 enumerate entries from the services database.
70 The setservent() function sets (or resets) the enumeration to the
73 beginning of the set of service entries. This function should be called
74 before the first call to getservent(). Calls to the functions get‐
75 servbyname() and getservbyport() leave the enumeration position in an
76 indeterminate state. If the stayopen flag is non-zero, the system may
77 keep allocated resources such as open file descriptors until a subse‐
78 quent call to endservent().
79 The getservent() function reads the next line of the file, opening the
82 file if necessary. getservent() opens and rewinds the file. If the
83 stayopen flag is non-zero, the net data base will not be closed after
84 each call to getservent() (either directly, or indirectly through one
85 of the other "getserv"calls).
86 Successive calls to getservent() return either successive entries or
89 NULL, indicating the end of the enumeration.
90 The endservent() function closes the file. The endservent() function
93 can be called to indicate that the caller expects to do no further ser‐
94 vice entry retrieval operations; the system can then deallocate
95 resources it was using. It is still allowed, but possibly less effi‐
96 cient, for the process to call more service entry retrieval functions
97 after calling endservent().
98 Reentrant Interfaces
100 The functions getservbyname(), getservbyport(), and getservent() use
101 static storage that is re-used in each call, making these functions
102 unsafe for use in multithreaded applications.
103 The functions getservbyname_r(), getservbyport_r(), and getservent_r()
106 provide reentrant interfaces for these operations.
107 Each reentrant interface performs the same operation as its non-reen‐
110 trant counterpart, named by removing the "_r" suffix. The reentrant
111 interfaces, however, use buffers supplied by the caller to store
112 returned results, and are safe for use in both single-threaded and
113 multithreaded applications.
114 Each reentrant interface takes the same parameters as its non-reentrant
117 counterpart, as well as the following additional parameters. The param‐
118 eter result must be a pointer to a struct servent structure allocated
119 by the caller. On successful completion, the function returns the ser‐
120 vice entry in this structure. The parameter buffer must be a pointer to
121 a buffer supplied by the caller. This buffer is used as storage space
122 for the service entry data. All of the pointers within the returned
123 struct servent result point to data stored within this buffer. See the
124 RETURN VALUES section of this manual page. The buffer must be large
125 enough to hold all of the data associated with the service entry. The
126 parameter buflen should give the size in bytes of the buffer indicated
127 by buffer.
128 For enumeration in multithreaded applications, the position within the
131 enumeration is a process-wide property shared by all threads. The set‐
132 servent() function can be used in a multithreaded application but
133 resets the enumeration position for all threads. If multiple threads
134 interleave calls to getservent_r(), the threads will enumerate disjoint
135 subsets of the service database.
136 Like their non-reentrant counterparts, getservbyname_r() and getservby‐
139 port_r() leave the enumeration position in an indeterminate state.
140
142 Service entries are represented by the struct servent structure defined
143 in <netdb.h>:
144 struct servent {
146 char *s_name; /* official name of service */
147 char **s_aliases; /* alias list */
148 int s_port; /* port service resides at */
149 char *s_proto; /* protocol to use */
150 };
151 The members of this structure are:
155 s_name The official name of the service.
157 s_aliases A zero terminated list of alternate names for the service.
160 s_port The port number at which the service resides. Port
164 numbers are returned in network byte
165 order.
166 s_proto The name of the protocol to use when contacting the
169 service
170 The functions getservbyname(), getservbyname_r(), getservbyport(), and
174 getservbyport_r() each return a pointer to a struct servent if they
175 successfully locate the requested entry; otherwise they return NULL.
176 The functions getservent() and getservent_r() each return a pointer to
179 a struct servent if they successfully enumerate an entry; otherwise
180 they return NULL, indicating the end of the enumeration.
181 The functions getservbyname(), getservbyport(), and getservent() use
184 static storage, so returned data must be copied before a subsequent
185 call to any of these functions if the data is to be saved.
186 When the pointer returned by the reentrant functions getservbyname_r(),
189 getservbyport_r(), and getservent_r() is non-null, it is always equal
190 to the result pointer that was supplied by the caller.
191
193 The reentrant functions getservbyname_r(), getservbyport_r(), and get‐
194 servent_r() return NULL and set errno to ERANGE if the length of the
195 buffer supplied by caller is not large enough to store the result. See
196 Intro(2) for the proper usage and interpretation of errno in multi‐
197 threaded applications.
198
200 /etc/services Internet network services
201 /etc/netconfig network configuration file
204 /etc/nsswitch.conf configuration file for the name-service switch
207
210 See attributes(5) for descriptions of the following attributes:
211 ┌─────────────────────────────┬─────────────────────────────┐
216 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
217 ├─────────────────────────────┼─────────────────────────────┤
218 │MT-Level │See "Reentrant Interfaces" │
219 │ │in DESCRIPTION. │
220 └─────────────────────────────┴─────────────────────────────┘
221
223 Intro(2), Intro(3), byteorder(3SOCKET), netdir(3NSL), netconfig(4),
224 nsswitch.conf(4), services(4), attributes(5), netdb.h(3HEAD)
225
227 The reentrant interfaces getservbyname_r(), getservbyport_r(), and get‐
228 servent_r() are included in this release on an uncommitted basis only,
229 and are subject to change or removal in future minor releases.
230
232 The functions that return struct servent return the least significant
233 16-bits of the s_port field in network byte order. getservbyport() and
234 getservbyport_r() also expect the input parameter port in the network
235 byte order. See htons(3SOCKET) for more details on converting between
236 host and network byte orders.
237 To ensure that they all return consistent results, getservbyname(),
240 getservbyname_r(), and netdir_getbyname() are implemented in terms of
241 the same internal library function. This function obtains the system-
242 wide source lookup policy based on the inet family entries in netcon‐
243 fig(4) and the services: entry in nsswitch.conf(4). Similarly, get‐
244 servbyport(), getservbyport_r(), and netdir_getbyaddr() are implemented
245 in terms of the same internal library function. If the inet family
246 entries in netconfig(4) have a ``-'' in the last column for nametoaddr
247 libraries, then the entry for services in nsswitch.conf will be used;
248 otherwise the nametoaddr libraries in that column will be used, and
249 nsswitch.conf will not be consulted.
250 There is no analogue of getservent() and getservent_r() in the netdir
253 functions, so these enumeration functions go straight to the services
254 entry in nsswitch.conf. Thus enumeration may return results from a dif‐
255 ferent source than that used by getservbyname(), getservbyname_r(),
256 getservbyport(), and getservbyport_r().
257 When compiling multithreaded applications, see Intro(3), Notes On Mul‐
260 tithread Applications, for information about the use of the _REENTRANT
261 flag.
262 Use of the enumeration interfaces getservent() and getservent_r() is
265 discouraged; enumeration may not be supported for all database sources.
266 The semantics of enumeration are discussed further in nsswitch.conf(4).
267SunOS 5.11 31 Jan 2007 getservbyname(3SOCKET)