Error Handling

Handling errors. More...

Macros
#define	ROC_ATTEMPT(EXPRESSION)
	A simple return-error-message error handling macro. More...

Typedefs
typedef const char *	roc_error
	A printable error string. More...
typedef void(*	roc_log_callback) (const char *)
	Pointer to a callback function used to forward roc_log activity. More...

Functions
void	roc_ensure (roc_error error)
	A simple log-and-exit error handling function. More...
roc_error	roc_set_logging (bool stdout_, const char *filename, roc_log_callback callback)
	Set application logging. More...
bool	roc_log (const char *message)
	Write a message to the logging infrastructure previously established by roc_set_logging. More...
bool	roc_log_no_callback (const char *message)
	Write a message to the logging infrastructure previously established by roc_set_logging. More...

Detailed Description

Handling errors.

All ROC functions return a printable roc_error message by design. The ROC_ATTEMPT macro and roc_ensure function are provided as basic error handling methods.

Macro Definition Documentation

ROC_ATTEMPT

#define ROC_ATTEMPT

(

EXPRESSION

)

Value:

{                                         \
    const roc_error error = (EXPRESSION); \
    if (error)                            \
        return error;                     \
}

A simple return-error-message error handling macro.

Example

ROC_ATTEMPT(roc_initialize(NULL, NULL))

See also

roc_ensure

Typedef Documentation

roc_error

typedef const char* roc_error

A printable error string.

All functions in the ROC API return a roc_error. A value of NULL indicates success, and all other values indicate failure.

Note

Failure values are statically-allocated strings that should not be freed.

Example

roc_error error = ...;
if (error) {
  puts(error);
  abort();
}

See also

ROC_ATTEMPT roc_ensure

roc_log_callback

typedef void(* roc_log_callback) (const char *)

Pointer to a callback function used to forward roc_log activity.

The function should return void and take one parameter: a const char* message.

The message is only valid for the lifetime of the callback function.

Function Documentation

roc_ensure()

void roc_ensure

(

roc_error

error

)

A simple log-and-exit error handling function.

void roc_ensure(roc_error error)
{
    if (error) {
        if (!roc_log(error))
            fprintf(stderr, "ROC Error: %s\n", error);
        exit(EXIT_FAILURE);
    }
}

Parameters

[in]

error

Error return value from a ROC API function call.

Remarks

This function is thread-safe.

See also

ROC_ATTEMPT

roc_set_logging()

roc_error roc_set_logging	(	bool	stdout_,
		const char *	filename,
		roc_log_callback	callback
	)

Set application logging.

For log file rotation, filename can include any of the expansions supported by strftime which will be substituted at runtime with the current date and time each occasion a log entry is written.

Parameters

[in]	stdout_	Print messages to STDOUT.
[in]	filename	Optional log file path to write messages to, or NULL. Log files are opened in append mode. An empty string will be treated as NULL.
[in]	callback	Optional callback function to forward messages to, or NULL.

Remarks

This function is thread-unsafe and must only be called once.

See also

roc_log

roc_log()

bool roc_log

(

const char *

message

)

Write a message to the logging infrastructure previously established by roc_set_logging.

If message is NULL, or roc_set_logging has not been called, this function is a no-op and returns false.

Parameters

[in]

message

Message to log.

Returns

true if message was logged, false otherwise.

Remarks

This function is thread-safe.

See also

roc_set_logging roc_log_no_callback

roc_log_no_callback()

bool roc_log_no_callback

(

const char *

message

)

Write a message to the logging infrastructure previously established by roc_set_logging.

An alternative to roc_log to explicitly avoid triggering roc_log_callback.

Parameters

[in]

message

Message to log.

Returns

true if message was logged, false otherwise.

Remarks

This function is thread-safe.

See also

roc_set_logging roc_log