Sockets Library Functions getservbyname(3SOCKET)
NAME
getservbyname, getservbynamer, getservbyport,
getservbyportr, getservent, getserventr, setservent,
endservent - get service entry
SYNOPSIS
cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
#include
struct servent *getservbyname(const char *name, const char *proto);
struct servent *getservbynamer(const char *name, const char *proto,
struct servent *result, char *buffer, int buflen);
struct servent *getservbyport(int port, const char *proto);
struct servent *getservbyportr(int port, const char *proto,
struct servent *result, char *buffer, int buflen);
struct servent *getservent(void);
struct servent *getserventr(struct servent *result, char *buffer,
int buflen);
int setservent(int stayopen);
int endservent(void);
DESCRIPTION
These functions are used to obtain entries for Internet ser-
vices. An entry may come from any of the sources for ser-
vices specified in the /etc/nsswitch.conf file. See
nsswitch.conf(4).
The getservbyname() and getservbyport() functions sequen-
tially search from the beginning of the file until a match-
ing protocol name or port number is found, or until end-
of-file is encountered. If a protocol name is also sup-
plied (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.
SunOS 5.11 Last change: 31 Jan 2007 1
Sockets Library Functions getservbyname(3SOCKET)
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(3SOCKET) must be used for
byte order conversion. The string proto is used by both get-
servbyname() and getservbyport() to restrict the search to
entries with the specified protocol. If proto is NUL,
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 func-
tion 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 allo-
cated resources such as open file descriptors until a subse-
quent 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 NUL, 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 getser-
vent() use static storage that is re-used in each call, mak-
ing these functions unsafe for use in multithreaded applica-
tions.
SunOS 5.11 Last change: 31 Jan 2007 2
Sockets Library Functions getservbyname(3SOCKET)
The functions getservbynamer(), getservbyportr(), and
getserventr() provide reentrant interfaces for these opera-
tions.
Each reentrant interface performs the same operation as its
non-reentrant counterpart, named by removing the "r" suf-
fix. The reentrant interfaces, however, use buffers sup-
plied by the caller to store returned results, and are safe
for use in both single-threaded and multithreaded applica-
tions.
Each reentrant interface takes the same parameters as its
non-reentrant counterpart, as well as the following addi-
tional parameters. The parameter result must be a pointer to
a struct servent structure allocated by the caller. On suc-
cessful 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 sec-
tion 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 mul-
tithreaded application but resets the enumeration position
for all threads. If multiple threads interleave calls to
getserventr(), the threads will enumerate disjoint subsets
of the service database.
Like their non-reentrant counterparts, getservbynamer() and
getservbyportr() leave the enumeration position in an
indeterminate state.
RETURN VALUES
Service entries are represented by the struct servent struc-
ture defined in :
struct servent {
char *sname; /* official name of service */
char **saliases; /* alias list */
int sport; /* port service resides at */
char *sproto; /* protocol to use */
};
SunOS 5.11 Last change: 31 Jan 2007 3
Sockets Library Functions getservbyname(3SOCKET)
The members of this structure are:
sname The official name of the service.
saliases A zero terminated list of alternate names for
the service.
sport The port number at which the service
resides. Port numbers are returned in net-
work byte order.
sproto The name of the protocol to use when con-
tacting the service
The functions getservbyname(), getservbynamer(), get-
servbyport(), and getservbyportr() each return a pointer to
a struct servent if they successfully locate the requested
entry; otherwise they return NUL.
The functions getservent() and getserventr() each return a
pointer to a struct servent if they successfully enumerate
an entry; otherwise they return NUL, indicating the end of
the enumeration.
The functions getservbyname(), getservbyport(), and getser-
vent() 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
getservbynamer(), getservbyportr(), and getserventr() is
non-null, it is always equal to the result pointer that was
supplied by the caller.
ERORS
The reentrant functions getservbynamer(),
getservbyportr(), and getserventr() return NUL 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
SunOS 5.11 Last change: 31 Jan 2007 4
Sockets Library Functions getservbyname(3SOCKET)
/etc/services Internet network services
/etc/netconfig network configuration file
/etc/nsswitch.conf configuration file for the name-
service switch
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level See "Reentrant Interfaces"
in DESCRIPTION.
SEE ALSO
Intro(2), Intro(3), byteorder(3SOCKET), netdir(3NSL),
netconfig(4), nsswitch.conf(4), services(4), attributes(5),
netdb.h(3HEAD)
WARNINGS
The reentrant interfaces getservbynamer(),
getservbyportr(), and getserventr() 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 sport field in network byte
order. getservbyport() and getservbyportr() also expect the
input parameter port in the network byte order. See
htons(3SOCKET) for more details on converting between host
and network byte orders.
To ensure that they all return consistent results, get-
servbyname(), getservbynamer(), and netdirgetbyname() 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(4) and the
services: entry in nsswitch.conf(4). Similarly, get-
servbyport(), getservbyportr(), and netdirgetbyaddr() are
implemented in terms of the same internal library function.
SunOS 5.11 Last change: 31 Jan 2007 5
Sockets Library Functions getservbyname(3SOCKET)
If the inet family entries in netconfig(4) have a ``-'' in
the last column for nametoaddr libraries, then the entry for
services in nsswitch.conf will be used; otherwise the name-
toaddr libraries in that column will be used, and
nsswitch.conf will not be consulted.
There is no analogue of getservent() and getserventr() 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(), getservbynamer(), get-
servbyport(), and getservbyportr().
When compiling multithreaded applications, see Intro(3),
Notes On Multithread Applications, for information about the
use of the RENTRANT flag.
Use of the enumeration interfaces getservent() and
getserventr() is discouraged; enumeration may not be sup-
ported for all database sources. The semantics of enumera-
tion are discussed further in nsswitch.conf(4).
SunOS 5.11 Last change: 31 Jan 2007 6
|
