src/xz/message.h

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