libstdc++: system_error Source File

libstdc++

system_error
Go to the documentation of this file.
1// <system_error> -*- C++ -*-
2
3// Copyright (C) 2007-2026 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#ifdef _GLIBCXX_SYSHDR
33#pragma GCC system_header
34#endif
35
36#include <bits/requires_hosted.h> // OS-dependent
37
38#if __cplusplus < 201103L
39# include <bits/c++0x_warning.h>
40#else
41
42#include <bits/c++config.h>
43#include <bits/error_constants.h>
44#include <iosfwd>
45#include <stdexcept>
46#if __cplusplus > 201703L
47# include <compare>
48#endif
49
50namespace std _GLIBCXX_VISIBILITY(default)
51{
52_GLIBCXX_BEGIN_NAMESPACE_VERSION
53
54 /** @addtogroup diagnostics
55 * @{
56 */
57
58 class error_code;
59 class error_condition;
60 class system_error;
61
62 /// is_error_code_enum
63 template<typename _Tp>
64 struct is_error_code_enum : public false_type { };
65
66 /// is_error_condition_enum
67 template<typename _Tp>
68 struct is_error_condition_enum : public false_type { };
69
70 template<>
71 struct is_error_condition_enum<errc>
72 : public true_type { };
73
74#if __cplusplus > 201402L
75 template <typename _Tp>
76 inline constexpr bool is_error_code_enum_v =
77 is_error_code_enum<_Tp>::value;
78 template <typename _Tp>
79 inline constexpr bool is_error_condition_enum_v =
80 is_error_condition_enum<_Tp>::value;
81#endif // C++17
82 /// @}
83
84_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
85
86 /** @addtogroup diagnostics
87 * @{
88 */
89
90 /** Abstract base class for types defining a category of error codes.
91 *
92 * An error category defines a context that gives meaning to the integer
93 * stored in an `error_code` or `error_condition` object. For example,
94 * the standard `errno` constants such a `EINVAL` and `ENOMEM` are
95 * associated with the "generic" category and other OS-specific error
96 * numbers are associated with the "system" category, but a user-defined
97 * category might give different meanings to the same numerical values.
98 *
99 * A user-defined category can override the `equivalent` member functions
100 * to define correspondence between errors in different categories.
101 * For example, a category for errors from disk I/O could consider some
102 * of its error numbers equivalent to ENOSPC and ENOENT in the generic
103 * category.
104 *
105 * @headerfile system_error
106 * @since C++11
107 */
108 class error_category
109 {
110 public:
111 constexpr error_category() noexcept = default;
112
113 virtual ~error_category();
114
115 error_category(const error_category&) = delete;
116 error_category& operator=(const error_category&) = delete;
117
118 /// A string that identifies the error category.
119 virtual const char*
120 name() const noexcept = 0;
121
122 // We need two different virtual functions here, one returning a
123 // COW string and one returning an SSO string. Their positions in the
124 // vtable must be consistent for dynamic dispatch to work, but which one
125 // the name "message()" finds depends on which ABI the caller is using.
126#if _GLIBCXX_USE_CXX11_ABI
127 private:
128 _GLIBCXX_DEFAULT_ABI_TAG
129 virtual __cow_string
130 _M_message(int) const;
131
132 public:
133 /// A description of the error condition corresponding to the number.
134 _GLIBCXX_DEFAULT_ABI_TAG
135 virtual string
136 message(int) const = 0;
137#else
138 virtual string
139 message(int) const = 0;
140
141 private:
142 virtual __sso_string
143 _M_message(int) const;
144#endif
145
146 public:
147 /// Return an error_condition corresponding to `i` in this category.
148 virtual error_condition
149 default_error_condition(int __i) const noexcept;
150
151 /// Test whether `cond` corresponds to `i` for this category.
152 virtual bool
153 equivalent(int __i, const error_condition& __cond) const noexcept;
154
155 /// Test whether `code` corresponds to `i` for this category.
156 virtual bool
157 equivalent(const error_code& __code, int __i) const noexcept;
158
159 /// An error_category only compares equal to itself.
160 [[__nodiscard__]]
161 bool
162 operator==(const error_category& __other) const noexcept
163 { return this == &__other; }
164
165 /// Ordered comparison that defines a total order for error categories.
166#if __cpp_lib_three_way_comparison
167 [[nodiscard]]
168 strong_ordering
169 operator<=>(const error_category& __rhs) const noexcept
170 { return std::compare_three_way()(this, &__rhs); }
171#else
172 bool
173 operator<(const error_category& __other) const noexcept
174 { return less<const error_category*>()(this, &__other); }
175
176 bool
177 operator!=(const error_category& __other) const noexcept
178 { return this != &__other; }
179#endif
180 };
181
182 // DR 890.
183
184 /// Error category for `errno` error codes.
185 [[__nodiscard__, __gnu__::__const__]]
186 const error_category&
187 generic_category() noexcept;
188
189 /// Error category for other error codes defined by the OS.
190 [[__nodiscard__, __gnu__::__const__]]
191 const error_category&
192 system_category() noexcept;
193
194 /// @}
195
196_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
197
198 /** @addtogroup diagnostics
199 * @{
200 */
201
202namespace __adl_only
203{
204 void make_error_code() = delete;
205 void make_error_condition() = delete;
206}
207
208 /** Class error_code
209 *
210 * This class is a value type storing an integer error number and a
211 * category that gives meaning to the error number. Typically this is done
212 * close the the point where the error happens, to capture the original
213 * error value.
214 *
215 * An `error_code` object can be used to store the original error value
216 * emitted by some subsystem, with a category relevant to the subsystem.
217 * For example, errors from POSIX library functions can be represented by
218 * an `errno` value and the "generic" category, but errors from an HTTP
219 * library might be represented by an HTTP response status code (e.g. 404)
220 * and a custom category defined by the library.
221 *
222 * @headerfile system_error
223 * @since C++11
224 */
225 class error_code
226 {
227 template<typename _ErrorCodeEnum>
228 using _Check
229 = __enable_if_t<is_error_code_enum<_ErrorCodeEnum>::value>;
230
231 public:
232 error_code() noexcept
233 : _M_value(0), _M_cat(&system_category()) { }
234
235 error_code(int __v, const error_category& __cat) noexcept
236 : _M_value(__v), _M_cat(&__cat) { }
237
238 /// Initialize with a user-defined type, by calling make_error_code.
239 template<typename _ErrorCodeEnum,
240 typename = _Check<_ErrorCodeEnum>>
241 error_code(_ErrorCodeEnum __e) noexcept
242 {
243 using __adl_only::make_error_code;
244 *this = make_error_code(__e);
245 }
246
247 error_code(const error_code&) = default;
248 error_code& operator=(const error_code&) = default;
249
250 void
251 assign(int __v, const error_category& __cat) noexcept
252 {
253 _M_value = __v;
254 _M_cat = &__cat;
255 }
256
257 void
258 clear() noexcept
259 { assign(0, system_category()); }
260
261 /// The error value.
262 [[__nodiscard__]]
263 int
264 value() const noexcept { return _M_value; }
265
266 /// The error category that this error belongs to.
267 [[__nodiscard__]]
268 const error_category&
269 category() const noexcept { return *_M_cat; }
270
271 /// An `error_condition` for this error's category and value.
272 error_condition
273 default_error_condition() const noexcept;
274
275 /// The category's description of the value.
276 _GLIBCXX_DEFAULT_ABI_TAG
277 string
278 message() const
279 { return category().message(value()); }
280
281 /// Test whether `value()` is non-zero.
282 [[__nodiscard__]]
283 explicit operator bool() const noexcept
284 { return _M_value != 0; }
285
286 // DR 804.
287 private:
288 int _M_value;
289 const error_category* _M_cat;
290 };
291
292 // C++11 19.5.2.5 non-member functions
293
294 /** Create an `error_code` representing a standard `errc` condition.
295 *
296 * The `std::errc` constants correspond to `errno` macros and so use the
297 * generic category.
298 *
299 * @relates error_code
300 * @since C++11
301 */
302 [[__nodiscard__]]
303 inline error_code
304 make_error_code(errc __e) noexcept
305 { return error_code(static_cast<int>(__e), generic_category()); }
306
307 /** Ordered comparison for std::error_code.
308 *
309 * This defines a total order by comparing the categories, and then
310 * if they are equal comparing the values.
311 *
312 * @relates error_code
313 * @since C++11
314 */
315#if __cpp_lib_three_way_comparison
316 [[nodiscard]]
317 inline strong_ordering
318 operator<=>(const error_code& __lhs, const error_code& __rhs) noexcept
319 {
320 if (auto __c = __lhs.category() <=> __rhs.category(); __c != 0)
321 return __c;
322 return __lhs.value() <=> __rhs.value();
323 }
324#else
325 inline bool
326 operator<(const error_code& __lhs, const error_code& __rhs) noexcept
327 {
328 return (__lhs.category() < __rhs.category()
329 || (__lhs.category() == __rhs.category()
330 && __lhs.value() < __rhs.value()));
331 }
332#endif
333
334 /** Write a std::error_code to an ostream.
335 *
336 * @relates error_code
337 * @since C++11
338 */
339 template<typename _CharT, typename _Traits>
340 basic_ostream<_CharT, _Traits>&
341 operator<<(basic_ostream<_CharT, _Traits>& __os, const error_code& __e)
342 { return (__os << __e.category().name() << ':' << __e.value()); }
343
344 /** Class error_condition
345 *
346 * This class represents error conditions that may be visible at an API
347 * boundary. Different `error_code` values that can occur within a library
348 * or module might map to the same `error_condition`.
349 *
350 * An `error_condition` represents something that the program can test for,
351 * and subsequently take appropriate action.
352 *
353 * @headerfile system_error
354 * @since C++11
355 */
356 class error_condition
357 {
358 template<typename _ErrorConditionEnum>
359 using _Check
360 = __enable_if_t<is_error_condition_enum<_ErrorConditionEnum>::value>;
361
362 public:
363 /// Initialize with a zero (no error) value and the generic category.
364 error_condition() noexcept
365 : _M_value(0), _M_cat(&generic_category()) { }
366
367 /// Initialize with the specified value and category.
368 error_condition(int __v, const error_category& __cat) noexcept
369 : _M_value(__v), _M_cat(&__cat) { }
370
371 /// Initialize with a user-defined type, by calling make_error_condition.
372 template<typename _ErrorConditionEnum,
373 typename = _Check<_ErrorConditionEnum>>
374 error_condition(_ErrorConditionEnum __e) noexcept
375 {
376 using __adl_only::make_error_condition;
377 *this = make_error_condition(__e);
378 }
379
380 error_condition(const error_condition&) = default;
381 error_condition& operator=(const error_condition&) = default;
382
383 /// Set the value and category.
384 void
385 assign(int __v, const error_category& __cat) noexcept
386 {
387 _M_value = __v;
388 _M_cat = &__cat;
389 }
390
391 /// Reset the value and category to the default-constructed state.
392 void
393 clear() noexcept
394 { assign(0, generic_category()); }
395
396 // C++11 19.5.3.4 observers
397
398 /// The error value.
399 [[__nodiscard__]]
400 int
401 value() const noexcept { return _M_value; }
402
403 /// The error category that this error belongs to.
404 [[__nodiscard__]]
405 const error_category&
406 category() const noexcept { return *_M_cat; }
407
408 /// The category's description of the value.
409 _GLIBCXX_DEFAULT_ABI_TAG
410 string
411 message() const
412 { return category().message(value()); }
413
414 /// Test whether `value()` is non-zero.
415 [[__nodiscard__]]
416 explicit operator bool() const noexcept
417 { return _M_value != 0; }
418
419 // DR 804.
420 private:
421 int _M_value;
422 const error_category* _M_cat;
423 };
424
425 // C++11 19.5.3.5 non-member functions
426
427 /** Create an `error_condition` representing a standard `errc` condition.
428 *
429 * The `std::errc` constants correspond to `errno` macros and so use the
430 * generic category.
431 *
432 * @relates error_condition
433 * @since C++11
434 */
435 [[__nodiscard__]]
436 inline error_condition
437 make_error_condition(errc __e) noexcept
438 { return error_condition(static_cast<int>(__e), generic_category()); }
439
440 // C++11 19.5.4 Comparison operators
441
442 /** Equality comparison for std::error_code.
443 *
444 * Returns true only if they have the same category and the same value.
445 *
446 * @relates error_condition
447 * @since C++11
448 */
449 [[__nodiscard__]]
450 inline bool
451 operator==(const error_code& __lhs, const error_code& __rhs) noexcept
452 {
453 return __lhs.category() == __rhs.category()
454 && __lhs.value() == __rhs.value();
455 }
456
457 /** Equality comparison for std::error_code and std::error_condition.
458 *
459 * Uses each category's `equivalent` member function to check whether
460 * the values correspond to an equivalent error in that category.
461 *
462 * @relates error_condition
463 * @since C++11
464 */
465 [[__nodiscard__]]
466 inline bool
467 operator==(const error_code& __lhs, const error_condition& __rhs) noexcept
468 {
469 return __lhs.category().equivalent(__lhs.value(), __rhs)
470 || __rhs.category().equivalent(__lhs, __rhs.value());
471 }
472
473 /** Equality comparison for std::error_condition.
474 *
475 * Returns true only if they have the same category and the same value.
476 *
477 * @relates error_condition
478 * @since C++11
479 */
480 [[__nodiscard__]]
481 inline bool
482 operator==(const error_condition& __lhs,
483 const error_condition& __rhs) noexcept
484 {
485 return __lhs.category() == __rhs.category()
486 && __lhs.value() == __rhs.value();
487 }
488
489 /** Ordered comparison for std::error_condition.
490 *
491 * This defines a total order by comparing the categories, and then
492 * if they are equal comparing the values.
493 *
494 * @relates error_condition
495 * @since C++11
496 */
497#if __cpp_lib_three_way_comparison
498 [[nodiscard]]
499 inline strong_ordering
500 operator<=>(const error_condition& __lhs,
501 const error_condition& __rhs) noexcept
502 {
503 if (auto __c = __lhs.category() <=> __rhs.category(); __c != 0)
504 return __c;
505 return __lhs.value() <=> __rhs.value();
506 }
507#else
508 inline bool
509 operator<(const error_condition& __lhs,
510 const error_condition& __rhs) noexcept
511 {
512 return (__lhs.category() < __rhs.category()
513 || (__lhs.category() == __rhs.category()
514 && __lhs.value() < __rhs.value()));
515 }
516
517 /// @relates error_condition
518 inline bool
519 operator==(const error_condition& __lhs, const error_code& __rhs) noexcept
520 {
521 return (__rhs.category().equivalent(__rhs.value(), __lhs)
522 || __lhs.category().equivalent(__rhs, __lhs.value()));
523 }
524
525 /// @relates error_code
526 inline bool
527 operator!=(const error_code& __lhs, const error_code& __rhs) noexcept
528 { return !(__lhs == __rhs); }
529
530 /// @relates error_code
531 inline bool
532 operator!=(const error_code& __lhs, const error_condition& __rhs) noexcept
533 { return !(__lhs == __rhs); }
534
535 /// @relates error_condition
536 inline bool
537 operator!=(const error_condition& __lhs, const error_code& __rhs) noexcept
538 { return !(__lhs == __rhs); }
539
540 /// @relates error_condition
541 inline bool
542 operator!=(const error_condition& __lhs,
543 const error_condition& __rhs) noexcept
544 { return !(__lhs == __rhs); }
545#endif // three_way_comparison
546 /// @}
547
548 /**
549 * @brief An exception type that includes an `error_code` value.
550 *
551 * Typically used to report errors from the operating system and other
552 * low-level APIs.
553 *
554 * @headerfile system_error
555 * @since C++11
556 * @ingroup exceptions
557 */
558 class system_error : public std::runtime_error
559 {
560 private:
561 error_code _M_code;
562
563 public:
564 system_error(error_code __ec = error_code())
565 : runtime_error(__ec.message()), _M_code(__ec) { }
566
567 system_error(error_code __ec, const string& __what)
568 : runtime_error(__what + (": " + __ec.message())), _M_code(__ec) { }
569
570 system_error(error_code __ec, const char* __what)
571 : runtime_error(__what + (": " + __ec.message())), _M_code(__ec) { }
572
573 system_error(int __v, const error_category& __ecat, const char* __what)
574 : system_error(error_code(__v, __ecat), __what) { }
575
576 system_error(int __v, const error_category& __ecat)
577 : runtime_error(error_code(__v, __ecat).message()),
578 _M_code(__v, __ecat) { }
579
580 system_error(int __v, const error_category& __ecat, const string& __what)
581 : runtime_error(__what + (": " + error_code(__v, __ecat).message())),
582 _M_code(__v, __ecat) { }
583
584#if __cplusplus >= 201103L
585 system_error (const system_error &) = default;
586 system_error &operator= (const system_error &) = default;
587#endif
588
589 virtual ~system_error() noexcept;
590
591 const error_code&
592 code() const noexcept { return _M_code; }
593 };
594
595_GLIBCXX_END_NAMESPACE_VERSION
596} // namespace
597
598#include <bits/functional_hash.h>
599
600namespace std _GLIBCXX_VISIBILITY(default)
601{
602_GLIBCXX_BEGIN_NAMESPACE_VERSION
603
604#ifndef _GLIBCXX_COMPATIBILITY_CXX0X
605 // DR 1182.
606 /// std::hash specialization for error_code.
607 /// @relates error_code
608 template<>
609 struct hash<error_code>
610 : public __hash_base<size_t, error_code>
611 {
612 size_t
613 operator()(const error_code& __e) const noexcept
614 {
615 const size_t __tmp = std::_Hash_impl::hash(__e.value());
616 return std::_Hash_impl::__hash_combine(&__e.category(), __tmp);
617 }
618 };
619#endif // _GLIBCXX_COMPATIBILITY_CXX0X
620
621#if __cplusplus >= 201703L
622 // DR 2686.
623 /// std::hash specialization for error_condition.
624 /// @relates error_condition
625 template<>
626 struct hash<error_condition>
627 : public __hash_base<size_t, error_condition>
628 {
629 size_t
630 operator()(const error_condition& __e) const noexcept
631 {
632 const size_t __tmp = std::_Hash_impl::hash(__e.value());
633 return std::_Hash_impl::__hash_combine(&__e.category(), __tmp);
634 }
635 };
636#endif
637
638_GLIBCXX_END_NAMESPACE_VERSION
639} // namespace
640
641#endif // C++11
642
643#endif // _GLIBCXX_SYSTEM_ERROR
compare
iosfwd
stdexcept
c++0x_warning.h
functional_hash.h
requires_hosted.h
error_constants.h
c++config.h
std::error_condition::operator==
bool operator==(const error_condition &__lhs, const error_condition &__rhs) noexcept
Definition system_error:482
std::generic_category
const error_category & generic_category() noexcept
Error category for errno error codes.
std::error_code::operator<=>
strong_ordering operator<=>(const error_code &__lhs, const error_code &__rhs) noexcept
Definition system_error:318
std::error_condition::operator==
bool operator==(const error_code &__lhs, const error_condition &__rhs) noexcept
Definition system_error:467
std::error_condition::operator<=>
strong_ordering operator<=>(const error_condition &__lhs, const error_condition &__rhs) noexcept
Definition system_error:500
std::error_code::make_error_code
error_code make_error_code(errc __e) noexcept
Definition system_error:304
std::error_condition::operator==
bool operator==(const error_code &__lhs, const error_code &__rhs) noexcept
Definition system_error:451
std::error_condition::make_error_condition
error_condition make_error_condition(errc __e) noexcept
Definition system_error:437
std::system_category
const error_category & system_category() noexcept
Error category for other error codes defined by the OS.
std::make_error_condition
error_condition make_error_condition(future_errc __errc) noexcept
Overload of make_error_condition for future_errc.
Definition future:103
std::make_error_code
error_code make_error_code(future_errc __errc) noexcept
Overload of make_error_code for future_errc.
Definition future:97
std::true_type
__bool_constant< true > true_type
The type used as a compile-time boolean with true value.
Definition type_traits:119
std::false_type
__bool_constant< false > false_type
The type used as a compile-time boolean with false value.
Definition type_traits:122
std
ISO C++ entities toplevel namespace is std.
std::operator<<
std::basic_ostream< _CharT, _Traits > & operator<<(std::basic_ostream< _CharT, _Traits > &__os, const bitset< _Nb > &__x)
Global I/O operators for bitsets.
Definition bitset:1754
std::hash
Primary class template hash.
Definition functional_hash.h:106
std::is_error_code_enum
is_error_code_enum
Definition system_error:64
std::is_error_condition_enum
is_error_condition_enum
Definition system_error:68
std::error_category
Definition system_error:109
std::error_category::equivalent
virtual bool equivalent(int __i, const error_condition &__cond) const noexcept
Test whether cond corresponds to i for this category.
std::error_category::equivalent
virtual bool equivalent(const error_code &__code, int __i) const noexcept
Test whether code corresponds to i for this category.
std::error_category::operator==
bool operator==(const error_category &__other) const noexcept
An error_category only compares equal to itself.
Definition system_error:162
std::error_category::name
virtual const char * name() const noexcept=0
A string that identifies the error category.
std::error_category::default_error_condition
virtual error_condition default_error_condition(int __i) const noexcept
Return an error_condition corresponding to i in this category.
std::error_category::operator<=>
strong_ordering operator<=>(const error_category &__rhs) const noexcept
Ordered comparison that defines a total order for error categories.
Definition system_error:169
std::error_category::message
virtual string message(int) const =0
A description of the error condition corresponding to the number.
std::error_code
Definition system_error:226
std::error_code::category
const error_category & category() const noexcept
The error category that this error belongs to.
Definition system_error:268
std::error_code::value
int value() const noexcept
The error value.
Definition system_error:263
std::error_code::message
string message() const
The category's description of the value.
Definition system_error:277
std::error_code::default_error_condition
error_condition default_error_condition() const noexcept
An error_condition for this error's category and value.
std::error_condition
Definition system_error:357
std::error_condition::category
const error_category & category() const noexcept
The error category that this error belongs to.
Definition system_error:405
std::error_condition::value
int value() const noexcept
The error value.
Definition system_error:400
std::error_condition::error_condition
error_condition() noexcept
Initialize with a zero (no error) value and the generic category.
Definition system_error:363
std::error_condition::message
string message() const
The category's description of the value.
Definition system_error:410
std::error_condition::assign
void assign(int __v, const error_category &__cat) noexcept
Set the value and category.
Definition system_error:384
std::error_condition::clear
void clear() noexcept
Reset the value and category to the default-constructed state.
Definition system_error:392
std::system_error
An exception type that includes an error_code value.
Definition system_error:559
std::runtime_error
One of two subclasses of exception.
Definition stdexcept_except.h:454
std::runtime_error::runtime_error
runtime_error(const string &__arg)
std::less
One of the comparison functors.
Definition stl_function.h:404