| Previous | Contents | Index |
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.
| Routine | Task Category |
|---|---|
| auth_destroy | Destroys authentication information associated with an authentication handle (macro). |
| authnone_create | Creates and returns a null authentication handle for the client process. |
| authunix_create | Creates and returns a UNIX-style authentication handle for the client process. |
| authunix_create_default | Creates and returns a UNIX-style authentication handle containing default authentication information for the client process. |
| callrpc | Calls the remote procedure identified by the routine's arguments. |
| clnt_broadcast | Broadcasts a remote procedure call to all locally connected networks using the broadcast address. |
| clnt_call | Calls a remote procedure (macro). |
| clnt_control | Changes or retrieves information about an RPC client process (macro). |
| clnt_create | Creates an RPC client handle for a remote server procedure. |
| clnt_create_vers | Creates an RPC client handle for a remote server procedure having the highest supported version number within a specified range. |
| clnt_destroy | Destroys a client handle (macro). |
| clnt_freeres | Frees the memory that RPC allocated when it decoded a remote procedure's results (macro). |
| clnt_geterr | Returns an error code indicating why an RPC call failed (macro). |
| clnt_pcreateerror | Prints an error message indicating why RPC could not create a client handle. |
| clnt_perrno | Prints an error message indicating why a callrpc or clnt_broadcast routine failed. |
| clnt_perror | Prints an error message indicating why a clnt_call routine failed. |
| clnt_spcreateerror | Returns a message string indicating why RPC could not create a client handle. |
| clnt_sperrno | Returns a message string indicating why a callrpc or clnt_broadcast routine failed. |
| clnt_sperror | Returns a message string indicating why a clnt_call routine failed. |
| clntraw_create | Creates an RPC client handle for a server procedure included in the same program as the client. |
| clnttcp_create | Creates an RPC client handle for a remote server procedure using the TCP transport. |
| clntudp_bufcreate | Creates an RPC client handle for a remote server procedure using a buffered UDP transport. |
| clntudp_create | Creates an RPC client handle for a remote server procedure using the UDP transport. |
| get_myaddress | Returns the local host's internet address. |
| get_myaddr_dest | Returns the local host's internet address as seen by the remote host. |
A macro that frees the memory associated with the authentication handle created by the authnone_create and authunix_create routines.
#include <rpc/rpc.h>void auth_destroy(AUTH *auth_handle)
auth_handle
An RPC authentication handle created by the authnone_create , authunix_create , or authunix_create_default routine.
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.
None
Creates an authentication handle for passing null credentials and verifiers to remote systems.
#include <rpc/rpc.h>AUTH *authnone_create ( )
None
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.
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.
#include <rpc/rpc.h>AUTH *authunix_create(char *host, int uid, int gid, int len, int *aup_gids );
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.
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.
AUTH * Authentication handle containing the pertinent information. NULL Indicates allocation of AUTH handle failed.
Returns a default authentication handle.
#include <rpc/rpc.h>AUTH *authunix_create_default( )
None
Calls the authunix_create routine with the local host name, effective process ID and group ID, and the process default groups.
AUTH * Authentication handle containing the pertinent information. NULL Indicates allocation of AUTH handle failed.
| #1 |
|---|
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.
#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);
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.
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.
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.
#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);
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.
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.
RPC_SUCCESS Indicates success. clnt_stat Returns the buffer of type enum clnt_stat containing the status of the clnt_broadcast operation.
| Previous | Next | Contents | Index |