apt-pkg/contrib/error.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: error.h,v 1.8 2001/05/07 05:06:52 jgg Exp $
   4 /* ######################################################################
   5
   6    Global Erorr Class - Global error mechanism
   7
   8    This class has a single global instance. When a function needs to
   9    generate an error condition, such as a read error, it calls a member
  10    in this class to add the error to a stack of errors.
  11
  12    By using a stack the problem with a scheme like errno is removed and
  13    it allows a very detailed account of what went wrong to be transmitted
  14    to the UI for display. (Errno has problems because each function sets
  15    errno to 0 if it didn't have an error thus eraseing erno in the process
  16    of cleanup)
  17
  18    Several predefined error generators are provided to handle common
  19    things like errno. The general idea is that all methods return a bool.
  20    If the bool is true then things are OK, if it is false then things
  21    should start being undone and the stack should unwind under program
  22    control.
  23
  24    A Warning should not force the return of false. Things did not fail, but
  25    they might have had unexpected problems. Errors are stored in a FIFO
  26    so Pop will return the first item..
  27
  28    I have some thoughts about extending this into a more general UI<->
  29    Engine interface, ie allowing the Engine to say 'The disk is full' in
  30    a dialog that says 'Panic' and 'Retry'.. The error generator functions
  31    like errno, Warning and Error return false always so this is normal:
  32      if (open(..))
  33         return _error->Errno(..);
  34
  35    This source is placed in the Public Domain, do with it what you will
  36    It was originally written by Jason Gunthorpe.
  37
  38    ##################################################################### */
  39                                                                         /*}}}*/
  40 #ifndef PKGLIB_ERROR_H
  41 #define PKGLIB_ERROR_H
  42
  43 #include <apt-pkg/macros.h>
  44
  45 #include <iostream>
  46 #include <list>
  47 #include <string>
  48
  49 #include <stdarg.h>
  50
  51 class GlobalError                                                       /*{{{*/
  52 {
  53 public:                                                                 /*{{{*/
  54         /** \brief a message can have one of following severity */
  55         enum MsgType {
  56                 /** \brief Message will be printed instantly as it is likely that
  57                         this error will lead to a complete crash */
  58                 FATAL = 40,
  59                 /** \brief An error does hinder the correct execution and should be corrected */
  60                 ERROR = 30,
  61                 /** \brief indicates problem that can lead to errors later on */
  62                 WARNING = 20,
  63                 /** \brief deprecation warnings, old fallback behavior, … */
  64                 NOTICE = 10,
  65                 /** \brief for developers only in areas it is hard to print something directly */
  66                 DEBUG = 0
  67         };
  68
  69         /** \brief add a fatal error message with errno to the list
  70          *
  71          *  \param Function name of the function generating the error
  72          *  \param Description format string for the error message
  73          *
  74          *  \return \b false
  75          */
  76         bool FatalE(const char *Function,const char *Description,...) __like_printf(3) __cold;
  77
  78         /** \brief add an Error message with errno to the list
  79          *
  80          *  \param Function name of the function generating the error
  81          *  \param Description format string for the error message
  82          *
  83          *  \return \b false
  84          */
  85         bool Errno(const char *Function,const char *Description,...) __like_printf(3) __cold;
  86
  87         /** \brief add a warning message with errno to the list
  88          *
  89          *  A warning should be considered less severe than an error and
  90          *  may be ignored by the client.
  91          *
  92          *  \param Function Name of the function generates the warning.
  93          *  \param Description Format string for the warning message.
  94          *
  95          *  \return \b false
  96          */
  97         bool WarningE(const char *Function,const char *Description,...) __like_printf(3) __cold;
  98
  99         /** \brief add a notice message with errno to the list
 100          *
 101          *  \param Function name of the function generating the error
 102          *  \param Description format string for the error message
 103          *
 104          *  \return \b false
 105          */
 106         bool NoticeE(const char *Function,const char *Description,...) __like_printf(3) __cold;
 107
 108         /** \brief add a debug message with errno to the list
 109          *
 110          *  \param Function name of the function generating the error
 111          *  \param Description format string for the error message
 112          *
 113          *  \return \b false
 114          */
 115         bool DebugE(const char *Function,const char *Description,...) __like_printf(3) __cold;
 116
 117         /** \brief add an fatal error message to the list
 118          *
 119          *  Most of the stuff we consider as "error" is also "fatal" for
 120          *  the user as the application will not have the expected result,
 121          *  but a fatal message here means that it gets printed directly
 122          *  to stderr in addiction to adding it to the list as the error
 123          *  leads sometimes to crashes and a maybe duplicated message
 124          *  is better than "Segfault" as the only displayed text
 125          *
 126          *  \param Description Format string for the fatal error message.
 127          *
 128          *  \return \b false
 129          */
 130         bool Fatal(const char *Description,...) __like_printf(2) __cold;
 131
 132         /** \brief add an Error message to the list
 133          *
 134          *  \param Description Format string for the error message.
 135          *
 136          *  \return \b false
 137          */
 138         bool Error(const char *Description,...) __like_printf(2) __cold;
 139
 140         /** \brief add a warning message to the list
 141          *
 142          *  A warning should be considered less severe than an error and
 143          *  may be ignored by the client.
 144          *
 145          *  \param Description Format string for the message
 146          *
 147          *  \return \b false
 148          */
 149         bool Warning(const char *Description,...) __like_printf(2) __cold;
 150
 151         /** \brief add a notice message to the list
 152          *
 153          *  A notice should be considered less severe than an error or a
 154          *  warning and can be ignored by the client without further problems
 155          *  for some times, but he should consider fixing the problem.
 156          *  This error type can be used for e.g. deprecation warnings of options.
 157          *
 158          *  \param Description Format string for the message
 159          *
 160          *  \return \b false
 161          */
 162         bool Notice(const char *Description,...) __like_printf(2) __cold;
 163
 164         /** \brief add a debug message to the list
 165          *
 166          *  \param Description Format string for the message
 167          *
 168          *  \return \b false
 169          */
 170         bool Debug(const char *Description,...) __like_printf(2) __cold;
 171
 172         /** \brief is an error in the list?
 173          *
 174          *  \return \b true if an error is included in the list, \b false otherwise
 175          */
 176         inline bool PendingError() const {return PendingFlag;};
 177
 178         /** \brief is the list empty?
 179          *
 180          *  The default checks if the list is empty or contains only notices,
 181          *  if you want to check if also no notices happend set the parameter
 182          *  flag to \b false.
 183          *
 184          *  \param WithoutNotice does notices count, default is \b true, so no
 185          *
 186          *  \return \b true if an the list is empty, \b false otherwise
 187          */
 188         bool empty(MsgType const &trashhold = WARNING) const;
 189
 190         /** \brief returns and removes the first (or last) message in the list
 191          *
 192          *  \param[out] Text message of the first/last item
 193          *
 194          *  \return \b true if the message was an error, \b false otherwise
 195          */
 196         bool PopMessage(std::string &Text);
 197
 198         /** \brief clears the list of messages */
 199         void Discard();
 200
 201         /** \brief outputs the list of messages to the given stream
 202          *
 203          *  Note that all messages are discarded, also the notices
 204          *  displayed or not.
 205          *
 206          *  \param[out] out output stream to write the messages in
 207          *  \param WithoutNotice output notices or not
 208          */
 209         void DumpErrors(std::ostream &out, MsgType const &trashhold = WARNING);
 210
 211         /** \brief dumps the list of messages to std::cerr
 212          *
 213          *  Note that all messages are discarded, also the notices
 214          *  displayed or not.
 215          *
 216          *  \param WithoutNotice print notices or not
 217          */
 218         void inline DumpErrors(MsgType const &trashhold = WARNING) {
 219                 DumpErrors(std::cerr, trashhold);
 220         }
 221
 222         GlobalError();
 223                                                                         /*}}}*/
 224 private:                                                                /*{{{*/
 225         struct Item {
 226                 std::string Text;
 227                 MsgType Type;
 228
 229                 Item(char const *Text, MsgType const &Type) :
 230                         Text(Text), Type(Type) {};
 231
 232                 friend std::ostream& operator<< (std::ostream &out, Item i) {
 233                         switch(i.Type) {
 234                         case FATAL:
 235                         case ERROR: out << "E"; break;
 236                         case WARNING: out << "W"; break;
 237                         case NOTICE: out << "N"; break;
 238                         case DEBUG: out << "D"; break;
 239                         }
 240                         return out << ": " << i.Text;
 241                 }
 242         };
 243
 244         std::list<Item> Messages;
 245         bool PendingFlag;
 246
 247         bool InsertErrno(MsgType type, const char* Function,
 248                          const char* Description, va_list const &args);
 249         bool Insert(MsgType type, const char* Description,
 250                          va_list const &args);
 251                                                                         /*}}}*/
 252 };
 253                                                                         /*}}}*/
 254
 255 // The 'extra-ansi' syntax is used to help with collisions.
 256 GlobalError *_GetErrorObj();
 257 #define _error _GetErrorObj()
 258
 259 #endif