rpc_call Subroutine

Purpose

Calls the remote procedure associated with the specified program and version on a remote host.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>
enum clnt_stat rpc_call(host, prognum, versnum, procnum, in_proc, input, out_proc, output, nettype)
const char *host;
const rpcprog_t prognum;
const rpcvers_t versnum;
const rpcproc_t procnum;
const xdrproc_t in_proc;
const char *input;
const xdrproc_t out_proc;
char *output;
const char *nettype;

Description

The rpc_call subroutine calls the remote procedure associated with the specified program and version. The remote procedure that is specified by the procnum procedure resides on a remote host. You can specify an eXternal Data Representation (XDR) procedure that encodes the procedure parameters along with the addresses of the parameters. Similarly, you can specify an XDR procedure that decodes the procedure results and address where those results are to be placed. You can specify the transport class using the nettype parameter. The rpc_call subroutine uses the first available transport. You cannot control timeout, and you cannot control authentication because the client handle is not created (as in client-creation subroutines).

Parameters

Item Description
host Specifies the host name where the server resides.
prognum Specifies the program number of the remote program.
versnum Specifies the version number of the remote program.
procnum The remote procedure number.
in_proc The XDR procedure for encoding the procedure parameters.
input The address of the procedure arguments.
out_proc The XDR procedure for decoding the procedure results.
output The address where the results are placed.
nettype Defines a class of transports that can be used for a particular application.

Return Values

Item Description
RPC_SUCCESS successful
an appropriate status unsuccessful

You can use the clnt_perrno subroutine to get the status.

Error Codes

The rpc_call subroutine returns failure when one or more of the following codes are true.

Item Description
RPC_UNKNOWNPROTO
  • The value specified by the nettype parameter is not valid.
  • The value specified by the nettype parameter is set to netpath, and the NETPATH environment variable is set to a transport service that is not valid.
RPC_UNKNOWNHOST The host name is not valid.
RPC_PROCUNAVAIL The remote procedure is not available
RPC_TIMEDOUT The timeout value has expired.
RPC_PROGVERSMISMATCH The specified version is not registered at the server.
RPC_FAILED An unspecified error occurred. The procedure specified by the in_proc or out_proc parameter might not be valid.
RPC_CANTDECODEARGS The arguments or results are not valid.
RPC_SYSTEMERROR All of the process memory is exhausted (heap).

Examples

#include <stdlib.h>
#include <rpc/rpc.h>
int main()
{
    char hostname[255] ; 
    /* The Remote host on which server is implemented */
    rpcprog_t program_number ;
    rpcvers_t version_number ;
    rpcproc_t procedure_number ;
    enum clnt_stat cs ;    
    char *nettype = "visible";

    cs = rpc_call(hostname, program_number, version_number, procedure_number,
         (xdrproc_t)xdr_void, NULL,(xdrproc_t)xdr_void, NULL, nettype);
    if (cs != RPC_SUCCESS)
    {
        fprintf(stderr,"\n RPC Call failed\n");
        exit(1);
    }

    return 0;
}