This chapter is for RPC programmers. It introduces RPC Run-Time Library (RTL) conventions and documents the management routines in the RPC RTL. These routines are the programming interface to RPC.
The RPC RTL contains:
· RPC management routines
· RPC client and server routines for the UDP and TCP transport layers
· On VAX and Alpha systems, RPC provides a single shareable image accessed via the TCPIP$RPCXDR_SHR logical. This shareable image contains routines for all of the HP C floating-point types. The correct routines will be called automatically based on the compiler options used to compile the RPC application. See the Hewlett-Packard C documentation for how to use the floating-point compiler options.
Chapter 7, Building Distributed Applications with RPC, explains how to link in the RPC RTL.
In this chapter, all routines are documented according to their standard UNIX names.
All RPC programs include the file named RPC.H. Locations for this file are TCPIP$RPC:RPC.H
The RPC.H file includes the files listed below:
|
Filename |
Purpose |
|
AUTH.H |
Used for authentication. |
|
AUTH_UNIX.H |
Contains XDR definitions for UNIX-style authentication. |
|
CLNT.H |
Contains various RPC client definitions. |
|
IN.H |
Defines structures for the internet and socket addresses (in_addrand and sockaddr_in). This file is part of the C Socket Library. |
|
RPC_MSG.H |
Defines the RPC message format. |
|
SVC.H |
Contains various RPC server definitions. |
|
SVC_AUTH.H |
Used for server authentication. |
|
TYPES.H |
Defines UNIX C data types. |
|
XDR.H |
Contains various XDR definitions. |
|
NETDB.H |
Defines structures and routines to parse /etc/rpc. |
There is an additional header file not included by RPC.H that is used by xdr_pmap and xdr_pmaplist routines. The file name is pmap_prot.h, and the location is TCPIP$RPC:PMAP_PROT.H.
RPC management routines retrieve and maintain information that describes how a process is using RPC. This section describes each management routine and function in detail. The following information is provided for each routine:
· Format
· Arguments
· Description
· Diagnostics, or status codes returned, if any
Returns the internet address of the local host.
void get_myaddress(struct sockaddr_in *addr);
addr
Address of a sockaddr_in structure that will be loaded with the host internet address. The port number is always set to htons(PMAPPORT).
The get_myaddress routine returns the internet address of the local host without doing any name translation or DNS lookups.
Gets an RPC entry.
struct rpcent *getrpcbynumber(int number);
number
Program name or number.
The getrpcbynumber routine returns a pointer to an object with the following structure containing the broken-out fields of a line in the RPC program number database.
struct rpcent
{
char *r_name; /* name of server for this RPC program */
char **r_aliases; /* zero-terminated list of alternate names */
long r_number; /* RPC program number */
};
The getrpcbynumber routine sequentially searches from the beginning of the file until a matching RPC program name or program number is found, or until an EOF is encountered.
A NULL pointer is returned on EOF or error.
Gets an RPC port number.
int getrpcport(char *host, int prognum, int versnum, int proto);
host
Host running the RPC program.
prognum
Program number.
proto
Protocol name. Must be IPPROTO_TCP or IPPROTO_UDP.
The getrpcport routine returns the port number for version versnum of the RPC program prognum running on host and using protocol proto.
It returns 0 if it cannot contact the portmapper, or if prognum is not registered. If prognum is registered but not with versnum, it still returns a port number (for some version of the program), indicating that the program is indeed registered. The version mismatch is detected on the first call to the service.