transmission/libtransmission/error.h

130 lines
4.0 KiB
C
Raw Normal View History

/*
* This file Copyright (C) 2013-2014 Mnemosyne LLC
*
* It may be used under the GNU GPL versions 2 or 3
* or any future license endorsed by Mnemosyne LLC.
*
*/
#pragma once
#include <stdarg.h>
#include "tr-macros.h"
/**
* @addtogroup error Error reporting
* @{
*/
/** @brief Structure holding error information. */
struct tr_error
{
/** @brief Error code, platform-specific */
int code;
/** @brief Error message */
char* message;
};
/**
* @brief Create new error object using literal error message.
*
* @param[in] code Error code (platform-specific).
* @param[in] message Error message.
*
* @return Newly allocated error object on success, `nullptr` otherwise.
*/
tr_error* tr_error_new_literal(int code, char const* message);
/**
* @brief Create new error object using `vprintf`-style formatting.
*
* @param[in] code Error code (platform-specific).
* @param[in] message_format Error message format string.
* @param[in] args Format arguments.
*
* @return Newly allocated error object on success, `nullptr` otherwise.
*/
fix: gcc warnings in libtransmission/ and utils/ (#843) * fix: __attribute__(__printf__) warnings * fix: implicit fallthrough warning * fixup! fix: implicit fallthrough warning * fix: disable warnings for 3rd party code Since we want to leave upstream code as-is * fixup! fix: disable warnings for 3rd party code * fixup! fix: disable warnings for 3rd party code * silence spurious alignment warning Xrefs Discussion: https://stackoverflow.com/a/35554349 Macro inspiration: https://pagure.io/SSSD/sssd/blob/90ac46f71068d131391492360a8553bdd005b5a7/f/src/util/util_safealign.h#_35 * fixup! fix: disable warnings for 3rd party code * fixup! fix: implicit fallthrough warning * make uncrustify happy * remove uncrustify-test.sh that's probably off-topic for this PR * fixup! fix: __attribute__(__printf__) warnings * Update libtransmission/CMakeLists.txt Co-Authored-By: ckerr <ckerr@github.com> * fixup! silence spurious alignment warning * use -w for DISABLE_WARNINGS in Clang * refactor: fix libtransmission deprecation warnings * fix: pthread_create's start_routine's return value This was defined as `void` on non-Windows but should have been `void*` * chore: uncrustify * fix: add DISABLE_WARNINGS option for SunPro Studio * fix "unused in lambda capture" warnings by clang++ * fix 'increases required alignment' warning Caused from storing int16_t's in a char array. * fix net.c 'increases required alignment' warning The code passes in a `struct sockaddr_storage*` which is a padded struct large enough for the necessary alignment. Unfortunately it was recast as a `struct sockaddr*` which has less padding and a smaller alignment. The warning occrred because of these differing alignments. * make building quieter so warnings are more visible * fixup! fix 'increases required alignment' warning * Fix -Wcast-function-type warnings in GTK+ app code https://gitlab.gnome.org/GNOME/gnome-terminal/issues/96 talks about both the issue and its solution. GCC 8's -Wcast-function-type, enabled by -Wextra, is problematic in glib applications because it's idiomatic there to recast function signatures, e.g. `g_slist_free(list, (GFunc)g_free, NULL);`. Disabling the warning with pragmas causes "unrecognized pragma" warnings on clang and older versions of gcc, and disabling the warning could miss actual bugs. GCC defines `void (*)(void)` as a special case that matches anything so we can silence warnings by double-casting through GCallback. In the previous example, the warning is silenced by changing the code to read `g_slist_free(list, (GFunc)(GCallback)g_free, NULL);`). * fixup! fix "unused in lambda capture" warnings by clang++ * fixup! fix "unused in lambda capture" warnings by clang++ * fix two more libtransmission compiler warnings * fix: in watchdir, use TR_ENABLE_ASSERTS not NDEBUG
2019-11-06 17:27:03 +00:00
tr_error* tr_error_new_valist(int code, char const* message_format, va_list args) TR_GNUC_PRINTF(2, 0);
/**
* @brief Free memory used by error object.
*
* @param[in] error Error object to be freed.
*/
void tr_error_free(tr_error* error);
/**
* @brief Create and set new error object using `printf`-style formatting.
*
* If passed pointer to error object is `nullptr`, do nothing.
*
* @param[in,out] error Pointer to error object to be set.
* @param[in] code Error code (platform-specific).
* @param[in] message_format Error message format string.
* @param[in] ... Format arguments.
*/
void tr_error_set(tr_error** error, int code, char const* message_format, ...) TR_GNUC_PRINTF(3, 4);
/**
* @brief Create and set new error object using literal error message.
*
* If passed pointer to error object is `nullptr`, do nothing.
*
* @param[in,out] error Pointer to error object to be set.
* @param[in] code Error code (platform-specific).
* @param[in] message Error message.
*/
void tr_error_set_literal(tr_error** error, int code, char const* message);
/**
* @brief Propagate existing error object upwards.
*
* If passed pointer to new error object is not `nullptr`, copy old error object
* to new error object and free old error object. Otherwise, just free old error
* object.
*
* @param[in,out] new_error Pointer to error object to be set.
* @param[in,out] old_error Error object to be propagated. Cleared on return.
*/
void tr_error_propagate(tr_error** new_error, tr_error** old_error);
/**
* @brief Clear error object.
*
* Free error object being pointed and set pointer to `nullptr`. If passed
* pointer is `nullptr`, do nothing.
*
* @param[in,out] error Pointer to error object to be cleared.
*/
void tr_error_clear(tr_error** error);
/**
* @brief Prefix message of exising error object.
*
* If passed pointer to error object is not `nullptr`, prefix its message with
* `printf`-style formatted text. Otherwise, do nothing.
*
* @param[in,out] error Pointer to error object to be set.
* @param[in] prefix_format Prefix format string.
* @param[in] ... Format arguments.
*/
void tr_error_prefix(tr_error** error, char const* prefix_format, ...) TR_GNUC_PRINTF(2, 3);
/**
* @brief Prefix message and propagate existing error object upwards.
*
* If passed pointer to new error object is not `nullptr`, copy old error object
* to new error object, prefix its message with `printf`-style formatted text,
* and free old error object. Otherwise, just free old error object.
*
* @param[in,out] new_error Pointer to error object to be set.
* @param[in,out] old_error Error object to be propagated. Cleared on return.
* @param[in] prefix_format Prefix format string.
* @param[in] ... Format arguments.
*/
void tr_error_propagate_prefixed(tr_error** new_error, tr_error** old_error, char const* prefix_format, ...)
TR_GNUC_PRINTF(3, 4);
/** @} */