apt: apt-pkg/contrib/error.h Source File

apt 2.7.5 commandline package manager

error.h
1// -*- mode: cpp; mode: fold -*-
2// SPDX-License-Identifier: GPL-2.0+
3// Description /*{{{*/
4/* ######################################################################
5
6 Global Error 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 file had this historic note, but now includes further changes
36 under the GPL-2.0+:
37
38 This source is placed in the Public Domain, do with it what you will
39 It was originally written by Jason Gunthorpe.
40
41 ##################################################################### */
42 /*}}}*/
43#ifndef PKGLIB_ERROR_H
44#define PKGLIB_ERROR_H
45
46#include <apt-pkg/macros.h>
47
48#include <iostream>
49#include <list>
50#include <string>
51
52#include <stdarg.h>
53#include <stddef.h>
54
55 class APT_PUBLIC GlobalError /*{{{*/
56{
57public: /*{{{*/
59 enum MsgType {
62 FATAL = 40,
64 ERROR = 30,
66 WARNING = 20,
68 NOTICE = 10,
70 DEBUG = 0
71 };
72
80 bool FatalE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
81
89 bool Errno(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
90
101 bool WarningE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
102
110 bool NoticeE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
111
119 bool DebugE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
120
127 bool InsertErrno(MsgType const &type, const char* Function,
128 const char* Description,...) APT_PRINTF(4) APT_COLD;
129
145 bool InsertErrno(MsgType type, const char* Function,
146 const char* Description, va_list &args,
147 int const errsv, size_t &msgSize) APT_COLD;
148
162 bool Fatal(const char *Description,...) APT_PRINTF(2) APT_COLD;
163
170 bool Error(const char *Description,...) APT_PRINTF(2) APT_COLD;
171
181 bool Warning(const char *Description,...) APT_PRINTF(2) APT_COLD;
182
194 bool Notice(const char *Description,...) APT_PRINTF(2) APT_COLD;
195
202 bool Debug(const char *Description,...) APT_PRINTF(2) APT_COLD;
203
209 bool Insert(MsgType const &type, const char* Description,...) APT_PRINTF(3) APT_COLD;
210
224 bool Insert(MsgType type, const char* Description,
225 va_list &args, size_t &msgSize) APT_COLD;
226
231 inline bool PendingError() const APT_PURE {return PendingFlag;};
232
243 bool empty(MsgType const &threshold = WARNING) const APT_PURE;
244
251 bool PopMessage(std::string &Text);
252
254 void Discard();
255
264 void DumpErrors(std::ostream &out, MsgType const &threshold = WARNING,
265 bool const &mergeStack = true);
266
274 void inline DumpErrors(MsgType const &threshold) {
275 DumpErrors(std::cerr, threshold);
276 }
277
278 // mvo: we do this instead of using a default parameter in the
279 // previous declaration to avoid a (subtle) API break for
280 // e.g. sigc++ and mem_fun0
286 void inline DumpErrors() {
287 DumpErrors(WARNING);
288 }
289
299 void PushToStack();
300
302 void RevertToStack();
303
305 void MergeWithStack();
306
308 size_t StackCount() const APT_PURE {
309 return Stacks.size();
310 }
311
312 GlobalError();
313 /*}}}*/
314private: /*{{{*/
315 struct Item {
316 std::string Text;
317 MsgType Type;
318
319 Item(char const *Text, MsgType const &Type) :
320 Text(Text), Type(Type) {};
321
322 APT_HIDDEN friend std::ostream &operator<<(std::ostream &out, Item i);
323 };
324
325 APT_HIDDEN friend std::ostream &operator<<(std::ostream &out, Item i);
326
327 std::list<Item> Messages;
328 bool PendingFlag;
329
330 struct MsgStack {
331 std::list<Item> Messages;
332 bool const PendingFlag;
333
334 MsgStack(std::list<Item> const &Messages, bool const &Pending) :
335 Messages(Messages), PendingFlag(Pending) {};
336 };
337
338 std::list<MsgStack> Stacks;
339 /*}}}*/
340};
341 /*}}}*/
342
343// The 'extra-ansi' syntax is used to help with collisions.
344APT_PUBLIC GlobalError *_GetErrorObj();
345static struct {
346 inline GlobalError* operator ->() { return _GetErrorObj(); }
347} _error APT_UNUSED;
348
349#endif
GlobalError
Definition error.h:56
GlobalError::MsgType
MsgType
a message can have one of following severity
Definition error.h:59
GlobalError::StackCount
size_t StackCount() const APT_PURE
return the deep of the stack
Definition error.h:308
GlobalError::DumpErrors
void DumpErrors()
dumps the messages of type WARNING or higher to std::cerr
Definition error.h:286
GlobalError::DumpErrors
void DumpErrors(MsgType const &threshold)
dumps the list of messages to std::cerr
Definition error.h:274
GlobalError::FatalE
bool FatalE(const char *Function, const char *Description,...) APT_PRINTF(3) APT_COLD
add a fatal error message with errno to the list