Compaq TCP/IP Services for OpenVMS
ONC RPC Programming


Previous Contents Index


clntraw_create

Creates a client handle for memory-based ONC RPC for simple testing and timing.

Format

#include <rpc/rpc.h>

CLIENT *clntraw_create(u_long prognum, u_long versnum);


Arguments

prognum

The program number associated with the remote program.

versnum

The version number associated with the remote program.

Description

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.

Return Values

CLIENT * A pointer to a client handle.
NULL Indicates failure.

clnttcp_create

Creates an ONC RPC client handle for a TCP/IP connection.

Format

#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);


Arguments

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 zero, the routine chooses a suitable default.

recvsize

The size of the receive buffer. If you specify zero, the routine chooses a suitable default.

Description

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.

Return Values

CLIENT * A pointer to the client handle.
NULL Indicates failure.

clntudp_bufcreate

Creates an ONC RPC client handle for a buffered I/O UDP connection.

Format

#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);


Arguments

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 zero, the routine chooses a suitable default.

recvsize

The size of the receive buffer. If you specify zero, the routine chooses a suitable default.

Description

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.

Return Values

CLIENT * A pointer to the client handle.
NULL Indicates failure.

clntudp_create

Creates an ONC RPC client handle for a nonbuffered I/O UDP connection.

Format

#include <rpc/rpc.h>

CLIENT *clntudp_create(struct sockaddr_in *addr, u_long prognum, u_long versnum, struct timeval wait, register int *sockp);


Arguments

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.

Description

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


Return Values

CLIENT * A pointer to the client handle.
NULL Indicates failure.

get_myaddress

Returns the local host's internet address.

Format

#include <rpc/rpc.h>

void get_myaddress(struct sockaddr_in *addr);


Arguments

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.

Description

Puts the local host's internet address into addr without doing any name translation. The port number is always set to htons (PMAPPORT) .

Return Values

None  

get_myaddr_dest

Returns the local host's internet address according to a destination address.

Format

#include <rpc/rpc.h>

void get_myaddr_dest(struct sockaddr_in *addr, struct sockaddr_in *dest);


Arguments

addr

A pointer to a sockaddr_in structure that the routine will load with the local internet address that 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.

Description

Since the local host may have multiple network addresses (each on its own interface), this routine is used to select the local address that 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.


Return Values

None  


Chapter 6
ONC RPC Portmapper Routines

This chapter describes the routines that allow C programs to access the Portmapper network service.

Table 6-1 describes the task that each routine performs.

Table 6-1 ONC RPC Portmapper Routines
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.


pmap_getmaps

Returns a copy of the current port mappings on a remote host.

Format

#include <rpc/pmap_clnt.h>

struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);


Arguments

addr

A pointer to a sockaddr_in structure containing the internet address of the host whose Portmapper you want to call.

Description

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 SHOW PORTMAPPER management command uses this routine.

Return Values

struct pmaplist * A pointer to the returned list of server-to-port mappings on host addr .
NULL Indicates failure.

pmap_getmaps_vms

Returns a copy of the current port mappings on a remote host running TCP/IP Services software.

Format

#include <rpc/pmap_clnt.h>

struct pmaplist_vms *pmap_getmaps_vms(struct sockaddr_in *addr);


Arguments

addr

A pointer to a sockaddr_in structure containing the internet address of the host whose Portmapper you wish to call.

Description

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 TCP/IP Services hosts.

Return Values

struct pmaplist * A pointer to the returned list of server-to-port mappings on host addr .
NULL Indicates failure.

pmap_getport

Returns the port number on which the specified service is waiting.

Format

#include <rpc/pmap_clnt.h>

u_short pmap_getport(struct sockaddr_in *addr, u_long prognum, u_long versnum, u_long protocol );


Arguments

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 .

Description

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.

The pmap_getport routine returns the port number in host byte order not network byte order. For certain routines you may need to convert this value to network byte order using the htons routine. For example, the sockaddr_in structure requires that the port number be in network byte order.


Return Values

x The port number of the service on the remote system.
0 No mapping exists or RPC could not contact the remote Portmapper service. In the latter case, the global variable rpc_createerr.cf_error contains the ONC RPC status.

pmap_rmtcall

The client interface to the Portmapper service for a remote call and broadcast service. This routine allows a program to do a lookup and call in one step.

Format

#include <rpc/pmap_clnt.h>

enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr, u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, char * in xdrproc_t outproc, char * out, struct timeval timeout, u_long *port );


Arguments

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.

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 timeval structure describing the time allowed for the results to return to the client.

port

A pointer to a location for the returned port number. Modified to the remote program's port number if the pmap_rmtcall routine succeeds.

Description

A client interface to the Portmapper, which instructs the Portmapper on the host at the internet address *addr to make a call on your behalf to a procedure on that host. Use this procedure for a ping operation and nothing else. You can use the clnt_perrno routine to print any error message.

Note

If the requested procedure is not registered with the remote Portmapper, the remote Portmapper does not reply to the request. The call to pmap_rmtcall will eventually time out. The pmap_rmtcall does not perform authentication.

Return Values

enum clnt_stat Returns the buffer containing the status of the operation.


Previous Next Contents Index