| Previous | Contents | Index |
This chapter describes the client routines that allow C programs to make procedure calls to server programs across the network.
Table 5-1 indicates the task that the 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 a 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.
A macro that calls a remote procedure.
#include <rpc/rpc.h>
enum clnt_stat clnt_call(CLIENT *handle, u_long procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char *out, struct timeval timeout);
handle
A pointer to a client handle created by any of the client handle creation routines.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.timeout
A structure describing the time allowed for results to return to the client. If you have previously used the clnt_control macro with the CLSET_TIMEOUT code, this value is ignored.
Use the clnt_call macro after using one of the client handle creation routines. After you are finished with the handle, return it using the clnt_destroy macro. Use the clnt_perror to print any errors that occurred.
RPC_SUCCESS Indicates success. clnt_stat Returns the buffer of type enum clnt_stat containing the status of the clnt_call operation.
A macro that changes or retrieves information about an RPC client process.
#include <rpc/rpc.h>
bool_t clnt_control(CLIENT *handle, u_int code, char *info);
handle
A pointer to a client handle created by any of the client handle creation routines.code
A code designating the type of information to be set or retrieved.info
A pointer to a buffer containing the information for a SET operation or the results of a GET operation.
For UDP and TCP transports specify any of the following for code:If you set the timeout using clnt_control, ONC RPC ignores the timeout parameter in all future clnt_call calls. The default total timeout is 25 seconds.
CLSET_TIMEOUT struct timeval Set total timeout CLGET_TIMEOUT struct timeval Get total timeout CLGET_SERVER_ADDR struct sockaddr_in Get server address CLGET_FD int Get associated socket CL_FD_CLOSE void Close socket on clnt_destroy CL_FD_NCLOSE void Leave socket open on clnt_destroy For the UDP transport two additional options are available:
CLSET_RETRY_TIMEOUT struct timeval Set retry timeout CLGET_RETRY_TIMEOUT struct timeval Get retry timeout The timeout value in these two calls is the time that UDP waits for a response before retransmitting the message to the server. The default time is 5 seconds. The retry timeout controls when UDP retransmits the request, the total timeout controls the total time that the client should wait for a response. For example, with the default settings, UDP will retry the transmission four times at 5-second intervals.
TRUE Success FALSE Failure
Creates a client handle and returns its address.
#include <rpc/rpc.h>
CLIENT *clnt_create(char *host, u_long prognum, u_long versnum, char *protocol);
host
A pointer to the name of the remote host.prognum
The program number associated with the remote procedure.versnum
The version number associated with the remote procedure.protocol
A pointer to a string containing the name of the protocol for transmitting and receiving RPC messages. Specify either tcp or udp.
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 Portmapper. 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
- A non-null authentication
- More than one active client at the same time
You can also use the clnttcp_create routine to use the TCP protocol, or the clntudp_create routine 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_createerrif 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.
Note
If the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_create_vers routine if you want to avoid this condition.
CLIENT * Client handle containing the server information. NULL Error occurred while creating the client handle. Use the clnt_pcreateerror or clnt_spcreateerror routine to obtain diagnostic information.
| Previous | Next | Contents | Index |