github.com/kubiko/snapd@v0.0.0-20201013125620-d4f3094d9ddf/cmd/libsnap-confine-private/panic.h (about)

     1  /*
     2   * Copyright (C) 2019 Canonical Ltd
     3   *
     4   * This program is free software: you can redistribute it and/or modify
     5   * it under the terms of the GNU General Public License version 3 as
     6   * published by the Free Software Foundation.
     7   *
     8   * This program is distributed in the hope that it will be useful,
     9   * but WITHOUT ANY WARRANTY; without even the implied warranty of
    10   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    11   * GNU General Public License for more details.
    12   *
    13   * You should have received a copy of the GNU General Public License
    14   * along with this program.  If not, see <http://www.gnu.org/licenses/>.
    15   *
    16   */
    17  
    18  #ifndef SC_PANIC_H
    19  #define SC_PANIC_H
    20  
    21  #include <stdarg.h>
    22  
    23  /**
    24   * sc_panic is an exit-with-message utility function.
    25   *
    26   * The function takes a printf-like format string that is formatted and printed
    27   * somehow. The function then terminates the process by calling exit. Both
    28   * aspects can be customized.
    29   *
    30   * The particular nature of the exit can be customized by calling
    31   * sc_set_panic_action. The panic action is a function that is called before
    32   * attempting to exit.
    33   *
    34   * The way the error message is formatted and printed can be customized by
    35   * calling sc_set_panic_format_fn(). By default the error is printed to
    36   * standard error. If the error is related to a system call failure then errno
    37   * can be set to a non-zero value just prior to calling sc_panic. The value
    38   * will then be used when crafting the error message.
    39   **/
    40  __attribute__((noreturn, format(printf, 1, 2))) void sc_panic(const char *fmt, ...);
    41  
    42  /**
    43   * sc_panicv is a variant of sc_panic with an argument list.
    44   **/
    45  __attribute__((noreturn)) void sc_panicv(const char *fmt, va_list ap);
    46  
    47  /**
    48   * sc_panic_exit_fn is the type of the exit function used by sc_panic().
    49   **/
    50  typedef void (*sc_panic_exit_fn)(void);
    51  
    52  /**
    53   * sc_set_panic_exit_fn sets the panic exit function.
    54   *
    55   * When sc_panic is called it will eventually exit the running process. Just
    56   * prior to that, it will call the panic exit function, if one has been set.
    57   *
    58   * If exiting the process is undesired, for example while running in intrd as
    59   * pid 1, during the system shutdown phase, then a process can set the panic
    60   * exit function. Note that if the specified function returns then panic will
    61   * proceed to call exit(3) anyway.
    62   *
    63   * The old exit function, if any, is returned.
    64   **/
    65  sc_panic_exit_fn sc_set_panic_exit_fn(sc_panic_exit_fn fn);
    66  
    67  /**
    68   * sc_panic_msg_fn is the type of the format function used by sc_panic().
    69   **/
    70  typedef void (*sc_panic_msg_fn)(const char *fmt, va_list ap, int errno_copy);
    71  
    72  /**
    73   * sc_set_panic_msg_fn sets the panic message function.
    74   *
    75   * When sc_panic is called it will attempt to print an error message to
    76   * standard error. The message includes information provided by the caller: the
    77   * format string, the argument vector for a printf-like function as well as a
    78   * copy of the system errno value, which may be zero if the error is not
    79   * originated by a system call error.
    80   *
    81   * If custom formatting of the error message is desired, for example while
    82   * running in initrd as pid 1, during the system shutdown phase, then a process
    83   * can set the panic message function. Once set the function takes over the
    84   * responsibility of printing an error message (in whatever form is
    85   * appropriate).
    86   *
    87   * The old message function, if any, is returned.
    88   **/
    89  sc_panic_msg_fn sc_set_panic_msg_fn(sc_panic_msg_fn fn);
    90  
    91  #endif