libstdc++
system_error
Go to the documentation of this file.
1 // <system_error> -*- C++ -*-
2 
3 // Copyright (C) 2007-2021 Free Software Foundation, Inc.
4 //
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 3, or (at your option)
9 // any later version.
10 
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
15 
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
19 
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
24 
25 /** @file include/system_error
26  * This is a Standard C++ Library header.
27  */
28 
29 #ifndef _GLIBCXX_SYSTEM_ERROR
30 #define _GLIBCXX_SYSTEM_ERROR 1
31 
32 #pragma GCC system_header
33 
34 #if __cplusplus < 201103L
35 # include <bits/c++0x_warning.h>
36 #else
37 
38 #include <bits/c++config.h>
39 #include <bits/error_constants.h>
40 #include <iosfwd>
41 #include <stdexcept>
42 #if __cplusplus > 201703L
43 # include <compare>
44 #endif
45 
46 namespace std _GLIBCXX_VISIBILITY(default)
47 {
48 _GLIBCXX_BEGIN_NAMESPACE_VERSION
49 
50  /** @addtogroup diagnostics
51  * @{
52  */
53 
54  class error_code;
55  class error_condition;
56  class system_error;
57 
58  /// is_error_code_enum
59  template<typename _Tp>
60  struct is_error_code_enum : public false_type { };
61 
62  /// is_error_condition_enum
63  template<typename _Tp>
64  struct is_error_condition_enum : public false_type { };
65 
66  template<>
67  struct is_error_condition_enum<errc>
68  : public true_type { };
69 
70 #if __cplusplus > 201402L
71  template <typename _Tp>
72  inline constexpr bool is_error_code_enum_v =
73  is_error_code_enum<_Tp>::value;
74  template <typename _Tp>
75  inline constexpr bool is_error_condition_enum_v =
76  is_error_condition_enum<_Tp>::value;
77 #endif // C++17
78  inline namespace _V2 {
79 
80  /** Abstract base class for types defining a category of error codes.
81  *
82  * An error category defines a context that give meaning to the integer
83  * stored in an `error_code` or `error_condition` object. For example,
84  * the standard `errno` constants such a `EINVAL` and `ENOMEM` are
85  * associated with the "generic" category and other OS-specific error
86  * numbers are associated with the "system" category, but a user-defined
87  * category might give different meanings to the same numerical values.
88  */
89  class error_category
90  {
91  public:
92  constexpr error_category() noexcept = default;
93 
94  virtual ~error_category();
95 
96  error_category(const error_category&) = delete;
97  error_category& operator=(const error_category&) = delete;
98 
99  virtual const char*
100  name() const noexcept = 0;
101 
102  // We need two different virtual functions here, one returning a
103  // COW string and one returning an SSO string. Their positions in the
104  // vtable must be consistent for dynamic dispatch to work, but which one
105  // the name "message()" finds depends on which ABI the caller is using.
106 #if _GLIBCXX_USE_CXX11_ABI
107  private:
108  _GLIBCXX_DEFAULT_ABI_TAG
109  virtual __cow_string
110  _M_message(int) const;
111 
112  public:
113  _GLIBCXX_DEFAULT_ABI_TAG
114  virtual string
115  message(int) const = 0;
116 #else
117  virtual string
118  message(int) const = 0;
119 
120  private:
121  virtual __sso_string
122  _M_message(int) const;
123 #endif
124 
125  public:
126  virtual error_condition
127  default_error_condition(int __i) const noexcept;
128 
129  virtual bool
130  equivalent(int __i, const error_condition& __cond) const noexcept;
131 
132  virtual bool
133  equivalent(const error_code& __code, int __i) const noexcept;
134 
135  bool
136  operator==(const error_category& __other) const noexcept
137  { return this == &__other; }
138 
139 #if __cpp_lib_three_way_comparison
140  strong_ordering
141  operator<=>(const error_category& __rhs) const noexcept
142  { return std::compare_three_way()(this, &__rhs); }
143 #else
144  bool
145  operator!=(const error_category& __other) const noexcept
146  { return this != &__other; }
147 
148  bool
149  operator<(const error_category& __other) const noexcept
150  { return less<const error_category*>()(this, &__other); }
151 #endif
152  };
153 
154  // DR 890.
155 
156  /// Error category for `errno` error codes.
157  _GLIBCXX_CONST const error_category& generic_category() noexcept;
158 
159  /// Error category for other error codes defined by the OS.
160  _GLIBCXX_CONST const error_category& system_category() noexcept;
161 
162  } // end inline namespace
163 
164  error_code make_error_code(errc) noexcept;
165 
166  /** Class error_code
167  *
168  * This class is a value type storing an integer error number and a
169  * category that gives meaning to the error number. Typically this is done
170  * close the the point where the error happens, to capture the original
171  * error value.
172  *
173  * An `error_code` object can be used to store the original error value
174  * emitted by some subsystem, with a category relevant to the subsystem.
175  * For example, errors from POSIX library functions can be represented by
176  * an `errno` value and the "generic" category, but errors from an HTTP
177  * library might be represented by an HTTP response status code (e.g. 404)
178  * and a custom category defined by the library.
179  */
180  class error_code
181  {
182  public:
183  error_code() noexcept
184  : _M_value(0), _M_cat(&system_category()) { }
185 
186  error_code(int __v, const error_category& __cat) noexcept
187  : _M_value(__v), _M_cat(&__cat) { }
188 
189  template<typename _ErrorCodeEnum, typename = typename
190  enable_if<is_error_code_enum<_ErrorCodeEnum>::value>::type>
191  error_code(_ErrorCodeEnum __e) noexcept
192  { *this = make_error_code(__e); }
193 
194  void
195  assign(int __v, const error_category& __cat) noexcept
196  {
197  _M_value = __v;
198  _M_cat = &__cat;
199  }
200 
201  void
202  clear() noexcept
203  { assign(0, system_category()); }
204 
205  // DR 804.
206  template<typename _ErrorCodeEnum>
207  typename enable_if<is_error_code_enum<_ErrorCodeEnum>::value,
208  error_code&>::type
209  operator=(_ErrorCodeEnum __e) noexcept
210  { return *this = make_error_code(__e); }
211 
212  int
213  value() const noexcept { return _M_value; }
214 
215  const error_category&
216  category() const noexcept { return *_M_cat; }
217 
218  error_condition
219  default_error_condition() const noexcept;
220 
221  _GLIBCXX_DEFAULT_ABI_TAG
222  string
223  message() const
224  { return category().message(value()); }
225 
226  explicit operator bool() const noexcept
227  { return _M_value != 0; }
228 
229  // DR 804.
230  private:
231  int _M_value;
232  const error_category* _M_cat;
233  };
234 
235  // 19.4.2.6 non-member functions
236 
237  /// @relates error_code @{
238 
239  inline error_code
240  make_error_code(errc __e) noexcept
241  { return error_code(static_cast<int>(__e), generic_category()); }
242 
243 #if __cpp_lib_three_way_comparison
244  inline strong_ordering
245  operator<=>(const error_code& __lhs, const error_code& __rhs) noexcept
246  {
247  if (auto __c = __lhs.category() <=> __rhs.category(); __c != 0)
248  return __c;
249  return __lhs.value() <=> __rhs.value();
250  }
251 #else
252  inline bool
253  operator<(const error_code& __lhs, const error_code& __rhs) noexcept
254  {
255  return (__lhs.category() < __rhs.category()
256  || (__lhs.category() == __rhs.category()
257  && __lhs.value() < __rhs.value()));
258  }
259 #endif
260 
261  template<typename _CharT, typename _Traits>
262  basic_ostream<_CharT, _Traits>&
263  operator<<(basic_ostream<_CharT, _Traits>& __os, const error_code& __e)
264  { return (__os << __e.category().name() << ':' << __e.value()); }
265 
266  // @}
267 
268  error_condition make_error_condition(errc) noexcept;
269 
270  /** Class error_condition
271  *
272  * This class represents error conditions that may be visible at an API
273  * boundary. Different `error_code` values that can occur within a library
274  * or module might map to the same `error_condition`.
275  *
276  * An `error_condition` represents something that the program can test for,
277  * and subsequently take appropriate action.
278  */
279  class error_condition
280  {
281  public:
282  error_condition() noexcept
283  : _M_value(0), _M_cat(&generic_category()) { }
284 
285  error_condition(int __v, const error_category& __cat) noexcept
286  : _M_value(__v), _M_cat(&__cat) { }
287 
288  template<typename _ErrorConditionEnum, typename = typename
289  enable_if<is_error_condition_enum<_ErrorConditionEnum>::value>::type>
290  error_condition(_ErrorConditionEnum __e) noexcept
291  { *this = make_error_condition(__e); }
292 
293  void
294  assign(int __v, const error_category& __cat) noexcept
295  {
296  _M_value = __v;
297  _M_cat = &__cat;
298  }
299 
300  // DR 804.
301  template<typename _ErrorConditionEnum>
302  typename enable_if<is_error_condition_enum
303  <_ErrorConditionEnum>::value, error_condition&>::type
304  operator=(_ErrorConditionEnum __e) noexcept
305  { return *this = make_error_condition(__e); }
306 
307  void
308  clear() noexcept
309  { assign(0, generic_category()); }
310 
311  // 19.4.3.4 observers
312  int
313  value() const noexcept { return _M_value; }
314 
315  const error_category&
316  category() const noexcept { return *_M_cat; }
317 
318  _GLIBCXX_DEFAULT_ABI_TAG
319  string
320  message() const
321  { return category().message(value()); }
322 
323  explicit operator bool() const noexcept
324  { return _M_value != 0; }
325 
326  // DR 804.
327  private:
328  int _M_value;
329  const error_category* _M_cat;
330  };
331 
332  // 19.4.3.6 non-member functions
333 
334  /// Create an `error_condition` representing a standard `errc` condition.
335  /// @relates error_condition
336  inline error_condition
337  make_error_condition(errc __e) noexcept
338  { return error_condition(static_cast<int>(__e), generic_category()); }
339 
340  // 19.4.4 Comparison operators
341 
342  /// @relates error_code
343  inline bool
344  operator==(const error_code& __lhs, const error_code& __rhs) noexcept
345  { return (__lhs.category() == __rhs.category()
346  && __lhs.value() == __rhs.value()); }
347 
348  /// @relates error_code
349  /// @relates error_condition
350  inline bool
351  operator==(const error_code& __lhs, const error_condition& __rhs) noexcept
352  {
353  return (__lhs.category().equivalent(__lhs.value(), __rhs)
354  || __rhs.category().equivalent(__lhs, __rhs.value()));
355  }
356 
357  /// @relates error_condition
358  inline bool
359  operator==(const error_condition& __lhs,
360  const error_condition& __rhs) noexcept
361  {
362  return (__lhs.category() == __rhs.category()
363  && __lhs.value() == __rhs.value());
364  }
365 
366 #if __cpp_lib_three_way_comparison
367  /// Define an ordering for error_condition objects.
368  /// @relates error_condition
369  inline strong_ordering
370  operator<=>(const error_condition& __lhs,
371  const error_condition& __rhs) noexcept
372  {
373  if (auto __c = __lhs.category() <=> __rhs.category(); __c != 0)
374  return __c;
375  return __lhs.value() <=> __rhs.value();
376  }
377 #else
378  /// Define an ordering for error_condition objects.
379  /// @relates error_condition
380  inline bool
381  operator<(const error_condition& __lhs,
382  const error_condition& __rhs) noexcept
383  {
384  return (__lhs.category() < __rhs.category()
385  || (__lhs.category() == __rhs.category()
386  && __lhs.value() < __rhs.value()));
387  }
388 
389  /// @relates error_code
390  /// @relates error_condition
391  inline bool
392  operator==(const error_condition& __lhs, const error_code& __rhs) noexcept
393  {
394  return (__rhs.category().equivalent(__rhs.value(), __lhs)
395  || __lhs.category().equivalent(__rhs, __lhs.value()));
396  }
397 
398  /// @relates error_code
399  inline bool
400  operator!=(const error_code& __lhs, const error_code& __rhs) noexcept
401  { return !(__lhs == __rhs); }
402 
403  /// @relates error_code
404  /// @relates error_condition
405  inline bool
406  operator!=(const error_code& __lhs, const error_condition& __rhs) noexcept
407  { return !(__lhs == __rhs); }
408 
409  /// @relates error_code
410  /// @relates error_condition
411  inline bool
412  operator!=(const error_condition& __lhs, const error_code& __rhs) noexcept
413  { return !(__lhs == __rhs); }
414 
415  /// @relates error_condition
416  inline bool
417  operator!=(const error_condition& __lhs,
418  const error_condition& __rhs) noexcept
419  { return !(__lhs == __rhs); }
420 #endif // three_way_comparison
421 
422  /**
423  * @brief An exception type that includes an `error_code` value.
424  *
425  * Typically used to report errors from the operating system and other
426  * low-level APIs.
427  *
428  * @ingroup exceptions
429  */
430  class system_error : public std::runtime_error
431  {
432  private:
433  error_code _M_code;
434 
435  public:
436  system_error(error_code __ec = error_code())
437  : runtime_error(__ec.message()), _M_code(__ec) { }
438 
439  system_error(error_code __ec, const string& __what)
440  : runtime_error(__what + ": " + __ec.message()), _M_code(__ec) { }
441 
442  system_error(error_code __ec, const char* __what)
443  : runtime_error(__what + (": " + __ec.message())), _M_code(__ec) { }
444 
445  system_error(int __v, const error_category& __ecat, const char* __what)
446  : system_error(error_code(__v, __ecat), __what) { }
447 
448  system_error(int __v, const error_category& __ecat)
449  : runtime_error(error_code(__v, __ecat).message()),
450  _M_code(__v, __ecat) { }
451 
452  system_error(int __v, const error_category& __ecat, const string& __what)
453  : runtime_error(__what + ": " + error_code(__v, __ecat).message()),
454  _M_code(__v, __ecat) { }
455 
456 #if __cplusplus >= 201103L
457  system_error (const system_error &) = default;
458  system_error &operator= (const system_error &) = default;
459 #endif
460 
461  virtual ~system_error() noexcept;
462 
463  const error_code&
464  code() const noexcept { return _M_code; }
465  };
466 
467 _GLIBCXX_END_NAMESPACE_VERSION
468 } // namespace
469 
470 #include <bits/functional_hash.h>
471 
472 namespace std _GLIBCXX_VISIBILITY(default)
473 {
474 _GLIBCXX_BEGIN_NAMESPACE_VERSION
475 
476 #ifndef _GLIBCXX_COMPATIBILITY_CXX0X
477  // DR 1182.
478  /// std::hash specialization for error_code.
479  /// @relates error_code
480  template<>
481  struct hash<error_code>
482  : public __hash_base<size_t, error_code>
483  {
484  size_t
485  operator()(const error_code& __e) const noexcept
486  {
487  const size_t __tmp = std::_Hash_impl::hash(__e.value());
488  return std::_Hash_impl::__hash_combine(&__e.category(), __tmp);
489  }
490  };
491 #endif // _GLIBCXX_COMPATIBILITY_CXX0X
492 
493 #if __cplusplus >= 201703L
494  // DR 2686.
495  /// std::hash specialization for error_condition.
496  /// @relates error_condition
497  template<>
498  struct hash<error_condition>
499  : public __hash_base<size_t, error_condition>
500  {
501  size_t
502  operator()(const error_condition& __e) const noexcept
503  {
504  const size_t __tmp = std::_Hash_impl::hash(__e.value());
505  return std::_Hash_impl::__hash_combine(&__e.category(), __tmp);
506  }
507  };
508 #endif
509 
510 _GLIBCXX_END_NAMESPACE_VERSION
511 } // namespace
512 
513 #endif // C++11
514 
515 #endif // _GLIBCXX_SYSTEM_ERROR