path: root/liberror.h

/* See LICENSE file for copyright and license details. */
#ifndef LIBERROR_H
#define LIBERROR_H

#include <stddef.h>
#include <stdint.h>
#include <stdio.h>


/**
 * Opaque backtrace structure
 */
struct liberror_backtrace;

/**
 * Value that specifies which feild in a
 * `union liberror_details` that is used
 */
enum liberror_details_type {
	/**
	 * No details
	 */
	LIBERROR_DETAILS_NONE,

	/**
	 * User-specific details
	 */
	LIBERROR_DETAILS_USER,

	/**
	 * Details for function that operates
	 * on a single file
	 */
	LIBERROR_DETAILS_ONE_FILE,

	/**
	 * Details for function that operates
	 * on two files
	 */
	LIBERROR_DETAILS_TWO_FILES
};

/**
 * Error details
 */
union liberror_details {
	/**
	 * For `LIBERROR_DETAILS_USER`
	 */
	struct {
		/**
		 * The library that defines the data
		 */
		const char *library;

		/**
		 * The data for the details
		 */
		void *data;

		/**
		 * Function that is used to deallocate `.data`
		 * 
		 * @param  data  The pointer `.data`
		 */
		void (*free_data)(void *);

		/**
		 * Function that is used to copy `.data`
		 * 
		 * @param   data  The pointer `.data`
		 * @return        Copy of `data`, `NULL` on failure
		 */
		void *(*copy_data)(void *);

		/**
		 * Function that is used to print `.data`
		 * 
		 * @param  data    The pointer `.data`, may be `NULL`
		 * @param  fp      File to print the details to, may not be `NULL`
		 * @param  prefix  Text to print at the beginning of each line,
		 *                 may not be `NULL`
		 */
		void (*print_data)(void *, FILE *, const char *);
	} user;

	/**
	 * For `LIBERROR_DETAILS_ONE_FILE`
	 */
	struct {
		/**
		 * The specified file descriptor,
		 * negative if none
		 */
		int fd;

		/**
		 * The filename or other string that
		 * identifies the file, `NULL` if
		 * none
		 */
		char *name;

		/**
		 * Description of the file's role in the
		 * function call, for example "Directory"
		 * for the mkdir(3) function
		 */
		const char *role;
	} one_file;

	/**
	 * For `LIBERROR_DETAILS_TWO_FILES`
	 */
	struct {
		/**
		 * The first specified file descriptor,
		 * negative if none
		 */
		int fd1;

		/**
		 * The second specified file descriptor,
		 * negative if none
		 */
		int fd2;

		/**
		 * The filename or other string that
		 * identifies the first file, `NULL` if
		 * none
		 */
		char *name1;

		/**
		 * The filename or other string that
		 * identifies the second file, `NULL`
		 * if none
		 */
		char *name2;

		/**
		 * Description of the role of the first
		 * file in the function call, for example
		 * "Target" for the symlink(3) function
		 */
		const char *role1;

		/**
		 * Description of the role of the first
		 * file in the function call, for example
		 * "Link" for the symlink(3) function
		 */
		const char *role2;
	} two_files;
};

/**
 * Error structure
 */
struct liberror_error {
	/**
	 * Backtrace for the error, `NULL` if the it could
	 * not be allocated or if the program is not linked
	 * with `-lerror-backtrace`
	 */
	struct liberror_backtrace *backtrace;

	/**
	 * Description of the error
	 */
	char description[256];

	/**
	 * The function that failed
	 */
	char source[64];

	/**
	 * Name of error code group, for normal `errno`
	 * errors this is "error", for getaddrinfo(3) errors
	 * this is "addrinfo", for custom errors it is the
	 * name of the library or application
	 */
	char code_group[64];

	/**
	 * The error code
	 */
	long long int code;

	/**
	 * The error that caused this error, `NULL` if
	 * none or it could not be allocated (if and only
	 * if so, `.failed_to_allocate_cause` will be set
	 * to a non-zero value, specifically 1)
	 */
	struct liberror_error *cause;

	/**
	 * Whether allocation of `.cause` failed
	 */
	int failed_to_allocate_cause;

	/**
	 * Whether the error is physically allocated
	 */
	int dynamically_allocated;

	/**
	 * Which value in `.details` that is used
	 */
	enum liberror_details_type details_type;

	/**
	 * Error detail
	 */
	union liberror_details details;
};

/**
 * Saved error state for a thread
 * 
 * This structure shall be regardes as opaque
 */
struct liberror_state {
	/**
	 * The backtrace for the next error
	 */
	struct liberror_backtrace *backtrace;

	/**
	 * The thread's error
	 */
	struct liberror_error error;

	/**
	 * Whether the thread hade an error
	 */
	int have_error;

	/**
	 * The thread's value of `errno`
	 */
	int errnum;
};


/**
 * Get the current error for the thread
 * 
 * @return  The current error, `NULL` if none
 */
struct liberror_error *liberror_get_error(void);

/**
 * Create a copy of an error
 * 
 * This function will only fail of enough memory
 * cannot be allocated, however `errno` will not
 * be changed
 * 
 * @param   error  The error to copy
 * @return         Copy of the error, `NULL` on failure
 */
struct liberror_error *liberror_copy_error(struct liberror_error *);

/**
 * Deallocate the error and the error stored as
 * its cause (recursively)
 * 
 * @param  error  The error to deallocate
 */
void liberror_free_error(struct liberror_error *);

/**
 * Deallocate the current error for the thread
 * and reset the error for the thread
 * 
 * This function shall be called after handling
 * the error
 */
void liberror_reset_error(void);

/**
 * Print the backtrace of an error
 * 
 * If the backtrace could not be allocated,
 * nothing will be printed
 * 
 * This function will never change `errno`
 * 
 * Note: this library does not actually save
 * a backtrace, `-lerror-backtrace` is needed
 * for that functionallity (it will replace
 * some things in this library, so no other
 * action is required)
 * 
 * @param  error   The error
 * @param  fp      The file to print the backtrace to
 * @param  indent  Text to print at the beginning of each line
 */
void liberror_print_backtrace(struct liberror_error *, FILE *, const char *);

/**
 * Get backtrace and save backtrace
 * 
 * This function will never change `errno`
 * 
 * Note: this library does not actually save
 * a backtrace, `-lerror-backtrace` is needed
 * for that functionallity (it will replace
 * some things in this library, so no other
 * action is required)
 * 
 * @param   error  The error the backtrace shall be stored in,
 *                 if `NULL`, the backtrafe is saved for the
 *                 next error in the thread
 * @return         0 on success, -1 on failure
 */
int liberror_save_backtrace(struct liberror_error *);

/**
 * Set the current error for the thread
 * 
 * If the thread already has an error saved,
 * it will be stored as the cause of the new
 * error
 * 
 * @param  description  Description of the error, empty for default description
 * @param  source       The function that failed
 * @param  code_group   Name of error code group, for normal `errno` errors
 *                      this shall be "error", for getaddrinfo(3) errors
 *                      this shall be "addrinfo", for custom errors it shall
 *                      be the name of the library or application
 * @param  code         The error code
 */
void liberror_set_error(const char[256], const char[64], const char[64], long long int);

/**
 * Set the current error for the thread
 * 
 * This function can be used as an alternative
 * to `liberror_set_error` for `errno` errors
 * 
 * If the thread already has an error saved,
 * it will be stored as the cause of the new
 * error
 * 
 * @param  description  Description of the error, empty for default description
 * @param  source       The function that failed
 * @param  code         The `errno` value
 */
void liberror_set_error_errno(const char[256], const char[64], int);

/**
 * Remove the current error and, if the
 * specified error is non-`NULL`, replace it
 * with the the specified error
 * 
 * @param  error  The error to set as the current error, must not
 *                be the pointer returned by liberror_get_error()
 *                for any thread, including the current thread,
 *                the function will copy and deallocate this error
 */
void liberror_set_error_existing(struct liberror_error *);

/**
 * Remove the current error and, if the error
 * has a cause, replace it with its cause
 */
void liberror_pop_error(void);

/**
 * The an error, its backtrace, and its
 * cause (recursively)
 * 
 * If `error` is `NULL` and the thread does
 * not have any error set, this function
 * will not do anything
 * 
 * @param  error   The error, the thread's current error if `NULL`
 * @param  fp      Output stream, standard error if `NULL`
 * @param  reset   Whether `error` shall be deallocated, `error`
 *                 is null and `reset` is non-zero, the thread's
 *                 error will be reset
 * @param  prefix  Prefix for each printed line, ": " will be
 *                 appended to this prefix; if `NULL` or empty,
 *                 no prefix is used; this should normally be
 *                 `argv[0]` from the main() function
 */
void liberror_print_error(struct liberror_error *, FILE *, int, const char *);

/**
 * Save the thread's liberror error, pending backtrace,
 * and `errno`, and then reset the error information
 * for the thread
 * 
 * Asynchronously called functions such as signal handlers
 * should call this function the first thing they do
 * 
 * @param  state  Output parameter for the error state
 */
void liberror_start(struct liberror_state *);

/**
 * Restore the thread's liberror error, pending backtrace,
 * and `errno`
 * 
 * Asynchronously called functions such as signal handlers
 * should call this function the last thing they do before
 * returning
 * 
 * @param  state  The saved error state to restore
 */
void liberror_end(const struct liberror_state *);


#endif