man2/ioctl_fat.2

   1 .\" Copyright (C) 2014, Heinrich Schuchardt <xypron.glpk@gmx.de>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of
   9 .\" this manual under the conditions for verbatim copying, provided that
  10 .\" the entire resulting derived work is distributed under the terms of
  11 .\" a permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume
  15 .\" no responsibility for errors or omissions, or for damages resulting
  16 .\" from the use of the information contained herein.  The author(s) may
  17 .\" not have taken the same level of care in the production of this
  18 .\" manual, which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .TH IOCTL_FAT 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 ioctl_fat \- manipulating the FAT filesystem
  27 .SH SYNOPSIS
  28 .nf
  29 .BR "#include <linux/msdos_fs.h>" "     /* Definition of [" V ] FAT_* " and"
  30 .BR "                                   ATTR_* " constants */"
  31 .B #include <sys/ioctl.h>
  32 .PP
  33 .BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t *" attr );
  34 .BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t *" attr );
  35 .BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t *" id );
  36 .BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH,"
  37 .BI "          struct __fat_dirent " entry [2]);
  38 .BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT,"
  39 .BI "          struct __fat_dirent " entry [2]);
  40 .fi
  41 .SH DESCRIPTION
  42 The
  43 .BR ioctl (2)
  44 system call can be used to read and write metadata of FAT filesystems that
  45 are not accessible using other system calls.
  46 .SS Reading and setting file attributes
  47 Files and directories in the FAT filesystem possess an attribute bit mask that
  48 can be read with
  49 .B FAT_IOCTL_GET_ATTRIBUTES
  50 and written with
  51 .BR FAT_IOCTL_SET_ATTRIBUTES .
  52 .PP
  53 The
  54 .I fd
  55 argument contains a file descriptor for a file or directory.
  56 It is sufficient to create the file descriptor by calling
  57 .BR open (2)
  58 with the
  59 .B O_RDONLY
  60 flag.
  61 .PP
  62 The
  63 .I attr
  64 argument contains a pointer to a bit mask.
  65 The bits of the bit mask are:
  66 .TP
  67 .B ATTR_RO
  68 This bit specifies that the file or directory is read-only.
  69 .TP
  70 .B ATTR_HIDDEN
  71 This bit specifies that the file or directory is hidden.
  72 .TP
  73 .B ATTR_SYS
  74 This bit specifies that the file is a system file.
  75 .TP
  76 .B ATTR_VOLUME
  77 This bit specifies that the file is a volume label.
  78 This attribute is read-only.
  79 .TP
  80 .B ATTR_DIR
  81 This bit specifies that this is a directory.
  82 This attribute is read-only.
  83 .TP
  84 .B ATTR_ARCH
  85 This bit indicates that this file or directory should be archived.
  86 It is set when a file is created or modified.
  87 It is reset by an archiving system.
  88 .PP
  89 The zero value
  90 .B ATTR_NONE
  91 can be used to indicate that no attribute bit is set.
  92 .SS Reading the volume ID
  93 FAT filesystems are identified by a volume ID.
  94 The volume ID can be read with
  95 .BR FAT_IOCTL_GET_VOLUME_ID .
  96 .PP
  97 The
  98 .I fd
  99 argument can be a file descriptor for any file or directory of the
 100 filesystem.
 101 It is sufficient to create the file descriptor by calling
 102 .BR open (2)
 103 with the
 104 .B O_RDONLY
 105 flag.
 106 .PP
 107 The
 108 .I id
 109 argument is a pointer to the field that will be filled with the volume ID.
 110 Typically the volume ID is displayed to the user as a group of two
 111 16-bit fields:
 112 .PP
 113 .in +4n
 114 .EX
 115 printf("Volume ID %04x\-%04x\en", id >> 16, id & 0xFFFF);
 116 .EE
 117 .in
 118 .SS Reading short filenames of a directory
 119 A file or directory on a FAT filesystem always has a short filename
 120 consisting of up to 8 capital letters, optionally followed by a period
 121 and up to 3 capital letters for the file extension.
 122 If the actual filename does not fit into this scheme, it is stored
 123 as a long filename of up to 255 UTF-16 characters.
 124 .PP
 125 The short filenames in a directory can be read with
 126 .BR VFAT_IOCTL_READDIR_SHORT .
 127 .B VFAT_IOCTL_READDIR_BOTH
 128 reads both the short and the long filenames.
 129 .PP
 130 The
 131 .I fd
 132 argument must be a file descriptor for a directory.
 133 It is sufficient to create the file descriptor by calling
 134 .BR open (2)
 135 with the
 136 .B O_RDONLY
 137 flag.
 138 The file descriptor can be used only once to iterate over the directory
 139 entries by calling
 140 .BR ioctl (2)
 141 repeatedly.
 142 .PP
 143 The
 144 .I entry
 145 argument is a two-element array of the following structures:
 146 .PP
 147 .in +4n
 148 .EX
 149 struct __fat_dirent {
 150     long            d_ino;
 151     __kernel_off_t  d_off;
 152     uint32_t short  d_reclen;
 153     char            d_name[256];
 154 };
 155 .EE
 156 .in
 157 .PP
 158 The first entry in the array is for the short filename.
 159 The second entry is for the long filename.
 160 .PP
 161 The
 162 .I d_ino
 163 and
 164 .I d_off
 165 fields are filled only for long filenames.
 166 The
 167 .I d_ino
 168 field holds the inode number of the directory.
 169 The
 170 .I d_off
 171 field holds the offset of the file entry in the directory.
 172 As these values are not available for short filenames, the user code should
 173 simply ignore them.
 174 .PP
 175 The field
 176 .I d_reclen
 177 contains the length of the filename in the field
 178 .IR d_name .
 179 To keep backward compatibility, a length of 0 for the short filename signals
 180 that the end of the directory has been reached.
 181 However, the preferred method for detecting the end of the directory
 182 is to test the
 183 .BR ioctl (2)
 184 return value.
 185 If no long filename exists, field
 186 .I d_reclen
 187 is set to 0 and
 188 .I d_name
 189 is a character string of length 0 for the long filename.
 190 .SH RETURN VALUE
 191 On error, \-1 is returned, and
 192 .I errno
 193 is set to indicate the error.
 194 .PP
 195 For
 196 .B VFAT_IOCTL_READDIR_BOTH
 197 and
 198 .B VFAT_IOCTL_READDIR_SHORT
 199 a return value of 1 signals that a new directory entry has been read and
 200 a return value of 0 signals that the end of the directory has been reached.
 201 .SH ERRORS
 202 .TP
 203 .B ENOENT
 204 This error is returned by
 205 .B VFAT_IOCTL_READDIR_BOTH
 206 and
 207 .B VFAT_IOCTL_READDIR_SHORT
 208 if the file descriptor
 209 .I fd
 210 refers to a removed, but still open directory.
 211 .TP
 212 .B ENOTDIR
 213 This error is returned by
 214 .B VFAT_IOCTL_READDIR_BOTH
 215 and
 216 .B VFAT_IOCTL_READDIR_SHORT
 217 if the file descriptor
 218 .I fd
 219 does not refer to a directory.
 220 .TP
 221 .B ENOTTY
 222 The file descriptor
 223 .I fd
 224 does not refer to an object in a FAT filesystem.
 225 .PP
 226 For further error values, see
 227 .BR ioctl (2).
 228 .SH VERSIONS
 229 .BR VFAT_IOCTL_READDIR_BOTH
 230 and
 231 .B VFAT_IOCTL_READDIR_SHORT
 232 first appeared in Linux 2.0.
 233 .PP
 234 .BR FAT_IOCTL_GET_ATTRIBUTES
 235 and
 236 .BR FAT_IOCTL_SET_ATTRIBUTES
 237 first appeared
 238 .\" just before we got Git history
 239 in Linux 2.6.12.
 240 .PP
 241 .B FAT_IOCTL_GET_VOLUME_ID
 242 was introduced in version 3.11
 243 .\" commit 6e5b93ee55d401f1619092fb675b57c28c9ed7ec
 244 of the Linux kernel.
 245 .SH CONFORMING TO
 246 This API is Linux-specific.
 247 .SH EXAMPLES
 248 .SS Toggling the archive flag
 249 The following program demonstrates the usage of
 250 .BR ioctl (2)
 251 to manipulate file attributes.
 252 The program reads and displays the archive attribute of a file.
 253 After inverting the value of the attribute,
 254 the program reads and displays the attribute again.
 255 .PP
 256 The following was recorded when applying the program for the file
 257 .IR /mnt/user/foo :
 258 .PP
 259 .in +4n
 260 .EX
 261 # ./toggle_fat_archive_flag /mnt/user/foo
 262 Archive flag is set
 263 Toggling archive flag
 264 Archive flag is not set
 265 .EE
 266 .in
 267 .SS Program source (toggle_fat_archive_flag.c)
 268 \&
 269 .EX
 270 #include <fcntl.h>
 271 #include <linux/msdos_fs.h>
 272 #include <stdint.h>
 273 #include <stdio.h>
 274 #include <stdlib.h>
 275 #include <sys/ioctl.h>
 276 #include <unistd.h>
 277
 278 /*
 279  * Read file attributes of a file on a FAT filesystem.
 280  * Output the state of the archive flag.
 281  */
 282 static uint32_t
 283 readattr(int fd)
 284 {
 285     uint32_t attr;
 286     int ret;
 287
 288     ret = ioctl(fd, FAT_IOCTL_GET_ATTRIBUTES, &attr);
 289     if (ret == \-1) {
 290         perror("ioctl");
 291         exit(EXIT_FAILURE);
 292     }
 293
 294     if (attr & ATTR_ARCH)
 295         printf("Archive flag is set\en");
 296     else
 297         printf("Archive flag is not set\en");
 298
 299     return attr;
 300 }
 301
 302 int
 303 main(int argc, char *argv[])
 304 {
 305     uint32_t attr;
 306     int fd;
 307     int ret;
 308
 309     if (argc != 2) {
 310         printf("Usage: %s FILENAME\en", argv[0]);
 311         exit(EXIT_FAILURE);
 312     }
 313
 314     fd = open(argv[1], O_RDONLY);
 315     if (fd == \-1) {
 316         perror("open");
 317         exit(EXIT_FAILURE);
 318     }
 319
 320     /*
 321      * Read and display the FAT file attributes.
 322      */
 323     attr = readattr(fd);
 324
 325     /*
 326      * Invert archive attribute.
 327      */
 328     printf("Toggling archive flag\en");
 329     attr \(ha= ATTR_ARCH;
 330
 331     /*
 332      * Write the changed FAT file attributes.
 333      */
 334     ret = ioctl(fd, FAT_IOCTL_SET_ATTRIBUTES, &attr);
 335     if (ret == \-1) {
 336         perror("ioctl");
 337         exit(EXIT_FAILURE);
 338     }
 339
 340     /*
 341      * Read and display the FAT file attributes.
 342      */
 343     readattr(fd);
 344
 345     close(fd);
 346
 347     exit(EXIT_SUCCESS);
 348 }
 349 .EE
 350 .\"
 351 .SS Reading the volume ID
 352 The following program demonstrates the use of
 353 .BR ioctl (2)
 354 to display the volume ID of a FAT filesystem.
 355 .PP
 356 The following output was recorded when applying the program for
 357 directory
 358 .IR /mnt/user :
 359 .PP
 360 .in +4n
 361 .EX
 362 $ ./display_fat_volume_id /mnt/user
 363 Volume ID 6443\-6241
 364 .EE
 365 .in
 366 .SS Program source (display_fat_volume_id.c)
 367 \&
 368 .EX
 369 #include <fcntl.h>
 370 #include <linux/msdos_fs.h>
 371 #include <stdint.h>
 372 #include <stdio.h>
 373 #include <stdlib.h>
 374 #include <sys/ioctl.h>
 375 #include <unistd.h>
 376
 377 int
 378 main(int argc, char *argv[])
 379 {
 380     uint32_t id;
 381     int fd;
 382     int ret;
 383
 384     if (argc != 2) {
 385         printf("Usage: %s FILENAME\en", argv[0]);
 386         exit(EXIT_FAILURE);
 387     }
 388
 389     fd = open(argv[1], O_RDONLY);
 390     if (fd == \-1) {
 391         perror("open");
 392         exit(EXIT_FAILURE);
 393     }
 394
 395     /*
 396      * Read volume ID.
 397      */
 398     ret = ioctl(fd, FAT_IOCTL_GET_VOLUME_ID, &id);
 399     if (ret == \-1) {
 400         perror("ioctl");
 401         exit(EXIT_FAILURE);
 402     }
 403
 404     /*
 405      * Format the output as two groups of 16 bits each.
 406      */
 407     printf("Volume ID %04x\-%04x\en", id >> 16, id & 0xFFFF);
 408
 409     close(fd);
 410
 411     exit(EXIT_SUCCESS);
 412 }
 413 .EE
 414 .\"
 415 .SS Listing a directory
 416 The following program demonstrates the use of
 417 .BR ioctl (2)
 418 to list a directory.
 419 .PP
 420 The following was recorded when applying the program to the directory
 421 .IR /mnt/user :
 422 .PP
 423 .in +4n
 424 .EX
 425 $ \fB./fat_dir /mnt/user\fP
 426 \[char46] \-> \(aq\(aq
 427 \[char46]. \-> \(aq\(aq
 428 ALONGF\(ti1.TXT \-> \(aqa long filename.txt\(aq
 429 UPPER.TXT \-> \(aq\(aq
 430 LOWER.TXT \-> \(aqlower.txt\(aq
 431 .EE
 432 .in
 433 .\"
 434 .SS Program source
 435 .in +4n
 436 .EX
 437 #include <fcntl.h>
 438 #include <linux/msdos_fs.h>
 439 #include <stdio.h>
 440 #include <stdlib.h>
 441 #include <sys/ioctl.h>
 442 #include <unistd.h>
 443
 444 int
 445 main(int argc, char *argv[])
 446 {
 447     struct __fat_dirent entry[2];
 448     int fd;
 449     int ret;
 450
 451     if (argc != 2) {
 452         printf("Usage: %s DIRECTORY\en", argv[0]);
 453         exit(EXIT_FAILURE);
 454     }
 455
 456     /*
 457      * Open file descriptor for the directory.
 458      */
 459     fd = open(argv[1], O_RDONLY | O_DIRECTORY);
 460     if (fd == \-1) {
 461         perror("open");
 462         exit(EXIT_FAILURE);
 463     }
 464
 465     for (;;) {
 466
 467         /*
 468          * Read next directory entry.
 469          */
 470         ret = ioctl( fd, VFAT_IOCTL_READDIR_BOTH, entry);
 471
 472         /*
 473          * If an error occurs, the return value is \-1.
 474          * If the end of the directory list has been reached,
 475          * the return value is 0.
 476          * For backward compatibility the end of the directory
 477          * list is also signaled by d_reclen == 0.
 478          */
 479         if (ret < 1)
 480             break;
 481
 482         /*
 483          * Write both the short name and the long name.
 484          */
 485         printf("%s \-> \(aq%s\(aq\en", entry[0].d_name, entry[1].d_name);
 486     }
 487
 488     if (ret == \-1) {
 489         perror("VFAT_IOCTL_READDIR_BOTH");
 490         exit(EXIT_FAILURE);
 491     }
 492
 493     /*
 494      * Close the file descriptor.
 495      */
 496     close(fd);
 497
 498     exit(EXIT_SUCCESS);
 499 }
 500 .EE
 501 .in
 502 .SH SEE ALSO
 503 .BR ioctl (2)