9. RPC RTL Client Routines

Introduction

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

 

Common Arguments

Many client, Port Mapper, and server routines use the same arguments.

Common Arguments  lists these arguments and defines their purpose. Arguments that are unique to each routine are documented together with their respective routines in this and the following chapters

Table 9-1     Common Arguments 

Argument

Purpose

args_ptr

Address of the buffer to contain the decoded RPC arguments.

auth

RPC authentication client handle created by the authnone_create, authunix_create, or authunix_create_default routine.

clnt

Client handle returned by any of the client create routines.

in

Input arguments for the service procedure.

inproc

XDR routine that encodes input arguments.

out

Results of the remote procedure call.

outproc

XDR routine that decodes output arguments.

procnum

Number of the service procedure.

prognum

Program number of the service program.

protocol

Transport protocol for the service. Must be IPPROTO_UDP or IPPROTO_TCP.

s

String containing the message of your choice. The routines append an error message to this string.

sockp

Socket to be used for this remote procedure call. If sockp is RPC_ANYSOCK, the routine creates a new socket and defines sockp. The clnt_destroy routine closes the socket.

If sockp is a value other than RPC_ANYSOCK, the routine uses this socket and ignores the internet address of the server.

versnum

Version number of the service program.

xdr_args

XDR procedure that describes the RPC arguments.

xdrs

Structure containing XDR encoding and decoding information.

xprt

RPC server handle.

 

Client Routines

The client routines are called by the client main program or the client stub procedures.

The following sections describe each client routine in detail. The client routines are

auth_destroy

clnt_destroy

authnone_create

clnt_geterr

authunix_create

clnt_pcreateerror / c

authunix_create_default

clnt_perrno / c

callrpc

clnt_perror / c

clnt_broadcast

clntraw_create

clnt_call

clnttcp_create

clnt_control

clntudp_create / c

clnt_create

 

auth_destroy

A macro that destroys authentication information associated with an authentication handle.

Format

void auth_destroy (AUTH *auth)

Argument

auth

RPC authentication client handle created by the authnone_create, authunix_create, or authunix_create_default routine.

Description

Use auth_destroy to free memory that was allocated for authentication handles. This routine undefines the value of auth by deallocating private data structures.

Do not use this memory space after auth_destroy has completed. You no longer own it.

See Also

authnone_create, authunix_create, authunix_create_default

authnone_create

Creates and returns a null RPC authentication handle for the client process.

Format

#include

AUTH *authnone_create();

Arguments

None.

Description

This routine is for client processes that require no authentication. RPC uses it as a default when it creates a client handle.

See Also

authnone_create, authunix_create_default, clnt_create, clntraw_create, clnttcp_create, clntudp_create / c

authunix_create

Creates and returns an RPC authentication handle for the client process. Use this routine when the server requires UNIX-style authentication.

Format

#include

AUTH *authunix_create (char *host, int uid, int gid, int len, int gids);

Arguments

host

Address of the name of the host that created the authentication information. This is usually the local host running the client process.

uid

User ID of the person who is executing this process.

gid

User's group ID.

len

Number of elements in the *gids array.

gids

Address of the array of groups to which the user belongs.

Description

Since the client does not validate the uid and gid, it is easy to impersonate an unauthorized user. Choose values the server expects to receive. The application must provide OpenVMS-to-UNIX authorization mapping.

You can use a Socket Library lookup routine to get the host name.

See Also

authnone_create, authunix_create_default

authunix_create_default

Calls the authunix_create routine and provides default values as arguments.

Format

#include
AUTH *authunix_create_default()

Arguments

See below.

Description

Like the authunix_create routine, authunix_create_default provides UNIX-style authentication for the client process. However, authunix_create_default does not require you to enter any arguments. Instead, this routine provides default values for the arguments used by authunix_create, listed in Default Arguments 

Table 9-2     Default Arguments 

Argument

Default Value

host

local host domain name

uid

getuid ( )

gid

getgid ( )

len

0

gids

0

 

You can replace this call with authunix_create and provide appropriate values.

Example

auth_destroy(client->cl_auth);
client->cl_auth = authunix_create_default();

This example overrides the authnone_create routine, where client is the value returned by the clnt_create, clntraw_create, clnttcp_create, or clntudp_create / c routine.

See Also

callrpc

callrpc

Format

#include

int callrpc (char *host, u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, u_char *in,
xdrproc_t outproc, u_char *out);

Arguments

host

Host where the procedure resides.

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

See Common Arguments  for a description of the above arguments.

Description

The callrpc routine performs the same functions as the clnt_create,  and clnt_destroy routines.

Since the callrpc routine uses the UDP transport protocol, messages can be no larger than 8Kbytes. This routine does not allow you to control timeouts or authentication.

If you want to use the TCP transport, use the clnt_create or clnttcp_create routine.

Diagnostics

The callrpc routine returns zero if it succeeds, and the value of enum clnt_stat cast to an integer if it fails.

You can use the clnt_perrno / c routine to translate failure status codes into messages.

See Also

clnt_broadcast, clnt_call, clnt_create, clnt_destroy, clnt_perrno / c, clnttcp_create

clnt_broadcast

Broadcasts a remote procedure call to all local networks, using the broadcast address.

Format

#include

enum clnt_stat clnt_broadcast (u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, u_char *in,
xdrproc_t outproc, u_char *out, resultproc_t eachresult);

Arguments

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

See Common Arguments  for a description of the above arguments.

eachresult

Each time clnt_broadcast receives a response, it calls the eachresult routine. If eachresult returns zero, clnt_broadcast waits for more replies. If eachresult returns a nonzero value, clnt_broadcast stops waiting for replies. The eachresult routine uses this form:

int eachresult(out, addr)

u_char *out;

struct sockaddr_in *addr;

out

Contains the results of the remote procedure call, in the local data format.

*addr

Is the address of the host that sent the results.

 

Description

The clnt_broadcast routine performs the same functions as the callrpc routine. However, clnt_broadcast sends a message to all local networks, using the broadcast address. The clnt_broadcast routine uses the UDP protocol.

Maximum Message Size  indicates how large a broadcast message can be.

Table 9-3     Maximum Message Size 

Line

Maximum Size

Ethernet

1500 bytes

proNet

2044 bytes

Diagnostics

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

See Also

callrpc, clnt_perrno / c

clnt_call

A macro that calls a remote procedure.

Format

enum clnt_stat clnt_call (CLIENT *clnt, u_long procnum,
xdrproc_t inproc, u_char *in, xdrproc_t outproc, u_char *out,
struct timeval tout);

Arguments

clnt, procnum, inproc, in, outproc, out

See Common Arguments  for a description of the above arguments.

tout

Time allowed for the results to return to the client, in seconds and microseconds. If you use the clnt_control routine to change the CLSET_TIMEOUT code, this argument is ignored.

Description

Use the clnt_call routine after using clnt_create. After you have finished with the client handle, use the clnt_destroy routine. You can use the clnt_perror / c routine to print messages for any errors that occurred.

Diagnostics

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

See Also

clnt_control, clnt_create, clnt_destroy, clnt_perrno / c

clnt_control

A macro that changes or retrieves information about an RPC client process.

Format

bool_t clnt_control (CLIENT *clnt, u_long code, void *info);

Arguments

clnt

Client handle returned by any of the client create routines.

code

Code listed in Valid Codes .

Table 9-4     Valid Codes 

Code

Type

Purpose

CLSET_TIMEOUT

struct timeval

Set total timeout

CLGET_TIMEOUT

struct timeval

Get total timeout

CLSET_RETRY_TIMEOUT*

struct timeval

Set retry timeout

CLGET_RETRY_TIMEOUT*

struct timeval

Get retry timeout

CLGET_SERVER_ADDR

struct sockaddr_in

Get server address

* Valid only for the UDP transport protocol.

 

The timeval is specified in seconds and microseconds. The total timeout is the length of time that the client waits for a reply. The default total timeout is 25 seconds.

The retry time is the length of time that UDP waits for the server to reply before transmitting the request. The default retry timeout is 5 seconds. You might want to increase the retry time if your network is slow.

For example, suppose the total timeout is 10 seconds and the retry time is five seconds. The client sends the request and waits five seconds. If the client does not receive a reply, it sends the request again. If the client does not receive a reply within five seconds, it does not send the request again.

If you use CLSET_TIMEOUT to set the timeout, theclnt_call routine ignores the timeout parameter it receives for all future calls.

info

Address of the information being changed or retrieved.

Diagnostics

This routine returns TRUE if it succeeds, and FALSE if it fails.

See Also

clnt_call, clnt_create, clnt_destroy, clntraw_create, clnttcp_create, clntudp_create / c

clnt_create

Creates an RPC client handle.

Format

#include

CLIENT *clnt_create (char *host, u_long prognum, u_long versnum, char *proto);

Arguments

host

Address of the string containing the name of the remote host where the server is located.

prognum, versnum

See Common Arguments  for a description of the above arguments.

proto

Address of a string containing the name of the transport protocol. Valid values are UDP and TCP.

Description

The clnt_create routine creates an RPC client handle for prognum. An RPC client handle is a structure containing information about the RPC client. The client can use the UDP or TCP transport protocol.

This routine uses the Port Mapper. You cannot control the local port.

The default sizes of the send and receive buffers are 8800 bytes for the UDP transport, and 4000 bytes for the TCP transport.

The retry time for the UDP transport is five seconds.

Use the clnt_create routine instead of the callrpc or clnt_broadcast routines if you want to use one of the following:

  The TCP transport

  An authentication other than null

  More than one active client at the same time

You can also use clntraw_create to use the IP protocol, clnttcp_create to use the TCP protocol, or clntudp_create / c to use the UDP protocol.

The clnt_create 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 client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed.

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

Diagnostics

The clnt_create routine returns the address of the client handle, or zero (if it could not create the client handle).

If the clnt_create routine fails, you can use the clnt_pcreateerror / c routine to obtain diagnostic information.

See Also

clnt_call, clnt_control, clnt_destroy, clntraw_create, clnt_pcreateerror / c, clnttcp_create, clntudp_create / c

clnt_destroy

A macro that destroys an RPC client handle.

Format

void clnt_destroy (CLIENT *clnt);

Argument

clnt

Client handle returned by any of the client create routines.

Description

The clnt_destroy routine destroys the client's RPC handle by deallocating all memory related to the handle. The client is undefined after the clnt_destroy call.

If theclnt_create routine had previously opened a socket, this routine closes the socket. Otherwise, the socket remains open.

See Also

clnt_create, clntraw_create, clnttcp_create, clntudp_create / c

clnt_geterr

A macro that returns an error code indicating why an RPC call failed.

Format

void clnt_geterr (CLIENT *clnt, struct rpc_err *errp);

Arguments

clnt

Client handle returned by any of the client create routines.

errp

Address of the structure containing information that indicates why an RPC call failed. This information is the same as clnt_stat contains, plus one of the following: the C error number, the range of server versions supported, or authentication errors.

Description

This routine is primarily for internal diagnostic use.

Example

#define PROGRAM         1
#define VERSION         1

  CLIENT          *clnt;
  struct rpc_err  err;

  clnt = clnt_create( "server name", PROGRAM, VERSION, "udp");

  /* calls to RPC library */

  clnt_geterr( clnt, &err);

This example creates a UDP client handle and performs some additional RPC processing. If an RPC call fails, clnt_geterr returns the error code.

See Also

clnt_perror / c

clnt_pcreateerror / clnt_spcreateerror

Return a message indicating why RPC could not create a client handle.

Format

#include

void clnt_pcreateerror (char *s);
char *clnt_spcreateerror (char *s);

Argument

s

String containing the message of your choice. The routines append an error message to this string.

Description

The clnt_pcreateerror / c routine prints a message to SYS$OUTPUT.

The clnt_pcreateerror / c routine returns the address of a string. Use this routine if:

  You want to save the string.

  You do not want to use printf to print the message.

  The message format is different from the one that clnt_perrno / c supports.

The clnt_pcreateerror / c routine overwrites the string it returns, unless you save the results.

Use these routines when the clnt_create, clntraw_create, clnttcp_create, or clntudp_create / c routine fails.

See Also

clnt_create, clntraw_create, clnttcp_create, clntudp_create / c

clnt_perrno / clnt_sperrno

Return a message indicating why the callrpc or clnt_broadcast routine failed to create a client handle.

Format

#include

void clnt_perrno (enum clnt_stat stat);
char *clnt_sperrno (enum clnt_stat stat);

Argument

stat

Appropriate error condition. Values for stat are defined in the CLNT.H file.

Description

The clnt_perrno / c routine prints a message to SYS$OUTPUT.

The clnt_perrno / c routine returns the address of a string. Use this routine instead if:

  You want to save the string.

  You do not want to use printf to print the message.

  The message format is different from the one that clnt_perrno / c supports.

To save the string, copy it into your own memory space.

See Also

callrpc, clnt_broadcast

clnt_perror / clnt_sperror

Return a message if the clnt_call routine fails.

Format

#include

void clnt_perror (CLIENT *clnt, char *s);
char *clnt_sperror (CLIENT *clnt, char *s);

Arguments

clnt

See Common Arguments  for a description of the above argument. String containing the message to output.

Description

Use these routines after clnt_call.

The clnt_perror / c routine prints an error message to SYS$OUTPUT.

The clnt_perror / c routine returns a string. Use this routine if:

  You want to save the string.

  You do not want to use printf to print the message.

  The message format is different from the one that clnt_perror / c supports.

The clnt_perror / c routine overwrites the string with each call. Copy the string into your own memory space if you want to save it.

See Also

clnt_call, clnt_create, clntraw_create, clnttcp_create, clntudp_create / c

clntraw_create

Returns an RPC client handle. The remote procedure call uses the IP transport.

Format

#include

CLIENT *clntraw_create (struct sockaddr_in *addr,
u_long prognum, u_long versnum, int *sockp, u_long sendsize,
u_long recvsize);

Arguments

addr, prognum, versnum

See Common Arguments  for a description of the above arguments.

sockp

Socket to be used for this remote procedure call. sockp can specify the local address and port number. If sockp is RPC_ANYSOCK, then a port number is assigned. The example shown for the clntudp_create / c routine shows how to set up sockp to specify a port. See Common Arguments  for a description of sockp and RPC_ANYSOCK.

addr

Internet address of the host on which the server resides.

sendsize

Size of the send buffer. If you enter a value less than 100, then 4000 is used as the default.

recvsize

Size of the receive buffer. If you enter a value less than 100, then 4000 is used as the default.

Description

The clntraw_create routine creates an RPC client handle for addr, prognum, and versnum. The client uses the IP transport. The routine is similar to the clnt_create routine, except clnttcp_create allows you to specify a socket and buffer sizes. If you specify the port number as zero by using addr->sin_port, the Port Mapper provides the number of the port on which the remote program is listening.

The transport used to pass messages to the service is actually a buffer within the process's address space, so the corresponding RPC server should live in the same address space (see also svcraw_create). This allows simulation of RPC and getting RPC overheads, such as round trip times, without kernel interference.

The clnttcp_create routine uses the global variable rpc_createerr, which is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. The rpc_createerr variable is defined in the CLNT.H file.

Diagnostics

The clntraw_createroutine returns the address of the client handle, or zero (if it could not create the client handle). If the routine fails, use the clnt_pcreateerror / c routine to obtain additional diagnostic information.

See Also

clnt_call, clnt_control, clnt_create, clnt_destroy, clnt_pcreateerror / c, clnttcp_create, clntudp_create / c

clnttcp_create

Returns an RPC client handle. The remote procedure call uses the TCP transport.

Format

#include

CLIENT *clnttcp_create (struct sockaddr_in *addr,
u_long prognum, u_long versnum, int *sockp, u_long sendsize,
u_long recvsize);

Arguments

addr, prognum, versnum

See Common Arguments  for a description of the above arguments.

sockp

Socket to be used for this remote procedure call. sockp can specify the local address and port number. If sockp is RPC_ANYSOCK, then a port number is assigned. The example shown for the clntudp_create / c routine shows how to set up sockp to specify a port. See Common Arguments  for a description of sockp and RPC_ANYSOCK.

addr

Internet address of the host on which the server resides.

sendsize

Size of the send buffer. If you enter a value less than 100, then 4000 is used as the default.

recvsize

Size of the receive buffer. If you enter a value less than 100, then 4000 is used as the default.

Description

The clnttcp_create routine creates an RPC client handle for addr, prognum, and versnum. The client uses the TCP transport. The routine is similar to the clnt_create routine, except clnttcp_create allows you to specify a socket and buffer sizes. If you specify the port number as zero by using addr->sin_port, the Port Mapper provides the number of the port on which the remote program is listening.

The clnttcp_createroutine 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 client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. The rpc_createerr variable is defined in the CLNT.H file.

Diagnostics

The clnttcp_create routine returns the address of the client handle, or zero (if it could not create the client handle). If the routine fails, use the clnt_pcreateerror / c routine to obtain additional diagnostic information.

See Also

clnt_call, clnt_control, clnt_create, clnt_destroy, clnt_pcreateerror / c, clntudp_create / c

clntudp_create / clntudp_bufcreate

Returns an RPC client handle. The remote procedure call uses the UDP transport.

Format

#include

CLIENT *clntudp_create (struct sockaddr_in *addr,
u_long prognum, u_long versnum, struct timeval wait,
int *sockp);

CLIENT *clntudp_bufcreate (struct sockaddr_in *addr,
u_long prognum, u_long versnum, struct timeval wait,
int *sockp, u_long sendsize, u_long recvsize);

Arguments

addr

Internet address of the host on which the server resides.

prognum, versnum, sockp

See Common Arguments  for a description of the above arguments.

wait

Time interval the client waits before resending the call message. This value changes the CLSET_RETRY_TIMEOUT code. The clnt_call routine uses this value.

sendsize

Size of the send buffer. If you enter a value less than 100, then 4000 is used as the default.

recvsize

Size of the receive buffer. If you enter a value less than 100, then 4000 is used as the default.

Description

These routines create an RPC client handle for addr, prognum, and versnum. The client uses the UDP transport protocol.

If you specify the port number as zero by using addr->sin_port, the Port Mapper provides the number of the port on which the remote program is listening.

Note!     Use the clntudp_create / c routine only for procedures that handle messages shorter than 8K bytes. Use the clntudp_create / c routine for procedures that handle messages longer than 8K bytes.

The clntudp_create / c 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 client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed.

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

Example

main()
{
        int     sock;
        u_long  prog = PROGRAM, vers = VERSION;
        CLIENT  *clnt;
        struct sockaddr_in      local_addr, remote_addr;
        struct timeval  timeout = { 35, 0},
                        retry = { 5, 0};

        remote_addr.sin_family = AF_INET;
        remote_addr.sin_port = 0;  /* consult the remote port mapper */
        remote_addr.sin_addr.s_addr = 0x04030201; /* internet
         addr 1.2.3.4 */

        local_addr.sin_family = AF_INET;
        local_addr.sin_port = 12345;                /* use port 12345 */
        local_addr.sin_addr.s_addr = 0x05030201;    /* internet addr
                                                            1.2.3.5 */

        sock = socket( AF_INET, SOCK_DGRAM, 0);

 

        /* bind the socket to the local addr */
        bind( sock, &local_addr, sizeof( local_addr));

 

        /* create a client that uses the local IA and port given above */
        clnt = clntudp_create( &remote_addr, prog, vers, retry, &sock);

 

        /* use a connection timeout of 35 seconds, not the default */
        clnt_control( clnt, CLSET_TIMEOUT, &timeout);
        /*call the server here*/
}

This example defines a socket structure, binds the socket, and creates a UDP client handle.

Diagnostics

These routines return the address of the client handle, or zero (if they cannot create the client handle).

If these routines fail, you can obtain additional diagnostic information by using the clnt_pcreateerror / c routine.

See Also

clnt_call, clnt_control, clnt_create, clnt_destroy, clnt_pcreateerror / c, clnttcp_create