Explain the "no-error" io::Error case
Fundamentally, querying the OS for error codes is a process that is deeply subject to the whims of chance and fortune. We can account for OS, but not for every combination of platform APIs. A compiled binary may not recognize new errors introduced years later. We should clarify a few especially odd situations, and what they mean: We can effectively promise nothing. This allows removing mention of ErrorKind::Uncategorized. That error variant is hidden quite deliberately, so we should not explicitly mention it.
This commit is contained in:
parent
4781233a77
commit
2d927cc194
@ -359,7 +359,7 @@ pub enum ErrorKind {
|
||||
|
||||
// "Unusual" error kinds which do not correspond simply to (sets
|
||||
// of) OS error codes, should be added just above this comment.
|
||||
// `Other` and `Uncategorised` should remain at the end:
|
||||
// `Other` and `Uncategorized` should remain at the end:
|
||||
//
|
||||
/// A custom error that does not fall under any other I/O error kind.
|
||||
///
|
||||
@ -565,6 +565,12 @@ pub(crate) const fn from_static_message(msg: &'static SimpleMessage) -> Error {
|
||||
/// other standard library functions may call platform functions that may
|
||||
/// (or may not) reset the error value even if they succeed.
|
||||
///
|
||||
/// If this is used in a case where no error has yet occurred in a program,
|
||||
/// e.g. right after the beginning of `fn main`,
|
||||
/// then in principle any possible Error may be returned.
|
||||
/// The error code may have been set by a previous program (e.g. `execve`)
|
||||
/// or the OS may have initialized it to an arbitrary, even random, value.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -871,6 +877,13 @@ pub fn downcast<E>(self) -> result::Result<Box<E>, Self>
|
||||
|
||||
/// Returns the corresponding [`ErrorKind`] for this error.
|
||||
///
|
||||
/// In some cases, the ErrorKind variant may not make much sense,
|
||||
/// either because the situation does not actually involve an error, or
|
||||
/// because of a new error code the standard library has not been taught.
|
||||
/// See [`last_os_error`] for more details.
|
||||
///
|
||||
/// [`last_os_error`]: Error::last_os_error
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -881,7 +894,8 @@ pub fn downcast<E>(self) -> result::Result<Box<E>, Self>
|
||||
/// }
|
||||
///
|
||||
/// fn main() {
|
||||
/// // Will print "Uncategorized".
|
||||
/// // As no error has occurred, this may print anything!
|
||||
/// // It likely prints a placeholder for unidentified (non-)errors.
|
||||
/// print_error(Error::last_os_error());
|
||||
/// // Will print "AddrInUse".
|
||||
/// print_error(Error::new(ErrorKind::AddrInUse, "oh no!"));
|
||||
|
Loading…
Reference in New Issue
Block a user