Text of rust.docs.kernel.org › next › src › core › io › error.rs.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

error.rs - source

Skip to main content core/io/ error.rs 1 #![unstable(feature = "core_io" , issue = "154046" )] 2 3 // On 64-bit platforms, `io::Error` may use a bit-packed representation to 4 // reduce size. However, this representation assumes that error codes are 5 // always 32-bit wide. 6 // 7 // This assumption is invalid on 64-bit UEFI, where error codes are 64-bit. 8 // Therefore, the packed representation is explicitly disabled for UEFI 9 // targets, and the unpacked representation must be used instead.

10 #[cfg_attr( 11 all(target_pointer_width = "64" , not(target_os = "uefi" )), 12 path = "error/repr_bitpacked.rs" 13 )] 14 #[cfg_attr( 15 not(all(target_pointer_width = "64" , not(target_os = "uefi" ))), 16 path = "error/repr_unpacked.rs" 17 )] 18 mod repr ; 19 20 #[cfg_attr( 21 all(target_has_atomic_load_store = "ptr" , not(no_io_statics)), 22 path = "error/os_functions_atomic.rs" 23 )] 24 #[cfg_attr( 25 not(all(target_has_atomic_load_store = "ptr" , not(no_io_statics))), 26 path = "error/os_functions.rs" 27 )] 28 mod os_functions ; 29 30 use self ::os_functions::{ decode_error_kind , format_os_error , is_interrupted , set_functions }; 31 use self ::repr::Repr ; 32 use crate ::ptr::NonNull ; 33 use crate ::{ error , fmt , mem , result }; 34 35 /// A specialized [`Result`] type for I/O operations.

36 /// 37 /// This type is broadly used across [`std::io`] for any operation which may 38 /// produce an error. 39 /// 40 /// This type alias is generally used to avoid writing out [`io::Error`] directly and 41 /// is otherwise a direct mapping to [`Result`]. 42 /// 43 /// While usual Rust style is to import types directly, aliases of [`Result`] 44 /// often are not, to make it easier to distinguish between them. [`Result`] is 45 /// generally assumed to be [`core::result::Result`][`Result`], and so users of this alias 46 /// will generally use `io::Result` instead of shadowing the [prelude]'s import 47 /// of [`core::result::Result`][`Result`].

48 /// 49 // FIXME(#74481): Hard-links required to link from `core` to `std` 50 /// [`std::io`]: ../../std/io/index.html 51 /// [`io::Error`]: Error 52 /// [`Result`]: crate::result::Result 53 /// [prelude]: crate::prelude 54 /// 55 /// # Examples 56 /// 57 /// A convenience function that bubbles an `io::Result` to its caller: 58 /// 59 /// ``` 60 /// use std::io; 61 /// 62 /// fn get_string() -> io::Result<String> { 63 /// let mut buffer = String::new(); 64 /// 65 /// io::stdin().read_line(&mut buffer)?; 66 /// 67 /// Ok(buffer) 68 /// } 69 /// ``` 70 #[stable(feature = "rust1" , since = "1.0.0" )] 71 #[doc(search_unbox)] 72 pub type Result <T> = result:: Result <T, Error >; 73 74 /// The error type for I/O operations of the [`Read`][Read], [`Write`][Write], [`Seek`][Seek], and 75 /// associated traits.

76 /// 77 /// Errors mostly originate from the underlying OS, but custom instances of 78 /// `Error` can be created with crafted error messages and a particular value of 79 /// [`ErrorKind`]. 80 /// 81 // FIXME(#74481): Hard-links required to link from `core` to `std` 82 /// [Read]: ../../std/io/trait.Read.html 83 /// [Write]: crate::io::Write 84 /// [Seek]: crate::io::Seek 85 #[stable(feature = "rust1" , since = "1.0.0" )] 86 #[rustc_has_incoherent_inherent_impls] 87 pub struct Error { 88 repr: Repr , 89 } 90 91 #[stable(feature = "rust1" , since = "1.0.0" )] 92 impl fmt::Debug for Error { 93 fn fmt( & self , f: &mut fmt:: Formatter < '_ >) -> fmt:: Result { 94 fmt::Debug:: fmt ( & self .repr, f ) 95 } 96 } 97 98 /// Common errors constants for use in std 99 #[doc(hidden)] 100 impl Error { 101 #[doc(hidden)] 102 #[unstable(feature = "core_io_internals" , reason = "exposed only for libstd" , issue = "none" )] 103 pub const INVALID_UTF8: Self = 104 const_error! (ErrorKind::InvalidData, "stream did not contain valid UTF-8" ); 105 106 #[doc(hidden)] 107 #[unstable(feature = "core_io_internals" , reason = "exposed only for libstd" , issue = "none" )] 108 pub const READ_EXACT_EOF: Self = 109 const_error! (ErrorKind::UnexpectedEof, "failed to fill whole buffer" ); 110 111 #[doc(hidden)] 112 #[unstable(feature = "core_io_internals" , reason = "exposed only for libstd" , issue = "none" )] 113 pub const UNKNOWN_THREAD_COUNT: Self = const_error! ( 114 ErrorKind::NotFound, 115 "the number of hardware threads is not known for the target platform" , 116 ); 117 118 #[doc(hidden)] 119 #[unstable(feature = "core_io_internals" , reason = "exposed only for libstd" , issue = "none" )] 120 pub const UNSUPPORTED_PLATFORM: Self = 121 const_error! (ErrorKind::Unsupported, "operation not supported on this platform" ); 122 123 #[doc(hidden)] 124 #[unstable(feature = "core_io_internals" , reason = "exposed only for libstd" , issue = "none" )] 125 pub const WRITE_ALL_EOF: Self = 126 const_error! (ErrorKind::WriteZero, "failed to write whole buffer" ); 127 128 #[doc(hidden)] 129 #[unstable(feature = "core_io_internals" , reason = "exposed only for libstd" , issue = "none" )] 130 pub const ZERO_TIMEOUT: Self = 131 const_error! (ErrorKind::InvalidInput, "cannot set a 0 duration timeout" ); 132 133 #[doc(hidden)] 134 #[unstable(feature = "core_io_internals" , reason = "exposed only for libstd" , issue = "none" )] 135 pub const NO_ADDRESSES: Self = 136 const_error! (ErrorKind::InvalidInput, "could not resolve to any addresses" ); 137 } 138 139 // Only derive debug in tests, to make sure it 140 // doesn't accidentally get printed.

141 #[cfg_attr(test, derive(Debug))] 142 enum ErrorData<C> { 143 Os( RawOsError ), 144 Simple( ErrorKind ), 145 SimpleMessage( & 'static SimpleMessage ), 146 Custom(C), 147 } 148 149 // `#[repr(align(4))]` is probably redundant, it should have that value or 150 // higher already. We include it just because repr_bitpacked.rs's encoding 151 // requires an alignment >= 4 (note that `#[repr(align)]` will not reduce the 152 // alignment required by the struct, only increase it).

153 // 154 // If we add more variants to ErrorData, this can be increased to 8, but it 155 // should probably be behind `#[cfg_attr(target_pointer_width = "64", ...)]` or 156 // whatever cfg we're using to enable the `repr_bitpacked` code, since only the 157 // that version needs the alignment, and 8 is higher than the alignment we'll 158 // have on 32 bit platforms. 159 // 160 // (For the sake of being explicit: the alignment requirement here only matters 161 // if `error/repr_bitpacked.rs` is in use — for the unpacked repr it doesn't 162 // matter at all) 163 #[doc(hidden)] 164 #[unstable(feature = "io_const_error_internals" , issue = "none" )] 165 #[repr(align( 4 ))] 166 #[derive( Debug )] 167 pub struct SimpleMessage { 168 pub kind: ErrorKind , 169 pub message: & 'static str , 170 } 171 172 /// Creates a new I/O error from a known kind of error and a string literal.

173 /// 174 /// Contrary to [`Error::new`][new], this macro does not allocate and can be used in 175 /// `const` contexts. 176 /// 177 // FIXME(#74481): Hard-links required to link from `core` to `alloc` for incoherent method 178 /// [new]: ../../alloc/io/struct.Error.html#method.new 179 /// 180 /// # Example 181 /// ``` 182 /// #![feature(io_const_error)] 183 /// use std::io::{const_error, Error, ErrorKind}; 184 /// 185 /// const FAIL: Error = const_error!(ErrorKind::Unsupported, "tried something that never works"); 186 /// 187 /// fn not_here() -> Result<(), Error> { 188 /// Err(FAIL) 189 /// } 190 /// ``` 191 #[rustc_macro_transparency = "semiopaque" ] 192 #[unstable(feature = "io_const_error" , issue = "133448" )] 193 #[allow_internal_unstable(core_io, hint_must_use, io_const_error_internals)] 194 pub macro const_error ( $kind :expr, $message :expr $(,) ? ) { 195 $crate::hint::must_use ( $crate::io::Error::from_static_message ( 196 const { & $crate::io::SimpleMessage { kind: $kind , message: $message } }, 197 )) 198 } 199 200 /// Intended for use for errors not exposed to the user, where allocating onto 201 /// the heap (for normal construction via Error::new) is too costly.

202 #[stable

The rest of this page is on the live site.