Signed-off-by: Jeremy Bongio <bongiojp@xxxxxxxxx>
---
This is a ext4 filesystem specific ioctl. However, this ioctl will
likely be implemented for multiple filesystems at which point this
manpage will be updated.
man2/ioctl_fsuuid.2 | 115 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 115 insertions(+)
create mode 100644 man2/ioctl_fsuuid.2
diff --git a/man2/ioctl_fsuuid.2 b/man2/ioctl_fsuuid.2
new file mode 100644
index 000000000..53747684f
--- /dev/null
+++ b/man2/ioctl_fsuuid.2
@@ -0,0 +1,115 @@
+.\" Copyright (c) 2022 Google, Inc., written by Jeremy Bongio <bongiojp@xxxxxxxxx>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.TH IOCTL_FSUUID 2 2022-07-20 "Linux" "Linux Programmer's Manual"
+.SH NAME
+ioctl_fsuuid \- get or set an ext4 filesystem uuid
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/ioctl.h>
+.PP
+.BI "int ioctl(int " fd ", EXT4_IOC_GETFSUUID, struct " fsuuid ");"
+.BI "int ioctl(int " fd ", EXT4_IOC_SETFSUUID, struct " fsuuid ");"
+.fi
+.SH DESCRIPTION
+If an ext4 filesystem supports uuid manipulation, these
+.BR ioctl (2)
+operations can be used to get or set the uuid for the ext4 filesystem
+on which
+.I fd
+resides.
+.PP
+The argument to these operations should be a pointer to a
+.IR "struct fsuuid" ":"
+.PP
+.in +4n
+.EX
+struct fsuuid {
+ __u32 fsu_len; /* Number of bytes in a uuid */
+ __u32 fsu_flags; /* Mapping flags */
+ __u8 fsu_uuid[]; /* Byte array for uuid */
+};
+.EE
+.PP
+The
+.I fsu_flags
+field must be set to 0.
+.PP
+If an
+.BR EXT4_IOC_GETFSUUID
+operation is called with
+.I fsu_len
+set to 0,
+.I fsu_len
+will be reassigned the number of bytes in an ext4 filesystem uuid
+and the return code will be -EINVAL.
+.PP
+If an
+.BR EXT4_IOC_GETFSUUID
+operation is called with
+.I fsu_len
+set to the number of bytes in an ext4 filesystem uuid and
+.I fsu_uuid
+is allocated at least that many bytes, then
+the filesystem uuid will be written to
+.I fsu_uuid.
+.PP
+If an
+.BR EXT4_IOC_SETFSUUID
+operation is called with
+.I fsu_len
+set to the number of bytes in an ext4 filesystem uuid and
+.I fsu_uuid
+contains a uuid with
+.I fsu_uuid
+bytes, then
+the filesystem uuid will be set to
+.I fsu_uuid.
+.PP
+The
+.B FS_IOC_SETFSUUID
+operation requires privilege
+.RB ( CAP_SYS_ADMIN ).
+If the filesystem is currently being resized, an
+.B EXT4_IOC_SETFSUUID
+operation will wait until the resize is finished and the uuid can safely be set.
+This may take a long time.
+.PP
+.SH RETURN VALUE
+On success zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+Possible errors include (but are not limited to) the following:
+.TP
+.B EFAULT
+Either the pointer to the
+.I fsuuid
+structure is invalid or
+.I fsu_uuid
+has not been initialized properly.
+.TP
+.B EINVAL
+The specified arguments are invalid.
+.I fsu_len
+did not match the filesystem uuid length or
+.I fsu_flags
+has bits set that are not implemented.
+.TP
+.B ENOTTY
+The filesystem does not support the ioctl.
+.TP
+.B EOPNOTSUPP
+The filesystem does not currently support changing the uuid through this
+ioctl. This may be due to incompatible feature flags.
+.TP
+.B EPERM
+The calling process does not have sufficient permissions to set the uuid.
+.SH CONFORMING TO
+This API is Linux-specific.
+.SH SEE ALSO
+.BR ioctl (2)
--
2.37.0.170.g444d1eabd0-goog
