Compaq TCP/IP Services for OpenVMS
ONC RPC Programming


Previous Contents Index


svc_unregister

Calls the Portmapper to unregister the specified program and version for all protocols. The program and version are removed from the list of active servers.

Format

#include <rpc/rpc.h>

void svc_unregister(u_long prognum, u_long versnum);


Arguments

prognum

The program number associated with the server procedure.

versnum

The version number associated with the server procedure.

Description

Removes all mapping of the double [prognum, versnum] to dispatch routines, and of the triple [prognum, versnum, *] to port number.

Return Values

None  

svcerr_auth

Sends an authentication error to the client.

Format

#include <rpc/rpc.h>

void svcerr_auth(SVCXPRT *xprt, enum auth_stat why);


Arguments

xprt

A pointer to an RPC server handle created by any of the server-handle creation routines.

why

The reason for the authentication error.

Description

Called by a service dispatch routine that refuses to perform a remote procedure call because of an authentication error.

Return Values

None  

svcerr_decode

Sends an error code to the client indicating that the server procedure cannot decode the client's arguments.

Format

#include <rpc/rpc.h>

void svcerr_decode(SVCXPRT *xprt);


Arguments

xprt

A pointer to an RPC server handle created by any of the server-handle creation routines.

Description

Called by a service dispatch routine that cannot successfully decode its parameters. See also the svc_getargs routine.

Return Values

None  

svcerr_noproc

Sends an error code to the client indicating that the server program does not implement the requested procedure.

Format

#include <rpc/rpc.h>

void svcerr_noproc(SVCXPRT *xprt);


Arguments

xprt

A pointer to an RPC server handle created by any of the server-handle creation routines.

Description

Called by a service dispatch routine that does not implement the procedure number that the client requested.

Return Values

None  

svcerr_noprog

Sends an error code to the client indicating that the server program is not registered with the Portmapper.

Format

#include <rpc/rpc.h>

void svcerr_noprog(SVCXPRT *xprt);


Arguments

xprt

A pointer to an RPC server handle created by any of the server-handle creation routines.

Description

Called when the desired program is not registered with the ONC RPC package. Generally, the Portmapper informs the client when a server is not registered. Therefore, service implementors usually do not use this routine.

Return Values

None  

svcerr_progvers

Sends an error code to the client indicating that the requested program is registered with the Portmapper but the requested version of the program is not registered.

Format

#include <rpc/rpc.h>

void svcerr_progvers(SVCXPRT *xprt, u_long low_vers, u_long high_vers);


Arguments

xprt

A pointer to an RPC server handle created by any of the server-handle creation routines.

low_vers

The lowest version of the requested program that the server supports.

high_vers

The highest version of the requested program that the server supports.

Description

Called when the desired version of a program is not registered with the ONC RPC package. Generally, the Portmapper informs the client when a requested program version is not registered. Therefore, service implementors usually do not use this routine.

Return Values

None  

svcerr_systemerr

Sends an error code to the client indicating that an error occurred that is not handled by the protocol being used.

Format

#include <rpc/rpc.h>

void svcerr_systemerr(SVCXPRT *xprt);


Arguments

xprt

A pointer to an RPC server handle created by any of the server-handle creation routines.

Description

Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine.

Return Values

None  

svcerr_weakauth

Sends an error code to the client indicating that an authentication error occurred. The authentication information was correct but was insufficient.

Format

#include <rpc/rpc.h>

void svcerr_weakauth(SVCXPRT *xprt);


Arguments

xprt

A pointer to an RPC server handle created by any of the server-handle creation routines.

Description

Called by a service dispatch routine that refuses to perform a remote procedure call because of insufficient (but correct) authentication parameters. The routine calls svcerr_auth (xprt, AUTH_TOOWEAK) .

Return Values

None  

svcraw_create

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

Format

#include <rpc/rpc.h>

SVCXPRT *svcraw_create();


Arguments

None


Description

Creates a in-program ONC RPC service transport, to which it returns a pointer. The transport is really a buffer within the process's address space, so the corresponding client should live in the same address space; see the clntraw_create routine. The svcraw_create and clntraw_create routines allow simulation and acquisition of ONC RPC overheads (such as round-trip times), without any kernel interference.

Return Values

SVCXPRT * A pointer to an RPC server handle for the in-memory transport.
NULL Indicates failure.

svcfd_create

Creates an RPC server handle using the specified open file descriptor.

Format

#include <rpc/rpc.h>

SVCXPRT *svcfd_create(int fd, u_int sendsize, u_int recvsize);


Arguments

fd

The number of an open file descriptor.

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 RPC server handle using the specified TCP socket, to which it returns a pointer. The server should call the svcfd_create routine after it accepts an incoming TCP connection.

Return Values

SVCXPRT * A pointer to the server handle.
NULL Indicates failure.

svctcp_create

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

Format

#include <rpc/rpc.h>

SVCXPRT *svctcp_create(int sock, u_int sendsize, u_int recvsize);


Arguments

sock

The socket with which the connection is associated. If sock is RPC_ANYSOCK , then this routine opens a new socket and sets sock. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port.

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 RPC server handle using the TCP/IP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls).

Return Values

SVCXPRT * A pointer to the server handle.
NULL Indicates failure.

svcudp_bufcreate

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

Format

#include <rpc/rpc.h>

SVCXPRT *svcudp_bufcreate(int sock, u_int sendsize, u_int recvsize);


Arguments

sock

The socket with which the connection is associated. If sock is RPC_ANYSOCK , then this routine opens a new socket and sets sock.

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 RPC server handle using the UDP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls).

Return Values

SVCXPRT * A pointer to the server handle.
NULL Indicates failure.

svcudp_create

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

Format

#include <rpc/rpc.h>

SVCXPRT *svcudp_create(int sock);


Arguments

sock

The socket with which the connection is associated. If sock is RPC_ANYSOCK , then this routine opens a new socket and sets sock.

Description

Creates an RPC server handle using the UDP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls).

Note

Since UDP/IP-based ONC RPC 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.

Return Values

SVCXPRT * A pointer to the server handle.
NULL Indicates failure.

xprt_register

Adds a socket associated with an RPC server handle to the list of registered sockets.

Format

#include <rpc/rpc.h>

void xprt_register(SVCXPRT *xprt);


Arguments

xprt

A pointer to an RPC server handle created by any of the server-handle creation routines.

Description

Activation of a transport handle involves setting the most appropriate bit for the socket associated with xprt in the svc_fds mask. When svc_run () is invoked, activity on the transport handle is eligible to be processed by the server.

The svc_register routine calls this routine; therefore, you are unlikely to use this routine directly.


Return Values

None  

xprt_unregister

Removes a socket associated with an RPC server handle from the list of registered sockets.

Format

#include <rpc/rpc.h>

void xprt_unregister(SVCXPRT *xprt);


Arguments

xprt

A pointer to an RPC server handle created by any of the server-handle creation routines.

Description

Removes the socket associated with the indicated handle from the list of registered sockets maintained in the svc_fdset variable. Activity on the socket associated with xprt will no longer be checked by the svc_run routine.

The svc_unregister routine calls this routine; therefore, you are unlikely to use this routine directly.


Return Values

None  

_authenticate

Authenticates the request message.

Format

#include <rpc/rpc.h>

enum auth_stat _authenticate(struct svc_req *rqst, struct rpc_msg *msg);


Arguments

rqst

A pointer to an svc_req structure with the requested program number, procedure number, version number, and credentials passed by the client.

msg

A pointer to an rpc_msg structure with members that make up the RPC message.

Description

Returns AUTH_OK if the message is authenticated successfully. If it returns AUTH_OK , the routine also does the following:

The expression rqst->rq_xprt->verf must be preallocated and its length must be set appropriately.

The program still owns and is responsible for msg->u.cmb.cred and msg->u.cmb.verf . The authentication system retains ownership of rqst->rq_client_cred , the "cooked" credentials.


Return Values

enum auth_stat The return status code for the authentication checks:
AUTH_OK=0---Authentication checks successful.
AUTH_BADCRED=1---Invalid credentials (seal broken)
AUTH_REJECTEDCRED=2---Client should begin new session
AUTH_BADVERF=3---Invalid verifier (seal broken)
AUTH_REJECTEDVERF=4---Verifier expired or was replayed
AUTH_TOOWEAK=5---Rejected for security reasons
AUTH_INVALIDRESP=6---Invalid response verifier
AUTH_FAILED=7---Some unknown reason


Previous Next Contents Index