HP OpenVMS Systems Documentation

HP TCP/IP Services for OpenVMS
ONC RPC Programming

This section describes advanced techniques for passing data structures, such as linked lists (of arbitrary length). The examples in this section are written using both the XDR C library routines and the XDR data description language.

The last example in Section 4.1.2 presents a C data structure and its associated XDR routines for an individual's gross assets and liabilities. The example is duplicated here:

struct gnumbers {
     long g_assets;
     long g_liabilities;
};

bool_t
xdr_gnumbers(xdrs, gp)
     XDR *xdrs;
     struct gnumbers *gp;
{
     if (xdr_long(xdrs, &(gp->g_assets)))
          return(xdr_long(xdrs, &(gp->g_liabilities)));
     return(FALSE);
}

If you want to implement a linked list of such information, you could construct the following data structure:

struct gnumbers_node {
     struct gnumbers gn_numbers;
     struct gnumbers_node *gn_next;
};

typedef struct gnumbers_node *gnumbers_list;

You can think of the head of the linked list as the data object; that is, the head is not merely a convenient shorthand for a structure. Similarly the gn_next field indicates whether the object has terminated. Unfortunately, if the object continues, the gn_next field is also the address of where it continues. The link addresses carry no useful information when the object is serialized.

The XDR data description of this linked list is described by the recursive declaration of gnumbers_list :

struct gnumbers {
     int g_assets;
     int g_liabilities;
};
struct gnumbers_node {
     gnumbers gn_numbers;
     gnumbers_node *gn_next;
};

Here, the boolean indicates whether there is more data following it. If the boolean is FALSE, then it is the last data field of the structure; if TRUE, then it is followed by a gnumbers structure and (recursively) by a gnumbers_list . Note that the C declaration has no boolean explicitly declared in it (though the gn_next field implicitly carries the information), while the XDR data description has no pointer explicitly declared in it. From the XDR description in the previous paragraph, you can determine how to write the XDR routines for a gnumbers_list . That is, the xdr_pointer primitive would implement the XDR union. Unfortunately, because of recursion, using XDR on a list with the following routines causes the C stack to grow linearly with respect to the number of nodes in the list:

bool_t
xdr_gnumbers_node(xdrs, gn)
     XDR *xdrs;
     gnumbers_node *gn;
{
     return(xdr_gnumbers(xdrs, &gn->gn_numbers) &&
     xdr_gnumbers_list(xdrs, &gp->gn_next));
}

bool_t
xdr_gnumbers_list(xdrs, gnp)
     XDR *xdrs;
     gnumbers_list *gnp;
{
     return(xdr_pointer(xdrs, gnp,
     sizeof(struct gnumbers_node),
     xdr_gnumbers_node));
}

The following routine combines these two mutually recursive routines into a single, nonrecursive one:

bool_t
xdr_gnumbers_list(xdrs, gnp)
     XDR *xdrs;
     gnumbers_list *gnp;
{
     bool_t more_data;
     gnumbers_list *nextp;

     for (;;) {
          more_data = (*gnp != NULL);
          if (!xdr_bool(xdrs, &more_data)) {
               return(FALSE);
          }
          if (! more_data) {
               break;
          }
          if (xdrs->x_op == XDR_FREE) {
               nextp = &(*gnp)->gn_next;
          }
          if (!xdr_reference(xdrs, gnp,
            sizeof(struct gnumbers_node), xdr_gnumbers)) {

              return(FALSE);
          }
          gnp = (xdrs->x_op == XDR_FREE) ?
          nextp : &(*gnp)->gn_next;
     }
     *gnp = NULL;
     return(TRUE);
}

The first task is to find out if there is more data, so the boolean information can be serialized. Notice that this is unnecessary in the XDR_DECODE case, because the value of more_data is not known until it is deserialized in the next statement, which uses XDR on the more_data field of the XDR union. If there is no more data, this last pointer is set to NULL to indicate the list end, and a TRUE is returned to indicate completion. Setting the pointer to NULL is only important in the XDR_DECODE case, since it is already NULL in the XDR_ENCODE and XDR_FREE cases.

Next, if the direction is XDR_FREE , the value of nextp is set to indicate the location of the next pointer in the list. This is for dereferencing gnp to find the location of the next item in the list; after the next statement, the storage pointed to by gnp is deallocated and is no longer valid. This cannot be done for all directions because, in the XDR_DECODE direction, the value of gnp is not set until the next statement.

Next, XDR operates on the data in the node through the primitive xdr_reference , which is like xdr_pointer (which was used before). However, xdr_reference does not send over the boolean indicating whether there is more data; it is used instead of xdr_pointer because XDR has already been used on this information. Notice that the XDR routine passed is not the same type as an element in the list. The routine passed is xdr_gnumbers , for using XDR on gnumbers ; however, each element in the list is of type gnumbers_node . The xdr_gnumbers_node is not passed because it is recursive; instead, use xdr_gnumbers , which uses XDR on all of the nonrecursive parts. Note that this works only if the gn_numbers field is the first item in each element, so the addresses are identical when passed to xdr_reference .

Finally, gnp is updated to point to the next item in the list. If the direction is XDR_FREE , it is set to the previously saved value; otherwise, gnp is dereferenced to get the proper value. Although more difficult to understand than the recursive version, the nonrecursive routine is much less likely to overflow the C stack. It also runs more efficiently because a lot of procedure call overhead has been removed. However, most lists are small (in the hundreds of items or less), and the recursive version should be sufficient for them.

This chapter describes the client routines that allow C programs to make procedure calls to server programs across the network.

Table 5-1 describes the task that each client routine performs.

A macro that frees the memory associated with the authentication handle created by the authnone_create and authunix_create routines.

Format

#include <rpc/rpc.h>

void auth_destroy(AUTH *auth_handle)

Arguments

auth_handle

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

Description

Frees the memory associated with the AUTH data structure created by the authnone_create , authunix_create , or authunix_create_default routine. Be careful not to reference the data structure after calling this routine.

Return Values

None

Creates an authentication handle for passing null credentials and verifiers to remote systems.

Format

#include <rpc/rpc.h>

AUTH *authnone_create ( )

Arguments

None

Description

Creates and returns an authentication handle that passes null authentication information with each remote procedure call. Use this routine if the server process does not require authentication information. RPC uses this routine as the default authentication routine unless you create another authentication handle using either the authunix_create or authunix_create_default routine.

Return Values

AUTH *	Authentication handle containing the pertinent information.
NULL	Indicates allocation of AUTH handle failed.

Creates and returns an RPC authentication handle that contains UNIX-style authentication information.

Format

#include <rpc/rpc.h>

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

Arguments

host

Pointer to the name of the host on which the information was created. This is usually the name of the system running the client process.

uid

The user's user identification.

gid

The user's current group.

len

The number of elements in aup_gids array.

Note This parameter is ignored by the product's RPC implementation.

aup_gids

A pointer to an array of groups to which the user belongs.

Note This parameter is ignored by the product's RPC implementation.

Description

Implements UNIX-style authentication parameters. The client uses no encryption for its credentials and only sends null verifiers. The server sends back null verifiers or, optionally, a verifier that suggests a new shorthand for the credentials.

Return Values

AUTH *	Authentication handle containing the pertinent information.
NULL	Indicates allocation of AUTH handle failed.

Returns a default authentication handle.

Format

#include <rpc/rpc.h>

AUTH *authunix_create_default( )

Arguments

None

Description

Calls the authunix_create routine with the local host name, effective process ID and group ID, and the process default groups.

Return Values

AUTH *	Authentication handle containing the pertinent information.
NULL	Indicates allocation of AUTH handle failed.

Examples

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

This example overrides the default authnone_create action. The client handle, client , is returned by the clnt_create , clnt_create_vers , clnttcp_create , or clntudp_create routine.

Executes a remote procedure call.

Format

#include <rpc/rpc.h>

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

Arguments

host

A pointer to the name of the host on which the remote procedure resides.

prognum

The program number associated with the remote procedure.

versnum

The version number associated with the remote procedure.

procnum

The procedure number associated with the remote procedure.

inproc

The XDR routine used to encode the remote procedure's arguments.

in

A pointer to the remote procedure's arguments.

outproc

The XDR routine used to decode the remote procedure's results.

out

A pointer to the remote procedure's results.

Description

Calls the remote procedure associated with prognum , versnum, and procnum on the host host . This routine performs the same functions as a set of calls to the clnt_create , clnt_call , and clnt_destroy routines. This routine returns RPC_SUCCESS if it succeeds, or the value of enum clnt_stat cast to an integer if it fails. The routine clnt_perrno is handy for translating a failure status into a message.

Note Calling remote procedures with this routine uses UDP/IP as a transport; see clntudp_create for restrictions. You do not have control of timeouts or authentication using this routine. If you want to use the TCP transport, use the clnt_create or clnttcp_create routine.

Return Values

RPC_SUCCESS	Indicates success.
clnt_stat	Returns a value of type enum clnt_stat cast to type int containing the status of the callrpc operation.

Executes a remote procedure call that is sent to all locally connected networks using the broadcast address.

Format

#include <rpc/rpc.h>

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

Arguments

prognum

The program number associated with the remote procedure.

versnum

The version number associated with the remote procedure.

procnum

The procedure number associated with the remote procedure.

inproc

The XDR routine used to encode the remote procedure's arguments.

in

A pointer to the remote procedure's arguments.

outproc

The XDR routine used to decode the remote procedure's results.

out

A pointer to the remote procedure's results.

eachresult

Called each time the routine receives a response. Specify the routine as follows:

int eachresult(char *resultsp, struct sockaddr_in *addr)

resultsp is the same as the parameter passed to clnt_broadcast() , except that the remote procedure's output is decoded there. addr is a pointer to a sockaddr_in structure containing the address of the host that sent the results.

If eachresult is NULL , the clnt_broadcast routine returns without waiting for any replies.

Description

Performs the same function as the callrpc routine, except that the call message is sent to all locally connected networks using the broadcast address. Each time it receives a response, this routine calls the eachresult routine. If eachresult returns zero, clnt_broadcast waits for more replies; otherwise it assumes success and returns RPC_SUCCESS .

Note This routine uses the UDP protocol. Broadcast sockets are limited in size to the maximum transfer unit of the data link. For Ethernet, this value is 1400 bytes. For FDDI, this value is 4500 bytes.

Return Values

RPC_SUCCESS	Indicates success.
clnt_stat	Returns the buffer of type enum clnt_stat containing the status of the clnt_broadcast operation.