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

apt 3.3.3 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 <cstdarg>
53#include <cstddef>
54
55 class APT_PUBLIC GlobalError /*{{{*/
56{
57public: /*{{{*/
59 enum MsgType {
62 FATAL = 40,
64 ERROR = 30,
66 WARNING = 20,
68 NOTICE = 10,
70 AUDIT = 5,
72 DEBUG = 0
73 };
74
82 bool FatalE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
83
91 bool Errno(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
92
103 bool WarningE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
104
112 bool NoticeE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
113
121 bool AuditE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
122
130 bool DebugE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
131
138 bool InsertErrno(MsgType const &type, const char* Function,
139 const char* Description,...) APT_PRINTF(4) APT_COLD;
140
156 bool InsertErrno(MsgType type, const char* Function,
157 const char* Description, va_list &args,
158 int const errsv, size_t &msgSize) APT_COLD;
159
173 bool Fatal(const char *Description,...) APT_PRINTF(2) APT_COLD;
174
181 bool Error(const char *Description,...) APT_PRINTF(2) APT_COLD;
182
192 bool Warning(const char *Description,...) APT_PRINTF(2) APT_COLD;
193
205 bool Notice(const char *Description,...) APT_PRINTF(2) APT_COLD;
206
217 bool Audit(const char *Description,...) APT_PRINTF(2) APT_COLD;
218
225 bool Debug(const char *Description,...) APT_PRINTF(2) APT_COLD;
226
232 bool Insert(MsgType const &type, const char* Description,...) APT_PRINTF(3) APT_COLD;
233
247 bool Insert(MsgType type, const char* Description,
248 va_list &args, size_t &msgSize) APT_COLD;
249
254 inline bool PendingError() const APT_PURE {return PendingFlag;};
255
266 bool empty(MsgType const &threshold = WARNING) const APT_PURE;
267
274 bool PopMessage(std::string &Text);
275
277 void Discard();
278
287 void DumpErrors(std::ostream &out, MsgType const &threshold = WARNING,
288 bool const &mergeStack = true);
289
297 void inline DumpErrors(MsgType const &threshold) {
298 DumpErrors(std::cerr, threshold);
299 }
300
301 // mvo: we do this instead of using a default parameter in the
302 // previous declaration to avoid a (subtle) API break for
303 // e.g. sigc++ and mem_fun0
309 void inline DumpErrors() {
310 DumpErrors(WARNING);
311 }
312
322 void PushToStack();
323
325 void RevertToStack();
326
328 void MergeWithStack();
329
331 size_t StackCount() const APT_PURE {
332 return Stacks.size();
333 }
334
335 GlobalError();
336 /*}}}*/
337private: /*{{{*/
338 struct Item {
339 std::string Text;
340 MsgType Type;
341
342 Item(char const *Text, MsgType const &Type) :
343 Text(Text), Type(Type) {};
344
345 APT_HIDDEN friend std::ostream &operator<<(std::ostream &out, Item i);
346 };
347
348 APT_HIDDEN friend std::ostream &operator<<(std::ostream &out, Item i);
349
350 std::list<Item> Messages;
351 bool PendingFlag;
352
353 struct MsgStack {
354 std::list<Item> Messages;
355 bool const PendingFlag;
356
357 MsgStack(std::list<Item> const &Messages, bool const &Pending) :
358 Messages(Messages), PendingFlag(Pending) {};
359 };
360
361 std::list<MsgStack> Stacks;
362 /*}}}*/
363};
364 /*}}}*/
365
366// The 'extra-ansi' syntax is used to help with collisions.
367APT_PUBLIC GlobalError *_GetErrorObj();
368static struct {
369 inline GlobalError* operator ->() { return _GetErrorObj(); }
370} _error [[maybe_unused]];
371
372#endif
GlobalError
Definition error.h:56
GlobalError::PendingError
bool PendingError() const APT_PURE
is an error in the list?
Definition error.h:254
GlobalError::MsgType
MsgType
a message can have one of following severity
Definition error.h:59
GlobalError::DEBUG
@ DEBUG
for developers only in areas it is hard to print something directly
Definition error.h:72
GlobalError::AUDIT
@ AUDIT
future deprecation warnings, divergence from best practices
Definition error.h:70
GlobalError::ERROR
@ ERROR
An error does hinder the correct execution and should be corrected.
Definition error.h:64
GlobalError::FATAL
@ FATAL
Message will be printed instantly as it is likely that this error will lead to a complete crash.
Definition error.h:62
GlobalError::WARNING
@ WARNING
indicates problem that can lead to errors later on
Definition error.h:66
GlobalError::NOTICE
@ NOTICE
deprecation warnings, old fallback behavior, …
Definition error.h:68
GlobalError::StackCount
size_t StackCount() const APT_PURE
return the deep of the stack
Definition error.h:331
GlobalError::DumpErrors
void DumpErrors(std::ostream &out, MsgType const &threshold=WARNING, bool const &mergeStack=true)
outputs the list of messages to the given stream
Definition error.cc:194
GlobalError::AuditE
bool AuditE(const char *Function, const char *Description,...) APT_PRINTF(3) APT_COLD
add an audit message with errno to the list
GlobalError::Insert
bool Insert(MsgType const &type, const char *Description,...) APT_PRINTF(3) APT_COLD
adds an error message with the given type
Definition error.cc:130
GlobalError::Fatal
bool Fatal(const char *Description,...) APT_PRINTF(2) APT_COLD
add an fatal error message to the list
GlobalError::DumpErrors
void DumpErrors()
dumps the messages of type WARNING or higher to std::cerr
Definition error.h:309
GlobalError::Notice
bool Notice(const char *Description,...) APT_PRINTF(2) APT_COLD
add a notice message to the list
GlobalError::DumpErrors
void DumpErrors(MsgType const &threshold)
dumps the list of messages to std::cerr
Definition error.h:297
GlobalError::DebugE
bool DebugE(const char *Function, const char *Description,...) APT_PRINTF(3) APT_COLD
add a debug message with errno to the list
GlobalError::Error
bool Error(const char *Description,...) APT_PRINTF(2) APT_COLD
add an Error message to the list
GlobalError::WarningE
bool WarningE(const char *Function, const char *Description,...) APT_PRINTF(3) APT_COLD
add a warning message with errno to the list
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
GlobalError::Audit
bool Audit(const char *Description,...) APT_PRINTF(2) APT_COLD
add an audit message to the list
GlobalError::Warning
bool Warning(const char *Description,...) APT_PRINTF(2) APT_COLD
add a warning message to the list
GlobalError::InsertErrno
bool InsertErrno(MsgType const &type, const char *Function, const char *Description,...) APT_PRINTF(4) APT_COLD
adds an errno message with the given type
Definition error.cc:74
GlobalError::Debug
bool Debug(const char *Description,...) APT_PRINTF(2) APT_COLD
add a debug message to the list
GlobalError::NoticeE
bool NoticeE(const char *Function, const char *Description,...) APT_PRINTF(3) APT_COLD
add a notice message with errno to the list
GlobalError::Errno
bool Errno(const char *Function, const char *Description,...) APT_PRINTF(3) APT_COLD
add an Error message with errno to the list