{
    "mode": "man",
    "parameter": "rpc_clnt_create",
    "section": "3t",
    "url": "https://www.chedong.com/phpMan.php/man/rpc_clnt_create/3t/json",
    "generated": "2026-06-02T15:56:57Z",
    "synopsis": "",
    "sections": {
        "NAME": {
            "content": "rpcclntcreate, clntcontrol, clntcreate, clntcreatetimed, clntcreatevers,\nclntcreateverstimed, clntdestroy, clntdgcreate, clntpcreateerror, clntrawcreate,\nclntspcreateerror, clnttlicreate, clnttpcreate, clnttpcreatetimed, clntvccreate,\nrpccreateerr — library routines for dealing with creation and manipulation of CLIENT handles\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "",
            "subsections": [
                {
                    "name": "#include <rpc/rpc.h>",
                    "content": "boolt\nclntcontrol(CLIENT *clnt, const uint req, char *info);\n\nCLIENT *\nclntcreate(const char * host, const rpcprogt prognum, const rpcverst versnum,\nconst char *nettype);\n\nCLIENT *\nclntcreatetimed(const char * host, const rpcprogt prognum, const rpcverst versnum,\nconst char *nettype, const struct timeval *timeout);\n\nCLIENT *\nclntcreatevers(const char * host, const rpcprogt prognum, rpcverst *versoutp,\nconst rpcverst verslow, const rpcverst vershigh, const char *nettype);\n\nCLIENT *\nclntcreateverstimed(const char * host, const rpcprogt prognum, rpcverst *versoutp,\nconst rpcverst verslow, const rpcverst vershigh, char *nettype,\nconst struct timeval *timeout);\n\nvoid\nclntdestroy(CLIENT *clnt);\n\nCLIENT *\nclntdgcreate(const int fildes, const struct netbuf *svcaddr, const rpcprogt prognum,\nconst rpcverst versnum, const uint sendsz, const uint recvsz);\n\nvoid\nclntpcreateerror(const char *s);\n\nchar *\nclntspcreateerror(const char *s);\n\nCLIENT *\nclntrawcreate(const rpcprogt prognum, const rpcverst versnum);\n\nCLIENT *\nclnttlicreate(const int fildes, const struct netconfig *netconf,\nconst struct netbuf *svcaddr, const rpcprogt prognum, const rpcverst versnum,\nconst uint sendsz, const uint recvsz);\n\nCLIENT *\nclnttpcreate(const char * host, const rpcprogt prognum, const rpcverst versnum,\nconst struct netconfig *netconf);\n\nCLIENT *\nclnttpcreatetimed(const char * host, const rpcprogt prognum, const rpcverst versnum,\nconst struct netconfig *netconf, const struct timeval *timeout);\n\nCLIENT *\nclntvccreate(const int fildes, const struct netbuf *svcaddr, const rpcprogt prognum,\nconst rpcverst versnum, uint sendsz, uint recvsz);\n"
                }
            ]
        },
        "DESCRIPTION": {
            "content": "RPC library routines allow C language programs to make procedure calls on other machines across\nthe network.  First a CLIENT handle is created and then the client calls a procedure to send a\nrequest to the server.  On receipt of the request, the server calls a dispatch routine to per‐\nform the requested service, and then sends a reply.\n",
            "subsections": []
        },
        "Routines": {
            "content": "clntcontrol()\nA function macro to change or retrieve various information about a client object.  The\nreq argument indicates the type of operation, and info is a pointer to the informa‐\ntion.  For both connectionless and connection-oriented transports, the supported val‐\nues of req and their argument types and what they do are:\n\nCLSETTIMEOUT      struct timeval *    set total timeout\nCLGETTIMEOUT      struct timeval *    get total timeout\n\nNote: if you set the timeout using clntcontrol(), the timeout argument passed by\nclntcall() is ignored in all subsequent calls.\n\nNote: If you set the timeout value to 0, clntcontrol() immediately returns an error\n(RPCTIMEDOUT).  Set the timeout argument to 0 for batching calls.\n\nCLGETSVCADDR     struct netbuf *     get servers address\nCLGETFD           int *               get fd from handle\nCLSETFDCLOSE     void                close fd on destroy\nCLSETFDNCLOSE    void                don't close fd on destroy\nCLGETVERS         uint32t *         get RPC program version\nCLSETVERS         uint32t *         set RPC program version\nCLGETXID          uint32t *         get XID of previous call\nCLSETXID          uint32t *         set XID of next call\n\nThe following operations are valid for connectionless transports only:\n\nCLSETRETRYTIMEOUT    struct timeval *    set the retry timeout\nCLGETRETRYTIMEOUT    struct timeval *    get the retry timeout\nCLSETCONNECT          int *               use connect(2)\n\nThe retry timeout is the time that RPC waits for the server to reply before retrans‐\nmitting the request.  The clntcontrol() function returns TRUE on success and FALSE on\nfailure.\n\nclntcreate()\nGeneric client creation routine for program prognum and version versnum.  The host ar‐\ngument identifies the name of the remote host where the server is located.  The\nnettype argument indicates the class of transport protocol to use.  The transports are\ntried in left to right order in NETPATH environment variable or in top to bottom order\nin the netconfig database.  The clntcreate() function tries all the transports of the\nnettype class available from the NETPATH environment variable and the netconfig data‐\nbase, and chooses the first successful one.  A default timeout is set and can be modi‐\nfied using clntcontrol().  This routine returns NULL if it fails.  The\nclntpcreateerror() routine can be used to print the reason for failure.\n\nNote: clntcreate() returns a valid client handle even if the particular version num‐\nber supplied to clntcreate() is not registered with the rpcbind(8) service.  This\nmismatch will be discovered by a clntcall() later (see rpcclntcalls(3)).\n\nclntcreatetimed()\nGeneric client creation routine which is similar to clntcreate() but which also has\nthe additional argument timeout that specifies the maximum amount of time allowed for\neach transport class tried.  In all other respects, the clntcreatetimed() call be‐\nhaves exactly like the clntcreate() call.\n\nclntcreatevers()\nGeneric client creation routine which is similar to clntcreate() but which also\nchecks for the version availability.  The host argument identifies the name of the re‐\nmote host where the server is located.  The nettype argument indicates the class\ntransport protocols to be used.  If the routine is successful it returns a client han‐\ndle created for the highest version between verslow and vershigh that is supported\nby the server.  The versoutp argument is set to this value.  That is, after a suc‐\ncessful return verslow <= *versoutp <= vershigh.  If no version between verslow\nand vershigh is supported by the server then the routine fails and returns NULL.  A\ndefault timeout is set and can be modified using clntcontrol().  This routine returns\nNULL if it fails.  The clntpcreateerror() routine can be used to print the reason for\nfailure.  Note: clntcreate() returns a valid client handle even if the particular\nversion number supplied to clntcreate() is not registered with the rpcbind(8) ser‐\nvice.  This mismatch will be discovered by a clntcall() later (see\nrpcclntcalls(3)).  However, clntcreatevers() does this for you and returns a valid\nhandle only if a version within the range supplied is supported by the server.\n\nclntcreateverstimed()\nGeneric client creation routine which is similar to clntcreatevers() but which also\nhas the additional argument timeout that specifies the maximum amount of time allowed\nfor each transport class tried.  In all other respects, the clntcreateverstimed()\ncall behaves exactly like the clntcreatevers() call.\n\nclntdestroy()\nA function macro that destroys the client's RPC handle.  Destruction usually involves\ndeallocation of private data structures, including clnt itself.  Use of clnt is unde‐\nfined after calling clntdestroy().  If the RPC library opened the associated file de‐\nscriptor, or CLSETFDCLOSE was set using clntcontrol(), the file descriptor will be\nclosed.  The caller should call authdestroy(clnt->clauth) (before calling\nclntdestroy()) to destroy the associated AUTH structure (see rpcclntauth(3)).\n\nclntdgcreate()\nThis routine creates an RPC client for the remote program prognum and version versnum;\nthe client uses a connectionless transport.  The remote program is located at address\nsvcaddr.  The fildes argument is an open and bound file descriptor.  This routine will\nresend the call message in intervals of 15 seconds until a response is received or un‐\ntil the call times out.  The total time for the call to time out is specified by\nclntcall() (see clntcall() in rpcclntcalls(3)).  The retry time out and the total\ntime out periods can be changed using clntcontrol().  The user may set the size of\nthe send and receive buffers with the sendsz and recvsz arguments; values of 0 choose\nsuitable defaults.  This routine returns NULL if it fails.\n\nclntpcreateerror()\nPrint a message to standard error indicating why a client RPC handle could not be cre‐\nated.  The message is prepended with the string s and a colon, and appended with a\nnewline.\n\nclntspcreateerror()\nLike clntpcreateerror(), except that it returns a string instead of printing to the\nstandard error.  A newline is not appended to the message in this case.  Warning: re‐\nturns a pointer to a buffer that is overwritten on each call.\n\nclntrawcreate()\nThis routine creates an RPC client handle for the remote program prognum and version\nversnum.  The transport used to pass messages to the service is a buffer within the\nprocess's address space, so the corresponding RPC server should live in the same ad‐\ndress space; (see svcrawcreate() in rpcsvccreate(3)).  This allows simulation of\nRPC and measurement of RPC overheads, such as round trip times, without any kernel or\nnetworking interference.  This routine returns NULL if it fails.  The\nclntrawcreate() function should be called after svcrawcreate().\n\nclnttlicreate()\nThis routine creates an RPC client handle for the remote program prognum and version\nversnum.  The remote program is located at address svcaddr.  If svcaddr is NULL and it\nis connection-oriented, it is assumed that the file descriptor is connected.  For con‐\nnectionless transports, if svcaddr is NULL, RPCUNKNOWNADDR error is set.  The fildes\nargument is a file descriptor which may be open, bound and connected.  If it is\nRPCANYFD, it opens a file descriptor on the transport specified by netconf.  If\nfildes is RPCANYFD and netconf is NULL, a RPCUNKNOWNPROTO error is set.  If fildes\nis unbound, then it will attempt to bind the descriptor.  The user may specify the\nsize of the buffers with the sendsz and recvsz arguments; values of 0 choose suitable\ndefaults.  Depending upon the type of the transport (connection-oriented or connec‐\ntionless), clnttlicreate() calls appropriate client creation routines.  This routine\nreturns NULL if it fails.  The clntpcreateerror() routine can be used to print the\nreason for failure.  The remote rpcbind service (see rpcbind(8)) is not consulted for\nthe address of the remote service.\n\nclnttpcreate()\nLike clntcreate() except clnttpcreate() tries only one transport specified through\nnetconf.  The clnttpcreate() function creates a client handle for the program\nprognum, the version versnum, and for the transport specified by netconf.  Default op‐\ntions are set, which can be changed using clntcontrol() calls.  The remote rpcbind\nservice on the host host is consulted for the address of the remote service.  This\nroutine returns NULL if it fails.  The clntpcreateerror() routine can be used to\nprint the reason for failure.\n\nclnttpcreatetimed()\nLike clnttpcreate() except clnttpcreatetimed() has the extra argument timeout\nwhich specifies the maximum time allowed for the creation attempt to succeed.  In all\nother respects, the clnttpcreatetimed() call behaves exactly like the\nclnttpcreate() call.\n\nclntvccreate()\nThis routine creates an RPC client for the remote program prognum and version versnum;\nthe client uses a connection-oriented transport.  The remote program is located at ad‐\ndress svcaddr.  The fildes argument is an open and bound file descriptor.  The user\nmay specify the size of the send and receive buffers with the sendsz and recvsz argu‐\nments; values of 0 choose suitable defaults.  This routine returns NULL if it fails.\nThe address svcaddr should not be NULL and should point to the actual address of the\nremote program.  The clntvccreate() function does not consult the remote rpcbind\nservice for this information.\n\nstruct rpccreateerr rpccreateerr;\nA global variable whose value is set by any RPC client handle creation routine that\nfails.  It is used by the routine clntpcreateerror() to print the reason for the\nfailure.\n",
            "subsections": []
        },
        "AVAILABILITY": {
            "content": "These functions are part of libtirpc.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "rpc(3), rpcclntauth(3), rpcclntcalls(3), rpcbind(8)\n\nBSD                               May 7, 1993                              BSD",
            "subsections": []
        }
    },
    "summary": "rpcclntcreate, clntcontrol, clntcreate, clntcreatetimed, clntcreatevers, clntcreateverstimed, clntdestroy, clntdgcreate, clntpcreateerror, clntrawcreate, clntspcreateerror, clnttlicreate, clnttpcreate, clnttpcreatetimed, clntvccreate, rpccreateerr — library routines for dealing with creation and manipulation of CLIENT handles",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "rpc",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/rpc/3/json"
        },
        {
            "name": "rpcclntauth",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/rpcclntauth/3/json"
        },
        {
            "name": "rpcclntcalls",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/rpcclntcalls/3/json"
        },
        {
            "name": "rpcbind",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/rpcbind/8/json"
        }
    ]
}