src/xz/message.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 //
   3 /// \file       message.h
   4 /// \brief      Printing messages to stderr
   5 //
   6 //  Author:     Lasse Collin
   7 //
   8 //  This file has been put into the public domain.
   9 //  You can do whatever you want with this file.
  10 //
  11 ///////////////////////////////////////////////////////////////////////////////
  12
  13 /// Verbosity levels
  14 enum message_verbosity {
  15         V_SILENT,   ///< No messages
  16         V_ERROR,    ///< Only error messages
  17         V_WARNING,  ///< Errors and warnings
  18         V_VERBOSE,  ///< Errors, warnings, and verbose statistics
  19         V_DEBUG,    ///< Debugging, FIXME remove?
  20 };
  21
  22
  23 /// \brief      Initializes the message functions
  24 ///
  25 /// If an error occurs, this function doesn't return.
  26 ///
  27 extern void message_init(void);
  28
  29
  30 /// Increase verbosity level by one step unless it was at maximum.
  31 extern void message_verbosity_increase(void);
  32
  33 /// Decrease verbosity level by one step unless it was at minimum.
  34 extern void message_verbosity_decrease(void);
  35
  36 /// Get the current verbosity level.
  37 extern enum message_verbosity message_verbosity_get(void);
  38
  39
  40 /// Set the total number of files to be processed (stdin is counted as a file
  41 /// here). The default is one.
  42 extern void message_set_files(unsigned int files);
  43
  44
  45 /// \brief      Print a message if verbosity level is at least "verbosity"
  46 ///
  47 /// This doesn't touch the exit status.
  48 extern void message(enum message_verbosity verbosity, const char *fmt, ...)
  49                 lzma_attribute((format(printf, 2, 3)));
  50
  51
  52 /// \brief      Prints a warning and possibly sets exit status
  53 ///
  54 /// The message is printed only if verbosity level is at least V_WARNING.
  55 /// The exit status is set to WARNING unless it was already at ERROR.
  56 extern void message_warning(const char *fmt, ...)
  57                 lzma_attribute((format(printf, 1, 2)));
  58
  59
  60 /// \brief      Prints an error message and sets exit status
  61 ///
  62 /// The message is printed only if verbosity level is at least V_ERROR.
  63 /// The exit status is set to ERROR.
  64 extern void message_error(const char *fmt, ...)
  65                 lzma_attribute((format(printf, 1, 2)));
  66
  67
  68 /// \brief      Prints an error message and exits with EXIT_ERROR
  69 ///
  70 /// The message is printed only if verbosity level is at least V_ERROR.
  71 extern void message_fatal(const char *fmt, ...)
  72                 lzma_attribute((format(printf, 1, 2)))
  73                 lzma_attribute((noreturn));
  74
  75
  76 /// Print an error message that an internal error occurred and exit with
  77 /// EXIT_ERROR.
  78 extern void message_bug(void) lzma_attribute((noreturn));
  79
  80
  81 /// Print a message that establishing signal handlers failed, and exit with
  82 /// exit status ERROR.
  83 extern void message_signal_handler(void) lzma_attribute((noreturn));
  84
  85
  86 /// Convert lzma_ret to a string.
  87 extern const char *message_strm(lzma_ret code);
  88
  89
  90 /// Print the filter chain.
  91 extern void message_filters(
  92                 enum message_verbosity v, const lzma_filter *filters);
  93
  94
  95 /// Print a message that user should try --help.
  96 extern void message_try_help(void);
  97
  98
  99 /// Print the memory usage limit and exit.
 100 extern void message_memlimit(void) lzma_attribute((noreturn));
 101
 102
 103 /// Prints the version number to stdout and exits with exit status SUCCESS.
 104 extern void message_version(void) lzma_attribute((noreturn));
 105
 106
 107 /// Print the help message.
 108 extern void message_help(bool long_help) lzma_attribute((noreturn));
 109
 110
 111 /// \brief      Start progress info handling
 112 ///
 113 /// This must be paired with a call to message_progress_end() before the
 114 /// given *strm becomes invalid.
 115 ///
 116 /// \param      strm      Pointer to lzma_stream used for the coding.
 117 /// \param      filename  Name of the input file. stdin_filename is
 118 ///                       handled specially.
 119 /// \param      in_size   Size of the input file, or zero if unknown.
 120 ///
 121 extern void message_progress_start(
 122                 lzma_stream *strm, const char *filename, uint64_t in_size);
 123
 124
 125 /// Update the progress info if in verbose mode and enough time has passed
 126 /// since the previous update. This can be called only when
 127 /// message_progress_start() has already been used.
 128 extern void message_progress_update(void);
 129
 130
 131 /// \brief      Finishes the progress message if we were in verbose mode
 132 ///
 133 /// \param      finished    True if the whole stream was successfully coded
 134 ///                         and output written to the output stream.
 135 ///
 136 extern void message_progress_end(bool finished);