fs-util: add comment explaining what xopenat() is for

diff --git a/TODO b/TODO
index 5262ca828fa8babb9dac5c7feab726f0e1427527..d6349c74d1b83bc5272c0b511528a080c3db132d 100644 (file)
--- a/TODO
+++ b/TODO
@@ -89,6 +89,9 @@ Janitorial Clean-ups:
   this up, and should probably always apply both, i.e. introduce
   unit_file_escape() or so, which applies both.
 
+* xopenat() should pin the parent dir of the inode it creates before doing its
+  thing, so that it can create, open, label somewhat atomically.
+
 Deprecations and removals:
 
 * Remove any support for booting without /usr pre-mounted in the initrd entirely.

diff --git a/src/basic/fs-util.c b/src/basic/fs-util.c
index f5a1a8edbf17c1584178b1e78275f4efacfea02f..ee38e0266a6f9d4ea8d6191a9c28e83e6e3ea1ba 100644 (file)
--- a/src/basic/fs-util.c
+++ b/src/basic/fs-util.c
@@ -1113,6 +1113,16 @@ int xopenat(int dir_fd, const char *path, int open_flags, XOpenFlags xopen_flags
 
         assert(dir_fd >= 0 || dir_fd == AT_FDCWD);
 
+        /* This is like openat(), but has a few tricks up its sleeves, extending behaviour:
+         *
+         *   • O_DIRECTORY|O_CREAT is supported, which causes a directory to be created, and immediately
+         *     opened. When used with the XO_SUBVOLUME flag this will even create a btrfs subvolume.
+         *
+         *   • If O_CREAT is used with XO_LABEL, any created file will be immediately relabelled.
+         *
+         *   • If the path is specified NULL or empty, behaves like fd_reopen().
+         */
+
         if (isempty(path)) {
                 assert(!FLAGS_SET(open_flags, O_CREAT|O_EXCL));
                 return fd_reopen(dir_fd, open_flags & ~O_NOFOLLOW);