Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/c++/15/system_error
1 // <system_error> -*- C++ -*- 2 3 // Copyright (C) 2007-2025 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 50 namespace 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 202 namespace __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 600 namespace 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
