getservent(3N)

NAME

getservent(), getservbyport(), getservbyname(), setservent(), endservent() — get, set, or end service entry

SYNOPSIS

#include <netdb.h> 

struct servent *getservent(void); 

struct servent *getservbyname(const char *name, 
                              const char *proto); 

struct servent *getservbyport(int port, const char *proto); 

int setservent(int stayopen); 

int endservent(void); 

_XOPEN_SOURCE_EXTENDED only 
void setservent(int stayopen); 
void endservent(void); 

DESCRIPTION

The getservent(), getservbyname(), and getservbyport() functions each return a pointer to a structure of type servent containing the broken-out fields of a line in the network services data base, /etc/services.

The members of this structure are:

s_name: The official name of the service.
s_aliases: A null-terminated list of alternate names for the service.
s_port: The port number at which the service resides.
s_proto: The name of the protocol to use when contacting the service.

Functions behave as follows:

getservent(): Reads the next line of the file, opening the file if necessary.
setservent(): Opens and rewinds the file. If the stayopen flag is non-zero, the services data base is not closed after each call to getservent() (either directly or indirectly through one of the other getserv* calls).
endservent(): Closes the file.
getservbyname(), getservbyport(): Each sequentially searches from the beginning of the file until a matching service name (among either the official names or the aliases) or port number is found, or until EOF is encountered. If a non-NULL protocol name is also supplied (such as tcp or udp), searches must also match the protocol.

If the system is running the Network Information Service (NIS), getservbyname() gets the service information from the NIS server (see ypserv(1M) and ypfiles(4)).

In a multithreaded application, getservent(), getservbyaddr(), and getservbyname() use thread-specific storage that is re-used in each call. The return value struct servent should be unique for each thread and should be saved, if desired, before the thread makes the next getserv*() call.

For enumeration in multithreaded applications, the position within the enumeration is a process-wide property shared by all threads. setservent() may be used in a multithreaded application, but resets the enumeration position for all threads. If multiple threads interleave calls to getservent(), the threads will enumerate disjoint subsets of the service database.

Name Service Switch-Based Operation

The library routines getservbyname(), getservbyport(), getservent(), and their reentrant counterparts, internally call the name service switch to access the "services" database lookup policy configured in the /etc/nsswitch.conf file (see nsswitch.conf(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports.

OBSOLESCENT INTERFACES

int getservent_r(struct servent *result, 
                 struct servent_data *buffer); 

int getservbyname_r(const char *name, 
                    const char *proto, 
                    struct servent *result, 
                    struct servent_data *buffer); 

int getservbyport_r(int port, 
                    const char *proto, 
                    struct servent *result, 
                    struct servent_data *buffer); 

int setservent_r(int stayopen, struct servent_data *buffer); 

int endservent_r(struct servent_data *buffer); 

The above reentrant interfaces have been moved from libc to libd4r. They are included to support existing applications and may be removed in a future release. New multithreaded applications should use the regular APIs without the _r suffix.

The reentrant interfaces performs the same operations as their regular counterpart (those without the _r suffix.) However, getservent_r(), getservbyname_r(), and getservbyport_r() expect to be passed the address of a struct servent and will store the address of the result at this supplied parameter. An additional parameter, an address to a struct servent_data, which is defined in the file <netdb.h> cannot be a NULL pointer.

The reentrant routines return -1 if the operation is unsuccessful, or, in the case of getservent_r(), if the end of the services list has been reached. 0 is returned otherwise.

RETURN VALUE

getservent(), getservbyname(), and getservbyport() return a null pointer (0) on EOF or when they are unable to open /etc/services.

EXAMPLES

The following code excerpt counts the number of service entries:

int count = 0; 

(void) setservent(0); 
while (getservent() != NULL) 
     count++; 
(void) endservent(); 

WARNINGS

Programs that use the interfaces described in this manpage cannot be linked statically because the implementations of these functions employ dynamic loading and linking of shared objects at run time.

AUTHOR

getservent() was developed by Sun Microsystems Inc.

FILES

/etc/services

STANDARDS CONFORMANCE

getservent(): XPG4