NAME

getservent(), getservent_r(), getservbyport(), getservbyport_r(), getservbyname(), getservbyname_r(), setservent(), setservent_r(), endservent(), endservent_r() − get service entry

SYNOPSIS

#include <netdb.h>

struct servent *getservent(void);

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

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

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

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

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

int setservent(int stayopen);

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

int endservent(void);

int endservent_r(struct servent_data *buffer);

_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)).

Reentrant Interfaces

getservent_r(), getservbyname_r(), and getservbyport_r() expect to be passed the address of a struct servent and will store the result at the supplied location.  An additional parameter, a pointer to a struct servent_data, must also be supplied. This structure is used to store data, to which fields in the struct servent will point, as well as state information such as open file descriptors.  The struct servent_data is defined in the file <netdb.h>. 

setservent_r() and endservent_r() are to be used only in conjunction with getservent_r() and take the same pointer to a struct servent_data as a parameter.  If the Network Information Service is being used, setservent_r() initializes an internal database key.  If the /etc/services file is being used, setservent_r() opens or rewinds the file.  endservent_r() should always be called to ensure that files are closed and internally allocated data structures are released. 

The stayopen parameter to setservent_r() currently has no effect.  However, setservent() can still be used to keep the /etc/services file open when making calls to getservbyname_r() and getservbyport_r(). 

The serv_fp field in the servent_data struct must be initialized to NULL before it is passed to either getservent_r() or setservent_r() for the first time.  Thereafter it should not be modified in any way.  This is the only servent_data field that should ever be explicitly accessed. 

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 switch(4)).  The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports. 

RETURN VALUE

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

The reentrant (_r) versions of these 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. 

EXAMPLES

The following code excerpt counts the number of service entries:

int count = 0;
struct servent servbuf;
struct servent_data sdbuf;

sdbuf.serv_fp = NULL;
(void) setservent_r(0, &sdbuf);
while (getservent_r(&servbuf, &sdbuf) != -1)
     count++;
(void) endservent_r(&sdbuf);

WARNINGS

In the nonreentrant versions of these routines, all information is contained in a static area, so it must be copied if it is to be saved. 

getservent(), getservbyport(), getservbyname(), setservent(), and endservent() are unsafe in multi-thread applications.  getservent_r(), getservbyport_r(), getservbyname_r(), setservent_r(), and endservent_r() are MT-Safe and should be used instead. 

AUTHOR

getservent() was developed by the University of California, Berkeley. 

FILES

/etc/services

SEE ALSO

ypserv(1M), services(4), ypfiles(4). 

STANDARDS CONFORMANCE

getservent(): XPG4

Hewlett-Packard Company  —  HP-UX Release 10.20:  July 1996