|
|
This appendix lists the RPC library calls in UNIX-style manual page format.
The RPC library calls are listed in alphabetical order in this chapter.
Following a brief introductory statement summarizing its use, each function is described using the documentation style of UNIX.
This table lists the basic components of each function description:
| Function | Description |
| Synopsis | A synopsis of the function is given in C language format. The function prototype statement is listed showing all function arguments. |
| Description | A description of the function is given, including any special rules for specifying arguments, alternative uses of the function, and any results returned. |
| Parameters | Each parameter for the call is described. |
| Files | Any required include files are listed in this section. |
| See Also | References to related functions are given. |
Destroy authentication information.
void auth_destroy(auth) AUTH *auth;
auth_destroy() is a macro that destroys the authentication information associated with auth. Destruction usually involves deallocation of private data structures. The use of auth is undefined after calling auth_destroy(). This routine is called indirectly based on the pointer to the routine passed in the struct AUTH. This routine may also be called using the upper-case AUTH_DESTROY().
| auth | RPC authentication handle |
rpc.h - RPC include file
authnone_create(), authunix_create(), authunix_create_default()
Create RPC authentication handle.
AUTH *authnone_create()
authnone_create() creates and returns an RPC authentication handle that passes nonusable authentication information with each remote procedure call. This is the default used by RPC.
rpc.h - RPC include file
auth_destroy(), authunix_create(), authunix_create_default()
Create RPC authentication handle.
AUTH *authunix_create(host, uid, gid, len, aup_gids) char *host; int uid, gid, len, *aup_gids;
authunix_create() creates and returns an RPC authentication handle that contains authentication information. It is easy to impersonate a user.
| host | The name of the machine on which the information was created. |
| uid | The user's user ID. |
| gid | The user's current group ID. |
| len | Refers to a counted array of groups to which the user belongs. |
| aup_gids | Refers to a counted array of groups to which the user belongs. |
rpc.h - RPC include file
auth_destroy(), authnone_create(), authunix_create_default()
Call authunix with default parameters.
AUTH *authunix_create_default()
authunix_create_default() calls authunix_create() with the appropriate parameters.
rpc.h - RPC include file
auth_destroy(), authnone_create(), authunix_create()
Call remote procedure.
int callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out) char *host; u_long prognum, versnum, procnum; char *in, *out; xdrproc_t inproc, outproc;
callrpc() calls the remote procedure associated with program number, version number, and remote procedure on the machine host. This routine returns zero if it succeeds, or the value of enum clnt_stat cast to an integer if it fails. The routine clnt_perrno() is handy for translating failure statuses into messages.
Calling remote procedures with this routine uses UDP/IP as a transport; see clntudp_create() for restrictions. You do not have control of time-outs or authentication using this routine.
| host | Machine name |
| prognum | Program number |
| versnum | Version number |
| procnum | Remote procedure |
| inproc | XDR routine used to encode the procedure's parameters |
| in | The address of the procedure's arguments |
| outproc | XDR routine used to decode the procedure's results |
| out | The address at which to place the result(s) |
rpc.h - RPC include file
clnt_stat(), clnt_perrno(), clnttcp_create(), clntudp;_create()
Broadcast RPC call message.
enum clnt_stat clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult) u_long prognum, versnum, procnum; char *in, *out; xdrproc_t inproc, outproc; resultproc_t eachresult;
clnt_broadcast() is like callrpc(), except the call message is broadcast to all locally connected broadcast nets. Each time it receives a response, this routine calls eachresult(), whose form is:
eachresult(out, addr) char *out; struct sockaddr_in *addr;
| out | The same as out passed to clnt_broadcast(), except that the remote procedure's output is decoded there |
| addr | Points to the address of the machine that sent the results. |
If eachresult() returns zero, clnt_broadcast() waits for more replies; otherwise it returns with appropriate status.
Note that broadcast sockets are limited in size to the maximum transfer unit of the data link. For Ethernet, this value is 1500 bytes.
| prognum | Program number |
| versnum | Version number |
| procnum | Remote procedure |
| inproc | XDR routine used to encode the procedure's parameters |
| in | The address of the procedure's arguments |
| outproc | XDR routine used to decode the procedure's results |
| out | The address of where to place the result(s) |
| eachresult | Routine called on response receipt (see above) |
rpc.h - RPC include file
pmapclnt.h - Portmapper include file
callrpc()
Call remote procedure.
enum clnt_stat clnt_call(clnt, procnum, inproc, in, outproc, out, timeout) CLIENT *clnt; ulong procnum; xdrproc_t inproc, outproc; char *in, *out; struct timeval timeout;
clnt_call() is a macro that calls the remote procedure procnum associated with the client handle clnt which is obtained with an RPC client creation routine such as clnt_create(). This routine is called indirectly based on the pointer to the routine passed in the struct CLIENT. This call may also be called using the upper-case CLNT_CALL().
| clnt | Client handle |
| procnum | Remote procedure |
| inproc | XDR routine used to encode the procedure's parameters |
| in | The address of the procedure's argument(s) |
| outproc | XDR routine used to decode the procedure's results |
| out | The address of where to place the result(s) |
| timeout | The time allowed for results to come back |
rpc.h - RPC include file
clnt_stat(), clnt_perrno(), clnttcp_create(), clntudp_create()
Change or receive information about client object.
bool_t clnt_control(cl, req, info) CLIENT *cl; int req; char *info
clnt_control() is a macro used to change or retrieve various information about a client object. req indicates the type of operation, and info is a pointer to the information. For both UDP and TCP, the supported values of req and their argument types and what they do are:
CLSET_TIMEOUT struct timeval set total timeout CLGET_TIMEOUT struct timeval get total timeout
CLGET_SERVER_ADDR struct sockaddr get server's address
The following operations are valid for UDP only:
CLSET_RETRY_TIMEOUT struct timeval set the retry timeout CLGET_RETRY_TIMEOUT struct timeval get the retry timeout
The retry timeout is the time that UDP RPC waits for the server to reply before retransmitting the request.
This routine is called indirectly based on the pointer to the routine passed in the struct CLIENT. This call may also be called using the upper-case CLNT_CONTROL().
This routine returns TRUE on success and FALSE on failure.
| cl | Client |
| req | Indicates the type of operation |
| info | A pointer to the information. |
rpc.h - RPC include file
clnt_call()
Client creation routine.
CLIENT *clnt_create(host, prognum, versnum, proto) char *host; u_long prognum, versnum; char *proto;
clnt_create() is a generic client creation routine. Default time-outs are set, but can be modified using clnt_control().
Using UDP has its shortcomings. Since UDP-based RPC messages can only hold up to 8K of encoded data, this transport cannot be used for procedures that take large arguments or return huge results.
| host | Identifies the name of the remote host where the server is located |
| prognum | Remote program number |
| versnum | Remote version number |
| proto | Indicates which kind of transport protocol to use. The currently supported values for this field are udp and tcp. |
rpc.h - RPC include file
clnt_control(), clnt_destroy(), clnttcp_create(), clntudp_create()
Destroy client's RPC handle.
void clnt_destroy(clnt) CLIENT *clnt;
clnt_destroy() is a macro that destroys the client's RPC handle. Destruction usually involves deallocation of private data structures, including clnt itself. Use of clnt is undefined after calling clnt_destroy(). If the RPC library opened the associated socket, it will close it also. Otherwise, the socket remains open. This routine is called indirectly based on the pointer to the routine passed in the struct CLIENT. This call may also be called using the upper-case CLNT_DESTROY().
| clnt | Client handle |
rpc.h - RPC include file
clnt_stat(), clnt_perrno(), clntudp_create()
Free data allocated by result decoding.
bool_t clnt_freeres(clnt, outproc, out) CLIENT *clnt; xdrproc_t outproc; char *out;
clnt_freeres() is a macro that frees any data allocated by the RPC/XDR system when it decoded the results of an RPC call. This routine returns TRUE if the results were successfully freed, and FALSE otherwise. This routine is called indirectly based on the pointer to the routine passed in the struct CLIENT. This routine may also be called using the upper-case CLNT_FREERES().
| clnt | Client |
| outproc | The XDR routine describing the results |
| out | The address of the results |
rpc. h - RPC include file
clnt_call()
Get error structure.
void clnt_geterr(clnt, errp) CLIENT *clnt; struct rpc_err *errp;
clnt_geterr() is a macro that copies the error structure out of the client handle to the structure at address errp. This routine is called indirectly based on the pointer to the routine passed in the struct CLIENT. This routine may also be called using the upper-case CLNT_GETERR().
| clnt | Client |
| errp | The address of the error structure |
rpc.h - RPC include file
clnt_call(), clnt_call()
Print error about client creation.
void clnt_pcreateerror(str) char *str;
clnt_pcreateerror() prints a message via the rpclog() facility indicating why a client RPC handle could not be created. The message is prepended with string str and a colon. Used when a clnt_create(), clntraw_create(), clnttcp_create(), or clntudp_create() call fails.
| str | string to prepend |
rpc.h - RPC include file
clnt_create(), clntraw_create(), clnttcp_create(), clntudp_create(), and clnt_spcreateerror()
Print standard error.
void clnt_perrno(stat) enum clnt_stat stat;
clnt_perrno() prints via the rpclog() facility, a standard error corresponding to the condition indicated by stat. Used after callrpc().
| stat | error indication |
rpc.h - RPC include file
callrpc(), clnt_call(), clnt_perror(), clnt_sperror(), and clnt_sperror()
Print message for why RPC call failed.
void clnt_perror(clnt, str) CLIENT *clnt; char *str;
clnt_perror() prints a message via the rpclog() facility indicating why an RPC call failed. The message is prepended with string str and a colon. Used after clnt_call() or callrpc().
| clnt | The handle used to do the call |
| str | String prepended to message |
rpc.h - RPC include file
clnt_call(), callrpc(), clnt_perrno(), clnt_sperrno(), and clnt_sperror()
Returns a string for why RPC handle could not be created.
char *clnt_spcreateerror(str) char *str;
clnt_spcreateerror() returns a string indicating why a client RPC handle could not be created. clnt_spcreateerror() is like clnt_pcreateerror(), except that it returns a string instead of using the rpclog() facility.
| str | String to be prepended to message |
rpc.h - RPC include file
clnt_pcreateerror()
Returns pointer to string for why an RPC call failed.
char *clnt_sperrno(stat) enum clnt_stat stat;
clnt_sperrno() takes the same arguments as clnt_perrno(), but instead of sending a message to the rpclog() facility indicating why an RPC call failed, returns a pointer to a string which contains the message. The string ends with a newline.
clnt_sperrno() is used instead of clnt_perrno() if the program does not want to use the rpclog() facility, or if a message format different than that supported by clnt_perrno() is to be used.
| stat | error condition |
rpc.h - RPC include file
clnt_perrno(), clnt_sperror(), and clnt_spcreateerror()
Returns a string for why an RPC call failed.
char *clnt_sperrno(rpch, str) CLIENT *rpch; char *str;
clnt_sperror( )is like clnt_perror(), except that, like clnt_sperrno(), it returns a string instead of using the rpclog() facility.
| rpch | Handle |
| str | String |
rpc.h - RPC include file
clnt_perrno(), and clnt_perror()
Creates an RPC client.
CLIENT *clntraw_create(prognum, versnum) u_long prognum, versnum;
clntraw_create() creates an RPC client for the remote program prognum, version versnum. The transport used to pass messages to the service is actually a buffer within the task's address space, so the corresponding RPC server should live in the same address space; see svcraw_create(). This allows simulation of RPC and acquisition of RPC overheads, such as round trip times, without any network interference. This routine returns NULL if it fails.
| prognum | remote program |
| versnum | version |
rpc.h - RPC include file
svcraw_create()
Creates an RPC client which uses TCP.
CLIENT *clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz) struct sockaddr_in *addr; u_long prognum, versnum; int *sockp; u_int sendsz, recvsz;
clnttcp_create() creates an RPC client for the remote program prognum, version versnum; the client uses TCP/IP as a transport. The remote program is located at Internet address *addr. If addr->sin_port is zero, then it is set to the actual port that the remote program is listening on (the remote portmap service is consulted for this information). The parameter sockp is a socket; if it is RPC_ANYSOCK, then this routine opens a new one and sets sockp. Since TCP-based RPC uses buffered I/O, the user may specify the size of the send and receive buffers with the parameters sendsz and recvsz; values of zero choose suitable defaults. This routine returns NULL if it fails.
| addr | Internet address |
| prognum | Remote program |
| versnum | Version |
| sockp | Pointer to a socket |
| sendsz | Size of send buffer |
| recvsz | Size of receive buffer |
rpc.h - RPC include file
clntudp_create()
Creates an RPC client which uses TCP.
CLIENT *clntudp_create(addr, prognum, versnum, wait, sockp) struct sockaddr_in *addr; u_long prognum, versnum; struct timeval wait; int *sockp;
clntudp_create() creates an RPC client for the remote program prognum, version versnum; the client uses UDP/IP as a transport. The remote program is located at Internet address *addr. If addr->sin_port is zero, then it is set to the actual port that the remote program is listening on (the remote portmap service is consulted for this information). The parameter sockp is a socket; if it is RPC_ANYSOCK, then this routine opens a new one and sets sockp. The UDP transport resends the call message in intervals of wait time until a response is received or until the call times out. The total time for the call to time out is specified by clnt_call().
Since UDP-based RPC messages can only hold up to 8K of encoded data, this transport cannot be used for procedures that take large arguments or return huge results.
| addr | Internet address |
| prognum | Remote program |
| versnum | Version |
| wait | Time interval to resend message |
| sockp | Socket pointer |
rpc.h - RPC include file
clnttcp_create()
Get machine's IP address.
void get_myaddress(addr) struct sockaddr_in *addr;
get_myaddress() returns the machine's IP address in *addr, without consulting the library routines that deal with /etc/hosts. The port number is always set to htons(PMAPPORT).
| addr | Internet address |
rpc. h - RPC include file
htons()
Get RPC entry by name.
struct rpcent *getrpcbyname(name) char *name;
getrpcbyname() returns a pointer to an object with the following structure containing the information returned by the Domain Name Resolver (DNR).
structrpcent{
char *r_name; /* name of server for this rpc program */
char **r_aliases; /* alias list */
long r_number; /* rpc program number */
};
|
r_name | The name of the server for this RPC program. |
| r_aliases | A zero terminated list of alternate names for the RPC program. |
| r_number | The RPC program number for this service. |
getrpcbyname() queries DNR with a DFRPCBYN request.
| name | Name of server |
rpc.h - RPC include file
getrpcbynumber()
Get RPC entry by number.
struct rpcent *getrpcbynumber(number) int number;
getrpcbynumber() queries the Domain Name Resolver (DNR) and returns a pointer to an object with the following structure:
structrpcent{
char *r_name; /* name of server for this rpc program */
char **r_aliases; /* alias list */
long r_number; /* rpc program number */
};
|
r_name | The name of the server for this RPC program. |
| r_aliases | A zero terminated list of alternate names for the RPC program. |
| r_number | The RPC program number for this service. |
getrpcbynumber() queries DNR with a DFRPCBYV request.
| number | RPC program number |
rpc.h - RPC include file
getrpcbyname()
Call the appropriate service routine for RPC requests.
int mvs_svc_run(ecblistp, ecbcount) unsigned long **ecblistp; int ecbcount;
mvs_svc_run() waits for RPC requests to arrive, and calls the appropriate service procedure using svc_getreq() when one arrives. mvs_svc_run() is similar to svc_run() but can wait on an ECB list in addition to the socket wait. This call returns if any ECB is posted. This procedure is usually waiting for a select() system call to return. mvs_svc_run() also returns if the API shuts down or encounters a system error.
| ecblistp | pointer to ECB list |
| ecbcount | ECB count to wait on |
rpc.h - RPC include file
svc_run()
Get list of port mappings.
struct pmaplist *pmap_getmaps(addr) struct sockaddr_in *addr;
pmap_getmaps() is a user interface to the portmap service, which returns a list of the current RPC program-to-port mappings on the host located at IP address *addr. This routine can return NULL. The rpcinfo utility uses this routine.
| addr | Internet address |
rpc.h - RPC include file
pmapclnt.h - Portmapper include file
pmap_getport(), pmap_set(), pmap_unset()
Get port number for a service.
u_short pmap_getport(addr, prognum, versnum, protocol) struct sockaddr_in *addr; u_long prognum, versnum, protocol;
pmap_getmaps() is a user interface to the portmap service, which returns the port number on which a service waits that supports program number prognum, version versnum, and speaks the transport protocol associated with protocol. The value of protocol is most likely IPPROTO_UDP or IPPROTO_TCP. A return value of zero means that the mapping does not exist or that the RPC system failed to contact the remote portmap service. In the latter case, the global variable rpc_createerr() contains the RPC status.
| addr | Internet address |
| prognum | Remote program number |
| versnum | Version number |
| protocol | Transport protocol |
rpc.h - RPC include file
pmapclnt.h - Portmapper include file
pmap_getmaps(), pmap_set(), pmap_unset()
Tell portmapper to make an RPC call.
enum clnt_stat pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in, outproc, out, timeout, portp) struct sockaddr_in *addr; u_long prognum, versnum, procnum; char *in, *out; xdrproc_t inproc, outproc; struct timeval timeout; u_long *portp;
pmap_rmtcall() is a user interface to the portmap service, which instructs portmap on the host at IP address *addr to make an RPC call on your behalf to a procedure on that host. The parameter *portp will be modified to the program's port number if the procedure succeeds. The definitions of other parameters are discussed in callrpc() and clnt_call(). This procedure should be used for a ping and nothing else. See also clnt_broadcast().
| addr | Internet address |
| prognum | Remote program number |
| versnum | Version number |
| procnum | Procedure number |
| inproc | XDR procedure used to encode the procedure's parameters |
| in | The address of the procedure's arguments |
| outproc | XDR procedure used to decode the procedure's results |
| out | The address of where to place the result(s) |
| timeout | The time allowed for results to come back |
| portp | Pointer to program's port number |
rpc.h - RPC include file
pmapclnt.h - Portmapper include file
pmap_getmaps(), pmap_getport(), pmap_set(), pmap_unset()
Set portmapping.
bool_t pmap_set(prognum, versnum, protocol, port) u_long prognum, versnum, protocol; u_long port;
pmap_set() is a user interface to the portmap service, which establishes a mapping between the triple (prognum, versnum, protocol) and port on the machine's portmap service. The value of protocol is most likely IPPROTO_UDP or IPPROTO_TCP. This routine returns TRUE if it succeeds, FALSE otherwise. It is automatically done by svc_register().
| prognum | Program number |
| versnum | Version number |
| protocol | Transport protocol |
| port | Program's port number |
rpc.h - RPC include file
pmapclnt.h - Portmapper include file
pmap_getmaps(), pmap_getport(), pmap_unset()
Unset portmapping.
bool_t pmap_unset(prognum, versnum) u_long prognum, versnum;
pmap_unset() is a user interface to the portmap service, which destroys all mapping between the triple (prognum, versnum,*) and ports on the machine's portmap service. This routine returns TRUE if it succeeds, FALSE otherwise.
| prognum | Program number |
| versnum | Version number |
rpc.h - RPC include file
pmapclnt.h - Portmapper include file
pmap_getmaps(), pmap_getport(), pmap_set()
Register a procedure with RPC.
int registerrpc(prognum, versnum, procnum, procname, inproc, outproc) u_long prognum, versnum, procnum; char *(*procname)(); xdrproc_t inproc, outproc;
registerrpc() registers procedure procname with the RPC service package. If a request arrives for program prognum, version versnum, and procedure procnum, procname is called with a pointer to its parameter(s); procname should return a pointer to its static result(s); inproc is used to decode the parameters; outproc is used to encode the results. This routine returns zero if the registration succeeded, -1 otherwise.
Remote procedures registered in this form are accessed using the UDP/IP transport; see svcudp_create() for restrictions.
| prognum | Program number |
| versum | Version number |
| procnum | Procedure number |
| procname | Procedure name |
| inproc | XDR procedure used to decode the procedure's parameters |
| outproc | XDR procedure used to encode the procedure's results |
rpc.h - RPC include file
svcudp_create()
Global variable for unsuccessful client creation.
struct rpc_createerr rpc_createerr
rpc_createerr is a global variable whose value is set by any RPC client creation routine that does not succeed. Use the routine clnt_pcreateerror() to print the reason why.
rpc.h - RPC include file
clnt_pcreateerror()
Destroy RPC transport handle.
void svc_destroy(xprt) SVCXPRT *xprt;
svc_destroy() is a macro that destroys the RPC service transport handle, xprt. Destruction usually involves deallocation of private data structures, including xprt itself. Use of xprt is undefined after calling this routine. This routine is called indirectly based on the pointer to the routine passed in the struct SVCXPRT. This routine may also be called using the upper-case SVC_DESTROY().
| xprt | RPC service transport handle |
rpc.h - RPC include file
svc_freeargs(), svc_getargs(), svc_getcaller(), svc_getreqset(), svc_getreq(), svc_register(),svc_run(), svc_sendreply() svc_unregister(), svcudp_create(), svctcp_create()
Global variable for RPC's file descriptor bit mask.
fd_set svc_fdset;
svc_fdset is a global variable reflecting the RPC service side's read file descriptor bit mask. It is suitable as a parameter to the select system call. This is only of interest if a service implementor does not call svc_run(), but rather does his own asynchronous event processing. This variable may change after calls to svc_getreqset() or any creation routines.
rpc.h - RPC include file
svc_freeargs(), svc_getargs(), svc_getcaller(), svc_getreqset(), svc_getreq(), svc_register(),svc_run(), svc_sendreply() svc_unregister(), svctcp_create(), svcudp_create()
Free data allocated by svc_getargs argument decoding.
bool_t svc_freeargs(xprt, inproc, in) SVCXPRT *xprt; xdrproc_t inproc; char *in;
svc_freeargs() is a macro that frees any data allocated by the RPC/XDR system when it decoded the arguments to a service procedure using svc_getargs(). This routine returns TRUE if the results were successfully freed, and FALSE otherwise. This routine is called indirectly based on the pointer to the routine passed in the struct SVCXPRT. This routine may also be called with the upper-case SVC_FREEARGS().
| xprt | RPC service transport handle |
| inproc | used to encode the procedure's parameters |
| in | the address of the procedure's arguments |
rpc.h - RPC include file
svc_getargs(), svc_getcaller(), svc_getreqset(), svc_getreq(), svc_register(),svc_run(), svc_sendreply() svc_unregister()
Decode RPC request arguments.
bool_t svc_getargs(xprt, inproc, in) SVCXPRT *xprt; xdrproc_t inproc; char *in;
svc_getargs() is a macro that decodes the arguments of an RPC request associated with the RPC service transport handle, xprt. The parameter in is the address where the arguments will be placed; inproc is the XDR routine used to decode the arguments. This routine returns TRUE if decoding succeeds, and FALSE otherwise. This routine is called indirectly based on the pointer to the routine passed in the struct SVCXPRT. This routine may also be called with the upper-case SVC_GETARGS().
| xprt | RPC service transport handle |
| inproc | used to encode the procedure's parameters |
| in | the address of the procedure's arguments |
rpc.h - RPC include file
svc_freeargs(), svc_getcaller(), svc_getreqset(), svc_getreq(), svc_register(),svc_run(), svc_sendreply() svc_unregister()
Get network address of caller.
struct sockaddr_in *svc_getcaller(xprt) SVCXPRT *xprt;
svc_getcaller() is the approved way of getting the network address of the caller of a procedure associated with the RPC service transport handle, xprt.
| xprt | RPC service transport handle. |
rpc.h - RPC include file
svc_freeargs(), svc_getargs(), svc_getreqset(), svc_getreq(), svc_register(),svc_run(), svc_sendreply() svc_unregister()
Service an RPC request on a socket.
svc_getreq(rdfds) int rdfds;
svc_getreq() is similar to svc_getreqset(). This interface is obsoleted by svc_getreqset().
| rdfds | read file descriptor bit mask |
rpc.h - RPC include file
svc_freeargs(), svc_getargs(), svc_getcaller(), svc_getreqset(), svc_register(),svc_run(), svc_sendreply() svc_unregister()
Service an RPC request that arrived on a socket.
svc_getreqset(rdfds) fd_set *rdfds;
svc_getreqset() is only of interest if a service implementor does not call svc_run(), but instead implements custom asynchronous event processing. It is called when the select() system call has determined that an RPC request has arrived on some RPC socket(s); rdfds is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of rdfds have been serviced.
| rdfds | read file descriptor bit mask. |
rpc.h - RPC include file
svc_freeargs(), svc_getargs(), svc_getcaller(), svc_getreq(), svc_register(), svc_run(), svc_sendreply(), svc_unregister()
Register procedure with service dispatch procedure.
bool_t svc_register(xprt, prognum, versnum, dispatch, protocol) SVCXPRT *xprt; u_long prognum, versnum; void (*dispatch) (); u_long protocol;
svc_register() associates prognum and versnum with the service dispatch procedure, dispatch. If protocol is zero, the service is not registered with the portmap service. If protocol is non-zero, then a mapping of the triple [prognum, versnum, protocol] to xprt->xp_port is established with the local portmap service (generally protocol is zero, IPPROTO_UDP or IPPROTO_TCP). The procedure dispatch has the following form:
dispatch(request, xprt) struct svc_req *request; SVCXPRT *xprt;
The svc_register() routine returns TRUE if it succeeds, and FALSE otherwise.
| xprt | RPC service transport handle |
| prognum | program number |
| versnum | version number |
| dispatch | service dispatch procedure |
| protocol | transport protocol |
rpc.h - RPC include file
svc_freeargs(), svc_getargs(), svc_getcaller(), svc_getreqset(), svc_getreq(), svc_run(), svc_sendreply() svc_unregister()
Call the appropriate service routine for RPC requests.
void svc_run()
svc_run() waits for RPC requests to arrive, and calls the appropriate service procedure using svc_getreq() when one arrives. This procedure is usually waiting for a select() system call to return. svc_run() doesn't return unless the API shuts down or encounters a system error.
rpc.h - RPC include file
svc_freeargs(), svc_getargs(), svc_getcaller(), svc_getreqset(), svc_getreq(), svc_register(), svc_sendreply() svc_unregister()
Send results of remote procedure call.
bool_t svc_sendreply(xprt, outproc, out) SVCXPRT *xprt; xdrproc_ t outproc; char *out;
svc_sendreply() is called by an RPC service's routine to send the results of a remote procedure call. The parameter xprt is the request's associated transport handle; outproc is the XDR routine which is used to encode the results; and out is the address of the results. This routine returns TRUE if it succeeds, FALSE otherwise.
| xprt | RPC service transport handle |
| outproc | XDR routine used to decode the procedure's results |
| out | The address of where to place the result(s) |
rpc.h - RPC include file
svc_freeargs(), svc_getargs(), svc_getcaller(), svc_getreqset(), svc_getreq(), svc_register(), svc_sendreply() svc_unregister()
Remove mapping to dispatch routines.
void svc_unregister(prognum, versnum) u_long prognum, versnum;
svc_unregister() removes all mapping of the double [prognum, versnum] to dispatch routine, and of the triple [prognum, versnum,*] to port number.
| prognum | Program number |
| versnum | Version number |
rpc.h - RPC include file
svc_freeargs(), svc_getargs(), svc_getcaller(), svc_getreqset(), svc_getreq(), svc_register(), svc_sendreply()
Called when insufficient authentication parameters are given.
void svcerr_weakauth(xprt) SVCXPRT *xprt;
svcerr_weakauth() is called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient (but correct) authentication parameters. The routine calls svcerr_auth(xprt, AUTH_TOOWEAK).
| xprt | RPC service transport handle |
rpc.h - RPC include file
svcerr_auth(), svcerr_decode(), svcerr_noproc(), svcerr_noprog(), svcerr_progvers(), svcerr_systemerr()
Called after an authentication error.
void svcerr_auth(xprt, why) SVCXPRT *xprt enum auth_stat why;
svcerr_auth() is called by a service dispatch routine that refuses to perform a remote procedure call due to an authentication error.
| xprt | RPC service transport handle |
| why | Error |
rpc.h - RPC include file
svcerr_decode(), svcerr_noproc(), svcerr_noprog(), svcerr_progvers(), svcerr_systemerr(), svcerr_weakauth()
Called for parameter decoding error.
void svcerr_decode(xprt) SVCXPRT *xprt;
svcerr_decode() is called by a service dispatch routine that cannot successfully decode its parameters. See also svc_getargs().
| xprt | RPC service transport handle |
rpc.h - RPC include file
svcerr_auth(), svcerr_noproc(), svcerr_noprog(), svcerr_progvers(), svcerr_systemerr(), svcerr_weakauth()
Called for procedure number error.
void svcerr_noproc(xprt) SVCXPRT *xprt;
svcerr_noproc() is called by a service dispatch routine that does not implement the procedure number that the caller requests.
| xprt | RPC service transport handle |
rpc.h - RPC include file
svcerr_auth(), svcerr_decode(), svcerr_noprog(), svcerr_progvers(), svcerr_systemerr(), svcerr_weakauth()
Called when program is not registered.
void svcerr_noprog(xprt) SVCXPRT *xprt;
svcerr_noprog() is called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine.
| xprt | RPC service transport handle |
rpc.h - RPC include file
svcerr_auth(), svcerr_decode(), svcerr_noproc(), svcerr_progvers(), svcerr_systemerr(), svcerr_weakauth()
Called when program version is not registered.
void svcerr_progvers(xprt) SVCXPRT *xprt;
svcerr_progvers() is called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine.
| xprt | RPC service transport handle |
rpc.h - RPC include file
svcerr_auth(), svcerr_decode(), svcerr_noproc(), svcerr_noprog(),svcerr_systemerr(), svcerr_weakauth()
Called when a system error is detected.
void svcerr_systemerr(xprt) SVCXPRT *xprt;
svcerr_systemerr() is 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.
| xprt | RPC service transport handle |
rpc.h - RPC include file
svcerr_auth(), svcerr_decode(), svcerr_noproc(), svcerr_noprog(), svcerr_progvers(), svcerr_weakauth()
Create a service on top of any open descriptor.
void svcfd_create(fd, sendsize, recvsize) int fd; u_int sendsize; u_int recvsize;
svcfd_create() creates a service on top of any open descriptor. Typically, this descriptor is a connected socket for a stream protocol such as TCP. sendsize and recvsize indicate sizes for the send and receive buffers. If they are zero, a reasonable default is chosen.
| fd | Descriptor |
| endsize | Size of send buffer |
| recvsize | Size of receive buffer |
rpc.h - RPC include file
svctcp_create(), svcudp_create()
Create an RPC service transport.
SVCXPRT *svcraw_create()
svcraw_create() creates an RPC service transport, to which it returns a pointer. 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 clntraw_create(). This routine allows simulation of RPC and acquisition of RPC overheads (such as round trip times), without any kernel interference. This routine returns NULL if it fails.
rpc.h - RPC include file
clntraw_create()
Create a TCP/IP based service transport.
SVCXPRT *svctcp_create(sock, send_buf_size, recv_buf_size) int sock; u_int send_buf_size, recv_buf_size;
svctcp_create() creates a TCP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket sock, which may be RPC_ANYSOCK, in which case a new socket is created. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. Upon completion, xprt->xp_sock is the transport's socket descriptor; xprt->xp_port is the transport's port number. This routine returns NULL if it fails. Since TCP- based RPC uses buffered I/O, users may specify the size of buffers; values of zero choose suitable defaults.
| sock | Socket |
| send_buf_size | Size of send buffer |
| recv_buf_size | Size of receive buffer |
rpc.h - RPC include file
svcudp_create()
Create a UDP/IP based service transport.
SVCXPRT *svcudp_create(sock) int sock;
svcudp_create() creates a UDP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket sock, which may be RPC_ANYSOCK, in which case a new socket is created. If the socket is not bound to a local UDP port, then this routine binds it to an arbitrary port. Upon completion, xprt->xp_sock is the transport's socket descriptor; whereas the field xprt->xp_port is the transport's port number. This routine returns NULL if it fails.
Since UDP-based RPC messages can only hold up to 8K of encoded data, this transport cannot be used for procedures that take large arguments or return huge results.
| sock | Socket |
rpc.h - RPC include file
svctcp_create()
Encode RPC reply messages.
bool_t xdr_accepted_reply(xdrs, ar) XDR *xdrs; struct accepted_reply *ar;
xdr_accepted_reply() is used for encoding RPC reply messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.
This routine returns TRUE if successful, otherwise it returns FALSE.
| xdrs | XDR structure |
| ar | Reply |
rpc.h - RPC include file
xdr_authunix_parms(), xdr_callhdr(), xdr_callmsg(), xdr_opaque_auth(), xdr_pmap(), xdr_pmaplist(), xdr_rejected_reply(), xdr_replymsg()
Describe UNIX credentials.
bool_t xdr_authunix_parms(xdrs, aupp) XDR *xdrs; struct authunix_parms *aupp;
xdr_authunix_parms() is used for describing UNIX credentials. This routine is useful for users who wish to generate these credentials without using the RPC authentication package.
This routine returns TRUE if successful, otherwise it returns FALSE.
| xdrs | XDR structure |
| aupp | UNIX credentials |
rpc.h - RPC include file
xdr_accepted_reply(), xdr_callhdr(), xdr_callmsg(), xdr_opaque_auth(), xdr_pmap(), xdr_pmaplist(), xdr_rejected_reply(), xdr_replymsg()
Describe RPC call header messages.
void xdr_callhdr(xdrs, chdr) XDR *xdrs; struct rpc_msg *chdr;
xdr_callhdr() is used for describing RPC call header messages. It encodes the static part of the call message header in the XDR language format. It includes information such as transaction ID, RPC version number, program number, and version number. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.
| xdrs | XDR structure |
| chdr | Call header message |
rpc.h - RPC include file
xdr_accepted_reply(), xdr_authunix_parms(), xdr_callmsg(), xdr_opaque_auth(), xdr_pmap(), xdr_pmaplist(), xdr_rejected_reply(), xdr_replymsg()
Describe RPC call messages.
bool_t xdr_callmsg(xdrs, cmsg) XDR *xdrs; struct rpc_msg *cmsg;
xdr_callmsg() is used for describing RPC call messages. It includes all the RPC call information such as transaction ID, RPC version number, program number and version number, authentication information, etc. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.
This routine returns TRUE if successful, FALSE otherwise.
| xdrs | XDR structure |
| cmsg | Call message |
rpc.h - RPC include file
xdr_accepted_reply(), xdr_authunix_parms(), xdr_callhdr(), xdr_opaque_auth(), xdr_pmap(), xdr_pmaplist(), xdr_rejected_reply(), xdr_replymsg()
Describe RPC authentication information message.
bool_t xdr_opaque_auth(xdrs, ap) XDR *xdrs; struct opaque_auth *ap;
xdr_opaque_auth() is used for describing RPC authentication information messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.
This routine returns TRUE if successful, FALSE otherwise.
| xdrs | XDR structure |
| ap | Authentication information message |
rpc.h - RPC include file
xdr_accepted_reply(), xdr_authunix_parms(), xdr_callhdr(), xdr_callmsg(), xdr_pmap(), xdr_pmaplist(), xdr_rejected_reply(), xdr_replymsg()
Describe parameters to portmap procedures.
bool_t xdr_pmap(xdrs,regs) XDR *xdrs; struct pmap *regs;
xdr_pmap() is used for describing parameters to various portmap procedures, externally. This routine is useful for users who wish to generate RPC-style messages without using the pmap package.
This routine returns TRUE if successful, FALSE otherwise.
| xdrs | XDR structure |
| regs | Portmap parameters |
rpc.h - RPC include file
pmapport.h - Portmap include file
xdr_accepted_reply(), xdr_authunix_parms(), xdr_callhdr(), xdr_callmsg(), xdr_opaque_auth(), xdr_pmaplist(), xdr_rejected_reply(), xdr_replymsg()
Describe list of portmappings.
bool_t xdr_pmaplist(xdrs, rp) XDR *xdrs; struct pmaplist **rp;
xdr_pmaplist() is used for describing a list of port mappings, externally. This routine is useful for users who wish to generate RPC-style messages without using the pmap interface.
This routine returns TRUE if successful, FALSE otherwise.
| xdrs | XDR structure |
| rp | port mapping list |
rpc.h -RPC include file
pmapport.h - portmap include file
xdr_accepted_reply(), xdr_authunix_parms(), xdr_callhdr(), xdr_callmsg(), xdr_opaque_auth(), xdr_pmap(), xdr_rejected_reply(), xdr_replymsg()
Describe RPC reply messages.
bool_t xdr_rejected_reply(xdrs, rr) XDR *xdrs; struct rejected_reply *rr;
xdr_rejected_reply() is used for describing RPC reply messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.
This routine returns TRUE if successful, FALSE otherwise.
| xdrs | XDR structure |
| rr | Reply message. |
rpc.h - RPC include file
xdr_accepted_reply(), xdr_authunix_parms(), xdr_callhdr(), xdr_callmsg(), xdr_opaque_auth(), xdr_pmap(), xdr_pmaplist(), xdr_replymsg()
Describe RPC reply messages.
bool_t xdr_replymsg(xdrs, rmsg) XDR *xdrs; struct rpc_msg *rmsg;
xdr_replymsg() is used for describing RPC reply messages. This reply could be an acceptance, rejection, or NULL. This routine is useful for users who wish to generate RPC-style messages without using the RPC package.
This routine returns TRUE if successful, FALSE otherwise.
| xdrs | XDR structure |
| rms | Reply message |
rpc.h - RPC include file
xdr_accepted_reply(), xdr_authunix_parms(), xdr_callhdr(), xdr_callmsg(), xdr_opaque_auth(), xdr_pmap(), xdr_pmaplist(), xdr_rejected_reply()
Register RPC service transport handle.
void xprt_register(xprt) SVCXPRT *xprt;
xprt_register() is used after RPC service transport handles are created, to register them with the RPC service package. This routine modifies the global variable svc_fds. Service implementors usually do not need this routine.
| xprt | RPC service transport handle. |
rpc.h - RPC include file
xprt_unregister()
Unregister RPC service transport handle.
void xprt_unregister(xprt) SVCXPRT *xprt;
xprt_unregister() is used before an RPC service transport handle is destroyed, to unregister it with the RPC service package. This routine modifies the global variable svc_fds. Service implementors usually do not need this routine.
| xprt | RPC service transport handle |
rpc.h - RPC include file
xprt_unregister()
|
|