Hello Heinrich and Ogawa,
On 23 January 2015 at 20:54, Heinrich Schuchardt <[email protected]> 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 [email protected] and
> [email protected] for review.
>
> version 3: correct typos
> version 2: consider comments by Michael Kerrisk
> verison 1: original patch
>
> Signed-by: Heinrich Schuchardt <[email protected]>
> ---
> 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 <[email protected]>
> +.\"
> +.\" %%%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/
"Michael Kerrisk (man-pages)" <[email protected]> writes:
> Hello Heinrich and Ogawa,
Hi,
> On 23 January 2015 at 20:54, Heinrich Schuchardt <[email protected]> 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 <[email protected]>
Hello Hirofumi,
Thanks for checking the page over.
On 3 February 2015 at 09:51, OGAWA Hirofumi <[email protected]> wrote:
> "Michael Kerrisk (man-pages)" <[email protected]> writes:
>
>> Hello Heinrich and Ogawa,
>
> Hi,
>
>> On 23 January 2015 at 20:54, Heinrich Schuchardt <[email protected]> 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/
"Michael Kerrisk (man-pages)" <[email protected]> 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 <[email protected]>
Hello Hirofumi,
On 3 February 2015 at 10:44, OGAWA Hirofumi <[email protected]> wrote:
> "Michael Kerrisk (man-pages)" <[email protected]> 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/
"Michael Kerrisk (man-pages)" <[email protected]> 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 <[email protected]>