fanotify_mark.2, futimesat.2, mount_setattr.2, statx.2, symlink.2, mkfifo.3: Refer the reader to openat(2) for explanation of why 'dirfd' is useful

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/fanotify_mark.2

@@ -358,6 +358,61 @@ has the value
 then the filesystem object to be marked is determined by interpreting
 .I pathname
 relative to the current working directory.
+(See
+.BR openat (2)
+for an explanation of why the
+.I dirfd
+argument is useful.)
+.PP
+The
+.BR mount_setattr ()
+system call uses an extensible structure
+.RI ( "struct mount_attr" )
+to allow for future extensions.
+Any non-flag extensions to
+.BR mount_setattr ()
+will be implemented as new fields appended to the this structure,
+with a zero value in a new field resulting in the kernel behaving
+as though that extension field was not present.
+Therefore,
+the caller
+.I must
+zero-fill this structure on initialization.
+See the "Extensibility" subsection under
+.B NOTES
+for more details.
+.PP
+The
+.I size
+argument should usually be specified as
+.IR "sizeof(struct mount_attr)" .
+However, if the caller is using a kernel that supports an extended
+.IR "struct mount_attr" ,
+but the caller does not intend to make use of these features,
+it is possible to pass the size of an earlier
+version of the structure together with the extended structure.
+This allows the kernel to not copy later parts of the structure
+that aren't used anyway.
+With each extension that changes the size of
+.IR "struct mount_attr" ,
+the kernel will expose a definition of the form
+.BI MOUNT_ATTR_SIZE_VER number\c
+\&.
+For example, the macro for the size of the initial version of
+.I struct mount_attr
+is
+.BR MOUNT_ATTR_SIZE_VER0 .
+.PP
+The
+.I flags
+argument can be used to alter the pathname resolution behavior.
+The supported values are:
+.TP
+.B AT_EMPTY_PATH
+If
+.I pathname
+is the empty string,
+change the mount properties on
 .SH RETURN VALUE
 On success,
 .BR fanotify_mark ()

man2/futimesat.2

@@ -83,6 +83,11 @@ If
 is absolute, then
 .I dirfd
 is ignored.
+(See
+.BR openat (2)
+for an explanation of why the
+.I dirfd
+argument is useful.)
 .SH RETURN VALUE
 On success,
 .BR futimesat ()

man2/mount_setattr.2

@@ -71,6 +71,11 @@ is specified in
 then the mount properties of the mount identified by
 .I dirfd
 are changed.
+(See
+.BR openat (2)
+for an explanation of why the
+.I dirfd
+argument is useful.)
 .PP
 The
 .BR mount_setattr ()

man2/statx.2

@@ -142,6 +142,9 @@ is a file descriptor that refers to a directory, then
 is a relative pathname that is interpreted relative to the directory
 referred to by
 .IR dirfd .
+(See
+.BR openat (2)
+for an explanation of why this is useful.)
 .TP
 By file descriptor
 If

man2/symlink.2

@@ -131,6 +131,11 @@ If
 is absolute, then
 .I newdirfd
 is ignored.
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR symlinkat ().
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and

man3/mkfifo.3

@@ -111,6 +111,11 @@ If
 is absolute, then
 .I dirfd
 is ignored.
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR mkfifoat ().
 .SH RETURN VALUE
 On success
 .BR mkfifo ()