getservbyname()--Get Port Number for Service Name

BSD 4.3 Syntax

  #include <netdb.h>

struct servent *getservbyname(char *service_name,
                              char *protocol_name)

  Service Program Name: QSOSRV2

  Default Public Authority: *USE

  Threadsafe: No; see Usage Notes.

UNIX^® 98 Compatible Syntax

  #define _XOPEN_SOURCE 520
  #include <netdb.h>

struct servent *getservbyname(const char *service_name,
                              const char *protocol_name)

  Service Program Name: QSOSRV2

  Default Public Authority: *USE

  Threadsafe: No; see Usage Notes.

The getservbyname() 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.

There are two versions of the API, as shown above. The base IBM^® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

Parameters

service_name: (Input) The pointer to the character string that contains the name of the service for which information is to be retrieved (for example, telnet).
protocol_name: (Input) The pointer to the character string that contains the name of the protocol that further qualifies the 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.

Authorities

No authorization is required.

Return Value

getservbyname() returns a pointer. Possible values are:

NULL (unsuccessful)
p (successful), where p is a pointer to struct servent.

The structure struct servent is defined in <netdb.h>.

      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 array of alternate names for the service. s_port is the port number assigned to the service. s_proto is the protocol being used by the service.

Usage Notes

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)
The pointer returned by getservbyname() points to static storage that is overwritten on subsequent calls to the getservbyname(), getservbyname(), or getservent() functions.
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() with a nonzero parameter value was not previously done.
A coded character set identifier (CCSID) of 65535 for the job requests that no database translation be performed. For translation to occur for the service name and the protocol name, specified by the service_name and protocol_name parameters, respectively, and for the service names returned in the servent structure, the job CCSID must be something other than 65535.
Do not use the getservbyname() function in a multithreaded environment. See the multithread alternative getservbyname_r() function.
When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the getservbyname() API is mapped to qso_getservbyname98().

Related Information

_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
getservbyport()--Get Service Name for Port Number
getservent()--Get Next Entry from Service Database
setservent()--Open Service Database
endservent()--Close Service Database

API introduced: V4R2

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