sg_get_error(3)

NAME
sg_get_error, sg_get_error_arg, sg_get_error_errno, sg_str_error, sg_get_error_details, sg_strperror - get last error status

SYNOPSIS
\FC#include <statgrab.h>\F[]

\FCsg_error sg_get_error\F[]
\FC(void);\F[]

\FCconst char *sg_get_error_arg\F[]
\FC(void);\F[]

\FCint sg_get_error_errno\F[]
\FC(void);\F[]

\FCsg_error sg_get_error_details\F[]
\FC(sg_error_details *err_details);\F[]

\FCconst char *sg_str_error\F[]
\FC(sg_error code);\F[]

\FCchar *sg_strperror\F[]
\FC(char **buf, const sg_error_details * const err_details);\F[]

DESCRIPTION
There are four functions to get information about the last occurred error: \FCsg_get_error\F[], \FCsg_get_error_arg\F[], \FCsg_get_error_errno\F[] and \FCsg_get_error_details\F[]. The remaining functions are intended to improve the machine-human-interface (e.g. the error log or a message box): \FCsg_str_error\F[] delivers a human readable error name and \FCsg_strperror\F[] prepares a full blown error message for printing.

The error argument (\FCsg_get_error_arg\F[]) is stored thread local and is reused every time an error occures. If a later usage is intended, duplicating it is a suitable strategy. Same for the \FCerror_arg\F[] of \FCsg_error_details\F[] delivered by \FCsg_get_error_details\F[].

When someone calls the function \FCsg_get_error_details\F[] with a NULL pointer, the last error is overridden with a new one describing that \FCsg_get_error_details\F[] is called with invalid arguments. Please be careful.

The function \FCsg_strperror\F[] is allowed to be called with or without (\FCerr_details\F[] is NULL) collected error details. In the latter case, the last occurred error of this thread is used to prepare the error message. Be aware, the the buffer pointer must be non-NULL (points to an existing \FCchar *\F[] lvalue), but the \FCchar *\F[] lvalue it points to, must be NULL. When invoked correctly, there are only two possible error conditions let \FCsg_strperror\F[] fail: ENOMEM (out of memory) and EINVAL (invalid error code). Example

\FC
if( NULL == sg_get_cpu_stats() ) {
    char *buf = NULL;
    if( NULL != sg_strperror( &buf, NULL ) ) {
        fprintf( stderr, "error getting CPU stats: %s\n", buf );
        free(buf);
        exit(255);
    }
    else {
        fprintf( stderr, "error getting CPU stats and error information\n" );
        exit(255);
    }
}
        \F[]

RETURN VALUES
The error details contains following information:

\FC
typedef struct sg_error_details {
        sg_error error;
        int errno_value;
        const char *error_arg;
} sg_error_details;
    \F[]

\FCerror\F[]
    The statgrab library error code.

\FCerrno_value\F[]
    The operating system error code.

\FCerror_arg\F[]
    Additional information set when the error was reported.

SEE ALSO
statgrab(3)

WEBSITE
⟨https://libstatgrab.org/⟩