error.h 文件参考

Error codes and functions for detecting and assessing them. 更多...

浏览该文件的源代码.

结构体
struct	stumpless_error
	Information describing an error encountered by the library. 更多...

宏定义
#define	STUMPLESS_FOREACH_ERROR(ERROR)
	A macro to implement error id enum and error string array.

枚举
enum	stumpless_error_id { STUMPLESS_GENERATE_ENUM =(STUMPLESS_ADDRESS_FAILURE, 0) STUMPLESS_GENERATE_ENUM(STUMPLESS_ARGUMENT_EMPTY, 1) STUMPLESS_GENERATE_ENUM(STUMPLESS_ARGUMENT_TOO_BIG, 2) STUMPLESS_GENERATE_ENUM(STUMPLESS_DUPLICATE_ELEMENT, 3) STUMPLESS_GENERATE_ENUM(STUMPLESS_ELEMENT_NOT_FOUND, 4) STUMPLESS_GENERATE_ENUM(STUMPLESS_FILE_OPEN_FAILURE, 5) STUMPLESS_GENERATE_ENUM(STUMPLESS_FILE_WRITE_FAILURE, 6) STUMPLESS_GENERATE_ENUM(STUMPLESS_INDEX_OUT_OF_BOUNDS, 7) STUMPLESS_GENERATE_ENUM(STUMPLESS_INVALID_FACILITY, 8) STUMPLESS_GENERATE_ENUM(STUMPLESS_INVALID_ID, 9) STUMPLESS_GENERATE_ENUM(STUMPLESS_INVALID_SEVERITY, 10) STUMPLESS_GENERATE_ENUM(STUMPLESS_MEMORY_ALLOCATION_FAILURE, 11) STUMPLESS_GENERATE_ENUM(STUMPLESS_NETWORK_PROTOCOL_UNSUPPORTED, 12) STUMPLESS_GENERATE_ENUM(STUMPLESS_PARAM_NOT_FOUND, 13) STUMPLESS_GENERATE_ENUM(STUMPLESS_SOCKET_BIND_FAILURE, 14) STUMPLESS_GENERATE_ENUM(STUMPLESS_SOCKET_CONNECT_FAILURE, 15) STUMPLESS_GENERATE_ENUM(STUMPLESS_SOCKET_FAILURE, 16) STUMPLESS_GENERATE_ENUM(STUMPLESS_SOCKET_SEND_FAILURE, 17) STUMPLESS_GENERATE_ENUM(STUMPLESS_STREAM_WRITE_FAILURE, 18) STUMPLESS_GENERATE_ENUM(STUMPLESS_TARGET_INCOMPATIBLE, 19) STUMPLESS_GENERATE_ENUM(STUMPLESS_TARGET_UNSUPPORTED, 20) STUMPLESS_GENERATE_ENUM(STUMPLESS_TRANSPORT_PROTOCOL_UNSUPPORTED, 21) STUMPLESS_GENERATE_ENUM(STUMPLESS_WINDOWS_EVENT_LOG_CLOSE_FAILURE, 22) STUMPLESS_GENERATE_ENUM(STUMPLESS_WINDOWS_EVENT_LOG_OPEN_FAILURE, 23) STUMPLESS_GENERATE_ENUM(STUMPLESS_INVALID_ENCODING, 24) STUMPLESS_GENERATE_ENUM(STUMPLESS_GETHOSTNAME_FAILURE, 25 ) STUMPLESS_GENERATE_ENUM(STUMPLESS_FUNCTION_TARGET_FAILURE, 26 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_JOURNALD_FAILURE, 27 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_WINDOWS_FAILURE, 28 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_INVALID_PARAM_STRING, 29 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_SQLITE3_BUSY, 30 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_SQLITE3_CALLBACK_FAILURE, 31 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_SQLITE3_FAILURE, 32 ) STUMPLESS_GENERATE_ENUM( STUMPLESS_NETWORK_CLOSED, 33 ) }
	An (enum) identifier of the types of errors that might be encountered. 更多...

函数
const struct stumpless_error *	stumpless_get_error (void)
	Retrieves the error encountered by the last library call.
enum stumpless_error_id	stumpless_get_error_id (const struct stumpless_error *err)
	Gets the error id of the given error.
const char *	stumpless_get_error_id_string (enum stumpless_error_id id)
	Gets the error string of the given error id.
FILE *	stumpless_get_error_stream (void)
	Gets the current stream that errors are written to.
bool	stumpless_has_error (void)
	True if the last call to a stumpless function encountered an error.
void	stumpless_perror (const char *prefix)
	Prints information about the current error to the error stream.
void	stumpless_set_error_stream (FILE *stream)
	Sets the stream to write errors to.

详细描述

Error codes and functions for detecting and assessing them.

宏定义说明

STUMPLESS_FOREACH_ERROR

#define STUMPLESS_FOREACH_ERROR

(

ERROR

)

A macro to implement error id enum and error string array.

枚举类型说明

stumpless_error_id

enum stumpless_error_id

An (enum) identifier of the types of errors that might be encountered.

Note that the same error may be encountered in different contexts with a different ultimate cause. To completely diagnose a problem, you will need to look at more than just the error id.

See STUMPLESS_FOREACH_ERROR() and STUMPLESS_GENERATE_ENUM() for how this enumeration is generated.

枚举值
STUMPLESS_GENERATE_ENUM	A provided network address was not valid. This might be formatting problem, or it might mean that a DNS lookup failed.

函数说明

stumpless_get_error()

const struct stumpless_error * stumpless_get_error

(

void

)

Retrieves the error encountered by the last library call.

The returned error struct is only valid until the next call to a stumpless function. After this, it should not be referred to, and if the error of any subsequent call is needed another call to stumpless_get_error must be made.

Note that the id is the only field of the error that is guaranteed to be set. Other members may or may not be set, depending on the context of the error.

If the code_type is NULL, then the code is not valid and should be ignored.

This function does not clear or update the per-thread error code for stumpless, as it is involved in the error handling process itself.

Thread Safety: MT-Safe This function is thread safe. No synchronization primitives are used as the returned pointer is specific to the thread of execution. As a result, the result should not be shared between threads.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers. If you do so, note that if it is called before a stumpless library function in the handler itself the result will not be meaningful.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be asynchronously cancelled.

返回

A stumpless_error struct describing the error encountered by the last function call. If no error was encountered, this will be NULL.

stumpless_get_error_id()

enum stumpless_error_id stumpless_get_error_id

(

const struct stumpless_error *

err

)

Gets the error id of the given error.

Thread Safety: MT-Safe race:err This function is thread safe, as long as err is not modifed by other threads during this call.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be asynchronously cancelled.

自从

release v1.5.0

参数

err	The error to get the id from. This must not be NULL.

返回

The error id of the given error.

stumpless_get_error_id_string()

const char * stumpless_get_error_id_string

(

enum stumpless_error_id

id

)

Gets the error string of the given error id.

This is a string literal that should not be modified or freed by the caller.

Thread Safety: MT-Safe This function is thread safe.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be asynchronously cancelled.

自从

release v1.6.0

参数

id	The error id to get the error string from.

返回

The error string of the given error id.

stumpless_get_error_stream()

FILE * stumpless_get_error_stream

(

void

)

Gets the current stream that errors are written to.

Thread Safety: MT-Safe This function is thread safe. Atomic variables are used to store and retrieve the error stream.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be ansynchronously cancelled.

返回

The current stream errors are written to.

stumpless_has_error()

bool stumpless_has_error

(

void

)

True if the last call to a stumpless function encountered an error.

To get the error itself, use the stumpless_get_error function.

Thread Safety: MT-Safe This function is thread safe. No synchronization primitives are used as the returned flag is specific to the thread of execution.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers. If you do so, note that if it is called before a stumpless library function in the handler itself the result will not be meaningful.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be asynchronously cancelled.

自从

release v1.6.0.

返回

True if the last stumpless call had an error, false if not.

stumpless_perror()

void stumpless_perror

(

const char *

prefix

)

Prints information about the current error to the error stream.

A prefix can be added to the information if desired. If one is provided then it will be followed by a colon character and a space, followed by the error information. If it is not provided then the colon and space characters will not be printed.

The message will end with a newline.

If there is not currently an active error message, then nothing will be printed (not even the prefix).

Thread Safety: MT-Safe race:prefix This function is thread safe, of course assuming that prefix is not changed by other threads during execution. A lock is used to coordinate accesses to the error stream.

Async Signal Safety: AS-Unsafe lock This function is not safe to call from signal handlers, as it uses a non-reentrant lock to synchronize access to the error stream.

Async Cancel Safety: AC-Unsafe lock This function is not safe to call from threads that may be asynchronously cancelled, as the lock used to control access to the error stream may not be released after a cancellation.

参数

prefix

An optional prefix to print in front of the message. If this is NULL then it will simply be ignored.

stumpless_set_error_stream()

void stumpless_set_error_stream

(

FILE *

stream

)

Sets the stream to write errors to.

This will be stderr by default, but can be set to any stream. If it is set to NULL then error messages will not be printed (essentially skipping all stumpless_perror calls).

Thread Safety: MT-Safe This function is thread safe. Atomic variables are used to store and retrieve the error stream.

Async Signal Safety: AS-Safe This function is safe to call from signal handlers.

Async Cancel Safety: AC-Safe This function is safe to call from threads that may be ansynchronously cancelled.

参数

stream

The stream to write errors to. If this is NULL then the messages intended for the error stream will be ignored.