contrib/xz/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,    ///< Very verbose
  20 };
  21
  22
  23 /// \brief      Signals used for progress message handling
  24 extern const int message_progress_sigs[];
  25
  26
  27 /// \brief      Initializes the message functions
  28 ///
  29 /// If an error occurs, this function doesn't return.
  30 ///
  31 extern void message_init(void);
  32
  33
  34 /// Increase verbosity level by one step unless it was at maximum.
  35 extern void message_verbosity_increase(void);
  36
  37 /// Decrease verbosity level by one step unless it was at minimum.
  38 extern void message_verbosity_decrease(void);
  39
  40 /// Get the current verbosity level.
  41 extern enum message_verbosity message_verbosity_get(void);
  42
  43
  44 /// \brief      Print a message if verbosity level is at least "verbosity"
  45 ///
  46 /// This doesn't touch the exit status.
  47 extern void message(enum message_verbosity verbosity, const char *fmt, ...)
  48                 lzma_attribute((format(printf, 2, 3)));
  49
  50
  51 /// \brief      Prints a warning and possibly sets exit status
  52 ///
  53 /// The message is printed only if verbosity level is at least V_WARNING.
  54 /// The exit status is set to WARNING unless it was already at ERROR.
  55 extern void message_warning(const char *fmt, ...)
  56                 lzma_attribute((format(printf, 1, 2)));
  57
  58
  59 /// \brief      Prints an error message and sets exit status
  60 ///
  61 /// The message is printed only if verbosity level is at least V_ERROR.
  62 /// The exit status is set to ERROR.
  63 extern void message_error(const char *fmt, ...)
  64                 lzma_attribute((format(printf, 1, 2)));
  65
  66
  67 /// \brief      Prints an error message and exits with EXIT_ERROR
  68 ///
  69 /// The message is printed only if verbosity level is at least V_ERROR.
  70 extern void message_fatal(const char *fmt, ...)
  71                 lzma_attribute((format(printf, 1, 2)))
  72                 lzma_attribute((noreturn));
  73
  74
  75 /// Print an error message that an internal error occurred and exit with
  76 /// EXIT_ERROR.
  77 extern void message_bug(void) lzma_attribute((noreturn));
  78
  79
  80 /// Print a message that establishing signal handlers failed, and exit with
  81 /// exit status ERROR.
  82 extern void message_signal_handler(void) lzma_attribute((noreturn));
  83
  84
  85 /// Convert lzma_ret to a string.
  86 extern const char *message_strm(lzma_ret code);
  87
  88
  89 /// Display how much memory was needed and how much the limit was.
  90 extern void message_mem_needed(enum message_verbosity v, uint64_t memusage);
  91
  92
  93 /// Buffer size for message_filters_to_str()
  94 #define FILTERS_STR_SIZE 512
  95
  96
  97 /// \brief      Get the filter chain as a string
  98 ///
  99 /// \param      buf         Pointer to caller allocated buffer to hold
 100 ///                         the filter chain string
 101 /// \param      filters     Pointer to the filter chain
 102 /// \param      all_known   If true, all filter options are printed.
 103 ///                         If false, only the options that get stored
 104 ///                         into .xz headers are printed.
 105 extern void message_filters_to_str(char buf[FILTERS_STR_SIZE],
 106                 const lzma_filter *filters, bool all_known);
 107
 108
 109 /// Print the filter chain.
 110 extern void message_filters_show(
 111                 enum message_verbosity v, const lzma_filter *filters);
 112
 113
 114 /// Print a message that user should try --help.
 115 extern void message_try_help(void);
 116
 117
 118 /// Prints the version number to stdout and exits with exit status SUCCESS.
 119 extern void message_version(void) lzma_attribute((noreturn));
 120
 121
 122 /// Print the help message.
 123 extern void message_help(bool long_help) lzma_attribute((noreturn));
 124
 125
 126 /// \brief      Set the total number of files to be processed
 127 ///
 128 /// Standard input is counted as a file here. This is used when printing
 129 /// the filename via message_filename().
 130 extern void message_set_files(unsigned int files);
 131
 132
 133 /// \brief      Set the name of the current file and possibly print it too
 134 ///
 135 /// The name is printed immediately if --list was used or if --verbose
 136 /// was used and stderr is a terminal. Even when the filename isn't printed,
 137 /// it is stored so that it can be printed later if needed for progress
 138 /// messages.
 139 extern void message_filename(const char *src_name);
 140
 141
 142 /// \brief      Start progress info handling
 143 ///
 144 /// message_filename() must be called before this function to set
 145 /// the filename.
 146 ///
 147 /// This must be paired with a call to message_progress_end() before the
 148 /// given *strm becomes invalid.
 149 ///
 150 /// \param      strm      Pointer to lzma_stream used for the coding.
 151 /// \param      in_size   Size of the input file, or zero if unknown.
 152 ///
 153 extern void message_progress_start(lzma_stream *strm, uint64_t in_size);
 154
 155
 156 /// Update the progress info if in verbose mode and enough time has passed
 157 /// since the previous update. This can be called only when
 158 /// message_progress_start() has already been used.
 159 extern void message_progress_update(void);
 160
 161
 162 /// \brief      Finishes the progress message if we were in verbose mode
 163 ///
 164 /// \param      finished    True if the whole stream was successfully coded
 165 ///                         and output written to the output stream.
 166 ///
 167 extern void message_progress_end(bool finished);