Merge pull request #32755 from yuwata/test-network-cleanups

[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:
 
-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),
-   [`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)
 
-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.)
@@ -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
-`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.
 
@@ -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.
 
-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
@@ -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
-   [`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
@@ -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
-[`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.)