The clnt_create_vers 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 5 seconds.
The clnt_create_vers routine differs from the standard clnt_create routine in that it seeks out the highest version number supported by the server. If the server does not support any version numbers within the requested range, the routine returns NULL and the versnum variable is undefined.
The clnt_create_vers 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.
CLIENT* Client handle containing the server information. NULL Error occurred while creating the client handle. Usually the error indicates that the server does not support any version numbers within the requested range. Use the clnt_pcreateerror or clnt_spcreateerror routine to obtain diagnostic information.
A macro that frees the memory associated with an RPC client handle.
#include <rpc/rpc.h>
void clnt_destroy(CLIENT *handle);
handle
A pointer to a client handle created by any of the client handle creation routines.
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 the clnt_create routine had previously opened the socket associated with the client handle or the program had used the clnt_control routine to set CL_FD_CLOSE, this routine closes the socket. If the clnt_create routine had not previously opened the socket associated with the client handle or the program had used the clnt_control routine to set CL_FD_NCLOSE, this routine leaves the socket open.
None
A macro that frees the memory that was allocated when the remote procedure's results were decoded.
#include <rpc/rpc.h>
bool_t clnt_freeres(CLIENT *handle, xdrproc_t outproc, char *out);
handle
A pointer to a client handle created by any of the client handle creation routines.outproc
The XDR routine used to decode the remote procedure's results.out
A pointer to the remote procedure's results.
The clnt_freeres routine calls the xdr_free routine to deallocate the memory where the remote procedure's results are stored.
TRUE Success. FALSE Error occurred while freeing the memory.
A macro that returns error information indicating why an RPC call failed.
#include <rpc/rpc.h>
void clnt_geterr(CLIENT *handle, struct rpc_err *errp);
handle
A pointer to a client handle created by any of the client handle creation routines.errp
A pointer to an rpc_err structure containing information that indicates why an RPC call failed. This information is the same information as clnt_stat contains, plus one of the following: the C error number, the range of server versions supported, or authentication errors.
This macro copies the error information from the client handle to the structure referenced by errp. The macro is mainly for diagnostic use.
None
Prints a message explaining why ONC RPC could not create a client handle.
#include <rpc/rpc.h>
void clnt_pcreateerror(char *sp);
sp
A pointer to a string to be used as the beginning of the error message.
The clnt_pcreateerror routine prints a message to SYS$OUTPUT. The message consists of the sp parameter followed by an RPC-generated error message. Use this routine when the clnt_create, clnttcp_create, or clntudp_create routine fails.
None
Prints a message indicating why the callrpc or clnt_broadcast routine failed.
#include <rpc/rpc.h>
void clnt_perrno(enum clnt_stat stat)
;
stat
A buffer containing status information.
Prints a message to standard error corresponding to the condition indicated by the stat argument.The data type declaration for clnt_stat in rpc/rpc.h lists the standard errors.
None
Prints a message explaining why an ONC RPC routine failed.
#include <rpc/rpc.h>
void clnt_perror(CLIENT *handle, char *sp);
handle
A pointer to the client handle used in the call that failed.sp
A pointer to a string to be used as the beginning of the error message.
Prints a message to standard error indicating why an ONC RPC call failed. The message is prepended with string sp and a colon.
None
Returns a message indicating why RPC could not create a client handle.
#include <rpc/rpc.h>
char *clnt_spcreateerror(char *sp);
sp
A pointer to a string to be used as the beginning of the error message.
The clnt_spcreateerror routine returns the address of a message string. The message consists of the sp parameter followed by an error message generated by calling the clnt_sperrno routine. Use the clnt_spcreateerror routine when the clnt_create, clnttcp_create, or clntudp_create routine fails.Use this routine if:
- You want to save the string.
- You do not want to use fprintf to print the message.
- The message format is different from the one that clnt_perrno supports.
The address that clnt_spcreateerror returns is the address of its own internal string buffer. The clnt_spcreateerror routine overwrites this buffer with each call. Therefore, you must copy the string to your own buffer if you wish to save the string.
char* A pointer to the message string terminated with a NULL character. NULL The routine was not able to allocate its internal buffer.
Returns a message indicating why the callrpc or clnt_broadcast routine failed to create a client handle.
#include <rpc/rpc.h>
char *clnt_sperrno(enum clnt_stat stat);
stat
A buffer containing status information.
The clnt_sperrno routine returns a pointer to a string.Use this routine instead if:
- The server does not have a stderr file; many servers do not.
- You want to save the string.
- You do not want to use fprintf to print the message.
- The message format is different from the one that clnt_perrno supports.
The address that clnt_sperrno returns is a pointer to the error message string for the error. Therefore, you do not have to copy the string to your own buffer in order to save the string.
char* A pointer to the message string terminated with a NULL character.
Returns a message indicating why an ONC RPC routine failed.
#include <rpc/rpc.h>
char *clnt_sperror(CLIENT *handle, char *sp);
handle
A pointer to the client handle used in the call that failed.sp
A pointer to a string to be used as the beginning of the error message.
The clnt_sperror routine returns a pointer to a message string. The message consists of the sp parameter followed by an error message generated by calling the clnt_sperrno routine. Use this routine when the clnt_call routine fails.Use this routine if:
- You want to save the string.
- You do not want to use fprintf to print the message.
- The message format is different from the one that clnt_perrno supports.
The address that clnt_sperror returns is a pointer to its own internal string buffer. The clnt_sperror routine overwrites this buffer with each call. Therefore, you must copy the string to your own buffer if you wish to save the string.
char* A pointer to the message string terminated with a NULL character. NULL The routine was not able to allocate its internal buffer.
Creates a client handle for memory-based ONC RPC for simple testing and timing.
#include <rpc/rpc.h>
CLIENT *clntraw_create(u_long prognum, u_long versnum);
prognum
The program number associated with the remote program.versnum
The version number associated with the remote program.
Creates an in-program ONC RPC client for the remote program prognum, version versnum. The transport used to pass messages to the service is actually a buffer within the process's address space, so the corresponding server should live in the same address space; see svcraw_create. This allows simulation of and acquisition of ONC RPC overheads, such as round-trip times, without any kernel interference.
CLIENT* A pointer to a client handle. NULL Indicates failure.
Creates an ONC RPC client handle for a TCP/IP connection.
#include <rpc/rpc.h>
CLIENT *clnttcp_create(struct sockaddr_in *addr, u_long prognum, u_long versnum, int *sockp, u_int sendsize, u_int recvsize);
addr
A pointer to a buffer containing the internet address where the remote program is located.prognum
The program number associated with the remote procedure.versnum
The version number associated with the remote procedure.sockp
A pointer to the socket number to be used for the remote procedure call. If sockp is RPC_ANYSOCK, then this routine opens a new socket and sets sockp.sendsize
The size of the send buffer. If you specify 0 the routine chooses a suitable default.recvsize
The size of the receive buffer. If you specify 0 the routine chooses a suitable default.
Creates an ONC RPC client handle for the remote program prognum, version versnum at address addr. The client uses TCP/IP as a transport. The routine is similar to the clnt_create routine, except clnttcp_create allows you to specify a socket and the send and receive buffer sizes.If you specify the port number as zero by using addr->sin_port, the Portmapper provides the number of the port on which the remote program is listening.
The clnttcp_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.
The socket referenced by sockp is copied into a private area for RPC to use. It is the client's responsibility to close the socket referenced by sockp.
The authentication scheme for the client, client->cl_auth, gets set to null authentication. The calling program can set this to something different if necessary.
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* A pointer to the client handle. NULL Indicates failure.
Creates an ONC RPC client handle for a buffered I/O UDP connection.
#include <rpc/rpc.h>
CLIENT *clntudp_bufcreate(struct sockaddr_in *addr, u_long prognum, u_long versnum, struct timeval wait, register int *sockp, u_int sendsize, u_int recvsize);
addr
A pointer to a buffer containing the internet address where the remote program is located.prognum
The program number associated with the remote procedure.versnum
The version number associated with the remote procedure.wait
The amount of time used between call retransmission if no response is received. Retransmission occurs until the ONC RPC calls time out.sockp
A pointer to the socket number to be used for the remote procedure call. If sockp is RPC_ANYSOCK, then this routine opens a new socket and sets sockp.sendsize
The size of the send buffer. If you specify 0, the routine chooses a suitable default.recvsize
The size of the receive buffer. If you specify 0, the routine chooses a suitable default.
Creates an ONC RPC client handle for the remote program prognum, version versnum at address addr. The client uses UDP as the transport. The routine is similar to the clnt_create routine, except clntudp_bufcreate allows you to specify a socket, the UDP retransmission time, and the send and receive buffer sizes.If you specify the port number as zero by using addr->sin_port, the Portmapper provides the number of the port on which the remote program is listening.
The clntudp_bufcreate 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.
The socket referenced by sockp is copied into a private area for RPC to use. It is the client's responsibility to close the socket referenced by sockp.
The authentication scheme for the client, client->cl_auth, gets set to null authentication. The calling program can set this to something different if necessary.
Note
If addr->sin_port is 0 and 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* A pointer to the client handle. NULL Indicates failure.
Creates an ONC RPC client handle for a non-buffered I/O UDP connection.
#include <rpc/rpc.h>
CLIENT *clntudp_create(struct sockaddr_in *addr, u_long prognum, u_long versnum, struct timeval wait, register int *sockp);
addr
A pointer to a buffer containing the internet address where the remote program is located.prognum
The program number associated with the remote procedure.versnum
The version number associated with the remote procedure.wait
The amount of time used between call retransmission if no response is received. Retransmission occurs until the ONC RPC calls time out.sockp
A pointer to the socket number to be used for the remote procedure call. If sockp is RPC_ANYSOCK, then this routine opens a new socket and sets sockp.
Creates an ONC RPC client handle for the remote program prognum, version versnum at address addr. The client uses UDP as the transport. The routine is similar to the clnt_create routine, except clntudp_create allows you to specify a socket and the UDP retransmission time.If you specify the port number as zero by using addr->sin_port, the Portmapper provides the number of the port on which the remote program is listening.
The clntudp_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.
The socket referenced by sockp is copied into a private area for RPC to use. It is the client's responsibility to close the socket referenced by sockp.
The authentication scheme for the client, client->cl_auth, gets set to null authentication. The calling program can set this to something different if necessary.
Notes
Since UDP/IP messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take large arguments or return huge results.If addr->sin_port is 0 and 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* A pointer to the client handle. NULL Indicates failure.
Returns the local host's internet address.
#include <rpc/rpc.h>
void get_myaddress(struct sockaddr_in *addr);
addr
A pointer to a sockaddr_in structure that the routine will load with the internet address of the host where the local procedure resides.
Puts the local host's internet address into addr without doing any name translation. The port number is always set to htons (PMAPPORT).
None
Returns the local host's internet address according to a destination address.
#include <rpc/rpc.h>
void get_myaddr_dest(struct sockaddr_in *addr, struct sockaddr_in *dest);
addr
A pointer to a sockaddr_in structure that the routine will load with the local internet address which would provide a connection to the remote address specified in dest.dest
A pointer to a sockaddr_in structure containing an internet address of a remote host.
Since the local host may have multiple network addresses (each on its own interface), this routine is used to select the local address which would provide a connection to the remote address specified in dest.This is an alternative to gethostbyname, which invokes yellow pages. It takes a destination (where we are trying to get to) and finds an exact network match to go to.
None
This chapter describes the routines that allow C programs to access the Portmapper network service.
Table 6-1 indicates the task that each routine performs.
| Routine | Task Category |
|---|---|
| pmap_getmaps | Returns a list of port mappings for the specified remote host. |
| pmap_getmaps_vms | Returns a list of port mappings (including OpenVMS process IDs) for the specified remote host. |
| pmap_getport | Returns the port number on which the specified service is waiting. |
| pmap_rmtcall | Requests the Portmapper on the specified remote host to call the specified procedure on that host. |
| pmap_set | Registers a remote server procedure with the host's Portmapper. |
| pmap_unset | Unregisters a remote server procedure with the host's Portmapper. |
Returns a copy of the current port mappings on a remote host.
#include <rpc/pmap_clnt.h>
struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);
addr
A pointer to a sockaddr_in structure containing the internet address of the host whose Portmapper you wish to call.
A client interface to the Portmapper, which returns a list of the current ONC RPC program-to-port mappings on the host located at the internet address addr. The UCX SHOW PORTMAPPER command uses this routine.
struct pmaplist* A pointer to the returned list of server-to-port mappings on host addr. NULL Indicates failure.
Returns a copy of the current port mappings on a remote UCX host.
#include <rpc/pmap_clnt.h>
struct pmaplist_vms *pmap_getmaps_vms(struct sockaddr_in *addr);
addr
A pointer to a sockaddr_in structure containing the internet address of the UCX host whose Portmapper you wish to call.
This routine is similar to the pmap_getmaps routine. However, pmap_getmaps_vms also returns the process identifiers (PIDs) that are required for mapping requests to UCX hosts.
struct pmaplist* A pointer to the returned list of server-to-port mappings on host addr. NULL Indicates failure.
Returns the port number on which the specified service is waiting.
#include <rpc/pmap_clnt.h>
u_short pmap_getport(struct sockaddr_in *addr, u_long prognum, u_long versnum, u_long protocol );
addr
A pointer to a sockaddr_in structure containing the internet address of the host where the remote Portmapper resides.prognum
The program number associated with the remote procedure.versnum
The version number associated with the remote procedure.protocol
The transport protocol that the remote procedure uses. Specify either IPPROTO_UDP or IPPROTO_TCP.
A client interface to the Portmapper. This routine returns the port number on which waits a server that supports program number prognum, version versnum, and speaks the transport protocol associated with protocol (IPPROTO_UDP or IPPROTO_TCP).
Notes
If the requested version is not available, but at least the requested program is registered, the routine returns a port number.
Previous | Next | Contents