util/messages.h

   1 /*
   2  * Prototypes for message and error reporting (possibly fatal).
   3  *
   4  * The canonical version of this file is maintained in the rra-c-util package,
   5  * which can be found at <https://www.eyrie.org/~eagle/software/rra-c-util/>.
   6  *
   7  * Written by Russ Allbery <eagle@eyrie.org>
   8  * Copyright 2015 Russ Allbery <eagle@eyrie.org>
   9  * Copyright 2008, 2010, 2013-2014
  10  *     The Board of Trustees of the Leland Stanford Junior University
  11  * Copyright 2004-2006 Internet Systems Consortium, Inc. ("ISC")
  12  * Copyright 1991, 1994-2003 The Internet Software Consortium and Rich Salz
  13  *
  14  * This code is derived from software contributed to the Internet Software
  15  * Consortium by Rich Salz.
  16  *
  17  * Permission to use, copy, modify, and distribute this software for any
  18  * purpose with or without fee is hereby granted, provided that the above
  19  * copyright notice and this permission notice appear in all copies.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  22  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  23  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  24  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  25  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  26  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  27  * PERFORMANCE OF THIS SOFTWARE.
  28  *
  29  * SPDX-License-Identifier: ISC
  30  */
  31
  32 #ifndef UTIL_MESSAGES_H
  33 #define UTIL_MESSAGES_H 1
  34
  35 #include <config.h>
  36 #include <portable/macros.h>
  37
  38 #include <stdarg.h>
  39 #include <stddef.h>
  40
  41 BEGIN_DECLS
  42
  43 /* Default to a hidden visibility for all util functions. */
  44 #pragma GCC visibility push(hidden)
  45
  46 /*
  47  * The reporting functions.  The ones prefaced by "sys" add a colon, a space,
  48  * and the results of strerror(errno) to the output and are intended for
  49  * reporting failures of system calls.
  50  */
  51 void debug(const char *, ...)
  52     __attribute__((__nonnull__, __format__(printf, 1, 2)));
  53 void notice(const char *, ...)
  54     __attribute__((__nonnull__, __format__(printf, 1, 2)));
  55 void sysnotice(const char *, ...)
  56     __attribute__((__nonnull__, __format__(printf, 1, 2)));
  57 void warn(const char *, ...)
  58     __attribute__((__nonnull__, __format__(printf, 1, 2)));
  59 void syswarn(const char *, ...)
  60     __attribute__((__nonnull__, __format__(printf, 1, 2)));
  61 void die(const char *, ...)
  62     __attribute__((__nonnull__, __noreturn__, __format__(printf, 1, 2)));
  63 void sysdie(const char *, ...)
  64     __attribute__((__nonnull__, __noreturn__, __format__(printf, 1, 2)));
  65
  66 /*
  67  * Set the handlers for various message functions.  All of these functions
  68  * take a count of the number of handlers and then function pointers for each
  69  * of those handlers.  These functions are not thread-safe; they set global
  70  * variables.
  71  */
  72 void message_handlers_debug(unsigned int count, ...);
  73 void message_handlers_notice(unsigned int count, ...);
  74 void message_handlers_warn(unsigned int count, ...);
  75 void message_handlers_die(unsigned int count, ...);
  76
  77 /*
  78  * Reset all message handlers back to the defaults and free any memory that
  79  * was allocated by the other message_handlers_* functions.
  80  */
  81 void message_handlers_reset(void);
  82
  83 /*
  84  * Some useful handlers, intended to be passed to message_handlers_*.  All
  85  * handlers take the length of the formatted message, the format, a variadic
  86  * argument list, and the errno setting if any.
  87  */
  88 void message_log_stdout(size_t, const char *, va_list, int)
  89     __attribute__((__format__(printf, 2, 0), __nonnull__));
  90 void message_log_stderr(size_t, const char *, va_list, int)
  91     __attribute__((__format__(printf, 2, 0), __nonnull__));
  92 void message_log_syslog_debug(size_t, const char *, va_list, int)
  93     __attribute__((__format__(printf, 2, 0), __nonnull__));
  94 void message_log_syslog_info(size_t, const char *, va_list, int)
  95     __attribute__((__format__(printf, 2, 0), __nonnull__));
  96 void message_log_syslog_notice(size_t, const char *, va_list, int)
  97     __attribute__((__format__(printf, 2, 0), __nonnull__));
  98 void message_log_syslog_warning(size_t, const char *, va_list, int)
  99     __attribute__((__format__(printf, 2, 0), __nonnull__));
 100 void message_log_syslog_err(size_t, const char *, va_list, int)
 101     __attribute__((__format__(printf, 2, 0), __nonnull__));
 102 void message_log_syslog_crit(size_t, const char *, va_list, int)
 103     __attribute__((__format__(printf, 2, 0), __nonnull__));
 104
 105 /* The type of a message handler. */
 106 typedef void (*message_handler_func)(size_t, const char *, va_list, int)
 107     __attribute__((__format__(printf, 2, 0)));
 108
 109 /* If non-NULL, called before exit and its return value passed to exit. */
 110 extern int (*message_fatal_cleanup)(void);
 111
 112 /*
 113  * If non-NULL, prepended (followed by ": ") to all messages printed by either
 114  * message_log_stdout or message_log_stderr.
 115  */
 116 extern const char *message_program_name;
 117
 118 /* Undo default visibility change. */
 119 #pragma GCC visibility pop
 120
 121 END_DECLS
 122
 123 #endif /* UTIL_MESSAGES_H */