Standard Interface Routines

The standard interfaces are divided into top level, intermediate level, expert level, and bottom level. These interfaces give a programmer much greater control over communication parameters such as the transport being used, how long to wait before responding to errors and retransmitting requests, and so on.

Top-Level Routines

At the top level, the interface is still simple, but the program has to create a client handle before making a call or create a server handle before receiving calls. If you want the application to run on all transports, use this interface. You can find the use of these routines and code samples in "Top-Level Interface".

Table 2-2 RPC Routines--Top Level

Routine	Description
clnt_create()	Generic client creation. The program tells clnt_create() where the server is located and the type of transport to use.
clnt_create_timed()	Similar to clnt_create() but enables the programmer to specify the maximum time allowed for each type of transport tried during the creation attempt.
svc_create()	Creates server handles for all transports of the specified type. The program tells svc_create() which dispatch function to use.
clnt_call() ()	Client calls a procedure to send a request to the server.

Intermediate-Level Routines

The intermediate level interface of RPC enables you to you control details. Programs written at these lower levels are more complicated but run more efficiently. The intermediate level enables you to specify the transport to use. "Intermediate-Level Interface" describes the use of these routines and code samples.

Table 2-3 RPC Routines--Intermediate Level

Routine	Description
clnt_tp_create()	Creates a client handle for the specified transport
clnt_tp_create_timed()	Similar to clnt_tp_create() but enables the programmer to specify the maximum time allowed
svc_tp_create()	Creates a server handle for the specified transport
clnt_call() ()	Client calls a procedure to send a request to the server

Expert-Level Routines

The expert level contains a larger set of routines with which to specify transport-related parameters. "Expert-Level Interface" describes the use of these routines and code samples.

Table 2-4 RPC Routines--Expert Level

Routine	Description
clnt_tli_create()	Creates a client handle for the specified transport
svc_tli_create()	Creates a server handle for the specified transport
rpcb_set()	Calls rpcbind to set a map between an RPC service and a network address
rpcb_unset()	Deletes a mapping set by rpcb_set()
rpcb_getaddr()	Calls rpcbind() to get the transport addresses of specified RPC services
svc_reg()	Associates the specified program and version number pair with the specified dispatch routine
svc_unreg()	Deletes an association set by svc_reg()
clnt_call()()	Client calls a procedure to send a request to the server

Bottom-Level Routines

The bottom level contains routines used for full control of transport options. "Bottom-Level Interface" describes these routines.

Table 2-5 RPC Routines--Bottom Level

Routine	Description
clnt_dg_create()	Creates an RPC client handle for the specified remote program using a connectionless transport
svc_dg_create()	Creates an RPC server handle using a connectionless transport
clnt_vc_create()	Creates an RPC client handle for the specified remote program using a connection-oriented transport
svc_vc_create()	Creates an RPC server handle using a connection-oriented transport
clnt_call()()	Client calls a procedure to send a request to the server

Network Selection

You can write programs to run on a specific transport or transport type, or to operate on a system-chosen or user-chosen transport. Two mechanisms for network selection are the /etc/netconfig database and the environmental variable NETPATH. These mechanisms enable a fine degree of control over network selection: a user can specify a preferred transport and an application will use it if it can. If the specified transport is inappropriate, the application automatically tries other transports with the right characteristics.

/etc/netconfig lists the transports available to the host and identifies them by type. NETPATH is optional and enables you to specify a transport or selection of transports from the list in /etc/netconfig. By setting the NETPATH, you specify the order in which the application tries the available transports. If NETPATH is not set, the system defaults to all visible transports specified in /etc/netconfig, in the order that they appear in that file.

For more details on network selection, see the getnetconfig(3NSL) and netconfig(4) man pages.

RPC divides selectable transports into the types described in the following table:

Table 2-6 nettype Parameters

Value	Meaning
NULL	Same as selecting netpath.
visible	Uses the transports chosen with the visible flag (`v') set in their /etc/netconfig entries.
circuit_v	Same as visible, but restricted to connection-oriented transports. Transports are selected in the order listed in /etc/netconfig.
datagram_v	Same as visible, but restricted to connectionless transports.
circuit_n	Uses the connection-oriented transports chosen in the order defined in NETPATH.
datagram_n	Uses the connectionless transports chosen in the order defined in NETPATH.
udp	Specifies Internet User Datagram Protocol (UDP).
tcp	Specifies Internet Transport Control Protocol (TCP).

Transport Selection

RPC services are supported on both circuit-oriented and datagram transports. The selection of the transport depends on the requirements of the application.

Choose a datagram transport if the application has all of the following characteristics:

• Calls to the procedures do not change the state of the procedure or of associated data.

• The size of both the arguments and results is smaller than the transport packet size.

• The server is required to handle hundreds of clients. A datagram server does not keep any state data on clients, so it can potentially handle many clients. A circuit-oriented server keeps state data on each open client connection, so the number of clients is limited by the host resources.

Choose a circuit-oriented transport if the application has any of the following characteristics:

• The application can tolerate or justify the higher cost of connection setup compared to datagram transports.

• Calls to the procedures can change the state of the procedure or of associated data.

• The size of either the arguments or the results exceeds the maximum size of a datagram packet.

Name-to-Address Translation

Each transport has an associated set of routines that translate between universal network addresses (string representations of transport addresses) and the local address representation. These universal addresses are passed around within the RPC system (for example, between rpcbind and a client). A runtime linkable library that contains the name-to-address translation routines is associated with each transport. Table 2-7 shows the main translation routines.

For more details on these routines, see the netdir(3NSL) man page. Note that the netconfig structure in each case provides the context for name-to-address translations.

Table 2-7 Name-to-Address Translation Routines

netdir_getbyname()	Translates from host or service pairs (for example server1, rpcbind) and a netconfig structure to a set of netbuf addresses. netbufs are Transport Level Interface (TLI) structures that contain transport-specific addresses at runtime.
	Translates from netbuf() addresses and a netconfig structure to host or service pairs.
uaddr2taddr()	Translates from universal addresses and a netconfig() structure to netbuf addresses.
taddr2uaddr ()	Translates from netbuf addresses and a netconfig structure to universal addresses.

Address Look-up Services

Transport services do not provide address look-up services. They provide only message transfer across a network. A client program needs a way to obtain the address of its server program. In previous system releases this service was performed by portmap. In this release, rpcbind replaces the portmap utility.

RPC makes no assumption about the structure of a network address. It handles universal addresses specified only as null-terminated strings of ASCII characters. RPC translates universal addresses into local transport addresses by using routines specific to the transport. For more details on these routines, see the netdir(3NSL) and rpcbind(3NSL) man pages.

rpcbind enables you to perform the following operations:

• Add a registration

• Delete a registration

• Get address of a specified program number, version number, and transport

• Get the complete registration list

• Perform a remote call for a client