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

Author: poettering

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.

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);