## TCPware V5.7 Programmer's Guide

- Introduction
- Port Mapper Routines
- Port Mapper Arguments
- Routine Descriptions

Chapter 17

ONC RPC RTL Port Mapper Routines

# Introduction

This chapter is for RPC programmers. It documents the port mapper routines in the ONC RPC Run-Time Library (RTL). These routines are the programming interface to ONC RPC.

# Port Mapper Routines

Port Mapper routines provide a simple callable interface to the Port Mapper. They allow you to request Port Mapper services and information about port mappings. Table 17-1 summarizes the purpose of each Port Mapper routine.

Table 17-1 Port Mapper Routines (Continued)

Routine | Purpose
pmap_freemaps | Frees memory that was allocated by the pmap_getmaps routine.
pmap_getmaps | Returns a list of Port Mappings for the specified host.
pmap_getport | Returns the port number on which a specified service is waiting.
pmap_rmtcall | Requests the Port Mapper on a remote host to call a procedure on that host.
pmap_set | Registers a remote service with a remote port.
pmap_unset | Unregisters a service so it is no longer mapped to a port.

# Port Mapper Arguments

Port Mapper routines use many of the same arguments as client routines.

See Table 16-1 in the ONC RPC RTL Client Routines chapter for a list of these arguments.

# Routine Descriptions

The following sections describe each Port Mapper routine in detail.

pmap_freemaps

ONC Frees memory that was allocated by the pmap_getmaps routine.

Format

void pmap_freemaps (struct pmaplist *list);

Argument

list

Address of a structure containing the list returned by the pmap_getmaps routine.

Description

Call the pmap_freemaps routine when the list returned by pmap_getmaps is no longer needed. Do not call pmap_freemaps to free a list that you created.

See Also

pmap_getmaps

pmap_getmaps

XDR ONC Returns a list of Port Mappings for the specified host.

Format

struct pmaplist *pmap_getmaps (struct sockaddr_in *addr);

Argument

addr

Address of a structure containing the internet address of the host whose Port Mapper is being called.

Description

The pmap_getmaps routine returns a list of current RPC server-to-Port Mappings on the host at addr. The list structure is defined in the PMAP_PROT.H file.

The RPCINFO command uses this routine.

Diagnostics

If an error occurs (for example, pmap_getmaps cannot get a list of Port Mappings, the internet address is invalid, or the remote Port Mapper does not exist), the routine returns either NULL or the address of the list.

See Also

pmap_freemaps, pmap_getport, pmap_set, pmap_unset

pmap_getport

XDR ONC Returns the port number on which a specified service is waiting.

Format

u_short pmap_getport (struct sockaddr_in *addr,
u_long prognum, u_long versnum, u_long protocol);

Arguments

addr

Address of a structure containing the internet address of the remote host on which the server resides.

prognum, versnum, protocol

See Table 16-1 in the ONC RPC RTL Client Routines chapter for a list of these arguments.

Diagnostics

If the requested mapping does not exist or the routine fails to contact the remote Port Mapper, the routine returns either the port number or zero.

The pmap_getport routine uses the global variable rpc_createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the service program to handle the error. The value of rpc_createerr is set by any RPC server creation routine that does not succeed.

The rpc_createerr variable is defined in the CLNT.H file.

See Also

pmap_getmaps, pmap_set, pmap_unset

pmap_rmtcall

XDR ONC Requests the Port Mapper on a remote host to call a procedure on that host.

Format

enum clnt_stat pmap_rmtcall (struct sockaddr_in *addr,
u_long prognum, u_long versnum, u_long procnum,
xdrproc_t inproc, u_char *in, xdrproc_t outproc, u_char *out, struct
timeval tout, u_long *portp);

Arguments

addr

Address of a structure containing the internet address of the remote host on which the server resides.

prognum, versnum, procnum, inproc, in, outproc, out

See Table 16-1 in the ONC RPC RTL Client Routines chapter for a list of these arguments.

tout

Time allowed for the results to return to the client, in seconds and microseconds.

portp

Address where pmap_rmtcall will write the port number of the remote service.

Description

The pmap_rmtcall routine allows you to get a port number and call a remote procedure in one call. The routine requests a remote Port Mapper to call a prognum, versnum, and procnum on the Port Mapper's host. The remote procedure call uses the UDP transport.

If pmap_rmtcall succeeds, it changes portp to contain the port number of the remote service.

After calling the pmap_rmtcall routine, you may call the clnt_perrno routine.

Example

The TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC]GETSYI_CLNT_RMTCALL.C file provides a sample program using pmap_rmtcall.

Diagnostics

This routine returns diagnostic values defined in the CLNT.H file for enumclnt_stat.

See Also

clnt_broadcast, clnt_perrno / clnt_sperrno

pmap_set

XDR ONC Registers a remote service with a remote port.

Format

bool_t pmap_set (u_long prognum, u_long versnum,
u_long protocol, u_short port);

Arguments

p rognum, versnum, protocol

See Table 16-1 in the ONC RPC RTL Client Routines chapter for a list of these arguments.

port

Remote port number.

Description

The pmap_set routine calls the local Port Mapper to tell it which port and protocol the prognum, versnum is using.

You are not likely to use pmap_set, because svc_register calls it.

Diagnostics

The pmap_set routine returns TRUE if it succeeds, and FALSE if it fails.

See Also

pmap_getport, pmap_getmaps, pmap_unset, svc_register

pmap_unset

XDR ONC Unregisters a service so it is no longer mapped it to a port.

Format

bool_t pmap_unset (u_long prognum, u_long versnum);

Arguments

prognum, versnum

See Table 16-1 in the ONC RPC RTL Client Routines chapter for a list of these arguments.

Description

The pmap_unset routine calls the local Port Mapper and, for all protocols, removes the prognum and versnum from the list that maps servers to ports.

You are not likely to use pmap_unset, because svc_unregister calls it.

Example

The GETSYI_PROC_A.C and GETSYI_SVC.C files provide sample programs using the pmap_unset routine.

These files are in the TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC] directory.

Diagnostics

The pmap_unset routine returns TRUE if it succeeds, FALSE if it fails.

See Also

pmap_getport, pmap_getmaps, pmap_set, svc_unregister