Programming Interfaces Guide

Chapter 11 Transport Selection and Name-to-Address Mapping

This chapter describes selecting transports and resolving network addresses. This chapter further describes interfaces that enable you to specify the available communication protocols for an application. The chapter also explains additional interfaces that provide direct mapping of names to network addresses.


Note –

In this chapter, the terms network and transport are used interchangeably. The terms refer to the programmatic interface that conforms to the transport layer of the OSI Reference Mode. The term network is also used to refer to the physical collection of computers that are connected through some electronic medium.


Transport Selection


Caution – Caution –

The interfaces that are described in this chapter are multithread safe. “Multithread safe” means that you can use applications that contain transport selection interface calls freely in a multithreaded application. These interface calls do not provide linear scalability because the calls are not re-entrant.


A distributed application must use a standard interface to the transport services to be portable to different protocols. Transport selection services provide an interface that allows an application to select which protocols to use. This interface makes an application independent of protocol and medium.

Transport selection means that a client application can easily try each available transport until the client establishes communication with a server. Transport selection enables request acceptance on multiple transports by server applications. The applications can then communicate over a number of protocols. Transports can be tried in either the order specified by the local default sequence or in an order specified by the user.

Choosing from the available transports is the responsibility of the application. The transport selection mechanism makes that selection uniform and simple.

Name-to-Address Mapping

Name-to-address mapping enables an application to obtain the address of a service on a specified host independent of the transport used. Name-to-address mapping consists of the following interfaces:

netdir_getbyname(3NSL)

Maps the host and service name to a set of addresses

netdir_getbyaddr(3NSL)

Maps addresses into host and service names

netdir_free(3NSL)

Frees structures allocated by the name-to-address translation routines

taddr2uaddr(3NSL)

Translates an address and returns a transport-independent character representation of the address

uaddr2taddr(3NSL)

The universal address is translated into a netbuf structure

netdir_options(3NSL)

Interfaces to transport-specific capabilities such as the broadcast address and reserved port facilities of TCP and UDP

netdir_perror(3NSL)

Displays a message stating why one of the routines that map name-to-address failed on stderr.

netdir_sperror(3NSL)

Returns a string containing the error message stating why one of the routines that map name-to-address failed.

The first argument of each routine points to a netconfig(4) structure that describes a transport. The routine uses the array of directory-lookup library paths in the netconfig(4) structure to call each path until the translation succeeds.

The name-to-address libraries are described in Table 11–1. The routines that are described in Using the Name-to-Address Mapping Routines are defined in the netdir(3NSL) man page.


Note –

The following libraries no longer exist in the Solaris environment: tcpip.so, switch.so, and nis.so. For more information on this change, see the nsswitch.conf(4) man page and the NOTES section of the gethostbyname(3NSL) man page.


Table 11–1 Name-to-Address Libraries

Library 

Transport Family 

Description 

-

inet

The name-to-address mapping for networks of the protocol family inet is provided by the name service switch based on the entries for hosts and services in the file nsswitch.conf(4). For networks of other families, the dash indicates a nonfunctional name-to-address mapping.

straddr.so

loopback

Contains the routines that map name-to-address in any protocol that accepts strings as addresses, such as the loopback transports. 

straddr.so Library

Name–to–address translation files for the straddr.so library are created by the system administrator. The system administrator also maintains these translation files. The straddr.so files are /etc/net/transport-name/hosts and /etc/net/transport-name/services. transport-name is the local name of the transport that accepts string addresses, which is specified in the network ID field of the /etc/netconfig file. For example, the host file for ticlts would be /etc/net/ticlts/hosts, and the service file for ticlts would be /etc/net/ticlts/services.

Most string addresses do not distinguish between host and service. However, separating the string into a host part and a service part is consistent with other transports. The /etc/net/transport-name/hosts file contains a text string that is assumed to be the host address, followed by the host name:

joyluckaddr

joyluck

carpediemaddr

carpediem

thehopaddr

thehop

pongoaddr

pongo

Because loopback transports cannot go outside the containing host, listing other hosts makes no sense.

The /etc/net/transport-name/services file contains service names followed by strings that identify the service address:


rpcbind	rpc
listen	serve

The routines create the full-string address by concatenating the host address, a period (.), and the service address. For example, the address of the listen service on pongo is pongoaddr.serve.

When an application requests the address of a service on a particular host on a transport that uses this library, the host name must be in /etc/net/transport/hosts. The service name must be in /etc/net/transport/services. If either name is missing, the name-to-address translation fails.

Using the Name-to-Address Mapping Routines

This section is an overview of the mapping routines that are available for use. The routines return or convert the network names to their respective network addresses. Note that netdir_getbyname(3NSL), netdir_getbyaddr(3NSL), and taddr2uaddr(3NSL) return pointers to data that must be freed by calls to netdir_free(3NSL).

	int netdir_getbyname(struct netconfig *nconf, 
			struct nd_hostserv *service, struct nd_addrlist **addrs);

netdir_getbyname(3NSL) maps the host and service name specified in service to a set of addresses that are consistent with the transport identified in nconf. The nd_hostserv and nd_addrlist structures are defined in the netdir(3NSL) man page. A pointer to the addresses is returned in addrs.

To find all addresses of a host and service on all available transports, call netdir_getbyname(3NSL) with each netconfig(4) structure returned by either getnetpath(3NSL) or getnetconfig(3NSL).

int netdir_getbyaddr(struct netconfig *nconf,
		struct nd_hostservlist **service, struct netbuf *netaddr);

netdir_getbyaddr(3NSL) maps addresses into host and service names. The interface is called with an address in netaddr and returns a list of host-name and service-name pairs in service. The nd_hostservlist structure is defined in netdir(3NSL).

void netdir_free(void *ptr, int struct_type);

The netdir_free(3NSL) routine frees structures allocated by the name-to-address translation routines. The parameters can take the values that are shown in the following table.

Table 11–2 netdir_free(3NSL) Routines

struct_type

ptr

ND_HOSTSERV

Pointer to an nd_hostserv structure

ND_HOSTSERVLIST

Pointer to an nd_hostservlist structure

ND_ADDR

Pointer to a netbuf structure

ND_ADDRLIST

Pointer to an nd_addrlist structure

char *taddr2uaddr(struct netconfig *nconf, struct netbuf *addr);

taddr2uaddr(3NSL) translates the address pointed to by addr and returns a transport-independent character representation of the address. This character representation is called a universal address. The value that is given in nconf specifies the transport for which the address is valid. The universal address can be freed by free(3C).

struct netbuf *uaddr2taddr(struct netconfig *nconf, char *uaddr);

The universal address pointed to by uaddr is translated into a netbuf structure. nconf specifies the transport for which the address is valid.

int netdir_options(const struct netconfig *config,
 		 const int option, const int fildes, char *point_to_args);

netdir_options(3NSL) provides interfaces to transport-specific capabilities, such as the broadcast address and reserved port facilities of TCP and UDP. The value of nconf specifies a transport, while option specifies the transport-specific action to take. The value in option might disable consideration of the value in fd. The fourth argument points to operation-specific data.

The following table shows the values used for option.

Table 11–3 Values for netdir_options

Option 

Description 

ND_SET_BROADCAST

Sets the transport for broadcast if the transport supports broadcast 

ND_SET_RESERVEDPORT

Enables application binding to reserved ports if allowed by the transport 

ND_CHECK_RESERVEDPORT

Verifies that an address corresponds to a reserved port if the transport supports reserved ports 

ND_MERGEADDR

Transforms a locally meaningful address into an address to which client hosts can connect 

The netdir_perror(3NSL) routine displays a message stating why one of the routines that map name-to-address failed on stderr.

void netdir_perror(char *s);

The netdir_sperror(3NSL) routine returns a string containing the error message stating why one of the routines that map name-to-address failed.

char *netdir_sperror(void);

The following example shows network selection and name-to-address mapping.


Example 11–1 Network Selection and Name-to-Address Mapping

#include <netconfig.h>
#include <netdir.h>
#include <sys/tiuser.h>

struct nd_hostserv nd_hostserv;   /* host and service information */
struct nd_addrlist *nd_addrlistp; /* addresses for the service */
struct netbuf *netbufp;           /* the address of the service */
struct netconfig *nconf;          /* transport information*/
int i;                            /* the number of addresses */
char *uaddr;                      /* service universal address */
void *handlep;                    /* a handle into network selection */
/*
 * Set the host structure to reference the "date"
 * service on host "gandalf"
 */
nd_hostserv.h_host = "gandalf";
nd_hostserv.h_serv = "date";
/*
 * Initialize the network selection mechanism.
 */
if ((handlep = setnetpath()) == (void *)NULL) {
   nc_perror(argv[0]);
   exit(1);
}
/*
 * Loop through the transport providers.
 */
while ((nconf = getnetpath(handlep)) != (struct netconfig *)NULL)
{
   /*
    * Print out the information associated with the
    * transport provider described in the "netconfig"
    * structure.
    */
   printf("Transport provider name: %s\n", nconf->nc_netid);
   printf("Transport protocol family: %s\n", nconf->nc_protofmly);
   printf("The transport device file: %s\n", nconf->nc_device);
   printf("Transport provider semantics: ");
	   switch (nconf->nc_semantics) {
   case NC_TPI_COTS:
      printf("virtual circuit\n");
      break;
   case NC_TPI_COTS_ORD:
      printf("virtual circuit with orderly release\n");
      break;

   case NC_TPI_CLTS:
      printf("datagram\n");
      break;
   }
   /*
    * Get the address for service "date" on the host
    * named "gandalf" over the transport provider
    * specified in the netconfig structure.
    */
   if (netdir_getbyname(nconf, &nd_hostserv, &nd_addrlistp) != ND_OK) {
      printf("Cannot determine address for service\n");
      netdir_perror(argv[0]);
      continue;
   }
   printf("<%d> addresses of date service on gandalf:\n",
      nd_addrlistp->n_cnt);
   /*
    * Print out all addresses for service "date" on
    * host "gandalf" on current transport provider.
    */
   netbufp = nd_addrlistp->n_addrs;
   for (i = 0; i < nd_addrlistp->n_cnt; i++, netbufp++) {
      uaddr = taddr2uaddr(nconf,netbufp);
      printf("%s\n",uaddr);
      free(uaddr);
   }
   	netdir_free( nd_addrlistp, ND_ADDRLIST );

}
endnetconfig(handlep);