Skip to content

Commit 6a5c902

Browse files
committed
Comment formatting cleanups.
1 parent 7e0057f commit 6a5c902

File tree

5 files changed

+61
-50
lines changed

5 files changed

+61
-50
lines changed

cap-net-ext/src/lib.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,8 @@ pub trait PoolExt: private::Sealed {
231231
addrs: A,
232232
) -> io::Result<()>;
233233

234-
/// Initiate a TCP connection, converting a [`TcpListener`] to a [`TcpStream`].
234+
/// Initiate a TCP connection, converting a [`TcpListener`] to a
235+
/// [`TcpStream`].
235236
///
236237
/// This is simlar to to [`Pool::connect_tcp_stream`] in that it performs a
237238
/// TCP connection, but instead of creating a new socket itself it takes a

cap-primitives/src/windows/fs/stat_unchecked.rs

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
1-
use crate::fs::{FollowSymlinks, Metadata};
1+
use crate::fs::{open_unchecked, FollowSymlinks, Metadata, OpenOptions};
2+
use std::os::windows::fs::OpenOptionsExt;
23
use std::path::Path;
34
use std::{fs, io};
4-
use {
5-
crate::fs::{open_unchecked, OpenOptions},
6-
std::os::windows::fs::OpenOptionsExt,
7-
windows_sys::Win32::Storage::FileSystem::{
8-
FILE_FLAG_BACKUP_SEMANTICS, FILE_FLAG_OPEN_REPARSE_POINT,
9-
},
5+
use windows_sys::Win32::Storage::FileSystem::{
6+
FILE_FLAG_BACKUP_SEMANTICS, FILE_FLAG_OPEN_REPARSE_POINT,
107
};
118

129
/// *Unsandboxed* function similar to `stat`, but which does not perform

cap-tempfile/src/tempfile.rs

Lines changed: 35 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -14,26 +14,32 @@ use std::io::{self, Read, Seek, Write};
1414
///
1515
/// # Name-able, but not necessarily named
1616
///
17-
/// By default, the file does not necessarily have an name until the file is written
18-
/// persistently.
17+
/// By default, the file does not necessarily have an name until the file is
18+
/// written persistently.
1919
///
2020
/// On some operating systems like Linux, it is possible to create anonymous
21-
/// temporary files that can still be written to disk persistently via `O_TMPFILE`.
22-
/// The advantage of this is that if the process (or operating system) crashes
23-
/// while the file is being written, the temporary space will be automatically cleaned up.
24-
/// For this reason, there is no API to retrieve the name, for either case.
21+
/// temporary files that can still be written to disk persistently via
22+
/// `O_TMPFILE`. The advantage of this is that if the process (or operating
23+
/// system) crashes while the file is being written, the temporary space will
24+
/// be automatically cleaned up. For this reason, there is no API to retrieve
25+
/// the name, for either case.
2526
///
26-
/// To more closely match the semantics of [`tempfile::tempfile`], use [`crate::TempFile::new_anonymous`].
27+
/// To more closely match the semantics of [`tempfile::tempfile`], use
28+
/// [`crate::TempFile::new_anonymous`].
2729
///
2830
/// # File permissions
2931
///
30-
/// Unlike the tempfile crate, the default [`TempFile::new`] will use the same permissions as [`File::create_new`] in
31-
/// the Rust standard library. Concretely on Unix systems for example this can (depending on `umask`) result in
32-
/// files that are readable by all users. The rationale for this is to make it more ergonomic and natural to use this API to
33-
/// atomically create new files and replace existing ones. Many cases that want "private" files will
34-
/// prefer [`TempFile::new_anonymous`] to have the file not be accessible at all outside the current process.
32+
/// Unlike the tempfile crate, the default [`TempFile::new`] will use the same
33+
/// permissions as [`File::create_new`] in the Rust standard library.
34+
/// Concretely on Unix systems for example this can (depending on `umask`)
35+
/// result in files that are readable by all users. The rationale for this is
36+
/// to make it more ergonomic and natural to use this API to atomically create
37+
/// new files and replace existing ones. Many cases that want "private" files
38+
/// will prefer [`TempFile::new_anonymous`] to have the file not be accessible
39+
/// at all outside the current process.
3540
///
36-
/// To fully control the permissions of the resulting file, you can use [`File::set_permissions`].
41+
/// To fully control the permissions of the resulting file, you can use
42+
/// [`File::set_permissions`].
3743
///
3844
/// [`tempfile::tempfile`]: https://docs.rs/tempfile/latest/tempfile/fn.tempfile.html
3945
/// [`tempfile::NamedTempFile`]: https://docs.rs/tempfile/latest/tempfile/struct.NamedTempFile.html
@@ -57,18 +63,19 @@ impl<'d> Debug for TempFile<'d> {
5763
fn new_tempfile_linux(d: &Dir, anonymous: bool) -> io::Result<Option<File>> {
5864
use cap_std::io_lifetimes::OwnedFd;
5965
use rustix::fs::{Mode, OFlags};
60-
// openat's API uses WRONLY. There may be use cases for reading too, so let's support it.
66+
// openat's API uses WRONLY. There may be use cases for reading too, so let's
67+
// support it.
6168
let mut oflags = OFlags::CLOEXEC | OFlags::TMPFILE | OFlags::RDWR;
6269
if anonymous {
6370
oflags |= OFlags::EXCL;
6471
}
65-
// We default to 0o666, same as main rust when creating new files; this will be modified by
66-
// umask: https://github.com/rust-lang/rust/blob/44628f7273052d0bb8e8218518dacab210e1fe0d/library/std/src/sys/unix/fs.rs#L762
72+
// We default to 0o666, same as main rust when creating new files; this will be
73+
// modified by umask: <https://github.com/rust-lang/rust/blob/44628f7273052d0bb8e8218518dacab210e1fe0d/library/std/src/sys/unix/fs.rs#L762>
6774
let mode = Mode::from_raw_mode(0o666);
6875
// Happy path - Linux with O_TMPFILE
6976
match rustix::fs::openat(d, ".", oflags, mode) {
7077
Ok(r) => return Ok(Some(File::from(OwnedFd::from(r)))),
71-
// See https://github.com/Stebalien/tempfile/blob/1a40687e06eb656044e3d2dffa1379f04b3ef3fd/src/file/imp/unix.rs#L81
78+
// See <https://github.com/Stebalien/tempfile/blob/1a40687e06eb656044e3d2dffa1379f04b3ef3fd/src/file/imp/unix.rs#L81>
7279
// TODO: With newer Rust versions, this could be simplied to only write `Err` once.
7380
Err(rustix::io::Errno::OPNOTSUPP)
7481
| Err(rustix::io::Errno::ISDIR)
@@ -94,8 +101,9 @@ fn generate_name_in(subdir: &Dir, f: &File) -> io::Result<String> {
94101
.map(|(_, name)| name)
95102
}
96103

97-
/// Create a new temporary file in the target directory, which may or may not have a (randomly generated) name at this point.
98-
/// If anonymous is specified, the file will be deleted
104+
/// Create a new temporary file in the target directory, which may or may not
105+
/// have a (randomly generated) name at this point. If anonymous is specified,
106+
/// the file will be deleted
99107
fn new_tempfile(d: &Dir, anonymous: bool) -> io::Result<(File, Option<String>)> {
100108
// On Linux, try O_TMPFILE
101109
#[cfg(any(target_os = "android", target_os = "linux"))]
@@ -125,8 +133,8 @@ impl<'d> TempFile<'d> {
125133
Ok(Self { dir, fd, name })
126134
}
127135

128-
/// Crate a new temporary file in the provided directory that will not have a
129-
/// name. This corresponds to [`tempfile::tempfile_in`].
136+
/// Crate a new temporary file in the provided directory that will not have
137+
/// a name. This corresponds to [`tempfile::tempfile_in`].
130138
///
131139
/// [`tempfile::tempfile_in`]: https://docs.rs/tempfile/latest/tempfile/fn.tempfile_in.html
132140
pub fn new_anonymous(dir: &'d Dir) -> io::Result<File> {
@@ -144,17 +152,18 @@ impl<'d> TempFile<'d> {
144152
}
145153

146154
fn impl_replace(mut self, destname: &OsStr) -> io::Result<()> {
147-
// At this point on Linux if O_TMPFILE is used, we need to give the file a temporary name in
148-
// order to link it into place. There are patches to add an `AT_LINKAT_REPLACE`
149-
// API. With that we could skip this and have file-leak-proof atomic file replacement:
150-
// https://marc.info/?l=linux-fsdevel&m=158028833007418&w=2
155+
// At this point on Linux if O_TMPFILE is used, we need to give the file a
156+
// temporary name in order to link it into place. There are patches to
157+
// add an `AT_LINKAT_REPLACE` API. With that we could skip this and
158+
// have file-leak-proof atomic file replacement: <https://marc.info/?l=linux-fsdevel&m=158028833007418&w=2>
151159
#[cfg(any(target_os = "android", target_os = "linux"))]
152160
let tempname = self
153161
.name
154162
.take()
155163
.map(Ok)
156164
.unwrap_or_else(|| generate_name_in(self.dir, &self.fd))?;
157-
// SAFETY: We only support anonymous files on Linux, so the file must have a name here.
165+
// SAFETY: We only support anonymous files on Linux, so the file must have a
166+
// name here.
158167
#[cfg(not(any(target_os = "android", target_os = "linux")))]
159168
let tempname = self.name.take().unwrap();
160169
// And try the rename into place.

tests/fs.rs

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -662,15 +662,17 @@ fn recursive_rmdir_toctou() {
662662
// Test for time-of-check to time-of-use issues.
663663
//
664664
// Scenario:
665-
// The attacker wants to get directory contents deleted, to which he does not have access.
666-
// He has a way to get a privileged Rust binary call `std::fs::remove_dir_all()` on a
667-
// directory he controls, e.g. in his home directory.
665+
// The attacker wants to get directory contents deleted, to which he does not
666+
// have access. He has a way to get a privileged Rust binary call
667+
// `std::fs::remove_dir_all()` on a directory he controls, e.g. in his home
668+
// directory.
668669
//
669-
// The POC sets up the `attack_dest/attack_file` which the attacker wants to have deleted.
670-
// The attacker repeatedly creates a directory and replaces it with a symlink from
671-
// `victim_del` to `attack_dest` while the victim code calls `std::fs::remove_dir_all()`
672-
// on `victim_del`. After a few seconds the attack has succeeded and
673-
// `attack_dest/attack_file` is deleted.
670+
// The POC sets up the `attack_dest/attack_file` which the attacker wants to
671+
// have deleted. The attacker repeatedly creates a directory and replaces
672+
// it with a symlink from `victim_del` to `attack_dest` while the victim
673+
// code calls `std::fs::remove_dir_all()` on `victim_del`. After a few
674+
// seconds the attack has succeeded and `attack_dest/attack_file` is
675+
// deleted.
674676
let tmpdir = tmpdir();
675677
let victim_del_path = "victim_del";
676678
let victim_del_path_clone = victim_del_path.clone();

tests/fs_utf8.rs

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -665,15 +665,17 @@ fn recursive_rmdir_toctou() {
665665
// Test for time-of-check to time-of-use issues.
666666
//
667667
// Scenario:
668-
// The attacker wants to get directory contents deleted, to which he does not have access.
669-
// He has a way to get a privileged Rust binary call `std::fs::remove_dir_all()` on a
670-
// directory he controls, e.g. in his home directory.
668+
// The attacker wants to get directory contents deleted, to which he does not
669+
// have access. He has a way to get a privileged Rust binary call
670+
// `std::fs::remove_dir_all()` on a directory he controls, e.g. in his home
671+
// directory.
671672
//
672-
// The POC sets up the `attack_dest/attack_file` which the attacker wants to have deleted.
673-
// The attacker repeatedly creates a directory and replaces it with a symlink from
674-
// `victim_del` to `attack_dest` while the victim code calls `std::fs::remove_dir_all()`
675-
// on `victim_del`. After a few seconds the attack has succeeded and
676-
// `attack_dest/attack_file` is deleted.
673+
// The POC sets up the `attack_dest/attack_file` which the attacker wants to
674+
// have deleted. The attacker repeatedly creates a directory and replaces
675+
// it with a symlink from `victim_del` to `attack_dest` while the victim
676+
// code calls `std::fs::remove_dir_all()` on `victim_del`. After a few
677+
// seconds the attack has succeeded and `attack_dest/attack_file` is
678+
// deleted.
677679
let tmpdir = tmpdir();
678680
let victim_del_path = "victim_del";
679681
let victim_del_path_clone = victim_del_path.clone();

0 commit comments

Comments
 (0)