Standard Routines

You might need to locate and construct network addresses. This section describes the routines that manipulate network addresses. Unless otherwise stated, functions presented in this section apply only to the Internet domain.

Locating a service on a remote host requires many levels of mapping before client and server communicate. A service has a name for human use. The service and host names must be translated to network addresses. Finally, the address is used to locate and route to the host. The specifics of the mappings can vary between network architectures. Preferably, a network will not require that hosts be named, thus protecting the identity of their physical locations. It is more flexible to discover the location of the host when it is addressed.

Standard routines map host names to network addresses, network names to network numbers, protocol names to protocol numbers, and service names to port numbers, and 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 Names

An Internet host-name-to-address mapping is represented by the hostent structure:

struct hostent {
	   char  *h_name;            /* official name of host */
	   char  **h_aliases;        /* alias list */
	   int   h_addrtype;         /* hostaddrtype(e.g.,AF_INET) */
	   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]

gethostbyname() maps an Internet host name to a hostent structure, gethostbyaddr() maps an Internet host address to a hostent structure, and inet_ntoa() maps an Internet host address to a displayable string.

The routines return a hostent structure containing the name of the host, its aliases, the address type (address family), 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

The routines to map network names to numbers, and back 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(), getnetbyaddr(), and getnetent() are the network counterparts to the host routines described above.

Protocol Names

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

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

In the UNIX domain, no protocol database exists.

Service Names

An Internet domain 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:

struct serven
   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() 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 using any protocol. The call:

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

returns the telnet server that uses the TCP protocol. getservbyport() and getservent() are also provided. getservbyport() has an interface similar to that of getservbyname(); an optional protocol name can be specified to qualify lookups.

Other Routines

In addition to address-related database routines, there are several other routines that simplify manipulating names and addresses. Table 2-3 summarizes the routines for manipulating variable-length byte strings and byte-swapping network addresses and values.

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. There are byte-swapping problems 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 certain machines, where these routines are not needed, they are defined as null macros.