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

NAME

6       getservbyname, getservbyname_r, getservbyport, getservbyport_r, getser‐
7       vent, getservent_r, setservent, endservent - get service entry
8

SYNOPSIS

10       cc [ flag ... ] file ... -lsocket  -lnsl  [ library ... ]
11       #include <netdb.h>
12
13       struct servent *getservbyname(const char *name, const char *proto);
14
15
16       struct servent *getservbyname_r(const char *name, const char *proto,
17            struct servent *result, char *buffer, int buflen);
18
19
20       struct servent *getservbyport(int port, const char *proto);
21
22
23       struct servent *getservbyport_r(int port, const char *proto,
24            struct servent *result, char *buffer, int buflen);
25
26
27       struct servent *getservent(void);
28
29
30       struct servent *getservent_r(struct servent *result, char *buffer,
31            int buflen);
32
33
34       int setservent(int stayopen);
35
36
37       int endservent(void);
38
39

DESCRIPTION

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
45
46       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
52
53       The getservbyname() function searches for an entry  with  the  Internet
54       service name specified by the name parameter.
55
56
57       The  getservbyport()  function  searches for an entry with the Internet
58       port number port.
59
60
61       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
67
68       The functions setservent(), getservent(), and endservent() are used  to
69       enumerate entries from the services database.
70
71
72       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
80
81       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
87
88       Successive  calls  to  getservent() return either successive entries or
89       NULL, indicating the end of the enumeration.
90
91
92       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
99   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
104
105       The  functions getservbyname_r(), getservbyport_r(), and getservent_r()
106       provide reentrant interfaces for these operations.
107
108
109       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
115
116       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
129
130       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
137
138       Like their non-reentrant counterparts, getservbyname_r() and getservby‐
139       port_r() leave the enumeration position in an indeterminate state.
140

RETURN VALUES

142       Service entries are represented by the struct servent structure defined
143       in <netdb.h>:
144
145         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
152
153
154       The members of this structure are:
155
156       s_name       The official name of the service.
157
158
159       s_aliases    A zero terminated list of alternate names for the service.
160
161
162
163       s_port       The  port  number  at  which  the  service  resides.  Port
164                    numbers  are                returned   in   network   byte
165                    order.
166
167
168       s_proto      The  name  of   the  protocol  to  use when contacting the
169                    service
170
171
172
173       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
177
178       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
182
183       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
187
188       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

ERRORS

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

FILES

200       /etc/services         Internet network services
201
202
203       /etc/netconfig        network configuration file
204
205
206       /etc/nsswitch.conf    configuration file for the name-service switch
207
208

ATTRIBUTES

210       See attributes(5) for descriptions of the following attributes:
211
212
213
214
215       ┌─────────────────────────────┬─────────────────────────────┐
216       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
217       ├─────────────────────────────┼─────────────────────────────┤
218       │MT-Level                     │See "Reentrant  Interfaces"  │
219       │                             │in DESCRIPTION.              │
220       └─────────────────────────────┴─────────────────────────────┘
221

SEE ALSO

223       Intro(2),  Intro(3),  byteorder(3SOCKET),  netdir(3NSL),  netconfig(4),
224       nsswitch.conf(4), services(4), attributes(5), netdb.h(3HEAD)
225

WARNINGS

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

NOTES

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
238
239       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
251
252       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
258
259       When compiling multithreaded applications, see  Intro(3), Notes On Mul‐
260       tithread  Applications, for information about the use of the _REENTRANT
261       flag.
262
263
264       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).
267
268
269
270SunOS 5.11                        31 Jan 2007           getservbyname(3SOCKET)
Impressum