summaryrefslogtreecommitdiffstats
path: root/vendor/rustix/src/lib.rs
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:02:58 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:02:58 +0000
commit698f8c2f01ea549d77d7dc3338a12e04c11057b9 (patch)
tree173a775858bd501c378080a10dca74132f05bc50 /vendor/rustix/src/lib.rs
parentInitial commit. (diff)
downloadrustc-698f8c2f01ea549d77d7dc3338a12e04c11057b9.tar.xz
rustc-698f8c2f01ea549d77d7dc3338a12e04c11057b9.zip
Adding upstream version 1.64.0+dfsg1.upstream/1.64.0+dfsg1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'vendor/rustix/src/lib.rs')
-rw-r--r--vendor/rustix/src/lib.rs230
1 files changed, 230 insertions, 0 deletions
diff --git a/vendor/rustix/src/lib.rs b/vendor/rustix/src/lib.rs
new file mode 100644
index 000000000..ca7c6cd4e
--- /dev/null
+++ b/vendor/rustix/src/lib.rs
@@ -0,0 +1,230 @@
+//! `rustix` provides efficient memory-safe and [I/O-safe] wrappers to
+//! POSIX-like, Unix-like, Linux, and Winsock2 syscall-like APIs, with
+//! configurable backends.
+//!
+//! With rustix, you can write code like this:
+//!
+//! ```rust
+//! # #[cfg(feature = "net")]
+//! # fn read(sock: std::net::TcpStream, buf: &mut [u8]) -> std::io::Result<()> {
+//! # use rustix::net::RecvFlags;
+//! let nread: usize = rustix::net::recv(&sock, buf, RecvFlags::PEEK)?;
+//! # let _ = nread;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! instead of like this:
+//!
+//! ```rust
+//! # #[cfg(feature = "net")]
+//! # fn read(sock: std::net::TcpStream, buf: &mut [u8]) -> std::io::Result<()> {
+//! # use std::convert::TryInto;
+//! # #[cfg(unix)]
+//! # use std::os::unix::io::AsRawFd;
+//! # #[cfg(target_os = "wasi")]
+//! # use std::os::wasi::io::AsRawFd;
+//! # #[cfg(windows)]
+//! # use windows_sys::Win32::Networking::WinSock as libc;
+//! # #[cfg(windows)]
+//! # use std::os::windows::io::AsRawSocket;
+//! # const MSG_PEEK: i32 = libc::MSG_PEEK;
+//! let nread: usize = unsafe {
+//! #[cfg(any(unix, target_os = "wasi"))]
+//! let raw = sock.as_raw_fd();
+//! #[cfg(windows)]
+//! let raw = sock.as_raw_socket();
+//! match libc::recv(
+//! raw as _,
+//! buf.as_mut_ptr().cast(),
+//! buf.len().try_into().unwrap_or(i32::MAX as _),
+//! MSG_PEEK,
+//! ) {
+//! -1 => return Err(std::io::Error::last_os_error()),
+//! nread => nread as usize,
+//! }
+//! };
+//! # let _ = nread;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! rustix's APIs perform the following tasks:
+//! - Error values are translated to [`Result`]s.
+//! - Buffers are passed as Rust slices.
+//! - Out-parameters are presented as return values.
+//! - Path arguments use [`Arg`], so they accept any string type.
+//! - File descriptors are passed and returned via [`AsFd`] and [`OwnedFd`]
+//! instead of bare integers, ensuring I/O safety.
+//! - Constants use `enum`s and [`bitflags`] types.
+//! - Multiplexed functions (eg. `fcntl`, `ioctl`, etc.) are de-multiplexed.
+//! - Variadic functions (eg. `openat`, etc.) are presented as non-variadic.
+//! - Functions and types which need `l` prefixes or `64` suffixes to enable
+//! large-file support are used automatically, and file sizes and offsets
+//! are presented as `u64` and `i64`.
+//! - Behaviors that depend on the sizes of C types like `long` are hidden.
+//! - In some places, more human-friendly and less historical-accident names
+//! are used (and documentation aliases are used so that the original names
+//! can still be searched for).
+//! - Provide y2038 compatibility, on platforms which support this.
+//! - Correct selected platform bugs, such as behavioral differences when
+//! running under seccomp.
+//!
+//! Things they don't do include:
+//! - Detecting whether functions are supported at runtime.
+//! - Hiding significant differences between platforms.
+//! - Restricting ambient authorities.
+//! - Imposing sandboxing features such as filesystem path or network address
+//! sandboxing.
+//!
+//! See [`cap-std`], [`system-interface`], and [`io-streams`] for libraries
+//! which do hide significant differences between platforms, and [`cap-std`]
+//! which does perform sandboxing and restricts ambient authorities.
+//!
+//! [`cap-std`]: https://crates.io/crates/cap-std
+//! [`system-interface`]: https://crates.io/crates/system-interface
+//! [`io-streams`]: https://crates.io/crates/io-streams
+//! [`getrandom`]: https://crates.io/crates/getrandom
+//! [`bitflags`]: https://crates.io/crates/bitflags
+//! [`AsFd`]: https://doc.rust-lang.org/stable/std/os/unix/io/trait.AsFd.html
+//! [`OwnedFd`]: https://docs.rs/io-lifetimes/latest/io_lifetimes/struct.OwnedFd.html
+//! [io-lifetimes crate]: https://crates.io/crates/io-lifetimes
+//! [I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md
+//! [`Result`]: https://docs.rs/rustix/latest/rustix/io/type.Result.html
+//! [`Arg`]: https://docs.rs/rustix/latest/rustix/path/trait.Arg.html
+
+#![deny(missing_docs)]
+#![allow(stable_features)]
+#![cfg_attr(linux_raw, deny(unsafe_code))]
+#![cfg_attr(rustc_attrs, feature(rustc_attrs))]
+#![cfg_attr(doc_cfg, feature(doc_cfg))]
+#![cfg_attr(all(target_os = "wasi", feature = "std"), feature(wasi_ext))]
+#![cfg_attr(
+ all(linux_raw, naked_functions, target_arch = "x86"),
+ feature(naked_functions)
+)]
+#![cfg_attr(io_lifetimes_use_std, feature(io_safety))]
+#![cfg_attr(core_ffi_c, feature(core_ffi_c))]
+#![cfg_attr(core_c_str, feature(core_c_str))]
+#![cfg_attr(alloc_c_string, feature(alloc_ffi))]
+#![cfg_attr(alloc_c_string, feature(alloc_c_string))]
+#![cfg_attr(not(feature = "std"), no_std)]
+#![cfg_attr(feature = "rustc-dep-of-std", feature(core_intrinsics))]
+#![cfg_attr(feature = "rustc-dep-of-std", feature(ip))]
+#![cfg_attr(
+ all(not(feature = "rustc-dep-of-std"), core_intrinsics),
+ feature(core_intrinsics)
+)]
+#![cfg_attr(asm_experimental_arch, feature(asm_experimental_arch))]
+#![cfg_attr(not(feature = "all-apis"), allow(dead_code))]
+
+#[cfg(not(feature = "rustc-dep-of-std"))]
+extern crate alloc;
+
+// Internal utilities.
+#[cfg(not(windows))]
+#[macro_use]
+pub(crate) mod cstr;
+#[macro_use]
+pub(crate) mod const_assert;
+pub(crate) mod utils;
+
+// Pick the backend implementation to use.
+#[cfg_attr(libc, path = "imp/libc/mod.rs")]
+#[cfg_attr(linux_raw, path = "imp/linux_raw/mod.rs")]
+#[cfg_attr(wasi, path = "imp/wasi/mod.rs")]
+mod imp;
+
+/// Export the `*Fd` types and traits that are used in rustix's public API.
+///
+/// Users can use this to avoid needing to import anything else to use the same
+/// versions of these types and traits.
+///
+/// Rustix APIs that use `OwnedFd` use [`rustix::io::OwnedFd`] instead, which
+/// allows rustix to implement `close` for them.
+///
+/// [`rustix::io::OwnedFd`]: crate::io::OwnedFd
+pub mod fd {
+ use super::imp;
+ pub use imp::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};
+ #[cfg(windows)]
+ pub use imp::fd::{AsSocket, FromSocket, IntoSocket};
+ #[cfg(feature = "std")]
+ pub use imp::fd::{FromFd, IntoFd};
+}
+
+// The public API modules.
+#[cfg(not(windows))]
+pub mod ffi;
+#[cfg(not(windows))]
+#[cfg(feature = "fs")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "fs")))]
+pub mod fs;
+pub mod io;
+#[cfg(any(target_os = "android", target_os = "linux"))]
+#[cfg(feature = "io_uring")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "io_uring")))]
+pub mod io_uring;
+#[cfg(not(any(windows, target_os = "wasi")))]
+#[cfg(feature = "mm")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "mm")))]
+pub mod mm;
+#[cfg(not(any(target_os = "redox", target_os = "wasi")))]
+#[cfg(feature = "net")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "net")))]
+pub mod net;
+#[cfg(not(windows))]
+#[cfg(feature = "param")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "param")))]
+pub mod param;
+#[cfg(not(windows))]
+#[cfg(any(feature = "fs", feature = "net"))]
+#[cfg_attr(doc_cfg, doc(cfg(any(feature = "fs", feature = "net"))))]
+pub mod path;
+#[cfg(not(windows))]
+#[cfg(feature = "process")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "process")))]
+pub mod process;
+#[cfg(not(windows))]
+#[cfg(feature = "rand")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "rand")))]
+pub mod rand;
+#[cfg(not(any(windows, target_os = "wasi")))]
+#[cfg(feature = "termios")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "termios")))]
+pub mod termios;
+#[cfg(not(windows))]
+#[cfg(feature = "thread")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "thread")))]
+pub mod thread;
+#[cfg(not(windows))]
+#[cfg(feature = "time")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "time")))]
+pub mod time;
+
+// "runtime" is also a public API module, but it's only for libc-like users.
+#[cfg(not(windows))]
+#[cfg(feature = "runtime")]
+#[doc(hidden)]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "runtime")))]
+pub mod runtime;
+
+// We have some internal interdependencies in the API features, so for now,
+// for API features that aren't enabled, declare them as `pub(crate)` so
+// that they're not public, but still available for internal use.
+
+#[cfg(not(windows))]
+#[cfg(not(feature = "fs"))]
+pub(crate) mod fs;
+#[cfg(not(windows))]
+#[cfg(all(
+ not(feature = "param"),
+ any(feature = "runtime", feature = "time", target_arch = "x86"),
+))]
+pub(crate) mod param;
+#[cfg(not(windows))]
+#[cfg(not(any(feature = "fs", feature = "net")))]
+pub(crate) mod path;
+#[cfg(not(windows))]
+#[cfg(not(feature = "process"))]
+pub(crate) mod process;