Debian Codegraph @

upstream/debian-trixie/man2/VFAT_IOCTL_READDIR_BOTH.2const

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