GETSERVBYNAME(3SOCKET) Sockets Library Functions GETSERVBYNAME(3SOCKET)
NAME
getservbyname, getservbyname_r, getservbyport, getservbyport_r,
getservent, getservent_r, setservent, endservent - get service entry
SYNOPSIS
cc [
flag ... ]
file ...
-lsocket -lnsl [
library ... ]
#include <netdb.h>
struct servent *getservbyname(
const char *name,
const char *proto);
struct servent *getservbyname_r(
const char *name,
const char *proto,
struct servent *result,
char *buffer,
int buflen);
struct servent *getservbyport(
int port,
const char *proto);
struct servent *getservbyport_r(
int port,
const char *proto,
struct servent *result,
char *buffer,
int buflen);
struct servent *getservent(
void);
struct servent *getservent_r(
struct servent *result,
char *buffer,
int buflen);
int setservent(
int stayopen);
int endservent(
void);
DESCRIPTION
These functions are used to obtain entries for Internet services. An
entry may come from any of the sources for
services specified in the
/etc/nsswitch.conf file. See
nsswitch.conf(5).
The
getservbyname() and
getservbyport() functions sequentially search
from the beginning of the file until a matching protocol name or port
number is found, or until end-of-file is encountered. If a protocol
name is also supplied (non-null), searches must also match the protocol.
The
getservbyname() function searches for an entry with the Internet
service name specified by the
name parameter.
The
getservbyport() function searches for an entry with the Internet port
number
port.
All addresses are returned in network order. In order to interpret the
addresses,
byteorder(3C) must be used for byte order conversion. The
string
proto is used by both
getservbyname() and
getservbyport() to
restrict the search to entries with the specified protocol. If
proto is
NULL, entries with any protocol can be returned.
The functions
setservent(),
getservent(), and
endservent() are used to
enumerate entries from the services database.
The
setservent() function sets (or resets) the enumeration to the
beginning of the set of service entries. This function should be called
before the first call to
getservent(). Calls to the functions
getservbyname() and
getservbyport() leave the enumeration position in an
indeterminate state. If the
stayopen flag is non-zero, the system may
keep allocated resources such as open file descriptors until a subsequent
call to
endservent().
The
getservent() function reads the next line of the file, opening the
file if necessary.
getservent() opens and rewinds the file. If the
stayopen flag is non-zero, the net data base will not be closed after
each call to
getservent() (either directly, or indirectly through one of
the other "getserv"calls).
Successive calls to
getservent() return either successive entries or
NULL, indicating the end of the enumeration.
The
endservent() function closes the file. The
endservent() function can
be called to indicate that the caller expects to do no further service
entry retrieval operations; the system can then deallocate resources it
was using. It is still allowed, but possibly less efficient, for the
process to call more service entry retrieval functions after calling
endservent().
Reentrant Interfaces
The functions
getservbyname(),
getservbyport(), and
getservent() use
static storage that is re-used in each call, making these functions
unsafe for use in multithreaded applications.
The functions
getservbyname_r(),
getservbyport_r(), and
getservent_r() provide reentrant interfaces for these operations.
Each reentrant interface performs the same operation as its non-reentrant
counterpart, named by removing the "
_r" suffix. The reentrant
interfaces, however, use buffers supplied by the caller to store returned
results, and are safe for use in both single-threaded and multithreaded
applications.
Each reentrant interface takes the same parameters as its non-reentrant
counterpart, as well as the following additional parameters. The
parameter
result must be a pointer to a
struct servent structure
allocated by the caller. On successful completion, the function returns
the service entry in this structure. The parameter
buffer must be a
pointer to a buffer supplied by the caller. This buffer is used as
storage space for the service entry data. All of the pointers within the
returned
struct servent result point to data stored within this buffer.
See the RETURN VALUES section of this manual page. The buffer must be
large enough to hold all of the data associated with the service entry.
The parameter
buflen should give the size in bytes of the buffer
indicated by
buffer.
For enumeration in multithreaded applications, the position within the
enumeration is a process-wide property shared by all threads. The
setservent() function can be used in a multithreaded application but
resets the enumeration position for all threads. If multiple threads
interleave calls to
getservent_r(), the threads will enumerate disjoint
subsets of the service database.
Like their non-reentrant counterparts,
getservbyname_r() and
getservbyport_r() leave the enumeration position in an indeterminate
state.
RETURN VALUES
Service entries are represented by the
struct servent structure defined
in <
netdb.h>:
struct servent {
char *s_name; /* official name of service */
char **s_aliases; /* alias list */
int s_port; /* port service resides at */
char *s_proto; /* protocol to use */
};
The members of this structure are:
s_name The official name of the service.
s_aliases A zero terminated list of alternate names for the service.
s_port The port number at which the service resides. Port
numbers are returned in network byte order.
s_proto The name of the protocol to use when contacting the
service
The functions
getservbyname(),
getservbyname_r(),
getservbyport(), and
getservbyport_r() each return a pointer to a
struct servent if they
successfully locate the requested entry; otherwise they return
NULL.
The functions
getservent() and
getservent_r() each return a pointer to a
struct servent if they successfully enumerate an entry; otherwise they
return
NULL, indicating the end of the enumeration.
The functions
getservbyname(),
getservbyport(), and
getservent() use
static storage, so returned data must be copied before a subsequent call
to any of these functions if the data is to be saved.
When the pointer returned by the reentrant functions
getservbyname_r(),
getservbyport_r(), and
getservent_r() is non-null, it is always equal to
the
result pointer that was supplied by the caller.
ERRORS
The reentrant functions
getservbyname_r(),
getservbyport_r(), and
getservent_r() return
NULL and set
errno to
ERANGE if the length of the
buffer supplied by caller is not large enough to store the result. See
Intro(2) for the proper usage and interpretation of
errno in
multithreaded applications.
FILES
/etc/services Internet network services
/etc/netconfig network configuration file
/etc/nsswitch.conf configuration file for the name-service switch
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+----------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+----------------------------+
|MT-Level | See "Reentrant Interfaces" |
| | in
DESCRIPTION. |
+---------------+----------------------------+
SEE ALSO
Intro(2),
Intro(3),
byteorder(3C),
netdb.h(3HEAD),
netdir(3NSL),
netconfig(5),
nsswitch.conf(5),
services(5),
attributes(7)WARNINGS
The reentrant interfaces
getservbyname_r(),
getservbyport_r(), and
getservent_r() are included in this release on an uncommitted basis only,
and are subject to change or removal in future minor releases.
NOTES
The functions that return
struct servent return the least significant
16-bits of the
s_port field in
network byte order.
getservbyport() and
getservbyport_r() also expect the input parameter
port in the
network byte order. See
htons(3C) for more details on converting between host and
network byte orders.
To ensure that they all return consistent results,
getservbyname(),
getservbyname_r(), and
netdir_getbyname() are implemented in terms of the
same internal library function. This function obtains the system-wide
source lookup policy based on the
inet family entries in
netconfig(5) and
the
services: entry in
nsswitch.conf(5). Similarly,
getservbyport(),
getservbyport_r(), and
netdir_getbyaddr() are implemented in terms of the
same internal library function. If the
inet family entries in
netconfig(5) have a ``-'' in the last column for nametoaddr libraries,
then the entry for
services in
nsswitch.conf will be used; otherwise the
nametoaddr libraries in that column will be used, and
nsswitch.conf will
not be consulted.
There is no analogue of
getservent() and
getservent_r() in the netdir
functions, so these enumeration functions go straight to the
services entry in
nsswitch.conf. Thus enumeration may return results from a
different source than that used by
getservbyname(),
getservbyname_r(),
getservbyport(), and
getservbyport_r().
When compiling multithreaded applications, see
Intro(3),
Notes On Multithread Applications, for information about the use of the
_REENTRANT flag.
Use of the enumeration interfaces
getservent() and
getservent_r() is
discouraged; enumeration may not be supported for all database sources.
The semantics of enumeration are discussed further in
nsswitch.conf(5).
January 31, 2007
GETSERVBYNAME(3SOCKET)