NEWS: finalize for v256~rc3

[thirdparty/systemd.git] / docs / TEMPORARY_DIRECTORIES.md

diff --git a/docs/TEMPORARY_DIRECTORIES.md b/docs/TEMPORARY_DIRECTORIES.md
index c7036517913de3580f849ebd4e0576fd65c065c0..bc9cb7bc455c8f0e180ba288199a77aa8a23ed7a 100644 (file)
--- a/docs/TEMPORARY_DIRECTORIES.md
+++ b/docs/TEMPORARY_DIRECTORIES.md
@@ -44,15 +44,15 @@ installation during runtime is permitted.)
 To protect yourself against these kinds of attacks Linux provides a couple of
 APIs that help you avoiding guessable names. Specifically:
 
 To protect yourself against these kinds of attacks Linux provides a couple of
 APIs that help you avoiding guessable names. Specifically:
 

-1. Use [`mkstemp()`](http://man7.org/linux/man-pages/man3/mkstemp.3.html)
+1. Use [`mkstemp()`](https://man7.org/linux/man-pages/man3/mkstemp.3.html)

    (POSIX), `mkostemp()` (glibc),
    (POSIX), `mkostemp()` (glibc),

-   [`mkdtemp()`](http://man7.org/linux/man-pages/man3/mkdtemp.3.html) (POSIX),
-   [`tmpfile()`](http://man7.org/linux/man-pages/man3/tmpfile.3.html) (C89)
+   [`mkdtemp()`](https://man7.org/linux/man-pages/man3/mkdtemp.3.html) (POSIX),
+   [`tmpfile()`](https://man7.org/linux/man-pages/man3/tmpfile.3.html) (C89)

 
 

-2. Use [`open()`](http://man7.org/linux/man-pages/man2/open.2.html) with
+2. Use [`open()`](https://man7.org/linux/man-pages/man2/open.2.html) with

    `O_TMPFILE` (Linux)
 
    `O_TMPFILE` (Linux)
 

-3. [`memfd_create()`](http://man7.org/linux/man-pages/man2/memfd_create.2.html)
+3. [`memfd_create()`](https://man7.org/linux/man-pages/man2/memfd_create.2.html)

    (Linux; this doesn't bother with `/tmp/` or `/var/tmp/` at all, but uses the
    same RAM/swap backing as `tmpfs` uses, hence is very similar to `/tmp/`
    semantics.)
    (Linux; this doesn't bother with `/tmp/` or `/var/tmp/` at all, but uses the
    same RAM/swap backing as `tmpfs` uses, hence is very similar to `/tmp/`
    semantics.)


@@ -84,7 +84,7 @@ By default, `systemd-tmpfiles` will apply a concept of ⚠️ "ageing" to all fi
 and directories stored in `/tmp/` and `/var/tmp/`. This means that files that
 have neither been changed nor read within a specific time frame are
 automatically removed in regular intervals. (This concept is not new to
 and directories stored in `/tmp/` and `/var/tmp/`. This means that files that
 have neither been changed nor read within a specific time frame are
 automatically removed in regular intervals. (This concept is not new to

-`systemd-tmpfiles` btw, it's inherited from previous subsystems such as
+`systemd-tmpfiles`, it's inherited from previous subsystems such as

 `tmpwatch`.) By default files in `/tmp/` are cleaned up after 10 days, and
 those in `/var/tmp` after 30 days.
 
 `tmpwatch`.) By default files in `/tmp/` are cleaned up after 10 days, and
 those in `/var/tmp` after 30 days.
 


@@ -111,14 +111,13 @@ strategies to avoid these issues:
    towards unexpected program termination as there are never files on disk that
    need to be explicitly deleted.
 
    towards unexpected program termination as there are never files on disk that
    need to be explicitly deleted.
 

-3. 🥇 Operate below a sub-directory of `/tmp/` and `/var/tmp/` you created, and
-   take a BSD file lock ([`flock(dir_fd,
-   LOCK_SH)`](http://man7.org/linux/man-pages/man2/flock.2.html)) on that
-   sub-directory. This is particularly interesting when operating on more than
-   a single file, or on file nodes that are not plain regular files, for
-   example when extracting a tarball to a temporary directory. The ageing
-   algorithm will skip all directories (and everything below them) that are
-   locked through a BSD file lock. As BSD file locks are automatically released
+3. 🥇 Take an exclusive or shared BSD file lock ([`flock()`](
+   https://man7.org/linux/man-pages/man2/flock.2.html)) on files and directories
+   you don't want to be removed. This is particularly interesting when operating
+   on more than a single file, or on file nodes that are not plain regular files,
+   for example when extracting a tarball to a temporary directory. The ageing
+   algorithm will skip all directories (and everything below them) and files that
+   are locked through a BSD file lock. As BSD file locks are automatically released

    when the file descriptor they are taken on is closed, and all file
    descriptors opened by a process are implicitly closed when it exits, this is
    a robust mechanism that ensures all temporary files are subject to ageing
    when the file descriptor they are taken on is closed, and all file
    descriptors opened by a process are implicitly closed when it exits, this is
    a robust mechanism that ensures all temporary files are subject to ageing


@@ -126,10 +125,8 @@ strategies to avoid these issues:
    this when decompressing tarballs that contain files with old
    modification/access times, as extracted files are otherwise immediately
    candidates for deletion by the ageing algorithm. The
    this when decompressing tarballs that contain files with old
    modification/access times, as extracted files are otherwise immediately
    candidates for deletion by the ageing algorithm. The

-   [`flock`](http://man7.org/linux/man-pages/man1/flock.1.html) tool of the
-   `util-linux` packages makes this concept available to shell scripts. Note
-   that `systemd-tmpfiles` only checks for BSD file locks on directories, locks
-   on other types of file nodes (including regular files) are not considered.
+   [`flock`](https://man7.org/linux/man-pages/man1/flock.1.html) tool of the
+   `util-linux` packages makes this concept available to shell scripts.

 
 4. Keep the access time of all temporary files created current. In regular
    intervals, use `utimensat()` or a related call to update the access time
 
 4. Keep the access time of all temporary files created current. In regular
    intervals, use `utimensat()` or a related call to update the access time


@@ -217,7 +214,7 @@ packages instead use `/dev/shm/` for temporary files during early boot; this is
 not advisable however, as it offers no benefits over a private directory in
 `/run/` as both are backed by the same concept: `tmpfs`. The directory
 `/dev/shm/` exists to back POSIX shared memory (see
 not advisable however, as it offers no benefits over a private directory in
 `/run/` as both are backed by the same concept: `tmpfs`. The directory
 `/dev/shm/` exists to back POSIX shared memory (see

-[`shm_open()`](http://man7.org/linux/man-pages/man3/shm_open.3.html) and
+[`shm_open()`](https://man7.org/linux/man-pages/man3/shm_open.3.html) and

 related calls), and not as a place for temporary files. `/dev/shm` is
 problematic as it is world-writable and there's no automatic clean-up logic in
 place.)
 related calls), and not as a place for temporary files. `/dev/shm` is
 problematic as it is world-writable and there's no automatic clean-up logic in
 place.)