diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e121efe..c93e187d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/). efficient in some scenarios (especially with the openat2-based resolver or for C FFI users where function calls are expensive) as it saves one file descriptor allocation and extra function calls. +- Error: `ErrorKind` is now exported, allowing you to programmatically handle + errors returned by libpathrs. This interface may change in the future (in + particular, `ErrorKind::OsError` might change its representation of `errno` + values). - capi: errors that are returned by libpathrs itself (such as invalid arguments being passed by users) will now contain a `saved_errno` value that makes sense for the error type (so `ErrorKind::InvalidArgument` will result in an diff --git a/src/error.rs b/src/error.rs index 8973b3e3..f4096a56 100644 --- a/src/error.rs +++ b/src/error.rs @@ -36,6 +36,10 @@ use std::{borrow::Cow, io::Error as IOError}; // export the crate types here without std::backtrace::Backtrace. // MSRV(1.65): Use std::backtrace::Backtrace. +/// Opaque error type for libpathrs. +/// +/// If you wish to do non-trivial error handling with libpathrs errors, use +/// [`Error::kind`] to get an [`ErrorKind`] you can handle programmatically. #[derive(thiserror::Error, Debug)] #[error(transparent)] pub struct Error(#[from] Box); @@ -49,7 +53,7 @@ impl> From for Error { } impl Error { - pub(crate) fn kind(&self) -> ErrorKind { + pub fn kind(&self) -> ErrorKind { self.0.kind() } } @@ -100,15 +104,28 @@ pub(crate) enum ErrorImpl { }, } -// TODO: Export this? +/// Underlying error class for libpathrs errors. +/// +/// This is similar in concept to [`std::io::ErrorKind`]. Note that the #[derive(Debug, PartialEq, Eq, Clone, Copy)] #[non_exhaustive] -pub(crate) enum ErrorKind { +pub enum ErrorKind { + /// The requested feature is not implemented in libpathrs. NotImplemented, + /// The requested feature is not supported by the system. NotSupported, + /// The provided arguments to libpathrs were invalid. InvalidArgument, + /// libpaths encountered a state where the safety of the operation could not + /// be guaranteeed. This is usually the result of an attack by a malicious + /// program. SafetyViolation, + /// Some internal error occurred. For more information, see the string + /// description of the original [`Error`]. InternalError, + /// The underlying error came from a system call. The provided + /// [`std::io::RawOsError`] is the numerical value of the `errno` number, if + /// available. // TODO: We might want to use Option? OsError(Option), }