| 1 |
.\" Copyright, the authors of the Linux man-pages project |
| 2 |
.\" |
| 3 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 4 |
.\" |
| 5 |
.TH VFAT_IOCTL_READDIR_BOTH 2const 2025-09-21 "Linux man-pages 6.18" |
| 6 |
.SH NAME |
| 7 |
VFAT_IOCTL_READDIR_BOTH, |
| 8 |
VFAT_IOCTL_READDIR_SHORT |
| 9 |
\- |
| 10 |
read filenames of a directory in a FAT filesystem |
| 11 |
.SH LIBRARY |
| 12 |
Standard C library |
| 13 |
.RI ( libc ,\~ \-lc ) |
| 14 |
.SH SYNOPSIS |
| 15 |
.nf |
| 16 |
.BR "#include <linux/msdos_fs.h>" " /* Definition of " VFAT_* " constants */" |
| 17 |
.B #include <sys/ioctl.h> |
| 18 |
.P |
| 19 |
.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH," |
| 20 |
.BI " struct __fat_dirent " entry [2]); |
| 21 |
.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT," |
| 22 |
.BI " struct __fat_dirent " entry [2]); |
| 23 |
.fi |
| 24 |
.SH DESCRIPTION |
| 25 |
A file or directory on a FAT filesystem always has a short filename |
| 26 |
consisting of up to 8 capital letters, optionally followed by a period |
| 27 |
and up to 3 capital letters for the file extension. |
| 28 |
If the actual filename does not fit into this scheme, it is stored |
| 29 |
as a long filename of up to 255 UTF-16 characters. |
| 30 |
.P |
| 31 |
The short filenames in a directory can be read with |
| 32 |
.BR VFAT_IOCTL_READDIR_SHORT . |
| 33 |
.B VFAT_IOCTL_READDIR_BOTH |
| 34 |
reads both the short and the long filenames. |
| 35 |
.P |
| 36 |
The |
| 37 |
.I fd |
| 38 |
argument must be a file descriptor for a directory. |
| 39 |
It is sufficient to create the file descriptor by calling |
| 40 |
.BR open (2) |
| 41 |
with the |
| 42 |
.B O_RDONLY |
| 43 |
flag. |
| 44 |
The file descriptor can be used only once to iterate over the directory |
| 45 |
entries by calling |
| 46 |
.BR ioctl (2) |
| 47 |
repeatedly. |
| 48 |
.P |
| 49 |
The |
| 50 |
.I entry |
| 51 |
argument is a two-element array of the following structures: |
| 52 |
.P |
| 53 |
.in +4n |
| 54 |
.EX |
| 55 |
struct __fat_dirent { |
| 56 |
long d_ino; |
| 57 |
__kernel_off_t d_off; |
| 58 |
uint32_t short d_reclen; |
| 59 |
char d_name[256]; |
| 60 |
}; |
| 61 |
.EE |
| 62 |
.in |
| 63 |
.P |
| 64 |
The first entry in the array is for the short filename. |
| 65 |
The second entry is for the long filename. |
| 66 |
.P |
| 67 |
The |
| 68 |
.I d_ino |
| 69 |
and |
| 70 |
.I d_off |
| 71 |
fields are filled only for long filenames. |
| 72 |
The |
| 73 |
.I d_ino |
| 74 |
field holds the inode number of the directory. |
| 75 |
The |
| 76 |
.I d_off |
| 77 |
field holds the offset of the file entry in the directory. |
| 78 |
As these values are not available for short filenames, the user code should |
| 79 |
simply ignore them. |
| 80 |
.P |
| 81 |
The field |
| 82 |
.I d_reclen |
| 83 |
contains the length of the filename in the field |
| 84 |
.IR d_name . |
| 85 |
To keep backward compatibility, a length of 0 for the short filename signals |
| 86 |
that the end of the directory has been reached. |
| 87 |
However, the preferred method for detecting the end of the directory |
| 88 |
is to test the |
| 89 |
.BR ioctl (2) |
| 90 |
return value. |
| 91 |
If no long filename exists, field |
| 92 |
.I d_reclen |
| 93 |
is set to 0 and |
| 94 |
.I d_name |
| 95 |
is a character string of length 0 for the long filename. |
| 96 |
.SH RETURN VALUE |
| 97 |
A return value of 1 signals that a new directory entry has been read and |
| 98 |
a return value of 0 signals that the end of the directory has been reached. |
| 99 |
.P |
| 100 |
On error, \-1 is returned, and |
| 101 |
.I errno |
| 102 |
is set to indicate the error. |
| 103 |
.SH ERRORS |
| 104 |
.TP |
| 105 |
.B ENOENT |
| 106 |
.I fd |
| 107 |
refers to a removed, but still open directory. |
| 108 |
.TP |
| 109 |
.B ENOTDIR |
| 110 |
.I fd |
| 111 |
does not refer to a directory. |
| 112 |
.SH STANDARDS |
| 113 |
Linux. |
| 114 |
.SH HISTORY |
| 115 |
Linux 2.0. |
| 116 |
.SH EXAMPLES |
| 117 |
The following program demonstrates the use of |
| 118 |
.BR ioctl (2) |
| 119 |
to list a directory. |
| 120 |
.P |
| 121 |
The following was recorded when applying the program to the directory |
| 122 |
.IR /mnt/user : |
| 123 |
.P |
| 124 |
.in +4n |
| 125 |
.EX |
| 126 |
.RB $ " ./fat_dir /mnt/user" ; |
| 127 |
\&.\& \-> \[aq]\[aq] |
| 128 |
\&..\& \-> \[aq]\[aq] |
| 129 |
ALONGF\[ti]1.TXT \-> \[aq]a long filename.txt\[aq] |
| 130 |
UPPER.TXT \-> \[aq]\[aq] |
| 131 |
LOWER.TXT \-> \[aq]lower.txt\[aq] |
| 132 |
.EE |
| 133 |
.in |
| 134 |
.\" |
| 135 |
.SS Program source |
| 136 |
.\" SRC BEGIN (ioctl_fat.c) |
| 137 |
.EX |
| 138 |
#include <fcntl.h> |
| 139 |
#include <linux/msdos_fs.h> |
| 140 |
#include <stdio.h> |
| 141 |
#include <stdlib.h> |
| 142 |
#include <sys/ioctl.h> |
| 143 |
#include <unistd.h> |
| 144 |
\& |
| 145 |
int |
| 146 |
main(int argc, char *argv[]) |
| 147 |
{ |
| 148 |
int fd; |
| 149 |
int ret; |
| 150 |
struct __fat_dirent entry[2]; |
| 151 |
\& |
| 152 |
if (argc != 2) { |
| 153 |
printf("Usage: %s DIRECTORY\[rs]n", argv[0]); |
| 154 |
exit(EXIT_FAILURE); |
| 155 |
} |
| 156 |
\& |
| 157 |
/* |
| 158 |
* Open file descriptor for the directory. |
| 159 |
*/ |
| 160 |
fd = open(argv[1], O_RDONLY | O_DIRECTORY); |
| 161 |
if (fd == \-1) { |
| 162 |
perror("open"); |
| 163 |
exit(EXIT_FAILURE); |
| 164 |
} |
| 165 |
\& |
| 166 |
for (;;) { |
| 167 |
\& |
| 168 |
/* |
| 169 |
* Read next directory entry. |
| 170 |
*/ |
| 171 |
ret = ioctl(fd, VFAT_IOCTL_READDIR_BOTH, entry); |
| 172 |
\& |
| 173 |
/* |
| 174 |
* If an error occurs, the return value is \-1. |
| 175 |
* If the end of the directory list has been reached, |
| 176 |
* the return value is 0. |
| 177 |
* For backward compatibility the end of the directory |
| 178 |
* list is also signaled by d_reclen == 0. |
| 179 |
*/ |
| 180 |
if (ret < 1) |
| 181 |
break; |
| 182 |
\& |
| 183 |
/* |
| 184 |
* Write both the short name and the long name. |
| 185 |
*/ |
| 186 |
printf("%s \-> \[aq]%s\[aq]\[rs]n", entry[0].d_name, entry[1].d_name); |
| 187 |
} |
| 188 |
\& |
| 189 |
if (ret == \-1) { |
| 190 |
perror("VFAT_IOCTL_READDIR_BOTH"); |
| 191 |
exit(EXIT_FAILURE); |
| 192 |
} |
| 193 |
\& |
| 194 |
/* |
| 195 |
* Close the file descriptor. |
| 196 |
*/ |
| 197 |
close(fd); |
| 198 |
\& |
| 199 |
exit(EXIT_SUCCESS); |
| 200 |
} |
| 201 |
.EE |
| 202 |
.\" SRC END |
| 203 |
.SH SEE ALSO |
| 204 |
.BR ioctl (2), |
| 205 |
.BR ioctl_fat (2) |