Skip to content

Commit

Permalink
Correct usage note on OpenOptions::append()
Browse files Browse the repository at this point in the history
  • Loading branch information
hniksic committed Feb 8, 2024
1 parent 0809f78 commit 5761ba9
Showing 1 changed file with 13 additions and 9 deletions.
22 changes: 13 additions & 9 deletions library/std/src/fs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -971,15 +971,18 @@ impl OpenOptions {
/// Note that setting `.write(true).append(true)` has the same effect as
/// setting only `.append(true)`.
///
/// For most filesystems, the operating system guarantees that all writes are
/// atomic: no writes get mangled because another process writes at the same
/// time.
///
/// One maybe obvious note when using append-mode: make sure that all data
/// that belongs together is written to the file in one operation. This
/// can be done by concatenating strings before passing them to [`write()`],
/// or using a buffered writer (with a buffer of adequate size),
/// and calling [`flush()`] when the message is complete.
/// Append mode guarantees that writes will be positioned at the current end of file,
/// even when there are other processes or threads appending to the same file. This is
/// unlike <code>[seek]([SeekFrom]::[End](0))</code>` followed by `write()`, which has
/// a race between seeking and writing during which another writer can write, with our
/// `write()` overwriting their data.
///
/// Keep in mind that atomicity of `write()` in append mode is less useful than it
/// appears at first. A successful `write()` is allowed to write only part of the
/// given data, so even if you're careful to provide the whole message in a single
/// call to `write()`, there is no guarantee that it will written out in full. Unless
/// the data to append consists of a single byte, you can't append atomically without
/// external locking.
///
/// If a file is opened with both read and append access, beware that after
/// opening, and after every write, the position for reading may be set at the
Expand All @@ -995,6 +998,7 @@ impl OpenOptions {
/// [`flush()`]: Write::flush "io::Write::flush"
/// [seek]: Seek::seek "io::Seek::seek"
/// [Current]: SeekFrom::Current "io::SeekFrom::Current"
/// [End]: SeekFrom::End "io::SeekFrom::End"
///
/// # Examples
///
Expand Down

0 comments on commit 5761ba9

Please sign in to comment.