trc_strerror Subroutine

Purpose

Returns the error message, or next error message, associated with a trace log object or trc_loginfo object.

Library

libtrace.a

Syntax

#include <sys/libtrace.h>

char *trc_strerror (handle, rv)
void *handle;
int rv;

Description

The trc_strerror subroutine is similar to the strerror subroutine. If the error in the rv parameter is an error from the errno.h file, it simply returns the string from the strerror subroutine. If the rv parameter is a libtrace error such as TRCE_EOF, it returns the string associated with this error. It is possible for multiple libtrace errors to be present. The trc_strerror subroutine returns the next error in this case. When no more errors are present, the trc_strerror subroutine returns NULL.

Like the strerror subroutine, the trc_strerror subroutine must not be used in a threaded environment.

Parameters

Item	Description
handle	Contains the handle returned from the trc_open subroutine, the pointer to a trc_loginfo_t object, or NULL. If a handle returned by the trc_open subroutine is passed, the trc_open subroutine need not have been successful, but the TRC_RETAIN_HANDLE open option must have been used.
rv	Contains the return value from a call to the libtrace subroutine.

Return Values

The trc_strerror subroutine returns a pointer to the associated error message. It returns NULL if no more errors are present.

Examples

To retrieve all error messages from a call to the trc_open subroutine, call the trc_strerror subroutine as follows:

{
   trc_loghandle_t h;
   int rv;
   char *fn, *tfn, *s;

    ...

    rv = trc_open(fn,tfn, TRC_LOGREAD|TRC_LOGPROC|TRC_RETAIN_HANDLE, &h);
    while (rv && s=trc_strerror(h, rv))  {
      fprintf(stderr, "%s\n", s);
    }
}

To accomplish the same thing as the previous example with a single call, do the following:

{
   trc_loghandle_t h;
   int rv;
   char *fn, *tfn;

   ...

   rv = trc_open(fn,tfn, TRC_LOGREAD|TRC_LOGPROC|TRC_RETAIN_HANDLE, &h);
   if (rv) trc_perror(h, rv, "");
   }