clnt_call Macro

Important: The macro is exported from both the libc and the libnsl libraries.

clnt_call Macro Exported from the libc Library

Purpose

Calls the remote procedure associated with the clnt parameter.

Library

C Library (libc.a)

Syntax

#include <rpc/rpc.h>

enum clnt_stat clnt_call (clnt, procnum, inproc, in, outproc, out, tout)
CLIENT * clnt;
u_long  procnum;
xdrproc_t  inproc;
char * in;
xdrproc_t  outproc;
char * out;
struct timeval  tout;

Description

The clnt_call macro calls the remote procedure associated with the client handle pointed to by the clnt parameter.

Parameters

Item Description
clnt Points to the structure of the client handle that results from a Remote Procedure Call (RPC) client creation subroutine, such as the clntudp_create subroutine that opens a User Datagram Protocol/Internet Protocol (UDP/IP) socket.
procnum Identifies the remote procedure on the host machine.
inproc Specifies the procedure that encodes the procedure's parameters.
in Specifies the address of the procedure's arguments.
outproc Specifies the procedure that decodes the procedure's results.
out Specifies the address where results are placed.
tout Sets the time allowed for results to return.

clnt_call Macro Exported from the libnsl Library

Purpose

Calls the remote procedure associated with the client handle.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>
clnt_call(clnt, procnum, inproc, in, outproc, out, tout)
CLIENT * clnt;
rpcproc_t procnum;
xdrproc_t  inproc;
caddr_t in;
xdrproc_t  outproc;
caddr_t out;
struct timeval  tout;

Description

The clnt_call macro calls the remote procedure associated with the client file handle. The handle is obtained by calling any of the client creation subroutines. You can specify the eXternal Data Representation (XDR) procedure that encodes the procedure parameters along with the address of the parameters. Similarly, you can specify the XDR procedure that decodes the procedure results and address where those results are to be placed.

Parameters

Item Description
clnt Specifies a generic client handle created by a successful call to the clnt_create subroutine.
procnum Specifies the remote procedure number.
inproc Specifies the XDR procedure that encodes the procedure parameters.
in Specifies the address of the procedure arguments.
outproc Specifies the XDR procedure that decodes the procedure results.
out Specifies the address where results are placed.
tout Sets the time given to the server to respond.

Return Values

Item Description
RPC_SUCCESS successful
nonzero unsuccessful

Error Codes

The clnt_call macro returns failure when one or more of the following codes are true.
Item Description
RPC_PROCUNAVAIL The remote procedure is not available.
RPC_TIMEDOUT The timeout value has expired.
RPC_AUTHERROR Authentication failure occurred.
RPC_FAILED An unspecified error occurred.
RPC_UNKNOWNPROTO The protocol is unknown.
RPC_UNKNOWNADDR The remote address is unknown.
RPC_CANTENCODEARGS The specified XDR procedures cannot encode arguments or cannot decode results.
RPC_PROGUNAVAIL The program is not available.
RPC_INTR The call is interrupted.

Examples

#include <stdlib.h>
#include <rpc/rpc.h>

int main()
{
    CLIENT *client ;
    char hostname[255] ; 
    /* The Remote host on which server is implemented */
    rpcprog_t program_number = 0x3fffffffL;
    rpcvers_t version_number = 0x1L;
    rpcproc_t procedure_number = 0x1L;
    struct timeval total_timeout = { 25 , 0 } ;
    enum clnt_stat cs ;    

    /* Create client handle by calling clnt_create subroutine */
    client = clnt_create(hostname, program_number, version_number, "tcp");
    if (client == (CLIENT *)NULL)
    {
        fprintf(stderr,"Couldn't create client\n");
        exit(1);
        }

    /* Calls the remote procedure */
    cs = clnt_call(client, procedure_number, (xdrproc_t)xdr_void, 
                   NULL, (xdrproc_t)xdr_void, NULL, total_timeout);
    if (cs != RPC_SUCCESS)
    {
        fprintf(stderr,"\n Client Call failed\n");
        exit(1);
    }

    /* Destroy the client handle at the end */
    clnt_destroy(client);

    return 0;
}