JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Programming Interfaces Guide     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information


1.  Memory and CPU Management

2.  Session Description Protocol API

3.  Process Scheduler

4.  Locality Group APIs

5.  Input/Output Interfaces

6.  Interprocess Communication

7.  Socket Interfaces

Overview of Sockets

Socket Libraries

Socket Types

Interface Sets

Socket Basics

Socket Creation

Binding Local Names

Connection Establishment

Connection Errors

Data Transfer

Closing Sockets

Connecting Stream Sockets

Input/Output Multiplexing

Datagram Sockets

Standard Routines

Host and Service Names

Host Names - hostent

Network Names - netent

Protocol Names - protoent

Service Names - servent

Other Routines

Client-Server Programs

Sockets and Servers

Sockets and Clients

Connectionless Servers

Advanced Socket Topics

Out-of-Band Data

Nonblocking Sockets

Asynchronous Socket I/O

Interrupt-Driven Socket I/O

Signals and Process Group ID

Selecting Specific Protocols

Address Binding

Socket Options

inetd Daemon

Broadcasting and Determining Network Configuration

Using Multicast

Sending IPv4 Multicast Datagrams

Receiving IPv4 Multicast Datagrams

Sending IPv6 Multicast Datagrams

Receiving IPv6 Multicast Datagrams

Stream Control Transmission Protocol

SCTP Stack Implementation

SCTP Socket Interfaces













Branched-off Association

Code Examples of SCTP Use

8.  Programming With XTI and TLI

9.  Packet Filtering Hooks

10.  Transport Selection and Name-to-Address Mapping

11.  Real-time Programming and Administration

12.  The Oracle Solaris ABI and ABI Tools

A.  UNIX Domain Sockets


Standard Routines

This section describes the routines that you can use to locate and construct network addresses. Unless otherwise stated, interfaces presented in this section apply only to the Internet family.

Locating a service on a remote host requires many levels of mapping before the client and server communicate. A service has a name for human use. The service and host names must translate to network addresses. Finally, the network address must be usable to locate and route to the host. The specifics of the mappings can vary between network architectures.

Standard routines map host names to network addresses, network names to network numbers, protocol names to protocol numbers, and service names to port numbers. The standard routines also indicate the appropriate protocol to use in communicating with the server process. The file netdb.h must be included when using any of these routines.

Host and Service Names

The interfaces getaddrinfo(3SOCKET), getnameinfo(3SOCKET), gai_strerror(3SOCKET), and freeaddrinfo(3SOCKET) provide a simplified way to translate between the names and addresses of a service on a host. These interfaces are more recent than the getipnodebyname(3SOCKET), gethostbyname(3NSL), and getservbyname(3SOCKET) APIs. Both IPv6 and IPv4 addresses are handled transparently.

The getaddrinfo(3SOCKET) routine returns the combined address and port number of the specified host and service names. Because the information returned by getaddrinfo(3SOCKET) is dynamically allocated, the information must be freed by freeaddrinfo(3SOCKET) to prevent memory leaks. getnameinfo(3SOCKET) returns the host and services names associated with a specified address and port number. Call gai_strerror(3SOCKET) to print error messages based on the EAI_xxx codes returned by getaddrinfo(3SOCKET) and getnameinfo(3SOCKET).

An example of using getaddrinfo(3SOCKET) follows.

struct addrinfo        *res, *aip;
struct addrinfo        hints;
int                    error;

/* Get host address.  Any type of address will do. */
bzero(&hints, sizeof (hints));
hints.ai_flags = AI_ALL|AI_ADDRCONFIG;
hints.ai_socktype = SOCK_STREAM;

error = getaddrinfo(hostname, servicename, &hints, &res);
if (error != 0) {
    (void) fprintf(stderr, "getaddrinfo: %s for host %s service %s\n",
    gai_strerror(error), hostname, servicename);
    return (-1);

After processing the information returned by getaddrinfo(3SOCKET) in the structure pointed to by res, the storage should be released by freeaddrinfo(res).

The getnameinfo(3SOCKET) routine is particularly useful in identifying the cause of an error, as in the following example:

struct sockaddr_storage faddr;
int                     sock, new_sock, sock_opt;
socklen_t               faddrlen;
int                     error;
char                    hname[NI_MAXHOST];
char                    sname[NI_MAXSERV];
faddrlen = sizeof (faddr);
new_sock = accept(sock, (struct sockaddr *)&faddr, &faddrlen);
if (new_sock == -1) {
    if (errno != EINTR && errno != ECONNABORTED) {
error = getnameinfo((struct sockaddr *)&faddr, faddrlen, hname, 
    sizeof (hname), sname, sizeof (sname), 0);
if (error) {
    (void) fprintf(stderr, "getnameinfo: %s\n",
} else {
    (void) printf("Connection from %s/%s\n", hname, sname);

Host Names – hostent

An Internet host-name-to-address mapping is represented by the hostent structure as defined in gethostent(3NSL):

struct hostent {
    char  *h_name;            /* official name of host */
    char  **h_aliases;        /* alias list */
    int   h_addrtype;         /* hostaddrtype(e.g.,AF_INET6) */
    int   h_length;           /* length of address */
    char  **h_addr_list;      /* list of addrs, null terminated */
/*1st addr, net byte order*/
#define h_addr h_addr_list[0]

Maps an Internet host name to a hostent structure


Maps an Internet host address to a hostent structure


Frees the memory of a hostent structure


Maps an Internet host address to a string

The routines return a hostent structure that contains the name of the host, its aliases, the address type, and a NULL-terminated list of variable length addresses. The list of addresses is required because a host can have many addresses. The h_addr definition is for backward compatibility, and is the first address in the list of addresses in the hostent structure.

Network Names – netent

The routines to map network names to numbers and the reverse return a netent structure:

 * Assumes that a network number fits in 32 bits.
struct netent {
   char     *n_name;      /* official name of net */
   char     **n_aliases;  /* alias list */
   int      n_addrtype;   /* net address type */
   int      n_net;        /* net number, host byte order */

getnetbyname(3SOCKET), getnetbyaddr_r(3SOCKET), and getnetent(3SOCKET) are the network counterparts to the host routines previously described.

Protocol Names – protoent

The protoent structure defines the protocol-name mapping used with getprotobyname(3SOCKET), getprotobynumber(3SOCKET), and getprotoent(3SOCKET) and defined in getprotoent(3SOCKET):

struct protoent {
    char    *p_name;       /* official protocol name */
    char    **p_aliases    /* alias list */
    int     p_proto;       /* protocol number */

Service Names – servent

An Internet family service resides at a specific, well-known port, and uses a particular protocol. A service-name-to-port-number mapping is described by the servent structure that is defined in getprotoent(3SOCKET):

struct servent {
    char    *s_name;        /* official service name */
    char    **s_aliases;    /* alias list */
    int     s_port;         /* port number, network byte order */
    char    *s_proto;       /* protocol to use */

getservbyname(3SOCKET) maps service names and, optionally, a qualifying protocol to a servent structure. The call:

sp = getservbyname("telnet", (char *) 0);

returns the service specification of a telnet server that is using any protocol. The call:

sp = getservbyname("telnet", "tcp");

returns the telnet server that uses the TCP protocol. getservbyport(3SOCKET) and getservent(3SOCKET) are also provided. getservbyport(3SOCKET) has an interface that is similar to the interface used by getservbyname(3SOCKET). You can specify an optional protocol name to qualify lookups.

Other Routines

Several other routines that simplify manipulating names and addresses are available. The following table summarizes the routines for manipulating variable-length byte strings and byte-swapping network addresses and values.

Table 7-2 Runtime Library Routines

Compares byte-strings; 0 if same, not 0 otherwise
Copies n bytes from s2 to s1
Sets n bytes to value starting at base
32-bit quantity from host into network byte order
16-bit quantity from host into network byte order
32-bit quantity from network into host byte order
16-bit quantity from network into host byte order

The byte-swapping routines are provided because the operating system expects addresses to be supplied in network order. On some architectures, the host byte ordering is different from network byte order, so programs must sometimes byte-swap values. Routines that return network addresses do so in network order. Byte-swapping problems occur only when interpreting network addresses. For example, the following code formats a TCP or UDP port:

printf("port number %d\n", ntohs(sp->s_port));

On machines that do not need these routines, the routines are defined as null macros.