getservbyname_r()--Get Port Number for Service Name

 #include <netdb.h>
 int getservbyname_r(char *service_name,
                   char *protocol_name,
                   struct servent
                      *servent_struct_addr,
                   struct servent_data
                      *servent_data_struct_addr)

The getservbyname_r() function is used to retrieve information about services: the protocol being used by the service and the port number assigned for the service. The information is retrieved from the service database file.

Parameters

char *service_name  (input) 

Specifies the pointer to the character string that contains the name of the service for which information is to be retrieved (for example, telnet).

char *protocol_name  (input) 

Specifies the pointer to the character string that contains the name of the protocol that further qualifies the search search criteria. For example, if the service_name is telnet, and the protocol_name is tcp, then the call will return the telnet server that uses the TCP protocol. If this parameter is set to NULL, then the first telnet server is returned, regardless of the protocol used.

struct servent *servent_struct_addr  (input/output) 

Specifies the pointer to a servent structure where the results will be placed. All results must be referenced through this structure.

struct servent_data *servent_data_struct_addr  (input/output) 

Specifies the pointer to the servent_data structure, which is used to pass and preserve results between function calls. The field serve_control_blk in the servent_data structure must be initialized with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then the entire servent_data structure must be initialized with hexadecimal zeros before initial use.

Authorities

No authorization is required.

Return Value

The getservbyname_r() function returns an integer. Possible values are:

• -1 (unsuccessful call)
• 0 (successful call)

The struct servent denoted by servent_struct_addr and struct servent_datadenoted by servent_data_struct_addr are both defined in <netdb.h>. The structure struct serventis defined as:

      struct servent [
        char            *s_name;
        char            **s_aliases;
        int             s_port;
        char            *s_proto
      ];

s_name points to the character string that contains the name of the service. s_aliases is a pointer to a NULL-terminated list of pointers, each of which points to a character string that represents an alternative name for the service. s_port is the port number assigned to the service. s_proto is a pointer to a character string that contains the name of the protocol being used by the service.

Error Conditions

When the getservbyname_r() function fails, errno can be set to:

[EINVAL]

?The servent_data structure was not properly initialized with hexadecimal zeros before initial use. For corrective action, see the description for structure servent_data.

Usage Notes

1. System i^® Navigator or the following CL commands can be used to access the services database file:
   
   
   • WRKSRVTBLE (Work with Service Table Entries)
   • ADDSRVTBLE (Add Service Table Entry)
   • RMVSRVTBLE (Remove Service Table Entry)
   
   
2. When the service information is obtained from the service database file, the file is opened and the service information is retrieved (if it exists) from the file. The file is then closed only if a setservent_r() call with a non-zero parameter value was not previously done.
   
   
3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation be performed. For translation to occur for the following, the job CCSID must be something other than 65535:
   
   
   • The service name and the protocol name, specified by the service_name and protocol_name parameters, respectively
   • The service names returned in the servent structure

Related Information

• getservbyport_r()--Get Service Name for Port Number
  
  
• getservent_r()--Get Next Entry from Service Database
  
  
• setservent_r()--Open Service Database
  
  
• endservent_r()--Close Service Database

[ Back to top | UNIX-Type APIs | APIs by category ]