8. RPC RTL Management Routines

 

Introduction

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.

Management Routines

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.

Routine Name Conventions

In this chapter, all routines are documented according to their standard UNIX names.

Header Files

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.

Management Routines

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


 

get_myaddress

Returns the internet address of the local host.

 

Format

void get_myaddress(struct sockaddr_in *addr);

 

Argument

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).

 

Description

The get_myaddress routine returns the internet address of the local host without doing any name translation or DNS lookups.

 

 

 

 


 

getrpcbynumber

Gets an RPC entry.

 

Format

struct rpcent *getrpcbynumber(int number);

 

Argument

number

Program name or number.

 

Description

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.

 

Returns

A NULL pointer is returned on EOF or error.

 

 

 

 


 

getrpcport

Gets an RPC port number.

 

Format

int getrpcport(char *host, int prognum, int versnum, int proto);

 

Arguments

host

Host running the RPC program.

 

prognum

Program number.

 

proto

Protocol name. Must be IPPROTO_TCP or IPPROTO_UDP.

 

Description

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.