NAME

getservbyname, getservbyname_r − Get a service entry by name

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <netdb.h>

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

int getservbyname_r(
const char ∗name,
const char ∗proto,
struct servent ∗serv,
struct servent_data ∗serv_data);

PARAMETERS

nameSpecifies the official name or alias name of the service. 

protoSpecifies the name of the protocol to use when contacting the service. 

servPoints to the servent structure. 

serv_dataIs data for the services database. 

DESCRIPTION

The getservbyname() function returns a pointer to a structure of type servent. Its members specify data in fields from a record line in the /etc/services database file. The netdb.h header file defines the servent structure. 

The getservbyname() function searches the /etc/services file sequentially until a match with the name parameter and with the proto parameter occurs. The name parameter can specify either the official name or its alias. When EOF (End-of-File) is reached without the match, an error value is returned by this subroutine. When the protocol name is not specified (proto parameter is NULL), the proto parameter need not be matched during the /etc/services file record search. 

The getservbyname() function searches the /etc/services file sequentially until one of the following occurs:

       •A service name and protocol name match. 

       •A service name matches while the proto parameter is set to NULL. 

       •The end of the /etc/services file is reached. 

Use the endservent() function to close the /etc/services file. 

The getservbyname_r() function is the reentrant version of the getservbyname() function.  When using the getservbyname_r() function, use the endservent_r() function to close the services file.  Upon successful completion, the returned structure is pointed to by serv.  The netdb.h header file defines the servent and servent_data structures. 

The system searches either the local /etc/services file or the NIS distributed networks file for the requested information.  To determine which file or files to search, and in which order, the system uses the switches in the /etc/svc.conf file. 

NOTES

The getservbyname() return value points to static data, which is overwritten by any subsequently called functions using the same structure. 

Before its first access by either the setservent_r() or getservbyname_r() function, you must zero-fill the servent_data structure. 

RETURN VALUES

Upon successful completion, the getservbyname() function returns a pointer to a servent structure.  A NULL pointer is returned when an error occurs or whenever the end of the /etc/services file is reached. 

Upon successful completion for getservbyname_r(), a value of 0 (zero) is returned.  Otherwise, a value of -1 is returned. 

ERRORS

If any of the following conditions occurs, the getservbyname() function sets errno to the corresponding value:

[EINVAL]The serv or serv_data parameter is invalid. 

[ESRCH]The search failed. 

In addition, if the function fails to open the file, it sets errno to indicate the cause of the failure. 

FILES

/etc/services
The DARPA Internet network service-name database. Each record in the file occupies a single line and has four fields: the official service name, the port reference, protocol name, and aliases.

RELATED INFORMATION

Functions: getservbyport(3), getservent(3), setservent(3), endservent(3).