clnt_sperror Subroutine

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

clnt_sperror Subroutine Exported from the libc Library

Purpose

Indicates why a remote procedure call failed.

Library

C Library (libc.a)

Syntax

#include <rpc/rpc.h>

char *clnt_sperror ( cl, s) CLIENT *cl; char *s;

Description

The clnt_sperror subroutine returns a string to standard error output indicating why a Remote Procedure Call (RPC) call failed. This subroutine also returns the pointer to static data overwritten on each call.

Parameters

Item	Description
cl	Points to the structure of the client handle.
s	Points to a character string that represents the error text.

Return Values

This subroutine returns an error string to standard error output.

clnt_sperror Subroutine Exported from the libnsl Library

Purpose

Returns the error message indicating why a remote procedure call failed.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>

char *clnt_sperror ( cl, s)
const CLIENT *cl;
const char *s;

Description

The clnt_sperror subroutine returns an error message indicating why a remote procedure call failed. The message is preceded by the string that is pointed to by the s parameter and a colon. The message is not appended by a newline. This subroutine is used after the clnt_call macro. The difference between the clnt_sperror and clnt_perror subroutines is that clnt_perror displays the error message on standard error whereas clnt_sperror just returns a pointer to the buffer that holds this error message.

Note: In a single thread, the subroutine uses the same buffer that is overwritten by the error message on successive calls. However, in multithreaded applications, the buffers used are thread-specific.

Parameters

Item	Description
cl	Points to the structure of the client handle.
s	Points to a character string that represents the error text.

Return Values

This subroutine returns an error string.

Examples

In the following example, the clnt_sperror subroutine returns the reason for failure of a remote procedure call that is pointed to by the err_str parameter.

#include <rpc/clnt.h>
#include <stdio.h>
#include <sys/time.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 ;
  char *err_str ;  

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

  /* Call remote procedure associated with client handle */
  cs = clnt_call(client, procedure_number, (xdrproc_t)xdr_void, NULL,
                    (xdrproc_t)xdr_void, NULL, total_timeout);
  if (cs != RPC_SUCCESS)
  {
      err_str = clnt_sperror(client,"Client Call failed");
      fprintf(stderr,"%s",err_str);
      exit(1);
  }

  /* Destroy client handle in the end */
  clnt_destroy(client);
  
  return 0;
}