clnt_sperrno Subroutine

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

clnt_sperrno Subroutine Exported from the libc Library

Purpose

Specifies the condition of the stat parameter by returning a pointer to a string containing a status message.

Library

C Library (libc.a)

Syntax

#include <rpc/rpc.h>

char *clnt_sperrno ( stat) enum clnt_stat stat;

Description

The clnt_sperrno subroutine specifies the condition of the stat parameter by returning a pointer to a string containing a status message. The string ends with a new-line character.

Whenever one of the following conditions exists, the clnt_sperrno subroutine is used instead of the clnt_perrno subroutine when a clnt_call routine fails:

The program does not have a standard error output. This is common for programs running as servers.
The programmer does not want the message to be output with the printf subroutine.
A message format differing from that supported by the clnt_perrno subroutine is being used.
Note: The clnt_sperrno subroutine does not return the pointer to static data, so the result is not overwritten on each call.

Parameters

Item	Description
stat	Specifies the client error status of the remote procedure call.

Return Values

The clnt_sperrno subroutine translates and displays the following enum clnt_stat error status messages:

Message	Description
RPC_SUCCESS = 0	Call succeeded.
RPC_CANTENCODEARGS = 1	Cannot encode arguments.
RPC_CANTDECODERES = 2	Cannot decode results.
RPC_CANTSEND = 3	Failure in sending call.
RPC_CANTRECV = 4	Failure in receiving result.
RPC_TIMEDOUT = 5	Call timed out.

clnt_sperrno Subroutine Exported from the libnsl Library

Purpose

Specifies the reason for failure of the procedure call.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>

char *clnt_sperrno(stat)
const enum clnt_stat stat;

Description

The clnt_sperrno subroutine specifies the condition of the stat parameter by returning a pointer to a string containing a status message. The string ends with a new-line character.

Whenever one of the following conditions exists, the clnt_sperrno subroutine is used instead of the clnt_perrno subroutine when a clnt_call routine fails:

The program does not have a standard error output. This is common for programs running as servers.
The programmer does not want the message to be output with the printf subroutine.
A message format differing from that supported by the clnt_perrno subroutine is being used.
Note: The clnt_sperrno subroutine does not return the pointer to static data, so the result is not overwritten on each call.

Parameters

Item	Description
stat	Specifies the client error status of the remote procedure call.

Error Codes

The following table list some error status codes that the clnt_sperrno subroutine can translate and display. You can find a complete list of error codes in the clnt_stat.h file.

Item	Description
RPC_SUCCESS = 0	The call succeeded.
RPC_CANTENCODEARGS = 1	Arguments cannot be encoded.
RPC_CANTDECODERES = 2	Results cannot be decoded .
RPC_CANTSEND = 3	A failure occurred in sending call.
RPC_CANTRECV = 4	A failure occurred in receiving result.
RPC_TIMEDOUT = 5	The call timed out.

Examples

In the following example, the clnt_sperrno subroutine returns the status message in the string pointed to by the err_str parameter.

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

  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)
  {
    err_str = clnt_sperrno(cs) ;
    fprintf(stdout,"\n%s",err_str) ;
  }

  return 0 ;
}