Skip to content

Commit bc8ea07

Browse files
committed
Write more comments.
Make a pass over the crate adding and cleanup up comments and doc aliases.
1 parent f409b65 commit bc8ea07

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+479
-55
lines changed

README.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ portable APIs built on this functionality, see the [`system-interface`],
3232

3333
The `linux_raw` backend is enabled by default on Linux on x86-64, x86, aarch64,
3434
riscv64gc and arm (v5 onwards), and uses raw Linux system calls and vDSO calls.
35-
It supports stable as well as nightly Rust.
35+
It supports stable as well as nightly and 1.48 Rust.
3636
- By being implemented entirely in Rust, avoiding `libc`, `errno`, and pthread
3737
cancellation, and employing some specialized optimizations, most functions
3838
compile down to very efficient code. On nightly Rust, they can often be
@@ -42,11 +42,10 @@ It supports stable as well as nightly Rust.
4242
- `linux_raw` uses a 64-bit `time_t` type on all platforms, avoiding the
4343
[y2038 bug].
4444

45-
The `libc` backend is enabled by default on all other platforms, and can be
46-
set explicitly for any target by setting `RUSTFLAGS` to
47-
`--cfg rustix_use_libc`. It uses the [`libc`] crate which provides bindings to
48-
native `libc` libraries, as well as [`winapi`] for Winsock2, and is portable to
49-
many OS's.
45+
The `libc` backend is enabled by default on all other platforms, and can be set
46+
explicitly for any target by setting `RUSTFLAGS` to `--cfg=rustix_use_libc`. It
47+
uses the [`libc`] crate which provides bindings to native `libc` libraries, and
48+
[`winapi`] for Winsock2, and is portable to many OS's.
5049

5150
## Similar crates
5251

@@ -80,12 +79,12 @@ way, so users don't need to open `.` to get a current-directory handle.
8079

8180
`rustix`'s `openat2` function is similar to the [`openat2`] crate, but uses
8281
I/O safety types rather than `RawFd`. `rustix` does not provide dynamic feature
83-
detection, so users must handle `NOSYS` themselves.
82+
detection, so users must handle the [`NOSYS`] error themselves.
8483

85-
# Minimum Supported Rust Version
84+
# Minimum Supported Rust Version (MSRV)
8685

87-
This crate currently works on the version of [Rust on Debian stable], which
88-
is currently Rust 1.48. This policy may change in the future, in minor version
86+
This crate currently works on the version of [Rust on Debian stable], which is
87+
currently Rust 1.48. This policy may change in the future, in minor version
8988
releases, so users using a fixed version of Rust should pin to a specific
9089
version of this crate.
9190

@@ -114,3 +113,4 @@ version of this crate.
114113
[y2038 bug]: https://en.wikipedia.org/wiki/Year_2038_problem
115114
[`OwnedFd`]: https://docs.rs/io-lifetimes/latest/io_lifetimes/struct.OwnedFd.html
116115
[`AsFd`]: https://docs.rs/io-lifetimes/latest/io_lifetimes/trait.AsFd.html
116+
[`NOSYS`]: https://docs.rs/rustix/latest/rustix/io/struct.Error.html#associatedconstant.NOSYS

examples/process.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
//! A command which prints out information about the process it runs in.
2+
13
#[cfg(not(windows))]
24
use rustix::io;
35
#[cfg(not(windows))]

examples/stdio.rs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//! A command which prints out information about the standard input,
2+
//! output, and error streams provided to it.
3+
14
#[cfg(not(windows))]
25
use rustix::fd::AsFd;
36
#[cfg(any(all(linux_raw, feature = "procfs"), all(not(windows), libc)))]

examples/time.rs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//! A command which prints the current values of the realtime and monotonic
2+
//! clocks it's given.
3+
14
#[cfg(not(windows))]
25
fn main() {
36
println!(

src/fs/fcntl.rs

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
//! The Unix `fcntl` function is effectively lots of different functions
2+
//! hidden behind a single dynamic dispatch interface. In order to provide
3+
//! a type-safe API, rustix makes them all separate functions so that they
4+
//! can have dedicated static type signatures.
5+
16
use crate::imp;
27
use crate::io::{self, OwnedFd};
38
use imp::fd::{AsFd, RawFd};
@@ -12,6 +17,7 @@ use imp::fs::{FdFlags, OFlags};
1217
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
1318
/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
1419
#[inline]
20+
#[doc(alias = "F_GETFD")]
1521
pub fn fcntl_getfd<Fd: AsFd>(fd: &Fd) -> io::Result<FdFlags> {
1622
let fd = fd.as_fd();
1723
imp::syscalls::fcntl_getfd(fd)
@@ -26,6 +32,7 @@ pub fn fcntl_getfd<Fd: AsFd>(fd: &Fd) -> io::Result<FdFlags> {
2632
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
2733
/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
2834
#[inline]
35+
#[doc(alias = "F_SETFD")]
2936
pub fn fcntl_setfd<Fd: AsFd>(fd: &Fd, flags: FdFlags) -> io::Result<()> {
3037
let fd = fd.as_fd();
3138
imp::syscalls::fcntl_setfd(fd, flags)
@@ -40,6 +47,7 @@ pub fn fcntl_setfd<Fd: AsFd>(fd: &Fd, flags: FdFlags) -> io::Result<()> {
4047
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
4148
/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
4249
#[inline]
50+
#[doc(alias = "F_GETFL")]
4351
pub fn fcntl_getfl<Fd: AsFd>(fd: &Fd) -> io::Result<OFlags> {
4452
let fd = fd.as_fd();
4553
imp::syscalls::fcntl_getfl(fd)
@@ -54,6 +62,7 @@ pub fn fcntl_getfl<Fd: AsFd>(fd: &Fd) -> io::Result<OFlags> {
5462
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
5563
/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
5664
#[inline]
65+
#[doc(alias = "F_SETFL")]
5766
pub fn fcntl_setfl<Fd: AsFd>(fd: &Fd, flags: OFlags) -> io::Result<()> {
5867
let fd = fd.as_fd();
5968
imp::syscalls::fcntl_setfl(fd, flags)
@@ -82,6 +91,7 @@ pub fn fcntl_setfl<Fd: AsFd>(fd: &Fd, flags: OFlags) -> io::Result<()> {
8291
)
8392
))]
8493
#[inline]
94+
#[doc(alias = "F_GET_SEALS")]
8595
pub fn fcntl_get_seals<Fd: AsFd>(fd: &Fd) -> io::Result<u32> {
8696
let fd = fd.as_fd();
8797
imp::syscalls::fcntl_get_seals(fd)
@@ -104,6 +114,7 @@ pub fn fcntl_get_seals<Fd: AsFd>(fd: &Fd) -> io::Result<u32> {
104114
/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
105115
#[cfg(not(target_os = "wasi"))]
106116
#[inline]
117+
#[doc(alias = "F_DUPFD_CLOEXEC")]
107118
pub fn fcntl_dupfd_cloexec<Fd: AsFd>(fd: &Fd, min: RawFd) -> io::Result<OwnedFd> {
108119
let fd = fd.as_fd();
109120
imp::syscalls::fcntl_dupfd_cloexec(fd, min)

src/fs/fd.rs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,12 +198,16 @@ pub(crate) fn _is_file_read_write(fd: BorrowedFd<'_>) -> io::Result<(bool, bool)
198198
/// `fsync(fd)`—Ensures that file data and metadata is written to the
199199
/// underlying storage device.
200200
///
201+
/// Note that on iOS and macOS this isn't sufficient to ensure that data has
202+
/// reached persistent storage; use [`fcntl_fullfsync`] to ensure that.
203+
///
201204
/// # References
202205
/// - [POSIX]
203206
/// - [Linux]
204207
///
205208
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/fsync.html
206209
/// [Linux]: https://man7.org/linux/man-pages/man2/fsync.2.html
210+
/// [`fcntl_fullfsync`]: https://docs.rs/rustix/*/x86_64-apple-darwin/rustix/fs/fn.fcntl_fullfsync.html
207211
#[inline]
208212
pub fn fsync<Fd: AsFd>(fd: &Fd) -> io::Result<()> {
209213
let fd = fd.as_fd();

src/imp/libc/conv.rs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
//! Libc call arguments and return values are often things like `c_int`,
2+
//! `c_uint`, or libc-specific pointer types. This module provides functions
3+
//! for converting between rustix's types and libc types.
4+
15
#![allow(dead_code)]
26

37
use super::c;

0 commit comments

Comments
 (0)