MAN page from PCLinuxOS lib64tirpc-devel-1.0.1-1pclos2017.x86_64.rpm


Section: C Library Functions (3)
BSD mandoc


rpc_clnt_calls clnt_call clnt_freeres clnt_geterr clnt_perrno clnt_perror clnt_sperrno clnt_sperror rpc_broadcast rpc_broadcast_exp rpc_call - library routines for client side calls 


In rpc/rpc.hFt enum clnt_statFn clnt_call CLIENT *clnt const rpcproc_t procnum const xdrproc_t inproc const caddr_t in const xdrproc_t outproc caddr_t out const struct timeval toutFt bool_tFn clnt_freeres CLIENT *clnt const xdrproc_t outproc caddr_t outFt voidFn clnt_geterr const CLIENT * clnt struct rpc_err * errpFt voidFn clnt_perrno const enum clnt_stat statFt voidFn clnt_perror CLIENT *clnt const char *sFt char *Fn clnt_sperrno const enum clnt_stat statFt char *Fn clnt_sperror CLIENT *clnt const char * sFt enum clnt_statFo rpc_broadcastFa const rpcprog_t prognum const rpcvers_t versnumFa const rpcproc_t procnum const xdrproc_t inprocFa const caddr_t in const xdrproc_t outproc caddr_t outFa const resultproc_t eachresult const char *nettypeFc Ft enum clnt_statFo rpc_broadcast_expFa const rpcprog_t prognum const rpcvers_t versnumFa const rpcproc_t procnum const xdrproc_t xargsFa caddr_t argsp const xdrproc_t xresultsFa caddr_t resultsp const resultproc_t eachresultFa const int inittime const int waittimeFa const char * nettypeFc Ft enum clnt_statFo rpc_callFa const char *host const rpcprog_t prognumFa const rpcvers_t versnum const rpcproc_t procnumFa const xdrproc_t inproc const char *inFa const xdrproc_t outproc char *out const char *nettypeFc  


RPC library routines allow C language programs to make procedurecalls on other machines across the network.First, the client calls a procedure to send a request to the server.Upon receipt of the request, the server calls a dispatch routineto perform the requested service, and then sends back a reply.

TheFn clnt_call ,Fn rpc_call ,andFn rpc_broadcastroutines handle the client side of the procedure call.The remaining routines deal with error handling in the case of errors.

Some of the routines take aVt CLIENThandle as one of the arguments.AVt CLIENThandle can be created by an RPC creation routine such asFn clnt_create(seerpc_clnt_create3).

These routines are safe for use in multithreaded applications.Vt CLIENThandles can be shared between threads, however in this implementationrequests by different threads are serialized (that is, the first request willreceive its results before the second request is sent). 


Seerpc(3)for the definition of theVt CLIENTdata structure.

Fn clnt_call
A function macro that calls the remote procedureFa procnumassociated with the client handle,Fa clnt ,which is obtained with an RPCclient creation routine such asFn clnt_create(seerpc_clnt_create3).TheFa inprocargumentis the XDR function used to encode the procedure's arguments, andFa outprocis the XDR function used to decode the procedure's results;Fa inis the address of the procedure's argument(s), andFa outis the address of where to place the result(s).TheFa toutargumentis the time allowed for results to be returned, which is overridden bya time-out set explicitly throughFn clnt_control ,seerpc_clnt_create3.If the remote call succeeds, the status returned isRPC_SUCCESS otherwise an appropriate status is returned.
Fn clnt_freeres
A function macro that frees any data allocated by theRPC/XDR system when it decoded the results of an RPC call.TheFa outargumentis the address of the results, andFa outprocis the XDR routine describing the results.This routine returns 1 if the results were successfully freed,and 0 otherwise.
Fn clnt_geterr
A function macro that copies the error structure out of the clienthandle to the structure at addressFa errp .
Fn clnt_perrno
Print a message to standard error correspondingto the condition indicated byFa stat .A newline is appended.Normally used after a procedure call fails for a routinefor which a client handle is not needed, for instanceFn rpc_call .
Fn clnt_perror
Print a message to the standard error indicating why anRPC call failed;Fa clntis the handle used to do the call.The message is prepended with stringFa sand a colon.A newline is appended.Normally used after a remote procedure call failsfor a routine which requires a client handle,for instanceFn clnt_call .
Fn clnt_sperrno
Take the same arguments asFn clnt_perrno ,but instead of sending a message to the standard errorindicating why an RPCcall failed, return a pointer to a string which contains the message.TheFn clnt_sperrnofunctionis normally used instead ofFn clnt_perrnowhen the program does not have a standard error (as a programrunning as a server quite likely does not), or if the programmerdoes not want the message to be output withFn printf(seeprintf(3)),or if a message format different than that supported byFn clnt_perrnois to be used.Note:unlikeFn clnt_sperrorandFn clnt_spcreateerror(seerpc_clnt_create3),Fn clnt_sperrnodoes not return pointer to static data so theresult will not get overwritten on each call.
Fn clnt_sperror
LikeFn clnt_perror ,except that (likeFn clnt_sperrno )it returns a string instead of printing to standard error.However,Fn clnt_sperrordoes not append a newline at the end of the message.Warning:returns pointer to a buffer that is overwrittenon each call.
Fn rpc_broadcast
LikeFn rpc_call ,except the call message is broadcast toall the connectionless transports specified byFa nettype .IfFa nettypeisNULL it defaults toQq netpath .Each time it receives a response,this routine callsFn eachresult ,whose form is:Ft bool_tFn eachresult caddr_t out const struct netbuf * addr const struct netconfig * netconfwhereFa outis the same asFa outpassed toFn rpc_broadcast ,except that the remote procedure's output is decoded there;Fa addrpoints to the address of the machine that sent the results, andFa netconfis the netconfig structure of the transport on which the remoteserver responded.IfFn eachresultreturns 0,Fn rpc_broadcastwaits for more replies;otherwise it returns with appropriate status.Warning:broadcast file descriptors are limited in size to themaximum transfer size of that transport.For Ethernet, this value is 1500 bytes.TheFn rpc_broadcastfunctionusesAUTH_SYScredentials by default (seerpc_clnt_auth3).
Fn rpc_broadcast_exp
LikeFn rpc_broadcast ,except that the initial timeout,Fa inittimeand the maximum timeout,Fa waittimeare specified in milliseconds.TheFa inittimeargumentis the initial time thatFn rpc_broadcast_expwaits before resending the request.After the first resend, the re-transmission intervalincreases exponentially until it exceedsFa waittime .
Fn rpc_call
Call the remote procedure associated withFa prognum ,Fa versnum ,andFa procnumon the machine,Fa host .TheFa inprocargumentis used to encode the procedure's arguments, andFa outprocis used to decode the procedure's results;Fa inis the address of the procedure's argument(s), andFa outis the address of where to place the result(s).TheFa nettypeargumentcan be any of the values listed onrpc(3).This routine returnsRPC_SUCCESSif it succeeds,or an appropriate status is returned.Use theFn clnt_perrnoroutine to translate failure status into error messages.Warning:Fn rpc_calluses the first available transport belongingto the classFa nettype ,on which it can create a connection.You do not have control of timeouts or authenticationusing this routine.



These functions are part of libtirpc. 






This document was created byman2html,using the manual pages.