Compaq TCP/IP Services for OpenVMS
ONC RPC Programming


Previous Contents Index


pmap_set

Called by the server procedure to have the Portmapper create a mapping of the procedure's program and version number.

Format

#include <rpc/pmap_clnt.h>

bool_t pmap_set(u_long prognum, u_long versnum, u_long protocol, u_short port);


Arguments

prognum

The program number associated with the server procedure.

versnum

The version number associated with the server procedure.

protocol

The transport protocol that the server procedure uses. Specify either IPPROTO_UDP or IPPROTO_TCP .

port

The port number associated with the server program.

Description

A server interface to the Portmapper, which establishes a mapping between the triple [prognum,versnum,protocol] and port on the server's Portmapper service. The svc_register routine calls this routine to register the server with the local Portmapper.

Return Values

TRUE Indicates success.
FALSE Indicates failure.

pmap_unset

Called by the server procedure to have the Portmapper delete a mapping of the procedure's program and version number.

Format

#include <rpc/pmap_clnt.h>

bool_t pmap_unset(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

A server interface to the Portmapper, which destroys all mapping between the triple [prognum, versnum, *] and ports on the local host's Portmapper.

Return Values

TRUE Indicates success.
FALSE Indicates failure.


Chapter 7
ONC RPC Server Routines

This chapter describes the server routines that allow C programs to receive procedure calls from client programs over the network.

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

Table 7-1 ONC RPC SERVER Routines
Routine Task Category
registerrpc Creates a server handle and registers the server program with the Portmapper.
seterr_reply Fills in the error field in an RPC reply message with the specified error information.
svc_destroy Destroys a server handle (macro).
svc_freeargs Frees the memory allocated when RPC decoded the server procedure's arguments (macro).
svc_getargs Decodes the server procedure's arguments (macro).
svc_getcaller Returns the address of the client that called the server procedure (macro).
svc_getreqset Reads data for each server connection.
svc_register Registers the server program with the Portmapper.
svc_run Waits for incoming RPC requests and dispatches to the appropriate service routine.
svc_sendreply Sends the results of an RPC request to the client.
svc_unregister Unregisters the server program with the Portmapper.
svcerr_auth Sends an error message to the client indicating that the authentication information was not correctly formatted.
svcerr_decode Sends an error message to the client indicating that the server could not decode the arguments.
svcerr_noproc Sends an error message to the client indicating that the server does not implement the desired procedure.
svcerr_noprog Sends an error message to the client indicating that the requested program is not available.
svcerr_progvers Sends an error message to the client indicating that the requested version is not available.
svcerr_systemerr Sends an error message to the client indicating that a system error occurred.
svcerr_weakauth Sends an error message to the client indicating that the authentication information was correctly formatted but was insufficient.
svcraw_create Creates a server handle for a client that shares the same program space.
svcfd_create Creates a server handle for a specified TCP socket.
svctcp_create Creates a server handle using the TCP protocol.
svcudp_bufcreate Creates a server handle using buffered UDP transport.
svcudp_create Creates a server handle using the UDP transport.
xprt_register Adds the UDP or TCP socket associated with the specified server handle to the list of registered sockets.
xprt_unregister Removes the UDP or TCP socket associated with the specified server handle from the list of sockets.
_authenticate Authenticates an RPC request message.


registerrpc

Obtains a unique systemwide procedure identification number.

Format

#include <rpc/rpc.h>

int registerrpc(u_long prognum, u_long versnum, u_long procnum, char *(*progname)(), xdrproc_t inproc, xdrproc_t outproc );


Arguments

prognum

The program number associated with the service procedure.

versnum

The version number associated with the service procedure.

procnum

The procedure number associated with the service procedure.

progname

The address of the service procedure being registered with the ONC RPC service package.

inproc

The XDR routine used to decode the service procedure's arguments.

outproc

The XDR routine used to encode the service procedure's results.

Description

The registerrpc routine performs the following tasks for a server:

A server should call registerrpc for every procedure it implements, except for the NULL procedure. If a request arrives for program prognum , version versnum , and procedure procnum , progname is called with a pointer to its parameters.


Return Values

0 Indicates success.
-1 Indicates failure.

seterr_reply

Fills in the error text in a reply message.

Format

#include <rpc/rpc.h>

void seterr_reply(struct rpc_msg *msg, struct rpc_err *error);


Arguments

msg

A pointer to a reply message buffer.

error

A pointer to an rpc_err structure containing the error associated with the reply message.

Description

Given a reply message, seterr_reply fills in the error field.

Return Values

None  

svc_destroy

A macro that frees the memory associated with an RPC server handle.

Format

#include <rpc/rpc.h>

void svc_destroy(SVCXPRT *xprt);


Arguments

xprt

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

Description

The svc_destroy routine returns all the private data structures associated with a server handle. If the server-handle creation routine received the value RPC_ANYSOCK as the socket, svc_destroy closes the socket. Otherwise, your program must close the socket.

Return Values

None  

svc_freeargs

A macro that frees the memory allocated when the procedure's arguments were decoded.

Format

#include <rpc/rpc.h>

bool_t svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);


Arguments

xprt

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

inproc

The XDR routine used to decode the service procedure's arguments.

in

A pointer to the service procedure's decoded arguments.

Description

The svc_destroy routine returns the memory that the svc_getargs routine allocated to hold the service procedure's decoded arguments. This routine calls the xdr_free routine.

Return Values

TRUE Success; memory successfully deallocated.
FALSE Failure; memory not deallocated.

svc_getargs

A macro that decodes the service procedure's arguments.

Format

#include <rpc/rpc.h>

bool_t svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);


Arguments

xprt

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

inproc

The XDR routine used to decode the service procedure's arguments.

in

A pointer to the service procedure's decoded arguments.

Description

This routine calls the specified XDR routine to decode the arguments passed to the service procedure.

Return Values

TRUE Successfully decoded.
FALSE Decoding unsuccessful.

svc_getcaller

A macro that returns the address of the client that called the service procedure.

Format

#include <rpc/rpc.h>

struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);


Arguments

xprt

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

Description

This routine returns a sockaddr_in structure containing the internet address of the RPC client routine that called the service procedure.

Return Values

struct sockaddr_in A pointer to the socket descriptor.

svc_getreqset

Returns data for each server connection.

Format

#include <rpc/rpc.h>

void svc_getreqset(fd_set *rdfds);


Arguments

rdfds

A pointer to the read file descriptor bit mask modified by the select routine.

Description

The svc_getreqset routine is for servers that implement custom asynchronous event processing or that do not use the svc_run routine. You can only use svc_fdset when the server does not use svc_run .

You are unlikely to call this routine directly, because the svc_run routine calls it. However, there are times when you cannot call svc_run . For example, suppose a program services RPC requests and reads or writes to another socket at the same time. The program cannot call svc_run . It must call select and svc_getreqset .

The server calls svc_getreqset when a call to the select system call determines that the server has received one or more RPC requests. The svc_getreqset routine reads in data for each server connection, then calls the server program to handle the data.

The svc_getreqset routine does not return a value. It finishes executing after all sockets associated with the variable rdfds have been serviced.

You can use the global variable svc_fdset with svc_getreqset . The svc_fdset variable is the RPC server's read file descriptor bit mask.

To use svc_fdset :

  1. Copy the global variable svc_fdset into a temporary variable.
  2. Pass the temporary variable to the select routine. The select routine overwrites the variable and returns it.
  3. Pass the temporary variable to the svc_getreqset routine.

Example


#define MAXSOCK 10 
 
     int readfds[ MAXSOCK+1],    /* sockets to select from*/ 
         i, j; 
 
     for(i = 0, j = 0; i << MAXSOCK; i++) 
          if((svc_fdset[i].sockname != 0) && (svc_fdset[i].sockname != -1)) 
               readfds[j++] = svc_fdset[i].sockname; 
     readfds[j] = 0;                 /* list of sockets ends with a zero */ 
     switch(select(0, readfds, 0, 0, 0)) 
     { 
       case -1:      /* an error happened */ 
       case 0:       /* time out */ 
            break; 
       default:      /* 1 or more sockets ready for reading */ 
            errno = 0; 
            svc_getreqset(readfds); 
            if( errno == ENETDOWN || errno == ENOTCONN) 
            sys$exit( SS$_THIRDPARTY); 
     } 
      


Return Values

None  

svc_register

Registers the server program with the Portmapper service.

Format

#include <rpc/rpc.h>

bool_t svc_register(SVCXPRT *xprt, u_long prognum, u_long versnum, void (*dispatch)(), u_long protocol);


Arguments

xprt

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

prognum

The program number associated with the server procedure.

versnum

The version number associated with the server procedure.

dispatch

The address of the service dispatch procedure that the server procedure calls. The procedure dispatch has the following form:


void dispatch(request, xprt) 
struct svc_req *request; 
SVCXPRT *xprt; 

The svc_run and svc_getreqset call the dispatch routine.

protocol

The protocol that the server procedure uses. Values for this parameter are zero, IPPROTO_UDP, or IPPROTO_TCP. If protocol is zero, the service is not registered with the Portmapper service.

Description

Associates prognum and versnum with the service dispatch procedure dispatch . If protocol is nonzero, then a mapping of the triple [prognum, versnum, protocol] to xprt->xp_port is also established with the local Portmapper service.

Return Values

TRUE Indicates success.
FALSE Indicates failure.

svc_run

Waits for incoming RPC requests and calls the svc_getreqset routine to dispatch to the appropriate RPC server program.

Format

#include <rpc/rpc.h>

void svc_run();


Arguments

None


Description

The svc_run routine calls the select routine to wait for RPC requests. When a request arrives, svc_run calls the svc_getreqset routine. Then svc_run calls the select routine again.

The svc_run routine never returns.

You may use the global variable svc_fdset with the svc_run routine. See the svc_getreqset routine for more information about svc_fdset .


Return Values

Never returns  

svc_sendreply

Sends the results of a remote procedure call to an RPC client.

Format

#include <rpc/rpc.h>

bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char *out);


Arguments

xprt

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

outproc

The XDR routine used to encode the server procedure's results.

out

A pointer to the server procedure's results.

Description

Called by an ONC RPC service's dispatch routine to send the results of a remote procedure call.

Return Values

TRUE Indicates success.
FALSE Indicates failure.


Previous Next Contents Index