RPC.DOC 14 March 1997 The RPC routines allow programs to make procedure calls on other machines across the network. The client calls a procedure to send a data packet to the server. Upon receipt of the packet, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. ----------- RPC on UNIX ----------- To include a file like RPC.H, use the statement #ifdef unix #include #endif The actual include files are in /usr/include/rpc. ------------------ TCPWARE RPC on VMS ------------------ To include a file like RPC.H, use the statement #ifdef VMS #include TCPWARE_INCLUDE:rpc.h #endif The include files are actually stored in SYS$COMMON:[TCPWARE.INCLUDE]. There is a TCPWARE: logical device (at least on TECH88). When you type HELP TCPWARE you get the following topics Overview FSS FTP NETCU NFSDISMOUNT NFSMOUNT NPS NSLOOKUP PING RCP RLOGIN RPCGEN RPCINFO RSH TELNET TES TFTP TRACEROUTE WHOIS Release_Notes Print_Commands Security_Services We are interested in TCPWARE because it provides an RPC (remote procedure call) facility. Remote procedure calls allow programs to invoke procedures on remote hosts as if the procedures were local. Data to be transferred back and forth must be handled by the XDR library. A program that wants to make a remote call will have to have a "stub" inserted into it, which * converts the input arguments from local to XDR form; * places the XDR arguments in a packet; * receives the XDR results in a packet; * converts the XDR results to local format results. Once the results have been returned, the program can resume execution. To write a distributed application: *) Write the application. If you're writing in C, you need to include the RPC.H file using the lines: #ifdef unix #include #endif #ifdef VMS #include tcpware_include:rpc.h #endif *) Write an RPC interface definition, compile it using RPCGEN, and edit the output files as necessary; *) Write any necessary code that RPCGEN did not provide; *) Compile the RPCGEN output files, server procedures, and main program; *) Link the object code with the ONC RPC run time library. $ LINK myfiles, SYS$INPUT/OPTIONS, SYS$SHARE:VAXCRTL/SHARE, - SYS$SHARE:TCPWARE_RPCLIB_SHR/SHARE *) Start the Port Mapper on the server host. If it is not already running, use the command: $ NETCU ADD SERVICE *) Execute the client and server programs. Run the server program interactively to debug it, or else using the $ RUN/DETACHED program_svc.exe command. To run client and server programs: *) Log on to the "server" terminal. Run the server with a command like $ RUN/DETACHED program_svc.exe VMS will assign this process a process_ID which you should note. *) Log on to the "client" terminal. Check that the Port Mapper is running, using the command $ RPCINFO or $ NETCU SHOW SERVICES Run the client program. $ RUN program_clnt.exe This program should stop itself. *) On the server computer, kill the server program: $ STOP process_name or $ STOP/ID=process_ID Notice that, at least on VMS, the "standard" output of a detached process does NOT go to the screen, but to SYS$OUTPUT, which doesn't even show up until you kill the detached process, I think. RPCINFO can request a listing of all programs registered with the Port Mapper, or call the NULL routine of any program. The command $ rpcinfo -p lists all programs registered with the local Port Mapper. You can also specify a nonlocal host. The command $ rpcinfo host prognum versnum will contact a version of the program running on a particular host. The program is identified by the values of prognum and versnum. ---------------------------------- The Form of an RPC Service Request ---------------------------------- The dispatch routine DISPATCH must have the form void dispatch( request, xprt) struct svc_req *request; SVCXPRT *xprt; The form of SVC_REQ may be of interest: struct svc_req { u_long rq_prog, /* service program number */ rq_vers, /* service protocol version */ rq_proc; /* the desired procedure */ opaque_auth rq_cred; /* raw creds from the wire */ u_char *rq_cookedcred; /* read only cooked cred */ SVCXPRT *rq_xprt; /* associated transport */ }; typedef struct svc_req svc_req; ------ RPCGEN ------ RPCGEN is a compiler that creates the network interface portion of a distributed application. RPCGEN is only for users calling the RPC library at the highest level, where most details are hidden from the user, and defaults used. If the user wants more control, and accesses lower level routines, the user will have to write the network interface portion by hand. RPCGEN accepts as input an interface definition, written in RPC language, with a name of the form "name.x", which includes *) The remote program number; *) The remote program version; *) The remote procedure numbers; *) Input and output arguments; *) Information about the kind of data to be transferred. RPCGEN is invoked by typing $ rpcgen name.x RPCGEN creates: *) name_clnt.c, the client stub; *) name_svc.c, the server stub; *) name.h, the header file; and *) name_xdr.c, the XDR filter routines. It is possible to have RPCGEN create only one of these files by using just ONE of the following switches: -c for the XDR file; -h for the header file; -l for the client stub; -m for the server stub. along with the switch: -o for the name of the file to be created. For example, assuming you have a file MEP.X, then you could create just the header file MEP.H by using the command: $ rpcgen -h -o mep.h mep.x ---------------- RPC return codes ---------------- RPC calls return an enum clnt_stat, defined in CLNT.H: enum clnt_stat { RPC_SUCCESS=0, /* call succeeded */ /* Local errors: */ RPC_CANTENCODEARGS=1, /* can't encode arguments */ RPC_CANTDECODERES=2, /* can't decode results */ RPC_CANTSEND=3, /* failure in sending call */ RPC_CANTRECV=4, /* failure in receiving result */ RPC_TIMEDOUT=5, /* call timed out */ /* Remote errors: */ RPC_VERSMISMATCH=6, /* rpc versions not compatible */ RPC_AUTHERROR=7, /* authentication error */ RPC_PROGUNAVAIL=8, /* program not available */ RPC_PROGVERSMISMATCH=9, /* program version mismatched */ RPC_PROCUNAVAIL=10, /* procedure unavailable */ RPC_CANTDECODEARGS=11, /* decode arguments error */ RPC_SYSTEMERROR=12, /* generic "other problem" */ /* CALLRPC & CLNT_CREATE errors: */ RPC_UNKNOWNHOST=13, /* unknown host name */ RPC_UNKNOWNPROTO=17, /* unkown protocol */ /* Create errors: */ RPC_PMAPFAILURE=14, /* the pmapper failed in its call */ RPC_PROGNOTREGISTERED=15, /* remote program is not registered */ /* Unspecified error: */ RPC_FAILED=16 }; -------------------- List of RPC Routines -------------------- auth_destroy destroys authentication information associated with an authentication handle. authnone_create creates and returns a null RPC authentication handle for the client process. authunix_create creates and returns an RPC authentication handle for the client process. Use this routine when the server requires UNIX-style authentication. authunix_create_default calls the AUTHUNIX_CREATE routine, and provides default values as arguments. callrpc calls the remote procedure identified by the routine's arguments. Uses the UDP protocol. clnt_broadcast broadcasts a remote procedure call to all local networks, using the broadcast address. Uses the UDP protocol. clnt_call calls a remote procedure. clnt_control changes or retrieves information about an RPC client process. clnt_create creates an RPC client handle. clnt_destroy destroys an RPC client handle. clnt_freeres frees the memory that was allocated when the RPC results were decoded. clnt_geterr returns an error code indicating why an RPC call failed. clnt_pcreateerror returns a message indicating why RPC could not create a client handle. clnt_perrno returns a message indicating why the callrpc or clnt_broadcast routine failed to create a client handle. clnt_perror returns a message if the CLNT_CALL routine fails. clnt_spcreateerror returns a message indicating why RPC could not create a client handle. clnt_sperrno returns a message indicating why the CALLRPC or CLNT_BROADCAST routine failed to create a client handle. clnt_sperror returns a message if the CLNT_CALL routine fails. clntraw_create creates a toy RPC client. clnttcp_create returns an RPC client handle. The remote procedure call uses the TCP transport. clntudp_create returns an RPC client handle. The remote procedure call uses the UDP transport. clntudp_bufcreate returns an RPC client handle. The remote procedure call uses the UDP transport. get_myaddress returns the Internet address of the local host. oncrpc_get_char returns the characteristic values of an RPC client or server process. oncrpc_get_stats returns counters for memory usage, the RPC server, or the RPC client. oncrpc_set_char defines the values of characteristics for each RPC client and server process. pmap_freemaps frees memory that was allocated by the PMAP_GETMAPS routine. pmap_getmaps returns a list of port mappings for the specified host. pmap_getport returns the port number of which a specified service is waiting. pmap_rmtcall requests the port mapper on a remote host to call a procedure on that host. pmap_set registers a remote service with a remote port. pmap_unset unregisters a service so it is no longer mapped to a port. registerrpc performs creation and registration tasks for the server. svc_destroy destroys the RPC server handle. svc_freeargs frees the memory that was allocated when the RPC arguments were decoded. svc_getargs decodes the RPC arguments. svc_getcaller returns the address of the client that called the receiver. svc_getchan returns the channel associated with the server handle. svc_getport returns the port associated with the server handle. svc_getreqset reads data for each server connection. svc_register adds the specified server to a list of active servers, and registers the service program with the port mapper. svc_run waits for RPC requests and calls the SVC_GETREQSET routine to dispatch to the appropriate RPC service program. svc_sendreply sends the results of a remote procedure call to the client. svc_sendreply_dq sends the results of a remote procedure call to the client. svc_unregister calls the port mapper to unregister the specified program and version for all protocols.The program and version are removed from the list of active servers. svcerr_auth sends an error code to the client because the client cannot be authenticated. svcerr_decode sends an error code to the client because the server cannot decode its arguments. svcerr_noproc sends an error code to the client because the server does not implement the requested procedure. svcerr_noprog sends an error code to the client because the requested program is not registered with the port mapper. svcerr_progvers sends an error code to the client because the requested program is registered with the port mapper, but not the requested version. svcerr_systemerr sends an error code to the client because an error was encountered that is not handled by a particular protocol. svcerr_weakauth sends an error code to the client because it received insufficient authentication. svcfd_create returns the address of a structure containing a server handle for the specified TCP socket. svcraw_create creates a toy RPC service transport. svctcp_create returns the address of a server handle that uses the TCP transport. svctcpa_create returns the address of a server handle that uses the TCPA transport. svctcpa_shutdown cancels all outstanding I/O on the channel associated with the server handle that is using TCPA transport. svcudp_bufcreate returns the address of a server handle that uses the UDP transport. svcudp_create returns the address of a server handle that uses the UDP transport. svcudp_enablecache enables the XID cache for the specified UDP transport server. svcudpa_bufcreate returns the address of a server handle that uses the UDPA transport. svcudpa_create returns the address of a server handle that uses the UDPA transport. svcudpa_enablecache enables the XID cache for the specified UDPA transport server. svcudpa_freecache deallocates the UDPA XID cache. svcudpa_getxdrs returns the XDR structure associated with the server handle that is using the UDPA transport. svcudpa_shutdown cancels all outstanding I/O on the channel that is associated with the server handle that is using the UDPA transport. xprt_register adds a TCP or UDP server socket to a list of sockets. xprt_unregister removes a TCP or UDP server socket to a list of sockets. --------------------- Detailed Descriptions --------------------- ------------ auth_destroy ------------ AUTH_DESTROY destroys authentication information associated with an authentication handle. void auth_destroy(auth) AUTH *auth; auth The RPC authentication client handle created by the authnone_create, authunix_create or authunix_create_default routine. --------------- authnone_create --------------- AUTHNONE_CREATE creates and returns a null RPC authentication handle for the client process. This routine is for client processes that require no authentication. RPC uses it as a default when it creates a client handle. AUTH * authnone_create() --------------- authunix_create --------------- AUTHUNIX_CREATE creates and returns an RPC authentication handle for the client process. Use this routine when the server requires UNIX-style authentication. AUTH * authunix_create(host, uid, gid, len, gids) char *host; int uid; int gid; int len; int *gids; host The address of the name of the host that created the authentication information. This is usually the local host running the client process. uid The user ID of the person who is executing this process. gid The user's group ID. len The number of elements in the *gids array. gids The address of the array of groups to which the user belongs. ----------------------- authunix_create_default ----------------------- AUTHUNIX_CREATE_DEFAULT calls the AUTHUNIX_CREATE routine, and provides default values as arguments. AUTH * authunix_create_default() ------- callrpc ------- CALLRPC calls a remote procedure identified by the routine's arguments. int callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out) char *host; u_long prognum; u_long versnum; u_long procnum; xdrproc_t inproc; u_char *in; xdrproc_t outproc; u_char *out; host The address of the string containing the name of the remote host where the server is located. prognum The program number of the service program. versnum The version number of the service program. procnum The number of the service procedure. inproc An XDR routine that encodes input arguments. in Input arguments for the service procedure. outproc An XDR routine that encodes output arguments. out Results of the remote procedure call. -------------- clnt_broadcast -------------- CLNT_BROADCST broadcasts a remote procedure call to all local networks, using the broadcast address. enum clnt_stat clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult) char *host; u_long prognum; u_long versnum; u_long procnum; xdrproc_t inproc; u_char *in; xdrproc_t outproc; u_char *out; resultproc_t eachresult; clnt_broadcast Returns a value indicating success or the type of error. The value RPC_SUCCESS=0 indicates success, while positive values indicate various errors, defined in the TCPWARE file clnt.h. prognum The program number of the service program. versnum The version number of the service program. procnum The number of the service procedure. inproc An XDR routine that encodes input arguments. in Input arguments for the service procedure. outproc An XDR routine that encodes output arguments. out Results of the remote procedure call. eachresult Each time CLNT_BROADCAST receives a response, it calls the EACHRESULT routine. If EACHRESULT returns 0, CLNT_BROADCAST waits for more replies. If EACHRESULT returns a nonzero value, CLNT_BROADCAST stops waiting for replies. EACHRESULT should have the form: int eachresult(out, addr) u_char *out; struct sockaddr_in *addr; where 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. --------- clnt_call --------- CLNT_CALL calls a remote procedure. enum clnt_stat clnt_call(clnt, procnum, inproc, in, outproc, out, tout) CLIENT *clnt; u_long procnum; xdrproc_t inproc; u_char *in; xdrproc_t outproc; u_char *out; struct timeval tout; clnt_call Returns a value indicating success or the type of error. The value RPC_SUCCESS=0 indicates success, while positive values indicate various errors, defined in the TCPWARE file CLNT.H. clnt The client handle returned by one of the client creation routines. procnum The number of the service procedure. inproc An XDR routine that encodes input arguments. in Input arguments for the service procedure. outproc An XDR routine that encodes output arguments. out Results of the remote procedure call. tout The time allowed for the results to return to the client, in seconds and microseconds. ------------ clnt_control ------------ CLNT_CONTROL changes or retrieves information about an RPC client process. bool_t clnt_control(clnt, code, info) CLIENT *clnt; u_long code; void *info; clnt_control Returns TRUE if it succeeds, and FALSE if it fails. clnt The client handle returned by any of the client create routines. code One of the following 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. info The address of the information being changed or retrieved. ----------- clnt_create ----------- CLNT_CREATE creates an RPC client handle. CLIENT * clnt_create(host, prognum, versnum, proto) char *host; u_long prognum; u_long versnum; char *proto; clnt_create Returns an RPC client handle for PROGNUM, or 0 if it could not create a handle. host The address of the string containing the name of the remote host where the server is located. prognum The program number of the service program. versnum The version number of the service program. proto The address of a string containing the name of the transport protocol. Valid values of the string are "UDP" and "TCP". ------------ clnt_destroy ------------ CLNT_DESTROY destroys an RPC client handle. void clnt_destroy(clnt) CLIENT *clnt; clnt The handle of the client that is to be destroyed. ------------ clnt_freeres ------------ CLNT_FREERES frees the memory that was allocated when the RPC results were decoded. bool_t clnt_freeres(clnt, xdr_res, res_ptr) CLIENT *clnt; xdrproc_t xdr_res; char *res_ptr; clnt_freeres Returns TRUE if it succeeds, and FALSE if it fails. clnt The handle of the client. xdr_res The address of the XDR procedure that describes the RPC results. res_ptr The address of the RPC results. ----------- clnt_geterr ----------- CLNT_GETERR returns an error code indicating why an RPC call failed. void clnt_geterr(clnt, errp) CLIENT *clnt; struct rpc_err *errp; clnt The handle of the client. errp The address of the structure containing information about why the RPC call failed. ----------------- clnt_pcreateerror ----------------- CLNT_PCREATEERROR returns a message indicating why RPC could not create a client handle. void clnt_pcreateerror(s) char *s; s A string containing the message of your choice. The routine appends an error message to this string. ----------- clnt_perrno ----------- CLNT_PERRNO prints a message indicating why the CALLRPC or CLNT_BROADCAST routine failed to create a client handle. void clnt_perrno(stat) enum clnt_stat stat; stat Indicates the appropriate error condition. Values for STAT are defined in the file CLNT.H. ----------- clnt_perror ----------- CLNT_PERROR returns a message if the CLNT_CALL routine fails. void clnt_perror(clnt, s) CLIENT *clnt; char *s; clnt The client handle created by one of the client creation routines. s A string containing the message of your choice. The routine appends an error message to this string. ----------------- clnt_spcreateerror ----------------- CLNT_SPCREATEERROR returns a message indicating why RPC could not create a client handle. char *clnt_spcreateerror(s) char *s; clnt_spcreateerror The address of a string containing the message. s A string containing the message of your choice. The routine appends an error message to this string. ------------ clnt_sperrno ------------ CLNT_SPERRNO returns a message indicating why the CALLRPC or CLNT_BROADCAST routine failed to create a client handle. char *clnt_sperrno(stat) enum clnt_stat stat; clnt_sperrno The address of a string containing the error message. stat Indicates the appropriate error condition. Values for STAT are defined in the file CLNT.H. ------------ clnt_sperror ------------ CLNT_SPERROR returns a message if the CLNT_CALL routine fails. char *clnt_sperror(clnt, s) CLIENT *clnt; char *s; clnt_sperror The address of a string containing the message. clnt The client handle created by one of the client creation routines. s A string containing the message of your choice. The routine appends an error message to this string. -------------- clntraw_create -------------- CLNTRAW_CREATE creates a toy RPC client. The transport is really a buffer within the process's address space, so the corresponding RPC client should live in the same address space. See SVCRAW_CREATE. This routine allows simulation of RPC and acquisition of RPC overheads without any kernel interference. This routine is in the IRIX manual, but not the TCPWARE manual. CLIENT *clntraw_create(prognum,versnum) u_long prognum; u_long versnum; clntraw_create The client handle, or 0 if there was a failure. prognum The program number of the service program. versnum The version number of the service program. -------------- clnttcp_create -------------- CLNTTCP_CREATE returns an RPC client handle. The remote procedure call uses the TCP transport. CLIENT * clnttcp_create(addr, prognum, versnum, sockp, sendsize, rcvsize) struct sockaddr_in *addr; u_long prognum; u_long versnum; int *sockp; u_long sendsize; u_long recvsize; clnttcp_create The client handle returned. addr The internet address of the host on which the server resides. prognum The program number of the service program. versnum The version number of the service program. sockp The socket to be used for this remote procedure call. sendsize The size of the send buffer. recvsize The size of the receive buffer. ----------------- clntudp_bufcreate ----------------- CLNTUDP_BUFCREATE returns an RPC client handle. The remote procedure call uses the UDP transport. CLIENT * clnttudp_bufcreate(addr, prognum, versnum, wait, sockp, sendsize, recvsize) struct sockaddr_in *addr; u_long prognum; u_long versnum; struct timeval wait; int *sockp; clntudp_bufcreate The client handle returned. addr The internet address of the host on which the server resides. prognum The program number of the service program. versnum The version number of the service program. wait The time interval the client waits before resending the call message. sockp The socket to be used for this remote procedure call. sendsize The size of the send buffer. recvsize The size of the receive buffer. -------------- clntudp_create -------------- CLNTUDP_CREATE returns an RPC client handle. The remote procedure call uses the UDP transport. CLIENT * clnttudp_create(addr, prognum, versnum, wait, sockp) struct sockaddr_in *addr; u_long prognum; u_long versnum; struct timeval wait; int *sockp; clntudp_create The client handle returned. addr The internet address of the host on which the server resides. prognum The program number of the service program. versnum The version number of the service program. wait The time interval the client waits before resending the call message. sockp The socket to be used for this remote procedure call. ------------- get_myaddress ------------- GET_MYADDRESS returns the Internet address of the local host. void get_myaddress(addr) struct sockaddr_in *addr; addr The address of a sockaddr_in structure that will be loaded with the host's Internet address. --------------- oncrpc_get_char --------------- ONCRPC_GET_CHAR returns the characteristic values of an RPC client or server process. This routine is in the TCPWARE manual, but not the IRIX manual. u_long oncrpc_get_char(code,value) u_long code; void *value; code The characteristic being returned. Legal values of code are RPCCHAR__AC_SIZE - alters the number of entries in the active cache. This code is for UDPA transports only. The default is 20. RPCCHAR__CHECKSUM - enables or disables checksums for outgoing packets. RPCCHAR__DEBUG - enables the printing of messages that indicate what ONCRPC is doing. All messages go to SYS$OUTPUT. The type is u_long *value and the default value is 0. These are the mask values: RPCDBG__XDR RPCDBG__XID RPCDBG__ACTIVE_CA RPCDBG__GENERAL RPCDBG__RAW_RCV RPCDBG__RAW_SEND RPCDBG__AUTH RPCDBG__MEMORY RPCCHAR__DEFPORTS - determines whether RPC uses privileged ports (600 to 1023) or nonprivileged ports (1024 and greater). Values are RPCPORTS__PRIVILEGE and RPCPORTS__NORMAL. RPCCHAR__FATALRTN - calls an error-handling routine when the TCPA or UDPA transports detect a fatal error. The VMS error status code is passed to the error handling routine. If *value is zero, the default value is used. The type is void (**value)(u_long status). The default is SYS$EXIT. value The address where the routine places the characteristic value. ---------------- oncrpc_get_stats ---------------- ONCRPC_GET_STATS returns counters for memory usage, the RPC server, or the RPC client. This routine is in the TCPWARE manual, but not the IRIX manual. u_long oncrpc_get_stats(code,buffer) u_long code; u_char *buffer; oncrpc_get_stats Returns one of the following status codes: SS$_NORMAL - The routine successfully returned the counters. SS$_BADPARAM - The value of CODE is invalid. SS$_ACCVIO - The BUFFER is a null address. code These codes are available RPCSTAT__ZERO zeroes out the client or server counters; RPCSTAT__CLIENT retrieves client counters; RPCSTAT__SERVER retrieves server counters; RPCSTAT__MEMORY retrieves memory counters. buffer The address of the structure to receive the requested counters. --------------- oncrpc_set_char --------------- ONCRPC_SET_CHAR defines the values of characteristics for each RPC client and server process. This routine is in the TCPWARE manual, but not the IRIX manual. u_long oncrpc_set_char(code,value) u_long code; void *value; code The characteristic being set. Refer to the ONCRPC_GET_CHAR routine for a description of each code. value The address of the characteristic value. ------------- pmap_freemaps ------------- PMAP_FREEMAPS frees memory that was allocated by the PMAP_GETMAPS routine. This routine is in the TCPWARE manual, but not the IRIX manual. void pmap_freemaps(list) struct pmaplist *list; list The address of a structure containing the list returned by the pmap_getmaps routine. ------------ pmap_getmaps ------------ PMAP_GETMAPS returns a list of Port Mappings for the specified host. struct pmaplist * pmap_getmaps(addr) struct sockaddr_in *addr; addr The address of a structure containing the internet address of the host whose Port Mapper is being called. ------------ pmap_getport ------------ PMAP_GETPORT returns the port number on which a specified service is waiting. u_short pmap_getport(addr, prognum, versnum, protocol) struct sockaddr_in *addr; u_long prognum; u_long versnum; u_long protocol; addr The internet address of the host on which the server resides. prognum The program number of the service program. versnum The version number of the service program. protocol The transport protocol for the service. Mut be IPPROTO_UDP or IPPROTO_TCP. ------------ pmap_rmtcall ------------ PMAP_RMTCALL requests the Port Mapper on a remote host to call a procedure on that host. enum clnt_stat pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in, outproc, out, tout, portp) struct sockaddr_in *addr; u_long prognum; u_long versnum; u_long procnum; xdrproc_t inproc; u_char *in; xdrproc_t outproc; u_char *out; struct timeval tout; u_long *portp; addr The address of a structure containing the internet address of the remote host on which the server resides. prognum The program number of the service program. versnum The version number of the service program. procnum The number of the service procedure. inproc An XDR routine that encodes input arguments. in Input arguments for the service procedure. outproc An XDR routine that encodes output arguments. out Results of the remote procedure call. tout The time allowed for the results to return to the client, in seconds and microseconds. portp The address where PMAP_RMTCALL will write the port number of the remote service. -------- pmap_set -------- PMAP_SET registers a remote service with a remote port. bool_t pmap_set(prognum, versnum, protocol, port) u_long prognum; u_long versnum; u_long protocol; u_short port; prognum The program number of the service program. versnum The version number of the service program. protocol The transport protocol for the service. Mut be IPPROTO_UDP or IPPROTO_TCP. port The remote port number. ---------- pmap_unset ---------- PMAP_UNSET unregisters a service so it is no longer mapped to a port. The typical user is unlikely to need PMAP_UNSET, since SVC_UNREGISTER calls it. bool_t pmap_unset(prognum,versnum) u_long prognum; u_long versnum; pmap_unset returns TRUE if it succeeds, and FALSE if it fails. prognum The program number of the service program. versnum The version number of the service program. ----------- registerrpc ----------- REGISTERRPC performs creation and registration tasks for the server. int registerrpc(prognum, versnum, procnum, procname, inproc, outproc) u_long prognum; u_long versnum; u_long procnum; u_char *(*procname) (); xdrproc_t inproc; xdrproc_t outproc; prognum The program number of the service program. versnum The version number of the service program. procnum The number of the service procedure. procname The address of the routine that implements the server procedure. The routine uses the following format: u_char *procname(out); u_char *out; where OUT is the address of the data decoded by OUTPROC. inproc An XDR routine that encodes input arguments. outproc An XDR routine that encodes output arguments. ----------- svc_destroy ----------- SVC_DESTROY destroys the RPC server handle. If the server creation routine received RPC_ANYSOCK as the socket, then SVC_DESTROY closes the socket. Otherwise, you must close the socket. If the SVCUDPA_CREATE routine received RPC_ANYCHAN as the channel, SVC_DESTROY deassigns the channel. Otherwise, you must deassign the channel. The SVCTPA_CREATE routine always deassigns the channel. void svc_destroy(xprt) SVCXPRT *xprt; xprt The RPC server handle. ------------ svc_freeargs ------------ SVC_FREEARGS frees the memory that was allocated when the RPC arguments were decoded. bool_t svc_freeargs(xprt, xdr_args, args_ptr) SVCXPRT *xprt; xdrproc_t xdr_args; char *args_ptr; svc_freeargs True if it succeeds, and FALSE otherwise. xprt The RPC server handle. xdr_args The XDR procedure that describes the RPC arguments. args_ptr The address of the buffer for the decoded RPC arguments. ----------- svc_getargs ----------- SVC_GETARGS decodes the RPC arguments. bool_t svc_getargs(xprt, xdr_args, args_ptr) SVCXPRT *xprt; xdrproc_t xdr_args; u_char *args_ptr; svc_getargs Returns TRUE if the arguments were decoded, FALSE otherwise. xprt The RPC server handle. xdr_args The XDR procedure that describes the RPC arguments. args_ptr The address of the buffer to contain the decoded RPC arguments. ------------- svc_getcaller ------------- SVC_GETCALLER returns the address of the client that called the server. struct sockaddr_in * svc_getcaller(xprt) SVCXPRT *xprt; xprt The RPC server handle. ----------- svc_getchan ----------- SVC_GETCHAN returns the channel associated with the server handle. This routine is in the TCPWARE manual, but not the IRIX manual. u_short svc_getchan(xprt) SVCXPRT *xprt; svc_getchan The channel associated with the server handle. xprt The RPC server handle. ----------- svc_getport ----------- SVC_GETPORT returns the port associated with the server handle. This routine is in the TCPWARE manual, but not the IRIX manual. u_short svc_getport(xprt) SVCXPRT *xprt; svc_getport The port associated with the server handle. xprt The RPC server handle. ------------- svc_getreqset ------------- SVC_GETREQSET reads data for each server connection. The server calls SVC_GETREQSET when it receives an RPC request, which reads in data for each server connection, and then calls the server program to handle the data. void svc_getreqset(rdfds) int rdfds[]; rdfds The address of the read socket descriptor array. This array is returned by the SELECT routine. ------------ svc_register ------------ SVC_REGISTER adds the specified server to a list of active servers, and registers the service program with the port mapper. bool_t svc_register(xprt, prognum, versnum, dispatch, protocol) SVCXPRT *xprt; u_long prognum; u_long versnum; u_long dispatch; u_long protocol; svc_register Returns TRUE if it succeeds, and FALSE if it fails. xprt The RPC server handle. prognum The program number of the service program. versnum The version number of the service program. dispatch A routine that SVC_REGISTER calls when the server receives a request for program number PROGNUM and version number VERSNUM. This routine determines which routine to call for each server procedure. This routine should have the following form: void dispatch(request, xprt) struct svc_req *request; SVCXPRT *xprt; protocol Must be IPPROTO_UDP, IPPROTO_TCP or 0. Zero indicates that you do not want to register the server with the Port Mapper. ------- svc_run ------- SVC_RUN waits for RPC requests and calls the SVC_GETREQSET routine to dispatch to the appropriate RPC service program. The SVC_RUN routine never returns. void svc_run() ------------- svc_sendreply ------------- SVC_SENDREPLY sends the results of a remote procedure call to the client. bool_t svc_sendreply(xprt, outproc, out) SVCXPRT *xprt; xdrproc_t outproc; u_char *out; svc_sendreply Returns TRUE if it succeeds, and FALSE othewise. xprt The RPC server handle. outproc The XDR routine that decodes the output arguments. out The results of the remote procedure call. ---------------- svc_sendreply_dq ---------------- SVC_SENDREPLY_DQ sends the results of a remote procedure call to the client. The SVC_SENDREPLY_DQ differs from the SVC_SENDREPLY routine. It does not queue a read, and is for UDPA and TCPA servers only. This routine is in the TCPWARE manual, but not the IRIX manual. bool_t svc_sendreply_dq(xprt, outproc, out) SVCXPRT *xprt; xdrproc_t outproc; u_char *out; svc_sendreply_dq Returns TRUE if it succeeds, and FALSE othewise. xprt The RPC server handle. outproc The XDR routine that decodes the output arguments. out The results of the remote procedure call. -------------- svc_unregister -------------- SVC_UNREGISTER calls the port mapper to unregister the specified program and version for all protocols. The program and version are removed from the list of active servers. void svc_unregister(prognum, versnum) u_long prognum; u_long versnum; prognum The program number of the service program. versnum The version number of the service program. ----------- svcerr_auth ----------- SVCERR_AUTH sends an error code to the client because the dispatch routine cannot authenticate the client. void svcerr_auth(xprt, why) SVCXPRT *xprt; enum auth_stat why; xprt The RPC server handle. why An error code defined in the AUTH.H file. ------------- svcerr_decode ------------- SVCERR_DECODE sends an error code to the client because the server cannot decode its arguments. void svcerr_decode(xprt) SVCXPRT *xprt; xprt The RPC server handle. ------------- svcerr_noproc ------------- SVCERR_NOPROC sends an error code to the client because the server does not implement the requested procedure. void svcerr_noproc(xprt) SVCXPRT *xprt; xprt The RPC server handle. ------------- svcerr_noprog ------------- SVCERR_NOPROG sends an error code to the client because the requested program is not registered with the Port Mapper. void svcerr_noprog(xprt) SVCXPRT *xprt; xprt The RPC server handle. --------------- svcerr_progvers --------------- SVCERR_PROGVERS sends an error to the client when the requested program is registered with the Port Mapper, but the requested version is not registered. void svcerr_progvers(xprt, low_vers, high_vers) SVCXPRT *xprt; u_long low_vers; u_long high_vers; xprt The RPC server handle. low_vers The lowest version number in the range of versions that the server supports. high_vers The highest version number in the range of versions that the server supports. ---------------- svcerr_systemerr ---------------- SVCERR_SYSTEMERR sends an error code to the client because an error was encountered that is not handled by a particular protocol. void svcerr_systemerr(xprt) SVCXPRT *xprt; xprt The RPC server handle. --------------- svcerr_weakauth --------------- SVCERR_WEAKAUTH sends an error code to the client when the server cannot perform a remote procedure call because it received insufficient authentication parameters. void svcerr_weakauth(xprt) SVCXPRT *xprt; xprt The RPC server handle. ------------- svcfd_create ------------- SVCFD_CREATE returns the address of a server handle for the specified TCP socket. SVCXPRT * svcfd_create(sock, sendsize, recvsize) int sock; u_long sendsize; u_long recvsize; svcfd_create The address of a server handle for the specified TCP socket, or 0 if it fails. sock The socket for this service, or 0 if SVCTCP_CREATE could not create the server handle. sendsize The size of the send buffer in bytes. If you enter a value less than 100, then 4000 bytes is used as the default. recvsize The size of the receive buffer in bytes. If you enter a value less than 100, then 4000 bytes is used as the default. ------------- svcraw_create ------------- SVCRAW_CREATE creates a toy RPC service transport. The transport is really a buffer within the process's address space, so the corresponding RPC cleint should live in the same address space. See CLNTRAW_CREATE. This routine allows simulation of RPC and acquisition of RPC overheads without any kernel interference. This routine is in the IRIX manual, but not the TCPWARE manual. SVCXPRT*svcraw_create() Returns either the address of the server handle, or 0 if it could not create the server handle. ------------- svctcp_create ------------- SVCTCP_CREATE returns the address of a server handle that uses the TCP transport. SVCXPRT svctcp_create(sock, sendsize, recvsize) int sock; u_long sendsize; u_long recvsize; svctcp_create Returns either the address of the server handle, or 0 if it could not create the server handle. sock The socket for this service. sendsize The size of the send buffer in bytes. If you enter a value less than 100, then 4000 bytes is used as the default. recvsize The size of the receive buffer in bytes. If you enter a value less than 100, then 4000 bytes is used as the default. -------------- svctcpa_create -------------- SVCTCP_CREATE returns the address of a server handle that uses the TCPA transport. This routine is in the TCPWARE manual, but not the IRIX manual. SVCXPRT svctcpa_create(channel, port, sendsize, recvsize) u_short channel; u_short port; u_long sendsize; u_long recvsize; svctcpa_create Returns either the address of the server handle, or 0 if it could not create the server handle. channel Must be zero. This argument is reserved for future use. port The number of the TCP port on which the server will listen. If you enter RPCANYPORT, then RPC assigns a port. sendsize The size of the send buffer in bytes. If you enter a value less than 100, then 4000 bytes is used as the default. recvsize The size of the receive buffer in bytes. If you enter a value less than 100, then 4000 bytes is used as the default. ---------------- svctcpa_shutdown ---------------- SVCTCPA_SHUTDOWN cancels all outstanding I/O on the channel associated with the server handle. This routine is in the TCPWARE manual, but not the IRIX manual. void svctcpa_shutdown(xprt) SVCXPRT *xprt; xprt The RPC server handle. ---------------- svcudp_bufcreate ---------------- SVCUDP_BUFCREATE returns the address of a server handle that uses the UDP transport. SVCXPRT * svcudp_bufcreate(sock, sendsize, recvsize) int sock; u_long sendsize; u_long recvsize; svcudp_bufcreate Returns either a server handle, or 0. sock The socket for this service. sendsize The size of the send buffer. The minimum is 100 bytes, and the maximum is 65468 bytes. recvsize The size of the receive buffer. The minimum is 100 bytes, and the maximum is 65000. ------------- svcudp_create ------------- SVCUDP_CREATE returns the address of a server handle that uses the UDP transport. This routine is in the TCPWARE manual, but not the IRIX manual. SVCXPRT * svcudp_create(sock) int sock; svcudp_create Returns either a server handle, or 0. sock The socket for this service. A new socket is created if you enter RPC_ANYSOCK. ------------------ svcudp_enablecache ------------------ SVCUDP_ENABLECACHE enables the XID cache for the specified UDP transport server. This routine is in the TCPWARE manual, but not the IRIX manual. bool_t svcudp_enablecache(xprt, size) SVCXPRT *xprt; u_long size; xprt The RPC server handle. size The number of entries permitted in the XID cache. You may estimate this number based on how active the server is, and how long you want to retain old replies. ----------------- svcudpa_bufcreate ----------------- SVCUDPA_BUFCREATE returns the address of a server handle that uses the UDPA transport. This routine is in the TCPWARE manual, but not the IRIX manual. SVCXPRT * svcudpa_bufcreate(channel, port, sendsize, recvsize) u_short channel; u_short port; u_long sendsize; u_long recvsize; svcudpa_bufcreate Returns either a UDPA server handle, or 0. channel If you enter RPC_ANYCHAN, then the routine assigns the channel, and sets the local port to PORT. If you enter any other value then the routine ignores the value of PORT. port The number of the UDP port on which the server will listen. If you enter RPCANYPORT, then RPC assigns a port. sendsize The size of the send buffer. The minimum is 100 bytes, and the maximum is 65468 bytes. recvsize The size of the receive buffer. The minimum is 100 bytes, and the maximum is 65000. -------------- svcudpa_create -------------- SVCUDPA_CREATE returns the address of a server handle that uses the UDPA transport. This routine is in the TCPWARE manual, but not the IRIX manual. SVCXPRT * svcudpa_create(channel, port) u_short channel; u_short port; svcudpa_create Returns either a UDPA server handle, or 0. channel If you enter RPC_ANYCHAN, then the routine assigns the channel, and sets the local port to PORT. If you enter any other value then the routine ignores the value of PORT. port The number of the UDP port on which the server will listen. If you enter RPCANYPORT, then RPC assigns a port. -------------------- svcudpa_enablecache ------------------- SVCUDPA_ENABLECACHE enables the XID cache for the specified UDPA transport server. This routine is in the TCPWARE manual, but not the IRIX manual. bool_t svcudpa_enablecache(xprt, cacheaddr, size, reqlst) SVCXPRT *xprt; void *cacheaddr; u_long size; reply_id *reqlst; xprt The RPC server handle. cacheaddr The address of the XID cache. If cacheaddr is zero, this routine allocates a cache with SIZE number of entries. size The number of entries permitted in the XID cache. You may estimate this number based on how active the server is, and how long you want to retain old replies. reqlst The address of an array of structures containing a list of procedures for which replies are to be cached. The array is terminated by PROGNUM=0. This is the structure: typedef struct { u_long prognum, versnum, procnum; } reply_id ----------------- svcudpa_freecache ----------------- SVCUDPA_FREECACHE deallocates the UDPA XID cache. This routine is in the TCPWARE manual, but not the IRIX manual. void svcudpa_freecache(cacheaddr) void *cacheaddr; cacheaddr The address of the UDPA XID cache. --------------- svcudpa_getxdrs --------------- SVCUDPA_GETXDRS returns the XDR structure associated with the server handle. This routine is in the TCPWARE manual, but not the IRIX manual. XDRS *svcudpa_getxdrs(xprt) SVCXPRT *xprt; svcudpa_getxdrs The address of the XDR structure associated with the server handle. xprt The RPC server handle. ---------------- svcudpa_shutdown ---------------- SVCUDPA_SHUTDOWN cancels all outstanding I/O on the channel associated with the server handle. This routine is in the TCPWARE manual, but not the IRIX manual. void svcudpa_shutdown(xprt) SVCXPRT *xprt; xprt The RPC server handle. ------------- xprt_register ------------- XPRT_REGISTER adds a TCP or UDP server socket to a list of sockets. void xprt_register(xprt) SVCXPRT *xprt; xprt The RPC server handle. --------------- xprt_unregister --------------- XPRT_UNREGISTER removes a TCP or UDP server socket from a list of sockets. void xprt_unregister(xprt) SVCXPRT *xprt; xprt The RPC server handle.