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.
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
|
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. |
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 |
|
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
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
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
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 .
|
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
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
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.
|
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
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
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 .
|
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
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
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
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
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
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
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