* [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
@ 2015-01-23 19:54 ` Heinrich Schuchardt
0 siblings, 0 replies; 23+ messages in thread
From: Heinrich Schuchardt @ 2015-01-23 19:54 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Ogawa Hirofumi, linux-fsdevel, linux-kernel, linux-man,
Heinrich Schuchardt
The ioctl(2) system call may be used to retrieve information about
the fat file system and to set file attributes.
This new manpage describes the details.
Michael Kerrisk suggested to CC linux-fsdevel@vger.kernel.org and
linux-kernel@vger.kernel.org for review.
version 3: correct typos
version 2: consider comments by Michael Kerrisk
verison 1: original patch
Signed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
man2/ioctl-fat.2 | 442 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 442 insertions(+)
create mode 100644 man2/ioctl-fat.2
diff --git a/man2/ioctl-fat.2 b/man2/ioctl-fat.2
new file mode 100644
index 0000000..80891d8
--- /dev/null
+++ b/man2/ioctl-fat.2
@@ -0,0 +1,442 @@
+.\" Copyright (C) 2014, Heinrich Schuchardt <xypron.glpk@gmx.de>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date. The author(s) assume.
+.\" no responsibility for errors or omissions, or for damages resulting.
+.\" from the use of the information contained herein. The author(s) may.
+.\" not have taken the same level of care in the production of this.
+.\" manual, which is licensed free of charge, as they might when working.
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.TH IOCTl-FAT 2 2015-01-23 "Linux" "Linux Programmer's Manual"
+.SH "NAME"
+ioctl-fat \- manipulating the FAT filesystem
+.SH SYNOPSIS
+.nf
+.B #include <linux/msdos_fs.h>
+.br
+.B #include <sys/ioctl.h>
+.sp
+.BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t * " attr);
+.BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t * " attr);
+.BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t * " id);
+.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH,
+.BI " struct __fat_dirent[2] " entry);
+.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT,
+.BI " struct __fat_dirent[2] " entry);
+.SH DESCRIPTION
+The
+.BR ioctl (2)
+function can be used to read and write metadata of the FAT filesystems that
+are not accessible using other system calls.
+.SS Reading and setting file attributes
+Files and directories in the FAT filesystem possess an attribute bit mask that
+can be read with
+.B FAT_IOCTL_GET_ATTRIBUTES
+and written with
+.BR FAT_IOCTL_SET_ATTRIBUTES .
+.PP
+The
+.I fd
+argument contains a file descriptor for the file or directory.
+It is sufficient to create the file descriptor by calling
+.BR open (2)
+with the
+.B O_RDONLY
+flag.
+.PP
+The
+.I attr
+argument contains a pointer to the bit mask.
+The bits of the bit mask are
+.TP
+.B ATTR_RO
+This bit specifies that the file or directory is read-only.
+.TP
+.B ATTR_HIDDEN
+This bit specifies that the file or directory is hidden.
+.TP
+.B ATTR_SYS
+This bit specifies that the file is a system file.
+.TP
+.B ATTR_VOLUME
+This bit specifies that the file is a volume label.
+This attribute is read-only.
+.TP
+.B ATTR_DIR
+This bit specifies that this is a directory.
+This attribute is read-only.
+.TP
+.B ATTR_ARCH
+This bit indicates that this file or directory should be archived.
+It is set when a file is created or modified.
+It is reset by an archiving system.
+.PP
+The zero value
+.B ATTR_NONE
+can be used to indicate that no attribute bit is set.
+.SS Reading the volume label
+Fat filesystems are identified by a volume label.
+The volume label can be read with
+.BR FAT_IOCTL_GET_VOLUME_ID .
+.PP
+The
+.I fd
+argument can be a file descriptor for any file or directory of the
+filesystem.
+It is sufficient to create the file descriptor by calling
+.BR open (2)
+with the
+.B O_RDONLY
+flag.
+.PP
+The
+.I id
+argument is a pointer to the field that will be filled with the volume ID.
+Typically the volume label is displayed to the user as a group of two
+16-bit fields.
+.PP
+.in +4n
+.nf
+printf("Volume ID %4x-%4x\\n", id >> 16, id & 0xFFFF);
+.fi
+.in
+.SS Reading short file names of a directory
+A file or directory on a FAT filesystem always has a short filename
+consisting of up to 8 capital letters, optionally followed by a period
+and up to 3 capital letters for the file extension.
+If the actual filename does not fit into this scheme, it is stored
+as a long filename of up to 255 UTF-16 characters.
+.PP
+The short filenames in a directory can be read with
+.BR VFAT_IOCTL_READDIR_SHORT .
+.B VFAT_IOCTL_READDIR_BOTH
+reads both the short and the long filenames.
+.PP
+The
+.I fd
+argument must be a file descriptor for a directory.
+It is sufficient to create the file descriptor by calling
+.BR open (2)
+with the
+.B O_RDONLY
+flag.
+The file descriptor can be only used once to iterate over the directory
+entries by calling
+.BR ioctl (2)
+repeatedly.
+.PP
+The
+.I entry
+argument is a two-element array of the following structures.
+
+.in +4n
+.nf
+struct __fat_dirent {
+ long d_ino;
+ __kernel_off_t d_off;
+ uint32_t short d_reclen;
+ char d_name[256];
+};
+.fi
+.in
+.PP
+The first entry in the array is for the short filename.
+The second entry is for the long filename.
+.PP
+Field
+.I d_reclen
+specifies the length of the filename in field
+.IR d_name .
+A length of 0 for the short filename signals that the end of the directory
+has been reached.
+.SH RETURN VALUE
+On error, -1 is returned, and errno is set to indicate the error.
+.SH ERRORS
+.TP
+.B ENOTDIR
+This error is returned by
+.B VFAT_IOCTL_READDIR_SHORT
+and
+.B VFAT_IOCTL_READDIR_SHORT
+if the file descriptor does not point to a directory.
+.TP
+.B ENOTTY
+This error signals that the file descriptor is not for a FAT filesystem.
+.PP
+For further error values see
+.BR ioctl (2).
+.SH VERSIONS
+.B FAT_IOCTL_GET_VOLUME_ID
+was introduced in version 3.11 of the Linux kernel.
+.PP
+.BR FAT_IOCTL_GET_ATTRIBUTES ,
+.BR FAT_IOCTL_SET_ATTRIBUTES ,
+.BR VFAT_IOCTL_READDIR_BOTH ,
+and
+.B VFAT_IOCTL_READDIR_SHORT
+were introduced before version 2.6.28 of the Linux kernel.
+.SH "CONFORMING TO"
+This API is Linux-specific.
+.SH EXAMPLE
+.SS Toggling the archive flag
+The following program demonstrates the usage of the ioctl API to manipulate
+file attributes.
+It reads and displays the archive attribute of a file.
+After inverting the value of the attribute, it reads and displays it again.
+.PP
+The following was recorded when applying the program for the file
+.IR /mnt/user/foo .
+.SS Example output
+.in +4n
+.nf
+# ./toggle_archive_flag /mnt/user/foo
+Archive flag is set
+Toggling archive flag
+Archive flag is not set
+.fi
+.in
+.SS Program source
+.in +4n
+.nf
+#include <fcntl.h>
+#include <linux/msdos_fs.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/ioctl.h>
+#include <unistd.h>
+
+/*
+ * Read file attributes of a file on a FAT filesystem.
+ * Output the state of the archive flag.
+ */
+static uint32_t
+readattr(int fd)
+{
+ uint32_t attr;
+ int ret;
+
+ ret = ioctl(fd, FAT_IOCTL_GET_ATTRIBUTES, &attr);
+ if (ret == \-1) {
+ perror("ioctl");
+ exit(EXIT_FAILURE);
+ }
+
+ if (attr & ATTR_ARCH)
+ printf("Archive flag is set\\n");
+ else
+ printf("Archive flag is not set\\n");
+
+ return attr;
+}
+
+int
+main(int argc, char *argv[])
+{
+ uint32_t attr;
+ int fd;
+ int ret;
+
+ if (argc != 2) {
+ printf("Usage: %s FILENAME\\n", argv[0]);
+ exit(EXIT_FAILURE);
+ }
+
+ fd = open(argv[1], O_RDONLY);
+ if (fd == \-1) {
+ perror("open");
+ exit(EXIT_FAILURE);
+ }
+
+ /*
+ * Read and display the FAT file attributes.
+ */
+ attr = readattr(fd);
+
+ /*
+ * Invert archive attribute.
+ */
+ printf("Toggling archive flag\\n");
+ attr ^= ATTR_ARCH;
+
+ /*
+ * Write the changed FAT file attributes.
+ */
+ ret = ioctl(fd, FAT_IOCTL_SET_ATTRIBUTES, &attr);
+ if (ret == \-1) {
+ perror("ioctl");
+ exit(EXIT_FAILURE);
+ }
+
+ /*
+ * Read and display the FAT file attributes.
+ */
+ readattr(fd);
+
+ close(fd);
+
+ return EXIT_SUCCESS;
+}
+.fi
+.in
+.SS Reading the volume label
+The following program demonstrates the usage of the ioctl API to
+display the volume label of a FAT filesystem.
+.PP
+The following output was recorded when applying the program for
+directory
+.IR /mnt/user .
+.SS Example output
+.in +4n
+.nf
+$ ./display_volume_id /mnt/user
+Volume ID 6443-6241
+.fi
+.in
+.SS Program source
+.in +4n
+.nf
+#include <fcntl.h>
+#include <linux/msdos_fs.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/ioctl.h>
+#include <unistd.h>
+
+int
+main(int argc, char *argv[])
+{
+ uint32_t id;
+ int fd;
+ int ret;
+
+ if (argc != 2) {
+ printf("Usage: %s FILENAME\\n", argv[0]);
+ exit(EXIT_FAILURE);
+ }
+
+ fd = open(argv[1], O_RDONLY);
+ if (fd == \-1) {
+ perror("open");
+ exit(EXIT_FAILURE);
+ }
+
+ /*
+ * Read volume ID.
+ */
+ ret = ioctl(fd, FAT_IOCTL_GET_VOLUME_ID, &id);
+ if (ret == \-1) {
+ perror("ioctl");
+ exit(EXIT_FAILURE);
+ }
+
+ /*
+ * Format the output as two groups of 16 bits each.
+ */
+ printf("Volume ID %4x\-%4x\\n", id >> 16, id & 0xFFFF);
+
+ close(fd);
+
+ return EXIT_SUCCESS;
+}
+.fi
+.in
+.SS Listing a directory
+The following program demonstrates the usage of the ioctl API to
+list a directory.
+.PP
+The following was recorded when applying the program for the directory
+.IR /mnt/user .
+.SS Example output
+.in +4n
+.nf
+$ ./fat_dir /mnt/user
+\[char46] -> ''
+\[char46]. -> ''
+ALONGF~1.TXT -> 'a long filename.txt'
+UPPER.TXT -> ''
+LOWER.TXT -> 'lower.txt'
+.fi
+.in
+.SS Program source
+.in +4n
+.nf
+#include <fcntl.h>
+#include <linux/msdos_fs.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/ioctl.h>
+#include <unistd.h>
+
+int
+main(int argc, char *argv[])
+{
+ struct __fat_dirent entry[2];
+ int fd;
+ int ret;
+
+ if (argc != 2) {
+ printf("Usage: %s DIRECTORY\\n", argv[0]);
+ exit(EXIT_FAILURE);
+ }
+
+ /*
+ * Open file descriptor for the directory.
+ */
+ fd = open(argv[1], O_RDONLY | O_DIRECTORY);
+ if (fd == \-1) {
+ perror("open");
+ exit(EXIT_FAILURE);
+ }
+
+ for (;;) {
+
+ /*
+ * Read next directory entry.
+ */
+ ret = ioctl( fd, VFAT_IOCTL_READDIR_BOTH, entry);
+
+ /*
+ * If an error occurs, the return value is \-1.
+ * If d_reclen is zero, the end of the directory
+ * list has been reached.
+ */
+ if (ret == \-1 || entry[0].d_reclen == 0)
+ break;
+
+ /*
+ * Write both the short name and the long name.
+ */
+ printf("%s \-> '%s'\\n", entry[0].d_name, entry[1].d_name);
+ }
+ if (ret == \-1) {
+ perror("VFAT_IOCTL_READDIR_BOTH");
+ exit(EXIT_FAILURE);
+ }
+
+ /*
+ * Close the file descriptor.
+ */
+ close(fd);
+
+ return EXIT_SUCCESS;
+}
+.fi
+.in
+.SH SEE ALSO
+.BR ioctl (2)
--
2.1.4
^ permalink raw reply related [flat|nested] 23+ messages in thread* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
2015-01-23 19:54 ` Heinrich Schuchardt
(?)
@ 2015-02-03 8:25 ` Michael Kerrisk (man-pages)
2015-02-03 8:51 ` OGAWA Hirofumi
-1 siblings, 1 reply; 23+ messages in thread
From: Michael Kerrisk (man-pages) @ 2015-02-03 8:25 UTC (permalink / raw)
To: Heinrich Schuchardt
Cc: Ogawa Hirofumi, linux-fsdevel@vger.kernel.org, lkml, linux-man
Hello Heinrich and Ogawa,
On 23 January 2015 at 20:54, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
> The ioctl(2) system call may be used to retrieve information about
> the fat file system and to set file attributes.
>
> This new manpage describes the details.
@Ogawa, as the FAT maintainer, might you be willing to review this page?
@Heinrich, thanks for this page. It's a nice piece of work. I renamed
the page to ioctl_fat.2, since we already have
console_ioctl (4) - ioctls for console terminal and virtual consoles
ioctl_list (2) - list of ioctl calls in Linux/i386 kernel
tty_ioctl (4) - ioctls for terminals and serial lines
and I think consistency is helpful.
I made some minor edits to the page. You can find the current revision
in a Git branch, at:
http://git.kernel.org/cgit/docs/man-pages/man-pages.git/log/?h=draft_ioctl_fat
Thanks,
Michael
> Michael Kerrisk suggested to CC linux-fsdevel@vger.kernel.org and
> linux-kernel@vger.kernel.org for review.
>
> version 3: correct typos
> version 2: consider comments by Michael Kerrisk
> verison 1: original patch
>
> Signed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> ---
> man2/ioctl-fat.2 | 442 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 442 insertions(+)
> create mode 100644 man2/ioctl-fat.2
>
> diff --git a/man2/ioctl-fat.2 b/man2/ioctl-fat.2
> new file mode 100644
> index 0000000..80891d8
> --- /dev/null
> +++ b/man2/ioctl-fat.2
> @@ -0,0 +1,442 @@
> +.\" Copyright (C) 2014, Heinrich Schuchardt <xypron.glpk@gmx.de>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of
> +.\" this manual under the conditions for verbatim copying, provided that
> +.\" the entire resulting derived work is distributed under the terms of
> +.\" a permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date. The author(s) assume.
> +.\" no responsibility for errors or omissions, or for damages resulting.
> +.\" from the use of the information contained herein. The author(s) may.
> +.\" not have taken the same level of care in the production of this.
> +.\" manual, which is licensed free of charge, as they might when working.
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.TH IOCTl-FAT 2 2015-01-23 "Linux" "Linux Programmer's Manual"
> +.SH "NAME"
> +ioctl-fat \- manipulating the FAT filesystem
> +.SH SYNOPSIS
> +.nf
> +.B #include <linux/msdos_fs.h>
> +.br
> +.B #include <sys/ioctl.h>
> +.sp
> +.BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t * " attr);
> +.BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t * " attr);
> +.BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t * " id);
> +.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH,
> +.BI " struct __fat_dirent[2] " entry);
> +.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT,
> +.BI " struct __fat_dirent[2] " entry);
> +.SH DESCRIPTION
> +The
> +.BR ioctl (2)
> +function can be used to read and write metadata of the FAT filesystems that
> +are not accessible using other system calls.
> +.SS Reading and setting file attributes
> +Files and directories in the FAT filesystem possess an attribute bit mask that
> +can be read with
> +.B FAT_IOCTL_GET_ATTRIBUTES
> +and written with
> +.BR FAT_IOCTL_SET_ATTRIBUTES .
> +.PP
> +The
> +.I fd
> +argument contains a file descriptor for the file or directory.
> +It is sufficient to create the file descriptor by calling
> +.BR open (2)
> +with the
> +.B O_RDONLY
> +flag.
> +.PP
> +The
> +.I attr
> +argument contains a pointer to the bit mask.
> +The bits of the bit mask are
> +.TP
> +.B ATTR_RO
> +This bit specifies that the file or directory is read-only.
> +.TP
> +.B ATTR_HIDDEN
> +This bit specifies that the file or directory is hidden.
> +.TP
> +.B ATTR_SYS
> +This bit specifies that the file is a system file.
> +.TP
> +.B ATTR_VOLUME
> +This bit specifies that the file is a volume label.
> +This attribute is read-only.
> +.TP
> +.B ATTR_DIR
> +This bit specifies that this is a directory.
> +This attribute is read-only.
> +.TP
> +.B ATTR_ARCH
> +This bit indicates that this file or directory should be archived.
> +It is set when a file is created or modified.
> +It is reset by an archiving system.
> +.PP
> +The zero value
> +.B ATTR_NONE
> +can be used to indicate that no attribute bit is set.
> +.SS Reading the volume label
> +Fat filesystems are identified by a volume label.
> +The volume label can be read with
> +.BR FAT_IOCTL_GET_VOLUME_ID .
> +.PP
> +The
> +.I fd
> +argument can be a file descriptor for any file or directory of the
> +filesystem.
> +It is sufficient to create the file descriptor by calling
> +.BR open (2)
> +with the
> +.B O_RDONLY
> +flag.
> +.PP
> +The
> +.I id
> +argument is a pointer to the field that will be filled with the volume ID.
> +Typically the volume label is displayed to the user as a group of two
> +16-bit fields.
> +.PP
> +.in +4n
> +.nf
> +printf("Volume ID %4x-%4x\\n", id >> 16, id & 0xFFFF);
> +.fi
> +.in
> +.SS Reading short file names of a directory
> +A file or directory on a FAT filesystem always has a short filename
> +consisting of up to 8 capital letters, optionally followed by a period
> +and up to 3 capital letters for the file extension.
> +If the actual filename does not fit into this scheme, it is stored
> +as a long filename of up to 255 UTF-16 characters.
> +.PP
> +The short filenames in a directory can be read with
> +.BR VFAT_IOCTL_READDIR_SHORT .
> +.B VFAT_IOCTL_READDIR_BOTH
> +reads both the short and the long filenames.
> +.PP
> +The
> +.I fd
> +argument must be a file descriptor for a directory.
> +It is sufficient to create the file descriptor by calling
> +.BR open (2)
> +with the
> +.B O_RDONLY
> +flag.
> +The file descriptor can be only used once to iterate over the directory
> +entries by calling
> +.BR ioctl (2)
> +repeatedly.
> +.PP
> +The
> +.I entry
> +argument is a two-element array of the following structures.
> +
> +.in +4n
> +.nf
> +struct __fat_dirent {
> + long d_ino;
> + __kernel_off_t d_off;
> + uint32_t short d_reclen;
> + char d_name[256];
> +};
> +.fi
> +.in
> +.PP
> +The first entry in the array is for the short filename.
> +The second entry is for the long filename.
> +.PP
> +Field
> +.I d_reclen
> +specifies the length of the filename in field
> +.IR d_name .
> +A length of 0 for the short filename signals that the end of the directory
> +has been reached.
> +.SH RETURN VALUE
> +On error, -1 is returned, and errno is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B ENOTDIR
> +This error is returned by
> +.B VFAT_IOCTL_READDIR_SHORT
> +and
> +.B VFAT_IOCTL_READDIR_SHORT
> +if the file descriptor does not point to a directory.
> +.TP
> +.B ENOTTY
> +This error signals that the file descriptor is not for a FAT filesystem.
> +.PP
> +For further error values see
> +.BR ioctl (2).
> +.SH VERSIONS
> +.B FAT_IOCTL_GET_VOLUME_ID
> +was introduced in version 3.11 of the Linux kernel.
> +.PP
> +.BR FAT_IOCTL_GET_ATTRIBUTES ,
> +.BR FAT_IOCTL_SET_ATTRIBUTES ,
> +.BR VFAT_IOCTL_READDIR_BOTH ,
> +and
> +.B VFAT_IOCTL_READDIR_SHORT
> +were introduced before version 2.6.28 of the Linux kernel.
> +.SH "CONFORMING TO"
> +This API is Linux-specific.
> +.SH EXAMPLE
> +.SS Toggling the archive flag
> +The following program demonstrates the usage of the ioctl API to manipulate
> +file attributes.
> +It reads and displays the archive attribute of a file.
> +After inverting the value of the attribute, it reads and displays it again.
> +.PP
> +The following was recorded when applying the program for the file
> +.IR /mnt/user/foo .
> +.SS Example output
> +.in +4n
> +.nf
> +# ./toggle_archive_flag /mnt/user/foo
> +Archive flag is set
> +Toggling archive flag
> +Archive flag is not set
> +.fi
> +.in
> +.SS Program source
> +.in +4n
> +.nf
> +#include <fcntl.h>
> +#include <linux/msdos_fs.h>
> +#include <stdint.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/ioctl.h>
> +#include <unistd.h>
> +
> +/*
> + * Read file attributes of a file on a FAT filesystem.
> + * Output the state of the archive flag.
> + */
> +static uint32_t
> +readattr(int fd)
> +{
> + uint32_t attr;
> + int ret;
> +
> + ret = ioctl(fd, FAT_IOCTL_GET_ATTRIBUTES, &attr);
> + if (ret == \-1) {
> + perror("ioctl");
> + exit(EXIT_FAILURE);
> + }
> +
> + if (attr & ATTR_ARCH)
> + printf("Archive flag is set\\n");
> + else
> + printf("Archive flag is not set\\n");
> +
> + return attr;
> +}
> +
> +int
> +main(int argc, char *argv[])
> +{
> + uint32_t attr;
> + int fd;
> + int ret;
> +
> + if (argc != 2) {
> + printf("Usage: %s FILENAME\\n", argv[0]);
> + exit(EXIT_FAILURE);
> + }
> +
> + fd = open(argv[1], O_RDONLY);
> + if (fd == \-1) {
> + perror("open");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Read and display the FAT file attributes.
> + */
> + attr = readattr(fd);
> +
> + /*
> + * Invert archive attribute.
> + */
> + printf("Toggling archive flag\\n");
> + attr ^= ATTR_ARCH;
> +
> + /*
> + * Write the changed FAT file attributes.
> + */
> + ret = ioctl(fd, FAT_IOCTL_SET_ATTRIBUTES, &attr);
> + if (ret == \-1) {
> + perror("ioctl");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Read and display the FAT file attributes.
> + */
> + readattr(fd);
> +
> + close(fd);
> +
> + return EXIT_SUCCESS;
> +}
> +.fi
> +.in
> +.SS Reading the volume label
> +The following program demonstrates the usage of the ioctl API to
> +display the volume label of a FAT filesystem.
> +.PP
> +The following output was recorded when applying the program for
> +directory
> +.IR /mnt/user .
> +.SS Example output
> +.in +4n
> +.nf
> +$ ./display_volume_id /mnt/user
> +Volume ID 6443-6241
> +.fi
> +.in
> +.SS Program source
> +.in +4n
> +.nf
> +#include <fcntl.h>
> +#include <linux/msdos_fs.h>
> +#include <stdint.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/ioctl.h>
> +#include <unistd.h>
> +
> +int
> +main(int argc, char *argv[])
> +{
> + uint32_t id;
> + int fd;
> + int ret;
> +
> + if (argc != 2) {
> + printf("Usage: %s FILENAME\\n", argv[0]);
> + exit(EXIT_FAILURE);
> + }
> +
> + fd = open(argv[1], O_RDONLY);
> + if (fd == \-1) {
> + perror("open");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Read volume ID.
> + */
> + ret = ioctl(fd, FAT_IOCTL_GET_VOLUME_ID, &id);
> + if (ret == \-1) {
> + perror("ioctl");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Format the output as two groups of 16 bits each.
> + */
> + printf("Volume ID %4x\-%4x\\n", id >> 16, id & 0xFFFF);
> +
> + close(fd);
> +
> + return EXIT_SUCCESS;
> +}
> +.fi
> +.in
> +.SS Listing a directory
> +The following program demonstrates the usage of the ioctl API to
> +list a directory.
> +.PP
> +The following was recorded when applying the program for the directory
> +.IR /mnt/user .
> +.SS Example output
> +.in +4n
> +.nf
> +$ ./fat_dir /mnt/user
> +\[char46] -> ''
> +\[char46]. -> ''
> +ALONGF~1.TXT -> 'a long filename.txt'
> +UPPER.TXT -> ''
> +LOWER.TXT -> 'lower.txt'
> +.fi
> +.in
> +.SS Program source
> +.in +4n
> +.nf
> +#include <fcntl.h>
> +#include <linux/msdos_fs.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/ioctl.h>
> +#include <unistd.h>
> +
> +int
> +main(int argc, char *argv[])
> +{
> + struct __fat_dirent entry[2];
> + int fd;
> + int ret;
> +
> + if (argc != 2) {
> + printf("Usage: %s DIRECTORY\\n", argv[0]);
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Open file descriptor for the directory.
> + */
> + fd = open(argv[1], O_RDONLY | O_DIRECTORY);
> + if (fd == \-1) {
> + perror("open");
> + exit(EXIT_FAILURE);
> + }
> +
> + for (;;) {
> +
> + /*
> + * Read next directory entry.
> + */
> + ret = ioctl( fd, VFAT_IOCTL_READDIR_BOTH, entry);
> +
> + /*
> + * If an error occurs, the return value is \-1.
> + * If d_reclen is zero, the end of the directory
> + * list has been reached.
> + */
> + if (ret == \-1 || entry[0].d_reclen == 0)
> + break;
> +
> + /*
> + * Write both the short name and the long name.
> + */
> + printf("%s \-> '%s'\\n", entry[0].d_name, entry[1].d_name);
> + }
> + if (ret == \-1) {
> + perror("VFAT_IOCTL_READDIR_BOTH");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Close the file descriptor.
> + */
> + close(fd);
> +
> + return EXIT_SUCCESS;
> +}
> +.fi
> +.in
> +.SH SEE ALSO
> +.BR ioctl (2)
> --
> 2.1.4
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
2015-02-03 8:25 ` Michael Kerrisk (man-pages)
@ 2015-02-03 8:51 ` OGAWA Hirofumi
0 siblings, 0 replies; 23+ messages in thread
From: OGAWA Hirofumi @ 2015-02-03 8:51 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Heinrich Schuchardt, linux-fsdevel@vger.kernel.org, lkml,
linux-man
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
> Hello Heinrich and Ogawa,
Hi,
> On 23 January 2015 at 20:54, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>> The ioctl(2) system call may be used to retrieve information about
>> the fat file system and to set file attributes.
>>
>> This new manpage describes the details.
>
> @Ogawa, as the FAT maintainer, might you be willing to review this page?
for (;;) {
/*
* Read next directory entry.
*/
ret = ioctl( fd, VFAT_IOCTL_READDIR_BOTH, entry);
/*
* If an error occurs, the return value is -1.
* If d_reclen is zero, the end of the directory
* list has been reached.
*/
if (ret == -1 || entry[0].d_reclen == 0)
break;
Quick reviewed, and looks good. However, entry[0].d_reclen == 0 works as
backward compatibility though. The example might be good to use usual
way of getdents().
I.e., "ret" means
-1 == error
0 == EOD
0 > how many bytes read
Thanks.
--
OGAWA Hirofumi <hirofumi@mail.parknet.co.jp>
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
@ 2015-02-03 8:51 ` OGAWA Hirofumi
0 siblings, 0 replies; 23+ messages in thread
From: OGAWA Hirofumi @ 2015-02-03 8:51 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Heinrich Schuchardt, linux-fsdevel@vger.kernel.org, lkml,
linux-man
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
> Hello Heinrich and Ogawa,
Hi,
> On 23 January 2015 at 20:54, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>> The ioctl(2) system call may be used to retrieve information about
>> the fat file system and to set file attributes.
>>
>> This new manpage describes the details.
>
> @Ogawa, as the FAT maintainer, might you be willing to review this page?
for (;;) {
/*
* Read next directory entry.
*/
ret = ioctl( fd, VFAT_IOCTL_READDIR_BOTH, entry);
/*
* If an error occurs, the return value is -1.
* If d_reclen is zero, the end of the directory
* list has been reached.
*/
if (ret == -1 || entry[0].d_reclen == 0)
break;
Quick reviewed, and looks good. However, entry[0].d_reclen == 0 works as
backward compatibility though. The example might be good to use usual
way of getdents().
I.e., "ret" means
-1 == error
0 == EOD
0 > how many bytes read
Thanks.
--
OGAWA Hirofumi <hirofumi@mail.parknet.co.jp>
^ permalink raw reply [flat|nested] 23+ messages in thread[parent not found: <87k2zze5tg.fsf-UIVanBePwB70ZhReMnHkpc8NsWr+9BEh@public.gmane.org>]
* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
2015-02-03 8:51 ` OGAWA Hirofumi
@ 2015-02-03 9:24 ` Michael Kerrisk (man-pages)
-1 siblings, 0 replies; 23+ messages in thread
From: Michael Kerrisk (man-pages) @ 2015-02-03 9:24 UTC (permalink / raw)
To: OGAWA Hirofumi
Cc: Heinrich Schuchardt,
linux-fsdevel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, lkml,
linux-man
Hello Hirofumi,
Thanks for checking the page over.
On 3 February 2015 at 09:51, OGAWA Hirofumi <hirofumi-UIVanBePwB70ZhReMnHkpc8NsWr+9BEh@public.gmane.org> wrote:
> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>
>> Hello Heinrich and Ogawa,
>
> Hi,
>
>> On 23 January 2015 at 20:54, Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org> wrote:
>>> The ioctl(2) system call may be used to retrieve information about
>>> the fat file system and to set file attributes.
>>>
>>> This new manpage describes the details.
>>
>> @Ogawa, as the FAT maintainer, might you be willing to review this page?
>
>
> for (;;) {
>
> /*
> * Read next directory entry.
> */
> ret = ioctl( fd, VFAT_IOCTL_READDIR_BOTH, entry);
>
> /*
> * If an error occurs, the return value is -1.
> * If d_reclen is zero, the end of the directory
> * list has been reached.
> */
> if (ret == -1 || entry[0].d_reclen == 0)
> break;
>
> Quick reviewed, and looks good. However, entry[0].d_reclen == 0 works as
> backward compatibility though. The example might be good to use usual
> way of getdents().
>
> I.e., "ret" means
> -1 == error
> 0 == EOD
> 0 > how many bytes read
Sorry -- I do not really understand what you mean here
"entry[0].d_reclen == 0 works as backward compatibility though"). Is
the line
if (ret == -1 || entry[0].d_reclen == 0)
incorrect? If yes, what should the code look like?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
@ 2015-02-03 9:24 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 23+ messages in thread
From: Michael Kerrisk (man-pages) @ 2015-02-03 9:24 UTC (permalink / raw)
To: OGAWA Hirofumi
Cc: Heinrich Schuchardt, linux-fsdevel@vger.kernel.org, lkml,
linux-man
Hello Hirofumi,
Thanks for checking the page over.
On 3 February 2015 at 09:51, OGAWA Hirofumi <hirofumi@mail.parknet.co.jp> wrote:
> "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>
>> Hello Heinrich and Ogawa,
>
> Hi,
>
>> On 23 January 2015 at 20:54, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>>> The ioctl(2) system call may be used to retrieve information about
>>> the fat file system and to set file attributes.
>>>
>>> This new manpage describes the details.
>>
>> @Ogawa, as the FAT maintainer, might you be willing to review this page?
>
>
> for (;;) {
>
> /*
> * Read next directory entry.
> */
> ret = ioctl( fd, VFAT_IOCTL_READDIR_BOTH, entry);
>
> /*
> * If an error occurs, the return value is -1.
> * If d_reclen is zero, the end of the directory
> * list has been reached.
> */
> if (ret == -1 || entry[0].d_reclen == 0)
> break;
>
> Quick reviewed, and looks good. However, entry[0].d_reclen == 0 works as
> backward compatibility though. The example might be good to use usual
> way of getdents().
>
> I.e., "ret" means
> -1 == error
> 0 == EOD
> 0 > how many bytes read
Sorry -- I do not really understand what you mean here
"entry[0].d_reclen == 0 works as backward compatibility though"). Is
the line
if (ret == -1 || entry[0].d_reclen == 0)
incorrect? If yes, what should the code look like?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
2015-02-03 9:24 ` Michael Kerrisk (man-pages)
@ 2015-02-03 9:44 ` OGAWA Hirofumi
-1 siblings, 0 replies; 23+ messages in thread
From: OGAWA Hirofumi @ 2015-02-03 9:44 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Heinrich Schuchardt, linux-fsdevel@vger.kernel.org, lkml,
linux-man
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>> Quick reviewed, and looks good. However, entry[0].d_reclen == 0 works as
>> backward compatibility though. The example might be good to use usual
>> way of getdents().
>>
>> I.e., "ret" means
>> -1 == error
>> 0 == EOD
>> 0 > how many bytes read
>
> Sorry -- I do not really understand what you mean here
> "entry[0].d_reclen == 0 works as backward compatibility though"). Is
> the line
>
> if (ret == -1 || entry[0].d_reclen == 0)
>
> incorrect? If yes, what should the code look like?
Sorry. I meant, "entry[0].d_reclen == 0" check works because fatfs still
have backward compatibility code. However it would not be preferred way.
In ancient version, fatfs didn't return proper return code, so apps (I
know only use is wine) had to check "entry[0].d_reclen == 0" to know
EOD.
But for a long time, fatfs returns proper return code like said in
previous email (previous email was wrong on "0 > how many bytes read",
see below instead). I.e., now user can use "ret" as similar to
getdents(), user can know the result as usual from "ret" without
"entry[0].d_reclen == 0".
while (1) {
ret = ioctl();
if (ret == -1) {
/* error */
if (ret == 0)
/* EOD */
/* got entry (would be ret == 1) */
}
--
OGAWA Hirofumi <hirofumi@mail.parknet.co.jp>
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
@ 2015-02-03 9:44 ` OGAWA Hirofumi
0 siblings, 0 replies; 23+ messages in thread
From: OGAWA Hirofumi @ 2015-02-03 9:44 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Heinrich Schuchardt, linux-fsdevel@vger.kernel.org, lkml,
linux-man
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>> Quick reviewed, and looks good. However, entry[0].d_reclen == 0 works as
>> backward compatibility though. The example might be good to use usual
>> way of getdents().
>>
>> I.e., "ret" means
>> -1 == error
>> 0 == EOD
>> 0 > how many bytes read
>
> Sorry -- I do not really understand what you mean here
> "entry[0].d_reclen == 0 works as backward compatibility though"). Is
> the line
>
> if (ret == -1 || entry[0].d_reclen == 0)
>
> incorrect? If yes, what should the code look like?
Sorry. I meant, "entry[0].d_reclen == 0" check works because fatfs still
have backward compatibility code. However it would not be preferred way.
In ancient version, fatfs didn't return proper return code, so apps (I
know only use is wine) had to check "entry[0].d_reclen == 0" to know
EOD.
But for a long time, fatfs returns proper return code like said in
previous email (previous email was wrong on "0 > how many bytes read",
see below instead). I.e., now user can use "ret" as similar to
getdents(), user can know the result as usual from "ret" without
"entry[0].d_reclen == 0".
while (1) {
ret = ioctl();
if (ret == -1) {
/* error */
if (ret == 0)
/* EOD */
/* got entry (would be ret == 1) */
}
--
OGAWA Hirofumi <hirofumi@mail.parknet.co.jp>
^ permalink raw reply [flat|nested] 23+ messages in thread[parent not found: <87fvane3ch.fsf-UIVanBePwB70ZhReMnHkpc8NsWr+9BEh@public.gmane.org>]
* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
2015-02-03 9:44 ` OGAWA Hirofumi
@ 2015-02-03 9:54 ` Michael Kerrisk (man-pages)
-1 siblings, 0 replies; 23+ messages in thread
From: Michael Kerrisk (man-pages) @ 2015-02-03 9:54 UTC (permalink / raw)
To: OGAWA Hirofumi
Cc: Heinrich Schuchardt,
linux-fsdevel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, lkml,
linux-man
Hello Hirofumi,
On 3 February 2015 at 10:44, OGAWA Hirofumi <hirofumi-UIVanBePwB70ZhReMnHkpc8NsWr+9BEh@public.gmane.org> wrote:
> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>
>>> Quick reviewed, and looks good. However, entry[0].d_reclen == 0 works as
>>> backward compatibility though. The example might be good to use usual
>>> way of getdents().
>>>
>>> I.e., "ret" means
>>> -1 == error
>>> 0 == EOD
>>> 0 > how many bytes read
>>
>> Sorry -- I do not really understand what you mean here
>> "entry[0].d_reclen == 0 works as backward compatibility though"). Is
>> the line
>>
>> if (ret == -1 || entry[0].d_reclen == 0)
>>
>> incorrect? If yes, what should the code look like?
>
> Sorry. I meant, "entry[0].d_reclen == 0" check works because fatfs still
> have backward compatibility code. However it would not be preferred way.
>
> In ancient version, fatfs didn't return proper return code, so apps (I
> know only use is wine) had to check "entry[0].d_reclen == 0" to know
> EOD.
>
> But for a long time, fatfs returns proper return code like said in
> previous email (previous email was wrong on "0 > how many bytes read",
> see below instead). I.e., now user can use "ret" as similar to
> getdents(), user can know the result as usual from "ret" without
> "entry[0].d_reclen == 0".
>
> while (1) {
> ret = ioctl();
> if (ret == -1) {
> /* error */
>
> if (ret == 0)
> /* EOD */
>
> /* got entry (would be ret == 1) */
> }
Thanks for the clarification. I have one other question. Currently the
man page does not document two fields in the __fat_dirent structure:
d_ino and d_offset. d_ino is presumably the inode number. But, what is
d_offset?
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
@ 2015-02-03 9:54 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 23+ messages in thread
From: Michael Kerrisk (man-pages) @ 2015-02-03 9:54 UTC (permalink / raw)
To: OGAWA Hirofumi
Cc: Heinrich Schuchardt, linux-fsdevel@vger.kernel.org, lkml,
linux-man
Hello Hirofumi,
On 3 February 2015 at 10:44, OGAWA Hirofumi <hirofumi@mail.parknet.co.jp> wrote:
> "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>
>>> Quick reviewed, and looks good. However, entry[0].d_reclen == 0 works as
>>> backward compatibility though. The example might be good to use usual
>>> way of getdents().
>>>
>>> I.e., "ret" means
>>> -1 == error
>>> 0 == EOD
>>> 0 > how many bytes read
>>
>> Sorry -- I do not really understand what you mean here
>> "entry[0].d_reclen == 0 works as backward compatibility though"). Is
>> the line
>>
>> if (ret == -1 || entry[0].d_reclen == 0)
>>
>> incorrect? If yes, what should the code look like?
>
> Sorry. I meant, "entry[0].d_reclen == 0" check works because fatfs still
> have backward compatibility code. However it would not be preferred way.
>
> In ancient version, fatfs didn't return proper return code, so apps (I
> know only use is wine) had to check "entry[0].d_reclen == 0" to know
> EOD.
>
> But for a long time, fatfs returns proper return code like said in
> previous email (previous email was wrong on "0 > how many bytes read",
> see below instead). I.e., now user can use "ret" as similar to
> getdents(), user can know the result as usual from "ret" without
> "entry[0].d_reclen == 0".
>
> while (1) {
> ret = ioctl();
> if (ret == -1) {
> /* error */
>
> if (ret == 0)
> /* EOD */
>
> /* got entry (would be ret == 1) */
> }
Thanks for the clarification. I have one other question. Currently the
man page does not document two fields in the __fat_dirent structure:
d_ino and d_offset. d_ino is presumably the inode number. But, what is
d_offset?
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
2015-02-03 9:54 ` Michael Kerrisk (man-pages)
@ 2015-02-03 10:05 ` OGAWA Hirofumi
-1 siblings, 0 replies; 23+ messages in thread
From: OGAWA Hirofumi @ 2015-02-03 10:05 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Heinrich Schuchardt, linux-fsdevel@vger.kernel.org, lkml,
linux-man
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
> Thanks for the clarification. I have one other question. Currently the
> man page does not document two fields in the __fat_dirent structure:
> d_ino and d_offset. d_ino is presumably the inode number. But, what is
> d_offset?
d_ino and d_off (I guess, d_off you meant) is used only for long
filename part in dirents. And,
d_off == seek offset
d_ino == inode number
same with getdents(), but again it is valid only on long name dirent.
--
OGAWA Hirofumi <hirofumi@mail.parknet.co.jp>
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
@ 2015-02-03 10:05 ` OGAWA Hirofumi
0 siblings, 0 replies; 23+ messages in thread
From: OGAWA Hirofumi @ 2015-02-03 10:05 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Heinrich Schuchardt, linux-fsdevel@vger.kernel.org, lkml,
linux-man
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
> Thanks for the clarification. I have one other question. Currently the
> man page does not document two fields in the __fat_dirent structure:
> d_ino and d_offset. d_ino is presumably the inode number. But, what is
> d_offset?
d_ino and d_off (I guess, d_off you meant) is used only for long
filename part in dirents. And,
d_off == seek offset
d_ino == inode number
same with getdents(), but again it is valid only on long name dirent.
--
OGAWA Hirofumi <hirofumi@mail.parknet.co.jp>
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH 1/1] ioctl_fat.2: d_ino, d_off, return value explained
[not found] ` <87fvane3ch.fsf-UIVanBePwB70ZhReMnHkpc8NsWr+9BEh@public.gmane.org>
2015-02-03 9:54 ` Michael Kerrisk (man-pages)
@ 2015-02-06 22:10 ` Heinrich Schuchardt
[not found] ` <1423260638-23504-1-git-send-email-xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
1 sibling, 1 reply; 23+ messages in thread
From: Heinrich Schuchardt @ 2015-02-06 22:10 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: OGAWA Hirofumi, linux-man, Andreas Dilger, Heinrich Schuchardt
The fields d_ino and d_off of structure __fat_dirent are explained.
The different return values of VFAT_IOCTL_READDIR_BOTH and
VFAT_IOCTL_READDIR_SHORT are explained.
The usage of the return value in the example is corrected.
Signed-off-by: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
---
man2/ioctl_fat.2 | 54 ++++++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 46 insertions(+), 8 deletions(-)
diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2
index 55417f6..2c28421 100644
--- a/man2/ioctl_fat.2
+++ b/man2/ioctl_fat.2
@@ -157,25 +157,61 @@ struct __fat_dirent {
The first entry in the array is for the short filename.
The second entry is for the long filename.
.PP
+Fields
+.I d_ino
+and
+.I d_off
+are only filled for long filenames.
+Field
+.I d_ino
+holds the inode number of the directory.
+Field
+.I d_off
+holds the offset of the file entry in the directory.
+As these values are not available for short filenames, the user code should
+simply ignore them.
+.PP
The field
.I d_reclen
contains the length of the filename in the field
.IR d_name .
-A length of 0 for the short filename signals that the end of the directory
-has been reached.
-.\" FIXME Missing here are explanations of the fileds ;d_ino' and 'd_off'
+To keep backwards compatibility a length of 0 for the short filename signals
+that the end of the directory has been reached.
+The user code should rely on the return value to identify the end of the
+directory.
+If no long filename exists, field
+.I d_reclen
+is set to 0 and
+.I d_name
+is a character string of length 0 for the long filename.
.SH RETURN VALUE
On error, \-1 is returned, and
.I errno
is set to indicate the error.
+.PP
+For
+.B VFAT_IOCTL_READDIR_BOTH
+and
+.B VFAT_IOCTL_READDIR_SHORT
+a return value of 1 signals that a new directory entry has been read and
+a return value of 0 signals that the end of the directory has been reached.
.SH ERRORS
.TP
-.B ENOTDIR
+.B ENOENT
This error is returned by
+.B VFAT_IOCTL_READDIR_BOTH
+and
.B VFAT_IOCTL_READDIR_SHORT
+if the file descriptor
+.I fd
+refers to a removed, but still open directory.
+.TP
+.B ENOTDIR
+This error is returned by
+.B VFAT_IOCTL_READDIR_BOTH
and
.B VFAT_IOCTL_READDIR_SHORT
-if
+if the file descriptor
.I fd
does not refer to a directory.
.TP
@@ -431,10 +467,12 @@ main(int argc, char *argv[])
/*
* If an error occurs, the return value is \-1.
- * If d_reclen is zero, the end of the directory
- * list has been reached.
+ * If the end of the directory list has been reached,
+ * the return value is 0.
+ * For backward compatibility the end of the directory
+ * list is also signaled by d_reclen == 0.
*/
- if (ret == \-1 || entry[0].d_reclen == 0)
+ if (ret < 1)
break;
/*
--
2.1.4
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 23+ messages in thread
* Re: [PATCH v3 1/1] ioctl-fat.2: new manpage for the ioctl fat API
2015-01-23 19:54 ` Heinrich Schuchardt
(?)
(?)
@ 2015-02-03 8:49 ` Andreas Dilger
[not found] ` <5984550D-1518-490C-9A3F-3F9B1FA2EA00-m1MBpc4rdrD3fQ9qLvQP4Q@public.gmane.org>
-1 siblings, 1 reply; 23+ messages in thread
From: Andreas Dilger @ 2015-02-03 8:49 UTC (permalink / raw)
To: Heinrich Schuchardt
Cc: Michael Kerrisk (man-pages), Ogawa Hirofumi,
Linux Filesystem Development List, LKML, linux-man
On Jan 23, 2015, at 12:54 PM, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> The ioctl(2) system call may be used to retrieve information about
> the fat file system and to set file attributes.
>
> This new manpage describes the details.
>
> Michael Kerrisk suggested to CC linux-fsdevel@vger.kernel.org and
> linux-kernel@vger.kernel.org for review.
>
> version 3: correct typos
> version 2: consider comments by Michael Kerrisk
> verison 1: original patch
>
> Signed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> ---
> man2/ioctl-fat.2 | 442 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 442 insertions(+)
> create mode 100644 man2/ioctl-fat.2
>
> diff --git a/man2/ioctl-fat.2 b/man2/ioctl-fat.2
> new file mode 100644
> index 0000000..80891d8
> --- /dev/null
> +++ b/man2/ioctl-fat.2
> @@ -0,0 +1,442 @@
> +.\" Copyright (C) 2014, Heinrich Schuchardt <xypron.glpk@gmx.de>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of
> +.\" this manual under the conditions for verbatim copying, provided that
> +.\" the entire resulting derived work is distributed under the terms of
> +.\" a permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date. The author(s) assume.
> +.\" no responsibility for errors or omissions, or for damages resulting.
> +.\" from the use of the information contained herein. The author(s) may.
> +.\" not have taken the same level of care in the production of this.
> +.\" manual, which is licensed free of charge, as they might when working.
There are extraneous periods at the end of each of these lines.
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.TH IOCTl-FAT 2 2015-01-23 "Linux" "Linux Programmer's Manual"
> +.SH "NAME"
> +ioctl-fat \- manipulating the FAT filesystem
> +.SH SYNOPSIS
> +.nf
> +.B #include <linux/msdos_fs.h>
> +.br
> +.B #include <sys/ioctl.h>
> +.sp
> +.BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t * " attr);
> +.BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t * " attr);
> +.BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t * " id);
> +.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH,
> +.BI " struct __fat_dirent[2] " entry);
> +.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT,
> +.BI " struct __fat_dirent[2] " entry);
> +.SH DESCRIPTION
> +The
> +.BR ioctl (2)
> +function can be used to read and write metadata of the FAT filesystems that
> +are not accessible using other system calls.
> +.SS Reading and setting file attributes
> +Files and directories in the FAT filesystem possess an attribute bit mask that
> +can be read with
> +.B FAT_IOCTL_GET_ATTRIBUTES
> +and written with
> +.BR FAT_IOCTL_SET_ATTRIBUTES .
> +.PP
> +The
> +.I fd
> +argument contains a file descriptor for the file or directory.
> +It is sufficient to create the file descriptor by calling
> +.BR open (2)
> +with the
> +.B O_RDONLY
> +flag.
> +.PP
> +The
> +.I attr
> +argument contains a pointer to the bit mask.
> +The bits of the bit mask are
> +.TP
> +.B ATTR_RO
> +This bit specifies that the file or directory is read-only.
It's too bad that these constants have such generic names. It would
be better to use MSDOS_ATTR_* or FAT_ATTR_*, since these are also
exposed to userspace, but are only used by FAT.
> +.TP
> +.B ATTR_HIDDEN
> +This bit specifies that the file or directory is hidden.
> +.TP
> +.B ATTR_SYS
> +This bit specifies that the file is a system file.
It might be useful if the FS_IOC_GETFLAGS ioctl was implemented for
FAT, and this was mapped to FS_IMMUTABLE_FL as it is in the kernel,
so that the more common lsattr and chattr commands worked on it, as
they do with ext*, btrfs, xfs, reiserfs, etc.
I guess these aren't problems with the man page per-se, but something
for the FAT developers to think about.
Cheers, Andreas
> +.TP
> +.B ATTR_VOLUME
> +This bit specifies that the file is a volume label.
> +This attribute is read-only.
> +.TP
> +.B ATTR_DIR
> +This bit specifies that this is a directory.
> +This attribute is read-only.
> +.TP
> +.B ATTR_ARCH
> +This bit indicates that this file or directory should be archived.
> +It is set when a file is created or modified.
> +It is reset by an archiving system.
> +.PP
> +The zero value
> +.B ATTR_NONE
> +can be used to indicate that no attribute bit is set.
> +.SS Reading the volume label
> +Fat filesystems are identified by a volume label.
> +The volume label can be read with
> +.BR FAT_IOCTL_GET_VOLUME_ID .
> +.PP
> +The
> +.I fd
> +argument can be a file descriptor for any file or directory of the
> +filesystem.
> +It is sufficient to create the file descriptor by calling
> +.BR open (2)
> +with the
> +.B O_RDONLY
> +flag.
> +.PP
> +The
> +.I id
> +argument is a pointer to the field that will be filled with the volume ID.
> +Typically the volume label is displayed to the user as a group of two
> +16-bit fields.
> +.PP
> +.in +4n
> +.nf
> +printf("Volume ID %4x-%4x\\n", id >> 16, id & 0xFFFF);
> +.fi
> +.in
> +.SS Reading short file names of a directory
> +A file or directory on a FAT filesystem always has a short filename
> +consisting of up to 8 capital letters, optionally followed by a period
> +and up to 3 capital letters for the file extension.
> +If the actual filename does not fit into this scheme, it is stored
> +as a long filename of up to 255 UTF-16 characters.
> +.PP
> +The short filenames in a directory can be read with
> +.BR VFAT_IOCTL_READDIR_SHORT .
> +.B VFAT_IOCTL_READDIR_BOTH
> +reads both the short and the long filenames.
> +.PP
> +The
> +.I fd
> +argument must be a file descriptor for a directory.
> +It is sufficient to create the file descriptor by calling
> +.BR open (2)
> +with the
> +.B O_RDONLY
> +flag.
> +The file descriptor can be only used once to iterate over the directory
> +entries by calling
> +.BR ioctl (2)
> +repeatedly.
> +.PP
> +The
> +.I entry
> +argument is a two-element array of the following structures.
> +
> +.in +4n
> +.nf
> +struct __fat_dirent {
> + long d_ino;
> + __kernel_off_t d_off;
> + uint32_t short d_reclen;
> + char d_name[256];
> +};
> +.fi
> +.in
> +.PP
> +The first entry in the array is for the short filename.
> +The second entry is for the long filename.
> +.PP
> +Field
> +.I d_reclen
> +specifies the length of the filename in field
> +.IR d_name .
> +A length of 0 for the short filename signals that the end of the directory
> +has been reached.
> +.SH RETURN VALUE
> +On error, -1 is returned, and errno is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B ENOTDIR
> +This error is returned by
> +.B VFAT_IOCTL_READDIR_SHORT
> +and
> +.B VFAT_IOCTL_READDIR_SHORT
> +if the file descriptor does not point to a directory.
> +.TP
> +.B ENOTTY
> +This error signals that the file descriptor is not for a FAT filesystem.
> +.PP
> +For further error values see
> +.BR ioctl (2).
> +.SH VERSIONS
> +.B FAT_IOCTL_GET_VOLUME_ID
> +was introduced in version 3.11 of the Linux kernel.
> +.PP
> +.BR FAT_IOCTL_GET_ATTRIBUTES ,
> +.BR FAT_IOCTL_SET_ATTRIBUTES ,
> +.BR VFAT_IOCTL_READDIR_BOTH ,
> +and
> +.B VFAT_IOCTL_READDIR_SHORT
> +were introduced before version 2.6.28 of the Linux kernel.
> +.SH "CONFORMING TO"
> +This API is Linux-specific.
> +.SH EXAMPLE
> +.SS Toggling the archive flag
> +The following program demonstrates the usage of the ioctl API to manipulate
> +file attributes.
> +It reads and displays the archive attribute of a file.
> +After inverting the value of the attribute, it reads and displays it again.
> +.PP
> +The following was recorded when applying the program for the file
> +.IR /mnt/user/foo .
> +.SS Example output
> +.in +4n
> +.nf
> +# ./toggle_archive_flag /mnt/user/foo
> +Archive flag is set
> +Toggling archive flag
> +Archive flag is not set
> +.fi
> +.in
> +.SS Program source
> +.in +4n
> +.nf
> +#include <fcntl.h>
> +#include <linux/msdos_fs.h>
> +#include <stdint.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/ioctl.h>
> +#include <unistd.h>
> +
> +/*
> + * Read file attributes of a file on a FAT filesystem.
> + * Output the state of the archive flag.
> + */
> +static uint32_t
> +readattr(int fd)
> +{
> + uint32_t attr;
> + int ret;
> +
> + ret = ioctl(fd, FAT_IOCTL_GET_ATTRIBUTES, &attr);
> + if (ret == \-1) {
> + perror("ioctl");
> + exit(EXIT_FAILURE);
> + }
> +
> + if (attr & ATTR_ARCH)
> + printf("Archive flag is set\\n");
> + else
> + printf("Archive flag is not set\\n");
> +
> + return attr;
> +}
> +
> +int
> +main(int argc, char *argv[])
> +{
> + uint32_t attr;
> + int fd;
> + int ret;
> +
> + if (argc != 2) {
> + printf("Usage: %s FILENAME\\n", argv[0]);
> + exit(EXIT_FAILURE);
> + }
> +
> + fd = open(argv[1], O_RDONLY);
> + if (fd == \-1) {
> + perror("open");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Read and display the FAT file attributes.
> + */
> + attr = readattr(fd);
> +
> + /*
> + * Invert archive attribute.
> + */
> + printf("Toggling archive flag\\n");
> + attr ^= ATTR_ARCH;
> +
> + /*
> + * Write the changed FAT file attributes.
> + */
> + ret = ioctl(fd, FAT_IOCTL_SET_ATTRIBUTES, &attr);
> + if (ret == \-1) {
> + perror("ioctl");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Read and display the FAT file attributes.
> + */
> + readattr(fd);
> +
> + close(fd);
> +
> + return EXIT_SUCCESS;
> +}
> +.fi
> +.in
> +.SS Reading the volume label
> +The following program demonstrates the usage of the ioctl API to
> +display the volume label of a FAT filesystem.
> +.PP
> +The following output was recorded when applying the program for
> +directory
> +.IR /mnt/user .
> +.SS Example output
> +.in +4n
> +.nf
> +$ ./display_volume_id /mnt/user
> +Volume ID 6443-6241
> +.fi
> +.in
> +.SS Program source
> +.in +4n
> +.nf
> +#include <fcntl.h>
> +#include <linux/msdos_fs.h>
> +#include <stdint.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/ioctl.h>
> +#include <unistd.h>
> +
> +int
> +main(int argc, char *argv[])
> +{
> + uint32_t id;
> + int fd;
> + int ret;
> +
> + if (argc != 2) {
> + printf("Usage: %s FILENAME\\n", argv[0]);
> + exit(EXIT_FAILURE);
> + }
> +
> + fd = open(argv[1], O_RDONLY);
> + if (fd == \-1) {
> + perror("open");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Read volume ID.
> + */
> + ret = ioctl(fd, FAT_IOCTL_GET_VOLUME_ID, &id);
> + if (ret == \-1) {
> + perror("ioctl");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Format the output as two groups of 16 bits each.
> + */
> + printf("Volume ID %4x\-%4x\\n", id >> 16, id & 0xFFFF);
> +
> + close(fd);
> +
> + return EXIT_SUCCESS;
> +}
> +.fi
> +.in
> +.SS Listing a directory
> +The following program demonstrates the usage of the ioctl API to
> +list a directory.
> +.PP
> +The following was recorded when applying the program for the directory
> +.IR /mnt/user .
> +.SS Example output
> +.in +4n
> +.nf
> +$ ./fat_dir /mnt/user
> +\[char46] -> ''
> +\[char46]. -> ''
> +ALONGF~1.TXT -> 'a long filename.txt'
> +UPPER.TXT -> ''
> +LOWER.TXT -> 'lower.txt'
> +.fi
> +.in
> +.SS Program source
> +.in +4n
> +.nf
> +#include <fcntl.h>
> +#include <linux/msdos_fs.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/ioctl.h>
> +#include <unistd.h>
> +
> +int
> +main(int argc, char *argv[])
> +{
> + struct __fat_dirent entry[2];
> + int fd;
> + int ret;
> +
> + if (argc != 2) {
> + printf("Usage: %s DIRECTORY\\n", argv[0]);
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Open file descriptor for the directory.
> + */
> + fd = open(argv[1], O_RDONLY | O_DIRECTORY);
> + if (fd == \-1) {
> + perror("open");
> + exit(EXIT_FAILURE);
> + }
> +
> + for (;;) {
> +
> + /*
> + * Read next directory entry.
> + */
> + ret = ioctl( fd, VFAT_IOCTL_READDIR_BOTH, entry);
> +
> + /*
> + * If an error occurs, the return value is \-1.
> + * If d_reclen is zero, the end of the directory
> + * list has been reached.
> + */
> + if (ret == \-1 || entry[0].d_reclen == 0)
> + break;
> +
> + /*
> + * Write both the short name and the long name.
> + */
> + printf("%s \-> '%s'\\n", entry[0].d_name, entry[1].d_name);
> + }
> + if (ret == \-1) {
> + perror("VFAT_IOCTL_READDIR_BOTH");
> + exit(EXIT_FAILURE);
> + }
> +
> + /*
> + * Close the file descriptor.
> + */
> + close(fd);
> +
> + return EXIT_SUCCESS;
> +}
> +.fi
> +.in
> +.SH SEE ALSO
> +.BR ioctl (2)
> --
> 2.1.4
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
Cheers, Andreas
^ permalink raw reply [flat|nested] 23+ messages in thread