SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

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

RPC_CLNT_CREATE

Section: C Library Functions (3)
Index
BSD mandoc
 

NAME

rpc_clnt_create clnt_control clnt_create clnt_create_timed clnt_create_vers clnt_create_vers_timed clnt_destroy clnt_dg_create clnt_pcreateerror clnt_raw_create clnt_spcreateerror clnt_tli_create clnt_tp_create clnt_tp_create_timed clnt_vc_create rpc_createerr - library routines for dealing with creation and manipulation ofVt CLIENThandles 

SYNOPSIS

In rpc/rpc.hFt bool_tFn clnt_control CLIENT *clnt const u_int req char *infoFt CLIENT *Fn clnt_create const char * host const rpcprog_t prognum const rpcvers_t versnum const char *nettypeFt CLIENT *Fn clnt_create_timed const char * host const rpcprog_t prognum const rpcvers_t versnum const char *nettype const struct timeval *timeoutFt CLIENT *Fn clnt_create_vers const char * host const rpcprog_t prognum rpcvers_t *vers_outp const rpcvers_t vers_low const rpcvers_t vers_high const char *nettypeFt CLIENT *Fn clnt_create_vers_timed const char * host const rpcprog_t prognum rpcvers_t *vers_outp const rpcvers_t vers_low const rpcvers_t vers_high char *nettype const struct timeval *timeoutFt voidFn clnt_destroy CLIENT *clntFt CLIENT *Fn clnt_dg_create const int fildes const struct netbuf *svcaddr const rpcprog_t prognum const rpcvers_t versnum const u_int sendsz const u_int recvszFt voidFn clnt_pcreateerror const char *sFt char *Fn clnt_spcreateerror const char *sFt CLIENT *Fn clnt_raw_create const rpcprog_t prognum const rpcvers_t versnumFt CLIENT *Fn clnt_tli_create const int fildes const struct netconfig *netconf const struct netbuf *svcaddr const rpcprog_t prognum const rpcvers_t versnum const u_int sendsz const u_int recvszFt CLIENT *Fn clnt_tp_create const char * host const rpcprog_t prognum const rpcvers_t versnum const struct netconfig *netconfFt CLIENT *Fn clnt_tp_create_timed const char * host const rpcprog_t prognum const rpcvers_t versnum const struct netconfig *netconf const struct timeval *timeoutFt CLIENT *Fn clnt_vc_create const int fildes const struct netbuf *svcaddr const rpcprog_t prognum const rpcvers_t versnum u_int sendsz u_int recvsz 

DESCRIPTION

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

Routines

Fn clnt_control
A function macro to change or retrieve various informationabout a client object.TheFa reqargumentindicates the type of operation, andFa infois a pointer to the information.For both connectionless and connection-oriented transports,the supported values ofFa reqand their argument types and what they do are:

CLSET_TIMEOUT Ta struct timeval * Ta set total timeout
CLGET_TIMEOUT Ta struct timeval * Ta get total timeout

Note:if you set the timeout usingFn clnt_control ,the timeout argument passed byFn clnt_callis ignored in all subsequent calls.

Note:If you set the timeout value to 0,Fn clnt_controlimmediately returns an error(RPC_TIMEDOUT) Set the timeout argument to 0 for batching calls.

CLGET_SVC_ADDR Ta struct netbuf * Ta get servers address
CLGET_FD Ta int * Ta get fd from handle
CLSET_FD_CLOSE Ta void Ta close fd on destroy
CLSET_FD_NCLOSE Ta void Ta don't close fd on destroy
CLGET_VERS Ta u_int32_t * Ta get RPC program version
CLSET_VERS Ta u_int32_t * Ta set RPC program version
CLGET_XID Ta u_int32_t * Ta get XID of previous call
CLSET_XID Ta u_int32_t * Ta set XID of next call

The following operations are valid for connectionless transports only:

CLSET_RETRY_TIMEOUT Ta struct timeval * Ta set the retry timeout
CLGET_RETRY_TIMEOUT Ta struct timeval * Ta get the retry timeout
CLSET_CONNECT Ta Vt int * Ta use connect(2)

The retry timeout is the time that RPCwaits for the server to reply before retransmitting the request.TheFn clnt_controlfunctionreturnsTRUEon success andFALSEon failure.

Fn clnt_create
Generic client creation routine for programFa prognumand versionFa versnum .TheFa hostargumentidentifies the name of the remote host where the serveris located.TheFa nettypeargumentindicates the class of transport protocol to use.The transports are tried in left to right order inNETPATHenvironment variable or in top to bottom order inthe netconfig database.TheFn clnt_createfunctiontries all the transports of theFa nettypeclass available from theNETPATHenvironment variable and the netconfig database,and chooses the first successful one.A default timeout is set and can be modified usingFn clnt_control .This routine returnsNULLif it fails.TheFn clnt_pcreateerrorroutine can be used to print the reason for failure.

Note:Fn clnt_createreturns a valid client handle evenif the particular version number supplied toFn clnt_createis not registered with therpcbind(8)service.This mismatch will be discovered by aFn clnt_calllater (seerpc_clnt_calls3).

Fn clnt_create_timed
Generic client creation routine which is similar toFn clnt_createbut which also has the additional argumentFa timeoutthat specifies the maximum amount of time allowed foreach transport class tried.In all other respects, theFn clnt_create_timedcall behaves exactly like theFn clnt_createcall.
Fn clnt_create_vers
Generic client creation routine which is similar toFn clnt_createbut which also checks for theversion availability.TheFa hostargumentidentifies the name of the remote host where the serveris located.TheFa nettypeargumentindicates the class transport protocols to be used.If the routine is successful it returns a client handle created forthe highest version betweenFa vers_lowandFa vers_highthat is supported by the server.TheFa vers_outpargumentis set to this value.That is, after a successful returnFa vers_low<=Fa *vers_outp<=Fa vers_high .If no version betweenFa vers_lowandFa vers_highis supported by the server then the routine fails and returnsNULL A default timeout is set and can be modified usingFn clnt_control .This routine returnsNULLif it fails.TheFn clnt_pcreateerrorroutine can be used to print the reason for failure.Note:Fn clnt_createreturns a valid client handle evenif the particular version number supplied toFn clnt_createis not registered with therpcbind(8)service.This mismatch will be discovered by aFn clnt_calllater (seerpc_clnt_calls3).However,Fn clnt_create_versdoes this for you and returns a valid handleonly if a version withinthe range supplied is supported by the server.
Fn clnt_create_vers_timed
Generic client creation routine which is similar toFn clnt_create_versbut which also has the additional argumentFa timeoutthat specifies the maximum amount of time allowed foreach transport class tried.In all other respects, theFn clnt_create_vers_timedcall behaves exactly like theFn clnt_create_verscall.
Fn clnt_destroy
A function macro that destroys the client's RPC handle.Destruction usually involves deallocationof private data structures, includingFa clntitself.Use ofFa clntis undefined after callingFn clnt_destroy .If the RPC library opened the associated file descriptor, orCLSET_FD_CLOSEwas set usingFn clnt_control ,the file descriptor will be closed.The caller should callFn auth_destroy clnt->cl_auth(before callingFn clnt_destroy )to destroy the associatedVt AUTHstructure (seerpc_clnt_auth3).
Fn clnt_dg_create
This routine creates an RPC client for the remote programFa prognumand versionFa versnum ;the client uses a connectionless transport.The remote program is located at addressFa svcaddr .TheFa fildesargumentis an open and bound file descriptor.This routine will resend the call message in intervals of15 seconds until a response is received or until thecall times out.The total time for the call to time out is specified byFn clnt_call(seeFn clnt_callinrpc_clnt_calls3).The retry time out and the total time out periods canbe changed usingFn clnt_control .The user may set the size of the send and receivebuffers with theFa sendszandFa recvszarguments;values of 0 choose suitable defaults.This routine returnsNULLif it fails.
Fn clnt_pcreateerror
Print a message to standard error indicatingwhy a client RPC handle could not be created.The message is prepended with the stringFa sand a colon, and appended with a newline.
Fn clnt_spcreateerror
LikeFn clnt_pcreateerror ,except that it returns a stringinstead of printing to the standard error.A newline is not appended to the message in this case.Warning:returns a pointer to a buffer that is overwrittenon each call.
Fn clnt_raw_create
This routine creates an RPCclient handle for the remote programFa prognumand versionFa versnum .The transport used to pass messages to the service isa buffer within the process's address space,so the corresponding RPCserver should live in the same address space;(seeFn svc_raw_createinrpc_svc_create3).This allows simulation of RPC and measurement ofRPC overheads, such as round trip times,without any kernel or networking interference.This routine returnsNULLif it fails.TheFn clnt_raw_createfunctionshould be called afterFn svc_raw_create .
Fn clnt_tli_create
This routine creates an RPCclient handle for the remote programFa prognumand versionFa versnum .The remote program is located at addressFa svcaddr .IfFa svcaddrisNULLand it is connection-oriented, it is assumed that the file descriptoris connected.For connectionless transports, ifFa svcaddrisNULL RPC_UNKNOWNADDRerror is set.TheFa fildesargumentis a file descriptor which may be open, bound and connected.If it isRPC_ANYFD it opens a file descriptor on the transport specified byFa netconf .IfFa fildesisRPC_ANYFDandFa netconfisNULL aRPC_UNKNOWNPROTOerror is set.IfFa fildesis unbound, then it will attempt to bind the descriptor.The user may specify the size of the buffers with theFa sendszandFa recvszarguments;values of 0 choose suitable defaults.Depending upon the type of the transport (connection-orientedor connectionless),Fn clnt_tli_createcalls appropriate client creation routines.This routine returnsNULLif it fails.TheFn clnt_pcreateerrorroutine can be used to print the reason for failure.The remote rpcbindservice (seerpcbind(8))is not consulted for the address of the remoteservice.
Fn clnt_tp_create
LikeFn clnt_createexceptFn clnt_tp_createtries only one transport specified throughFa netconf .TheFn clnt_tp_createfunctioncreates a client handle for the programFa prognum ,the versionFa versnum ,and for the transport specified byFa netconf .Default options are set,which can be changed usingFn clnt_controlcalls.The remote rpcbind service on the hostFa hostis consulted for the address of the remote service.This routine returnsNULLif it fails.TheFn clnt_pcreateerrorroutine can be used to print the reason for failure.
Fn clnt_tp_create_timed
LikeFn clnt_tp_createexceptFn clnt_tp_create_timedhas the extra argumentFa timeoutwhich specifies the maximum time allowed forthe creation attempt to succeed.In all other respects, theFn clnt_tp_create_timedcall behaves exactly like theFn clnt_tp_createcall.
Fn clnt_vc_create
This routine creates an RPCclient for the remote programFa prognumand versionFa versnum ;the client uses a connection-oriented transport.The remote program is located at addressFa svcaddr .TheFa fildesargumentis an open and bound file descriptor.The user may specify the size of the send and receive bufferswith theFa sendszandFa recvszarguments;values of 0 choose suitable defaults.This routine returnsNULLif it fails.The addressFa svcaddrshould not beNULLand should point to the actual address of the remote program.TheFn clnt_vc_createfunctiondoes not consult the remote rpcbind service for this information.
Vt struct rpc_createerr Va rpc_createerr ;
A global variable whose value is set by any RPCclient handle creation routinethat fails.It is used by the routineFn clnt_pcreateerrorto print the reason for the failure.

 

AVAILABILITY

These functions are part of libtirpc. 

SEE ALSO

rpc(3),rpc_clnt_auth3,rpc_clnt_calls3,rpcbind(8)


 

Index

NAME
SYNOPSIS
DESCRIPTION
Routines
AVAILABILITY
SEE ALSO

This document was created byman2html,using the manual pages.