]>
Commit | Line | Data |
---|---|---|
28f540f4 | 1 | @node File System Interface, Pipes and FIFOs, Low-Level I/O, Top |
7a68c94a | 2 | @c %MENU% Functions for manipulating files |
28f540f4 RM |
3 | @chapter File System Interface |
4 | ||
1f77f049 | 5 | This chapter describes @theglibc{}'s functions for manipulating |
8b7fb588 UD |
6 | files. Unlike the input and output functions (@pxref{I/O on Streams}; |
7 | @pxref{Low-Level I/O}), these functions are concerned with operating | |
04b9968b | 8 | on the files themselves rather than on their contents. |
28f540f4 RM |
9 | |
10 | Among the facilities described in this chapter are functions for | |
11 | examining or modifying directories, functions for renaming and deleting | |
12 | files, and functions for examining and setting file attributes such as | |
13 | access permissions and modification times. | |
14 | ||
15 | @menu | |
16 | * Working Directory:: This is used to resolve relative | |
17 | file names. | |
3de73f97 | 18 | * Descriptor-Relative Access:: Ways to control file name lookup. |
28f540f4 RM |
19 | * Accessing Directories:: Finding out what files a directory |
20 | contains. | |
d01d6319 | 21 | * Working with Directory Trees:: Apply actions to all files or a selectable |
f2ea0f5b | 22 | subset of a directory hierarchy. |
28f540f4 RM |
23 | * Hard Links:: Adding alternate names to a file. |
24 | * Symbolic Links:: A file that ``points to'' a file name. | |
25 | * Deleting Files:: How to delete a file, and what that means. | |
26 | * Renaming Files:: Changing a file's name. | |
27 | * Creating Directories:: A system call just for creating a directory. | |
28 | * File Attributes:: Attributes of individual files. | |
29 | * Making Special Files:: How to create special files. | |
30 | * Temporary Files:: Naming and creating temporary files. | |
31 | @end menu | |
32 | ||
33 | @node Working Directory | |
34 | @section Working Directory | |
35 | ||
36 | @cindex current working directory | |
37 | @cindex working directory | |
38 | @cindex change working directory | |
39 | Each process has associated with it a directory, called its @dfn{current | |
40 | working directory} or simply @dfn{working directory}, that is used in | |
41 | the resolution of relative file names (@pxref{File Name Resolution}). | |
42 | ||
43 | When you log in and begin a new session, your working directory is | |
44 | initially set to the home directory associated with your login account | |
45 | in the system user database. You can find any user's home directory | |
46 | using the @code{getpwuid} or @code{getpwnam} functions; see @ref{User | |
47 | Database}. | |
48 | ||
49 | Users can change the working directory using shell commands like | |
50 | @code{cd}. The functions described in this section are the primitives | |
51 | used by those commands and by other programs for examining and changing | |
52 | the working directory. | |
53 | @pindex cd | |
54 | ||
55 | Prototypes for these functions are declared in the header file | |
56 | @file{unistd.h}. | |
57 | @pindex unistd.h | |
58 | ||
28f540f4 | 59 | @deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size}) |
d08a7e4c | 60 | @standards{POSIX.1, unistd.h} |
de55fdf4 AO |
61 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
62 | @c If buffer is NULL, this function calls malloc and realloc, and, in | |
63 | @c case of error, free. Linux offers a getcwd syscall that we use on | |
64 | @c GNU/Linux systems, but it may fail if the pathname is too long. As a | |
65 | @c fallback, and on other systems, the generic implementation opens each | |
66 | @c parent directory with opendir, which allocates memory for the | |
67 | @c directory stream with malloc. If a fstatat64 syscall is not | |
68 | @c available, very deep directory trees may also have to malloc to build | |
69 | @c longer sequences of ../../../... than those supported by a global | |
70 | @c const read-only string. | |
71 | ||
72 | @c linux/__getcwd | |
73 | @c posix/__getcwd | |
74 | @c malloc/realloc/free if buffer is NULL, or if dir is too deep | |
75 | @c lstat64 -> see its own entry | |
76 | @c fstatat64 | |
77 | @c direct syscall if possible, alloca+snprintf+*stat64 otherwise | |
78 | @c openat64_not_cancel_3, close_not_cancel_no_status | |
79 | @c __fdopendir, __opendir, __readdir, rewinddir | |
28f540f4 RM |
80 | The @code{getcwd} function returns an absolute file name representing |
81 | the current working directory, storing it in the character array | |
82 | @var{buffer} that you provide. The @var{size} argument is how you tell | |
83 | the system the allocation size of @var{buffer}. | |
84 | ||
1f77f049 | 85 | The @glibcadj{} version of this function also permits you to specify a |
28f540f4 RM |
86 | null pointer for the @var{buffer} argument. Then @code{getcwd} |
87 | allocates a buffer automatically, as with @code{malloc} | |
88 | (@pxref{Unconstrained Allocation}). If the @var{size} is greater than | |
89 | zero, then the buffer is that large; otherwise, the buffer is as large | |
90 | as necessary to hold the result. | |
91 | ||
92 | The return value is @var{buffer} on success and a null pointer on failure. | |
93 | The following @code{errno} error conditions are defined for this function: | |
94 | ||
95 | @table @code | |
96 | @item EINVAL | |
97 | The @var{size} argument is zero and @var{buffer} is not a null pointer. | |
98 | ||
99 | @item ERANGE | |
100 | The @var{size} argument is less than the length of the working directory | |
101 | name. You need to allocate a bigger array and try again. | |
102 | ||
103 | @item EACCES | |
104 | Permission to read or search a component of the file name was denied. | |
105 | @end table | |
106 | @end deftypefun | |
107 | ||
9afc8a59 UD |
108 | You could implement the behavior of GNU's @w{@code{getcwd (NULL, 0)}} |
109 | using only the standard behavior of @code{getcwd}: | |
28f540f4 RM |
110 | |
111 | @smallexample | |
112 | char * | |
d1d62b53 | 113 | gnu_getcwd () |
28f540f4 | 114 | @{ |
d1d62b53 AJ |
115 | size_t size = 100; |
116 | ||
28f540f4 RM |
117 | while (1) |
118 | @{ | |
e8b1163e | 119 | char *buffer = (char *) xmalloc (size); |
d1d62b53 | 120 | if (getcwd (buffer, size) == buffer) |
60ab36c1 | 121 | return buffer; |
28f540f4 | 122 | free (buffer); |
e8b1163e | 123 | if (errno != ERANGE) |
d1d62b53 | 124 | return 0; |
e8b1163e | 125 | size *= 2; |
28f540f4 RM |
126 | @} |
127 | @} | |
128 | @end smallexample | |
129 | ||
130 | @noindent | |
131 | @xref{Malloc Examples}, for information about @code{xmalloc}, which is | |
132 | not a library function but is a customary name used in most GNU | |
133 | software. | |
134 | ||
cb4fe8a2 | 135 | @deftypefn {Deprecated Function} {char *} getwd (char *@var{buffer}) |
d08a7e4c | 136 | @standards{BSD, unistd.h} |
de55fdf4 AO |
137 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{} @acsfd{}}} |
138 | @c Besides the getcwd safety issues, it calls strerror_r on error, which | |
139 | @c brings in all of the i18n issues. | |
28f540f4 | 140 | This is similar to @code{getcwd}, but has no way to specify the size of |
1f77f049 | 141 | the buffer. @Theglibc{} provides @code{getwd} only |
28f540f4 RM |
142 | for backwards compatibility with BSD. |
143 | ||
144 | The @var{buffer} argument should be a pointer to an array at least | |
a7a93d50 JM |
145 | @code{PATH_MAX} bytes long (@pxref{Limits for Files}). On @gnuhurdsystems{} |
146 | there is no limit to the size of a file name, so this is not | |
28f540f4 RM |
147 | necessarily enough space to contain the directory name. That is why |
148 | this function is deprecated. | |
cb4fe8a2 UD |
149 | @end deftypefn |
150 | ||
7d15ef84 | 151 | @vindex PWD |
cb4fe8a2 | 152 | @deftypefun {char *} get_current_dir_name (void) |
d08a7e4c | 153 | @standards{GNU, unistd.h} |
de55fdf4 AO |
154 | @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
155 | @c Besides getcwd, which this function calls as a fallback, it calls | |
156 | @c getenv, with the potential thread-safety issues that brings about. | |
7d15ef84 RJ |
157 | The @code{get_current_dir_name} function is basically equivalent to |
158 | @w{@code{getcwd (NULL, 0)}}, except the value of the @env{PWD} | |
159 | environment variable is first examined, and if it does in fact | |
160 | correspond to the current directory, that value is returned. This is | |
161 | a subtle difference which is visible if the path described by the | |
162 | value in @env{PWD} is using one or more symbolic links, in which case | |
163 | the value returned by @code{getcwd} would resolve the symbolic links | |
164 | and therefore yield a different result. | |
cb4fe8a2 UD |
165 | |
166 | This function is a GNU extension. | |
28f540f4 RM |
167 | @end deftypefun |
168 | ||
28f540f4 | 169 | @deftypefun int chdir (const char *@var{filename}) |
d08a7e4c | 170 | @standards{POSIX.1, unistd.h} |
de55fdf4 | 171 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
172 | This function is used to set the process's working directory to |
173 | @var{filename}. | |
174 | ||
175 | The normal, successful return value from @code{chdir} is @code{0}. A | |
176 | value of @code{-1} is returned to indicate an error. The @code{errno} | |
177 | error conditions defined for this function are the usual file name | |
178 | syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the | |
179 | file @var{filename} is not a directory. | |
180 | @end deftypefun | |
181 | ||
e4cf5229 | 182 | @deftypefun int fchdir (int @var{filedes}) |
d08a7e4c | 183 | @standards{XPG, unistd.h} |
de55fdf4 | 184 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
e4cf5229 UD |
185 | This function is used to set the process's working directory to |
186 | directory associated with the file descriptor @var{filedes}. | |
187 | ||
188 | The normal, successful return value from @code{fchdir} is @code{0}. A | |
189 | value of @code{-1} is returned to indicate an error. The following | |
190 | @code{errno} error conditions are defined for this function: | |
191 | ||
192 | @table @code | |
193 | @item EACCES | |
194 | Read permission is denied for the directory named by @code{dirname}. | |
195 | ||
196 | @item EBADF | |
197 | The @var{filedes} argument is not a valid file descriptor. | |
198 | ||
199 | @item ENOTDIR | |
200 | The file descriptor @var{filedes} is not associated with a directory. | |
201 | ||
202 | @item EINTR | |
203 | The function call was interrupt by a signal. | |
204 | ||
205 | @item EIO | |
206 | An I/O error occurred. | |
207 | @end table | |
208 | @end deftypefun | |
209 | ||
3de73f97 FW |
210 | @node Descriptor-Relative Access |
211 | @section Descriptor-Relative Access | |
212 | @cindex file name resolution based on descriptors | |
213 | @cindex descriptor-based file name resolution | |
214 | @cindex @code{@dots{}at} functions | |
215 | ||
216 | Many functions that accept file names have @code{@dots{}at} variants | |
217 | which accept a file descriptor and a file name argument instead of just | |
218 | a file name argument. For example, @code{fstatat} is the | |
219 | descriptor-based variant of the @code{fstat} function. Most such | |
220 | functions also accept an additional flags argument which changes the | |
221 | behavior of the file name lookup based on the passed @code{AT_@dots{}} | |
222 | flags. | |
223 | ||
224 | There are several reasons to use descriptor-relative access: | |
225 | ||
226 | @itemize @bullet | |
227 | @item | |
228 | The working directory is a process-wide resource, so individual threads | |
229 | cannot change it without affecting other threads in the process. | |
230 | Explicitly specifying the directory against which relative paths are | |
231 | resolved can be a thread-safe alternative to changing the working | |
232 | directory. | |
233 | ||
234 | @item | |
235 | If a program wishes to access a directory tree which is being modified | |
236 | concurrently, perhaps even by a different user on the system, the | |
237 | program must avoid looking up file names with multiple components, in | |
238 | order to detect symbolic links, using the @code{O_NOFOLLOW} flag | |
239 | (@pxref{Open-time Flags}) or the @code{AT_SYMLINK_FOLLOW} flag | |
240 | (described below). Without directory-relative access, it is necessary | |
241 | to use the @code{fchdir} function to change the working directory | |
242 | (@pxref{Working Directory}), which is not thread-safe. | |
243 | ||
244 | @item | |
245 | Listing directory contents using the @code{readdir} or @code{readdir64} | |
246 | functions (@pxref{Reading/Closing Directory}) does not provide full file | |
247 | name paths. Using @code{@dots{}at} functions, it is possible to use the | |
248 | file names directly, without having to construct such full paths. | |
249 | ||
250 | @item | |
251 | Additional flags available with some of the @code{@dots{}at} functions | |
252 | provide access to functionality which is not available otherwise. | |
253 | @end itemize | |
254 | ||
255 | The file descriptor used by these @code{@dots{}at} functions has the | |
256 | following uses: | |
257 | ||
258 | @itemize @bullet | |
259 | @item | |
260 | It can be a file descriptor referring to a directory. Such a descriptor | |
261 | can be created explicitly using the @code{open} function and the | |
262 | @code{O_RDONLY} file access mode, with or without the @code{O_DIRECTORY} | |
263 | flag. @xref{Opening and Closing Files}. Or it can be created | |
264 | implicitly by @code{opendir} and retrieved using the @code{dirfd} | |
265 | function. @xref{Opening a Directory}. | |
266 | ||
267 | If a directory descriptor is used with one of the @code{@dots{}at} | |
268 | functions, a relative file name argument is resolved relative to | |
269 | directory referred to by the file descriptor, just as if that directory | |
270 | were the current working directory. Absolute file name arguments | |
271 | (starting with @samp{/}) are resolved against the file system root, and | |
272 | the descriptor argument is effectively ignored. | |
273 | ||
274 | This means that file name lookup is not constrained to the directory of | |
275 | the descriptor. For example, it is possible to access a file | |
276 | @file{example} in the descriptor's parent directory using a file name | |
277 | argument @code{"../example"}, or in the root directory using | |
278 | @code{"/example"}. | |
279 | ||
280 | If the file descriptor refers to a directory, the empty string @code{""} | |
281 | is not a valid file name argument. It is possible to use @code{"."} to | |
282 | refer to the directory itself. Also see @code{AT_EMPTY_PATH} below. | |
283 | ||
284 | @item | |
285 | @vindex @code{AT_FDCWD} | |
286 | The special value @code{AT_FDCWD}. This means that the current working | |
287 | directory is used for the lookup if the file name is a relative. For | |
288 | @code{@dots{}at} functions with an @code{AT_@dots{}} flags argument, | |
289 | this provides a shortcut to use those flags with regular (not | |
290 | descriptor-based) file name lookups. | |
291 | ||
292 | If @code{AT_FDCWD} is used, the empty string @code{""} is not a valid | |
293 | file name argument. | |
294 | ||
295 | @item | |
296 | An arbitrary file descriptor, along with an empty string @code{""} as | |
297 | the file name argument, and the @code{AT_EMPTY_PATH} flag. In this | |
298 | case, the operation uses the file descriptor directly, without further | |
299 | file name resolution. On Linux, this allows operations on descriptors | |
300 | opened with the @code{O_PATH} flag. For regular descriptors (opened | |
301 | without @code{O_PATH}), the same functionality is also available through | |
302 | the plain descriptor-based functions (for example, @code{fstat} instead | |
303 | of @code{fstatat}). | |
304 | ||
305 | This is a GNU extension. | |
306 | @end itemize | |
307 | ||
308 | @cindex file name resolution flags | |
309 | @cindex @code{AT_*} file name resolution flags | |
310 | The flags argument in @code{@dots{}at} functions can be a combination of | |
311 | the following flags, defined in @file{fcntl.h}. Not all such functions | |
312 | support all flags, and some (such as @code{openat}) do not accept a | |
313 | flags argument at all. | |
314 | ||
315 | In the flag descriptions below, the @dfn{effective final path component} | |
316 | refers to the final component (basename) of the full path constructed | |
317 | from the descriptor and file name arguments, using file name lookup, as | |
318 | described above. | |
319 | ||
320 | @vtable @code | |
321 | @item AT_EMPTY_PATH | |
322 | This flag is used with an empty file name @code{""} and a descriptor | |
323 | which does not necessarily refer to a directory. It is most useful with | |
324 | @code{O_PATH} descriptors, as described above. This flag is a GNU | |
325 | extension. | |
326 | ||
327 | @item AT_NO_AUTOMOUNT | |
328 | If the effective final path component refers to a potential file system | |
329 | mount point controlled by an auto-mounting service, the operation does | |
330 | not trigger auto-mounting and refers to the unmounted mount point | |
331 | instead. @xref{Mount-Unmount-Remount}. If a file system has already | |
332 | been mounted at the effective final path component, the operation | |
333 | applies to the file or directory in the mounted file system, not the | |
334 | underlying file system that was mounted over. This flag is a GNU | |
335 | extension. | |
336 | ||
337 | @item AT_SYMLINK_FOLLOW | |
338 | If the effective final path component is a symbolic link, the | |
339 | operation follows the symbolic link and operates on its target. (For | |
340 | most functions, this is the default behavior.) | |
341 | ||
342 | @item AT_SYMLINK_NOFOLLOW | |
343 | If the effective final path component is a symbolic link, the | |
344 | operation operates on the symbolic link, without following it. The | |
345 | difference in behavior enabled by this flag is similar to the difference | |
346 | between the @code{lstat} and @code{stat} functions, or the behavior | |
347 | activated by the @code{O_NOFOLLOW} argument to the @code{open} function. | |
348 | Even with the @code{AT_SYMLINK_NOFOLLOW} flag present, symbolic links in | |
349 | a non-final component of the file name are still followed. | |
350 | @end vtable | |
351 | ||
352 | @strong{Note:} There is no relationship between these flags and the type | |
353 | argument to the @code{getauxval} function (with @code{AT_@dots{}} | |
354 | constants defined in @file{elf.h}). @xref{Auxiliary Vector}. | |
28f540f4 RM |
355 | |
356 | @node Accessing Directories | |
357 | @section Accessing Directories | |
358 | @cindex accessing directories | |
359 | @cindex reading from a directory | |
360 | @cindex directories, accessing | |
361 | ||
362 | The facilities described in this section let you read the contents of a | |
363 | directory file. This is useful if you want your program to list all the | |
364 | files in a directory, perhaps as part of a menu. | |
365 | ||
366 | @cindex directory stream | |
367 | The @code{opendir} function opens a @dfn{directory stream} whose | |
bc3a45ce UD |
368 | elements are directory entries. Alternatively @code{fdopendir} can be |
369 | used which can have advantages if the program needs to have more | |
370 | control over the way the directory is opened for reading. This | |
371 | allows, for instance, to pass the @code{O_NOATIME} flag to | |
372 | @code{open}. | |
373 | ||
374 | You use the @code{readdir} function on the directory stream to | |
375 | retrieve these entries, represented as @w{@code{struct dirent}} | |
376 | objects. The name of the file for each entry is stored in the | |
377 | @code{d_name} member of this structure. There are obvious parallels | |
378 | here to the stream facilities for ordinary files, described in | |
28f540f4 RM |
379 | @ref{I/O on Streams}. |
380 | ||
381 | @menu | |
382 | * Directory Entries:: Format of one directory entry. | |
383 | * Opening a Directory:: How to open a directory stream. | |
384 | * Reading/Closing Directory:: How to read directory entries from the stream. | |
385 | * Simple Directory Lister:: A very simple directory listing program. | |
386 | * Random Access Directory:: Rereading part of the directory | |
387 | already read with the same stream. | |
0d8733c4 UD |
388 | * Scanning Directory Content:: Get entries for user selected subset of |
389 | contents in given directory. | |
390 | * Simple Directory Lister Mark II:: Revised version of the program. | |
51ea67d5 | 391 | * Low-level Directory Access:: AS-Safe functions for directory access. |
28f540f4 RM |
392 | @end menu |
393 | ||
394 | @node Directory Entries | |
395 | @subsection Format of a Directory Entry | |
396 | ||
397 | @pindex dirent.h | |
398 | This section describes what you find in a single directory entry, as you | |
399 | might obtain it from a directory stream. All the symbols are declared | |
400 | in the header file @file{dirent.h}. | |
401 | ||
28f540f4 | 402 | @deftp {Data Type} {struct dirent} |
d08a7e4c | 403 | @standards{POSIX.1, dirent.h} |
28f540f4 RM |
404 | This is a structure type used to return information about directory |
405 | entries. It contains the following fields: | |
406 | ||
407 | @table @code | |
408 | @item char d_name[] | |
409 | This is the null-terminated file name component. This is the only | |
410 | field you can count on in all POSIX systems. | |
411 | ||
412 | @item ino_t d_fileno | |
413 | This is the file serial number. For BSD compatibility, you can also | |
a7a93d50 | 414 | refer to this member as @code{d_ino}. On @gnulinuxhurdsystems{} and most POSIX |
28f540f4 RM |
415 | systems, for most files this the same as the @code{st_ino} member that |
416 | @code{stat} will return for the file. @xref{File Attributes}. | |
417 | ||
418 | @item unsigned char d_namlen | |
03879793 AJ |
419 | This is the length of the file name, not including the terminating |
420 | null character. Its type is @code{unsigned char} because that is the | |
421 | integer type of the appropriate size. This member is a BSD extension. | |
422 | The symbol @code{_DIRENT_HAVE_D_NAMLEN} is defined if this member is | |
423 | available. | |
28f540f4 RM |
424 | |
425 | @item unsigned char d_type | |
426 | This is the type of the file, possibly unknown. The following constants | |
427 | are defined for its value: | |
428 | ||
e4cf5229 | 429 | @vtable @code |
28f540f4 | 430 | @item DT_UNKNOWN |
95c3f29a AJ |
431 | The type is unknown. Only some filesystems have full support to |
432 | return the type of the file, others might always return this value. | |
28f540f4 RM |
433 | |
434 | @item DT_REG | |
435 | A regular file. | |
436 | ||
437 | @item DT_DIR | |
438 | A directory. | |
439 | ||
440 | @item DT_FIFO | |
441 | A named pipe, or FIFO. @xref{FIFO Special Files}. | |
442 | ||
443 | @item DT_SOCK | |
444 | A local-domain socket. @c !!! @xref{Local Domain}. | |
445 | ||
446 | @item DT_CHR | |
447 | A character device. | |
448 | ||
449 | @item DT_BLK | |
450 | A block device. | |
61efba8c AJ |
451 | |
452 | @item DT_LNK | |
453 | A symbolic link. | |
e4cf5229 | 454 | @end vtable |
28f540f4 | 455 | |
e4cf5229 UD |
456 | This member is a BSD extension. The symbol @code{_DIRENT_HAVE_D_TYPE} |
457 | is defined if this member is available. On systems where it is used, it | |
28f540f4 | 458 | corresponds to the file type bits in the @code{st_mode} member of |
4ffa3672 | 459 | @code{struct stat}. If the value cannot be determined the member |
e4cf5229 UD |
460 | value is DT_UNKNOWN. These two macros convert between @code{d_type} |
461 | values and @code{st_mode} values: | |
28f540f4 RM |
462 | |
463 | @deftypefun int IFTODT (mode_t @var{mode}) | |
d08a7e4c | 464 | @standards{BSD, dirent.h} |
de55fdf4 | 465 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
466 | This returns the @code{d_type} value corresponding to @var{mode}. |
467 | @end deftypefun | |
468 | ||
838e5ffe | 469 | @deftypefun mode_t DTTOIF (int @var{dtype}) |
d08a7e4c | 470 | @standards{BSD, dirent.h} |
de55fdf4 | 471 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
838e5ffe | 472 | This returns the @code{st_mode} value corresponding to @var{dtype}. |
28f540f4 RM |
473 | @end deftypefun |
474 | @end table | |
475 | ||
e4cf5229 UD |
476 | This structure may contain additional members in the future. Their |
477 | availability is always announced in the compilation environment by a | |
4ffa3672 | 478 | macro named @code{_DIRENT_HAVE_D_@var{xxx}} where @var{xxx} is replaced |
cb4fe8a2 | 479 | by the name of the new member. For instance, the member @code{d_reclen} |
e4cf5229 UD |
480 | available on some systems is announced through the macro |
481 | @code{_DIRENT_HAVE_D_RECLEN}. | |
28f540f4 RM |
482 | |
483 | When a file has multiple names, each name has its own directory entry. | |
484 | The only way you can tell that the directory entries belong to a | |
485 | single file is that they have the same value for the @code{d_fileno} | |
486 | field. | |
487 | ||
04b9968b UD |
488 | File attributes such as size, modification times etc., are part of the |
489 | file itself, not of any particular directory entry. @xref{File | |
28f540f4 RM |
490 | Attributes}. |
491 | @end deftp | |
492 | ||
493 | @node Opening a Directory | |
494 | @subsection Opening a Directory Stream | |
495 | ||
496 | @pindex dirent.h | |
497 | This section describes how to open a directory stream. All the symbols | |
498 | are declared in the header file @file{dirent.h}. | |
499 | ||
28f540f4 | 500 | @deftp {Data Type} DIR |
d08a7e4c | 501 | @standards{POSIX.1, dirent.h} |
d68171ed | 502 | The @code{DIR} data type represents a directory stream. |
28f540f4 RM |
503 | @end deftp |
504 | ||
505 | You shouldn't ever allocate objects of the @code{struct dirent} or | |
506 | @code{DIR} data types, since the directory access functions do that for | |
507 | you. Instead, you refer to these objects using the pointers returned by | |
508 | the following functions. | |
509 | ||
51ea67d5 FW |
510 | Directory streams are a high-level interface. On Linux, alternative |
511 | interfaces for accessing directories using file descriptors are | |
512 | available. @xref{Low-level Directory Access}. | |
513 | ||
28f540f4 | 514 | @deftypefun {DIR *} opendir (const char *@var{dirname}) |
d08a7e4c | 515 | @standards{POSIX.1, dirent.h} |
de55fdf4 AO |
516 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
517 | @c Besides the safe syscall, we have to allocate the DIR object with | |
518 | @c __alloc_dir, that calls malloc. | |
28f540f4 RM |
519 | The @code{opendir} function opens and returns a directory stream for |
520 | reading the directory whose file name is @var{dirname}. The stream has | |
521 | type @code{DIR *}. | |
522 | ||
523 | If unsuccessful, @code{opendir} returns a null pointer. In addition to | |
524 | the usual file name errors (@pxref{File Name Errors}), the | |
525 | following @code{errno} error conditions are defined for this function: | |
526 | ||
527 | @table @code | |
528 | @item EACCES | |
529 | Read permission is denied for the directory named by @code{dirname}. | |
530 | ||
531 | @item EMFILE | |
532 | The process has too many files open. | |
533 | ||
534 | @item ENFILE | |
535 | The entire system, or perhaps the file system which contains the | |
536 | directory, cannot support any additional open files at the moment. | |
a7a93d50 | 537 | (This problem cannot happen on @gnuhurdsystems{}.) |
bc3a45ce UD |
538 | |
539 | @item ENOMEM | |
540 | Not enough memory available. | |
28f540f4 RM |
541 | @end table |
542 | ||
543 | The @code{DIR} type is typically implemented using a file descriptor, | |
544 | and the @code{opendir} function in terms of the @code{open} function. | |
545 | @xref{Low-Level I/O}. Directory streams and the underlying | |
546 | file descriptors are closed on @code{exec} (@pxref{Executing a File}). | |
547 | @end deftypefun | |
548 | ||
bc3a45ce UD |
549 | The directory which is opened for reading by @code{opendir} is |
550 | identified by the name. In some situations this is not sufficient. | |
551 | Or the way @code{opendir} implicitly creates a file descriptor for the | |
552 | directory is not the way a program might want it. In these cases an | |
553 | alternative interface can be used. | |
554 | ||
bc3a45ce | 555 | @deftypefun {DIR *} fdopendir (int @var{fd}) |
d08a7e4c | 556 | @standards{GNU, dirent.h} |
de55fdf4 AO |
557 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
558 | @c The DIR object is allocated with __alloc_dir, that calls malloc. | |
bc3a45ce UD |
559 | The @code{fdopendir} function works just like @code{opendir} but |
560 | instead of taking a file name and opening a file descriptor for the | |
561 | directory the caller is required to provide a file descriptor. This | |
562 | file descriptor is then used in subsequent uses of the returned | |
563 | directory stream object. | |
564 | ||
565 | The caller must make sure the file descriptor is associated with a | |
566 | directory and it allows reading. | |
567 | ||
568 | If the @code{fdopendir} call returns successfully the file descriptor | |
569 | is now under the control of the system. It can be used in the same | |
570 | way the descriptor implicitly created by @code{opendir} can be used | |
571 | but the program must not close the descriptor. | |
572 | ||
573 | In case the function is unsuccessful it returns a null pointer and the | |
574 | file descriptor remains to be usable by the program. The following | |
575 | @code{errno} error conditions are defined for this function: | |
576 | ||
577 | @table @code | |
578 | @item EBADF | |
579 | The file descriptor is not valid. | |
580 | ||
581 | @item ENOTDIR | |
582 | The file descriptor is not associated with a directory. | |
583 | ||
584 | @item EINVAL | |
585 | The descriptor does not allow reading the directory content. | |
586 | ||
587 | @item ENOMEM | |
588 | Not enough memory available. | |
589 | @end table | |
590 | @end deftypefun | |
591 | ||
e4cf5229 UD |
592 | In some situations it can be desirable to get hold of the file |
593 | descriptor which is created by the @code{opendir} call. For instance, | |
594 | to switch the current working directory to the directory just read the | |
595 | @code{fchdir} function could be used. Historically the @code{DIR} type | |
596 | was exposed and programs could access the fields. This does not happen | |
1f77f049 | 597 | in @theglibc{}. Instead a separate function is provided to allow |
e4cf5229 UD |
598 | access. |
599 | ||
e4cf5229 | 600 | @deftypefun int dirfd (DIR *@var{dirstream}) |
d08a7e4c | 601 | @standards{GNU, dirent.h} |
de55fdf4 | 602 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
e4cf5229 UD |
603 | The function @code{dirfd} returns the file descriptor associated with |
604 | the directory stream @var{dirstream}. This descriptor can be used until | |
605 | the directory is closed with @code{closedir}. If the directory stream | |
606 | implementation is not using file descriptors the return value is | |
607 | @code{-1}. | |
608 | @end deftypefun | |
609 | ||
28f540f4 RM |
610 | @node Reading/Closing Directory |
611 | @subsection Reading and Closing a Directory Stream | |
612 | ||
613 | @pindex dirent.h | |
614 | This section describes how to read directory entries from a directory | |
615 | stream, and how to close the stream when you are done with it. All the | |
616 | symbols are declared in the header file @file{dirent.h}. | |
617 | ||
28f540f4 | 618 | @deftypefun {struct dirent *} readdir (DIR *@var{dirstream}) |
d08a7e4c | 619 | @standards{POSIX.1, dirent.h} |
a42478b7 | 620 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
de55fdf4 AO |
621 | @c This function holds dirstream's non-recursive lock, which brings |
622 | @c about the usual issues with locks and async signals and cancellation, | |
623 | @c but the lock taking is not enough to make the returned value safe to | |
624 | @c use, since it points to a stream's internal buffer that can be | |
625 | @c overwritten by subsequent calls or even released by closedir. | |
28f540f4 | 626 | This function reads the next entry from the directory. It normally |
91ce4085 FW |
627 | returns a pointer to a structure containing information about the |
628 | file. This structure is associated with the @var{dirstream} handle | |
629 | and can be rewritten by a subsequent call. | |
28f540f4 | 630 | |
04b9968b | 631 | @strong{Portability Note:} On some systems @code{readdir} may not |
28f540f4 RM |
632 | return entries for @file{.} and @file{..}, even though these are always |
633 | valid file names in any directory. @xref{File Name Resolution}. | |
634 | ||
635 | If there are no more entries in the directory or an error is detected, | |
636 | @code{readdir} returns a null pointer. The following @code{errno} error | |
637 | conditions are defined for this function: | |
638 | ||
639 | @table @code | |
640 | @item EBADF | |
641 | The @var{dirstream} argument is not valid. | |
642 | @end table | |
a68b0d31 | 643 | |
91ce4085 FW |
644 | To distinguish between an end-of-directory condition or an error, you |
645 | must set @code{errno} to zero before calling @code{readdir}. To avoid | |
646 | entering an infinite loop, you should stop reading from the directory | |
647 | after the first error. | |
648 | ||
a42478b7 FW |
649 | @strong{Caution:} The pointer returned by @code{readdir} points to |
650 | a buffer within the @code{DIR} object. The data in that buffer will | |
651 | be overwritten by the next call to @code{readdir}. You must take care, | |
652 | for instance, to copy the @code{d_name} string if you need it later. | |
653 | ||
654 | Because of this, it is not safe to share a @code{DIR} object among | |
655 | multiple threads, unless you use your own locking to ensure that | |
656 | no thread calls @code{readdir} while another thread is still using the | |
657 | data from the previous call. In @theglibc{}, it is safe to call | |
658 | @code{readdir} from multiple threads as long as each thread uses | |
659 | its own @code{DIR} object. POSIX.1-2008 does not require this to | |
660 | be safe, but we are not aware of any operating systems where it | |
661 | does not work. | |
662 | ||
663 | @code{readdir_r} allows you to provide your own buffer for the | |
664 | @code{struct dirent}, but it is less portable than @code{readdir}, and | |
665 | has problems with very long filenames (see below). We recommend | |
666 | you use @code{readdir}, but do not share @code{DIR} objects. | |
a68b0d31 UD |
667 | @end deftypefun |
668 | ||
dd7d45e8 | 669 | @deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result}) |
d08a7e4c | 670 | @standards{GNU, dirent.h} |
de55fdf4 | 671 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
91ce4085 FW |
672 | This function is a version of @code{readdir} which performs internal |
673 | locking. Like @code{readdir} it returns the next entry from the | |
674 | directory. To prevent conflicts between simultaneously running | |
675 | threads the result is stored inside the @var{entry} object. | |
676 | ||
7584a3f9 FW |
677 | @strong{Portability Note:} @code{readdir_r} is deprecated. It is |
678 | recommended to use @code{readdir} instead of @code{readdir_r} for the | |
679 | following reasons: | |
91ce4085 FW |
680 | |
681 | @itemize @bullet | |
682 | @item | |
683 | On systems which do not define @code{NAME_MAX}, it may not be possible | |
684 | to use @code{readdir_r} safely because the caller does not specify the | |
685 | length of the buffer for the directory entry. | |
686 | ||
687 | @item | |
688 | On some systems, @code{readdir_r} cannot read directory entries with | |
689 | very long names. If such a name is encountered, @theglibc{} | |
690 | implementation of @code{readdir_r} returns with an error code of | |
691 | @code{ENAMETOOLONG} after the final directory entry has been read. On | |
692 | other systems, @code{readdir_r} may return successfully, but the | |
693 | @code{d_name} member may not be NUL-terminated or may be truncated. | |
694 | ||
695 | @item | |
696 | POSIX-1.2008 does not guarantee that @code{readdir} is thread-safe, | |
697 | even when access to the same @var{dirstream} is serialized. But in | |
698 | current implementations (including @theglibc{}), it is safe to call | |
699 | @code{readdir} concurrently on different @var{dirstream}s, so there is | |
700 | no need to use @code{readdir_r} in most multi-threaded programs. In | |
701 | the rare case that multiple threads need to read from the same | |
702 | @var{dirstream}, it is still better to use @code{readdir} and external | |
703 | synchronization. | |
704 | ||
705 | @item | |
706 | It is expected that future versions of POSIX will obsolete | |
707 | @code{readdir_r} and mandate the level of thread safety for | |
708 | @code{readdir} which is provided by @theglibc{} and other | |
709 | implementations today. | |
710 | @end itemize | |
a68b0d31 | 711 | |
05dab910 RM |
712 | Normally @code{readdir_r} returns zero and sets @code{*@var{result}} |
713 | to @var{entry}. If there are no more entries in the directory or an | |
714 | error is detected, @code{readdir_r} sets @code{*@var{result}} to a | |
715 | null pointer and returns a nonzero error code, also stored in | |
716 | @code{errno}, as described for @code{readdir}. | |
c063ba61 | 717 | |
c329332e UD |
718 | It is also important to look at the definition of the @code{struct |
719 | dirent} type. Simply passing a pointer to an object of this type for | |
720 | the second parameter of @code{readdir_r} might not be enough. Some | |
721 | systems don't define the @code{d_name} element sufficiently long. In | |
722 | this case the user has to provide additional space. There must be room | |
723 | for at least @code{NAME_MAX + 1} characters in the @code{d_name} array. | |
724 | Code to call @code{readdir_r} could look like this: | |
725 | ||
726 | @smallexample | |
727 | union | |
728 | @{ | |
729 | struct dirent d; | |
730 | char b[offsetof (struct dirent, d_name) + NAME_MAX + 1]; | |
731 | @} u; | |
732 | ||
733 | if (readdir_r (dir, &u.d, &res) == 0) | |
95fdc6a0 | 734 | @dots{} |
c329332e UD |
735 | @end smallexample |
736 | @end deftypefun | |
737 | ||
738 | To support large filesystems on 32-bit machines there are LFS variants | |
739 | of the last two functions. | |
740 | ||
c329332e | 741 | @deftypefun {struct dirent64 *} readdir64 (DIR *@var{dirstream}) |
d08a7e4c | 742 | @standards{LFS, dirent.h} |
a42478b7 | 743 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
c329332e UD |
744 | The @code{readdir64} function is just like the @code{readdir} function |
745 | except that it returns a pointer to a record of type @code{struct | |
746 | dirent64}. Some of the members of this data type (notably @code{d_ino}) | |
747 | might have a different size to allow large filesystems. | |
748 | ||
749 | In all other aspects this function is equivalent to @code{readdir}. | |
750 | @end deftypefun | |
751 | ||
c329332e | 752 | @deftypefun int readdir64_r (DIR *@var{dirstream}, struct dirent64 *@var{entry}, struct dirent64 **@var{result}) |
d08a7e4c | 753 | @standards{LFS, dirent.h} |
de55fdf4 | 754 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
7584a3f9 FW |
755 | The deprecated @code{readdir64_r} function is equivalent to the |
756 | @code{readdir_r} function except that it takes parameters of base type | |
757 | @code{struct dirent64} instead of @code{struct dirent} in the second and | |
758 | third position. The same precautions mentioned in the documentation of | |
c329332e | 759 | @code{readdir_r} also apply here. |
28f540f4 RM |
760 | @end deftypefun |
761 | ||
28f540f4 | 762 | @deftypefun int closedir (DIR *@var{dirstream}) |
d08a7e4c | 763 | @standards{POSIX.1, dirent.h} |
de55fdf4 AO |
764 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@acsmem{} @acsfd{} @aculock{/hurd}}} |
765 | @c No synchronization in the posix implementation, only in the hurd | |
766 | @c one. This is regarded as safe because it is undefined behavior if | |
767 | @c other threads could still be using the dir stream while it's closed. | |
28f540f4 | 768 | This function closes the directory stream @var{dirstream}. It returns |
d68171ed | 769 | @code{0} on success and @code{-1} on failure. |
28f540f4 RM |
770 | |
771 | The following @code{errno} error conditions are defined for this | |
772 | function: | |
773 | ||
774 | @table @code | |
775 | @item EBADF | |
776 | The @var{dirstream} argument is not valid. | |
777 | @end table | |
778 | @end deftypefun | |
779 | ||
780 | @node Simple Directory Lister | |
781 | @subsection Simple Program to List a Directory | |
782 | ||
783 | Here's a simple program that prints the names of the files in | |
784 | the current working directory: | |
785 | ||
786 | @smallexample | |
787 | @include dir.c.texi | |
788 | @end smallexample | |
789 | ||
790 | The order in which files appear in a directory tends to be fairly | |
791 | random. A more useful program would sort the entries (perhaps by | |
0d8733c4 | 792 | alphabetizing them) before printing them; see |
8b7fb588 | 793 | @ref{Scanning Directory Content}, and @ref{Array Sort Function}. |
28f540f4 | 794 | |
28f540f4 RM |
795 | |
796 | @node Random Access Directory | |
797 | @subsection Random Access in a Directory Stream | |
798 | ||
799 | @pindex dirent.h | |
800 | This section describes how to reread parts of a directory that you have | |
801 | already read from an open directory stream. All the symbols are | |
802 | declared in the header file @file{dirent.h}. | |
803 | ||
28f540f4 | 804 | @deftypefun void rewinddir (DIR *@var{dirstream}) |
d08a7e4c | 805 | @standards{POSIX.1, dirent.h} |
de55fdf4 | 806 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
28f540f4 RM |
807 | The @code{rewinddir} function is used to reinitialize the directory |
808 | stream @var{dirstream}, so that if you call @code{readdir} it | |
809 | returns information about the first entry in the directory again. This | |
810 | function also notices if files have been added or removed to the | |
811 | directory since it was opened with @code{opendir}. (Entries for these | |
812 | files might or might not be returned by @code{readdir} if they were | |
813 | added or removed since you last called @code{opendir} or | |
814 | @code{rewinddir}.) | |
815 | @end deftypefun | |
816 | ||
cc6e48bc | 817 | @deftypefun {long int} telldir (DIR *@var{dirstream}) |
d08a7e4c | 818 | @standards{BSD, dirent.h} |
de55fdf4 AO |
819 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}} |
820 | @c The implementation is safe on most platforms, but on BSD it uses | |
821 | @c cookies, buckets and records, and the global array of pointers to | |
822 | @c dynamically allocated records is guarded by a non-recursive lock. | |
28f540f4 RM |
823 | The @code{telldir} function returns the file position of the directory |
824 | stream @var{dirstream}. You can use this value with @code{seekdir} to | |
825 | restore the directory stream to that position. | |
826 | @end deftypefun | |
827 | ||
6992a6b2 | 828 | @deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos}) |
d08a7e4c | 829 | @standards{BSD, dirent.h} |
de55fdf4 AO |
830 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}} |
831 | @c The implementation is safe on most platforms, but on BSD it uses | |
832 | @c cookies, buckets and records, and the global array of pointers to | |
833 | @c dynamically allocated records is guarded by a non-recursive lock. | |
28f540f4 RM |
834 | The @code{seekdir} function sets the file position of the directory |
835 | stream @var{dirstream} to @var{pos}. The value @var{pos} must be the | |
836 | result of a previous call to @code{telldir} on this particular stream; | |
837 | closing and reopening the directory can invalidate values returned by | |
838 | @code{telldir}. | |
839 | @end deftypefun | |
840 | ||
0d8733c4 UD |
841 | |
842 | @node Scanning Directory Content | |
843 | @subsection Scanning the Content of a Directory | |
844 | ||
845 | A higher-level interface to the directory handling functions is the | |
846 | @code{scandir} function. With its help one can select a subset of the | |
04b9968b UD |
847 | entries in a directory, possibly sort them and get a list of names as |
848 | the result. | |
0d8733c4 | 849 | |
8ded91fb | 850 | @deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const struct dirent **, const struct dirent **)) |
d08a7e4c RJ |
851 | @standards{BSD, dirent.h} |
852 | @standards{SVID, dirent.h} | |
de55fdf4 AO |
853 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
854 | @c The scandir function calls __opendirat, __readdir, and __closedir to | |
855 | @c go over the named dir; malloc and realloc to allocate the namelist | |
856 | @c and copies of each selected dirent, besides the selector, if given, | |
857 | @c and qsort and the cmp functions if the latter is given. In spite of | |
858 | @c the cleanup handler that releases memory and the file descriptor in | |
859 | @c case of synchronous cancellation, an asynchronous cancellation may | |
860 | @c still leak memory and a file descriptor. Although readdir is unsafe | |
861 | @c in general, the use of an internal dir stream for sequential scanning | |
862 | @c of the directory with copying of dirents before subsequent calls | |
863 | @c makes the use safe, and the fact that the dir stream is private to | |
864 | @c each scandir call does away with the lock issues in readdir and | |
865 | @c closedir. | |
0d8733c4 UD |
866 | |
867 | The @code{scandir} function scans the contents of the directory selected | |
04b9968b | 868 | by @var{dir}. The result in *@var{namelist} is an array of pointers to |
4ffa3672 | 869 | structures of type @code{struct dirent} which describe all selected |
0d8733c4 UD |
870 | directory entries and which is allocated using @code{malloc}. Instead |
871 | of always getting all directory entries returned, the user supplied | |
872 | function @var{selector} can be used to decide which entries are in the | |
04b9968b | 873 | result. Only the entries for which @var{selector} returns a non-zero |
0d8733c4 UD |
874 | value are selected. |
875 | ||
04b9968b UD |
876 | Finally the entries in *@var{namelist} are sorted using the |
877 | user-supplied function @var{cmp}. The arguments passed to the @var{cmp} | |
878 | function are of type @code{struct dirent **}, therefore one cannot | |
879 | directly use the @code{strcmp} or @code{strcoll} functions; instead see | |
880 | the functions @code{alphasort} and @code{versionsort} below. | |
0d8733c4 | 881 | |
04b9968b UD |
882 | The return value of the function is the number of entries placed in |
883 | *@var{namelist}. If it is @code{-1} an error occurred (either the | |
bdc674d9 | 884 | directory could not be opened for reading or memory allocation failed) and |
af6f3906 | 885 | the global variable @code{errno} contains more information on the error. |
0d8733c4 UD |
886 | @end deftypefun |
887 | ||
4ffa3672 | 888 | As described above, the fourth argument to the @code{scandir} function |
04b9968b | 889 | must be a pointer to a sorting function. For the convenience of the |
1f77f049 | 890 | programmer @theglibc{} contains implementations of functions which |
04b9968b | 891 | are very helpful for this purpose. |
0d8733c4 | 892 | |
2302d679 | 893 | @deftypefun int alphasort (const struct dirent **@var{a}, const struct dirent **@var{b}) |
d08a7e4c RJ |
894 | @standards{BSD, dirent.h} |
895 | @standards{SVID, dirent.h} | |
de55fdf4 AO |
896 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} |
897 | @c Calls strcoll. | |
5679cdb6 | 898 | The @code{alphasort} function behaves like the @code{strcoll} function |
0d8733c4 UD |
899 | (@pxref{String/Array Comparison}). The difference is that the arguments |
900 | are not string pointers but instead they are of type | |
901 | @code{struct dirent **}. | |
902 | ||
04b9968b UD |
903 | The return value of @code{alphasort} is less than, equal to, or greater |
904 | than zero depending on the order of the two entries @var{a} and @var{b}. | |
0d8733c4 UD |
905 | @end deftypefun |
906 | ||
2302d679 | 907 | @deftypefun int versionsort (const struct dirent **@var{a}, const struct dirent **@var{b}) |
d08a7e4c | 908 | @standards{GNU, dirent.h} |
de55fdf4 AO |
909 | @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} |
910 | @c Calls strverscmp, which will accesses the locale object multiple | |
911 | @c times. | |
04b9968b | 912 | The @code{versionsort} function is like @code{alphasort} except that it |
1f205a47 UD |
913 | uses the @code{strverscmp} function internally. |
914 | @end deftypefun | |
915 | ||
5679cdb6 UD |
916 | If the filesystem supports large files we cannot use the @code{scandir} |
917 | anymore since the @code{dirent} structure might not able to contain all | |
918 | the information. The LFS provides the new type @w{@code{struct | |
919 | dirent64}}. To use this we need a new function. | |
920 | ||
8ded91fb | 921 | @deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const struct dirent64 **, const struct dirent64 **)) |
d08a7e4c | 922 | @standards{GNU, dirent.h} |
de55fdf4 AO |
923 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
924 | @c See scandir. | |
5679cdb6 | 925 | The @code{scandir64} function works like the @code{scandir} function |
04b9968b UD |
926 | except that the directory entries it returns are described by elements |
927 | of type @w{@code{struct dirent64}}. The function pointed to by | |
928 | @var{selector} is again used to select the desired entries, except that | |
5679cdb6 | 929 | @var{selector} now must point to a function which takes a |
789b13c4 | 930 | @w{@code{struct dirent64 *}} parameter. |
5679cdb6 | 931 | |
04b9968b UD |
932 | Similarly the @var{cmp} function should expect its two arguments to be |
933 | of type @code{struct dirent64 **}. | |
5679cdb6 UD |
934 | @end deftypefun |
935 | ||
04b9968b UD |
936 | As @var{cmp} is now a function of a different type, the functions |
937 | @code{alphasort} and @code{versionsort} cannot be supplied for that | |
938 | argument. Instead we provide the two replacement functions below. | |
5679cdb6 | 939 | |
2302d679 | 940 | @deftypefun int alphasort64 (const struct dirent64 **@var{a}, const struct dirent **@var{b}) |
d08a7e4c | 941 | @standards{GNU, dirent.h} |
de55fdf4 AO |
942 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} |
943 | @c See alphasort. | |
5679cdb6 UD |
944 | The @code{alphasort64} function behaves like the @code{strcoll} function |
945 | (@pxref{String/Array Comparison}). The difference is that the arguments | |
946 | are not string pointers but instead they are of type | |
947 | @code{struct dirent64 **}. | |
948 | ||
789b13c4 UD |
949 | Return value of @code{alphasort64} is less than, equal to, or greater |
950 | than zero depending on the order of the two entries @var{a} and @var{b}. | |
5679cdb6 UD |
951 | @end deftypefun |
952 | ||
2302d679 | 953 | @deftypefun int versionsort64 (const struct dirent64 **@var{a}, const struct dirent64 **@var{b}) |
d08a7e4c | 954 | @standards{GNU, dirent.h} |
de55fdf4 AO |
955 | @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} |
956 | @c See versionsort. | |
5679cdb6 UD |
957 | The @code{versionsort64} function is like @code{alphasort64}, excepted that it |
958 | uses the @code{strverscmp} function internally. | |
959 | @end deftypefun | |
960 | ||
04b9968b | 961 | It is important not to mix the use of @code{scandir} and the 64-bit |
5679cdb6 | 962 | comparison functions or vice versa. There are systems on which this |
68b50604 | 963 | works but on others it will fail miserably. |
5679cdb6 | 964 | |
0d8733c4 UD |
965 | @node Simple Directory Lister Mark II |
966 | @subsection Simple Program to List a Directory, Mark II | |
967 | ||
968 | Here is a revised version of the directory lister found above | |
969 | (@pxref{Simple Directory Lister}). Using the @code{scandir} function we | |
04b9968b UD |
970 | can avoid the functions which work directly with the directory contents. |
971 | After the call the returned entries are available for direct use. | |
0d8733c4 UD |
972 | |
973 | @smallexample | |
974 | @include dir2.c.texi | |
975 | @end smallexample | |
976 | ||
04b9968b UD |
977 | Note the simple selector function in this example. Since we want to see |
978 | all directory entries we always return @code{1}. | |
0d8733c4 | 979 | |
51ea67d5 FW |
980 | @node Low-level Directory Access |
981 | @subsection Low-level Directory Access | |
982 | ||
983 | The stream-based directory functions are not AS-Safe and cannot be | |
984 | used after @code{vfork}. @xref{POSIX Safety Concepts}. The functions | |
985 | below provide an alternative that can be used in these contexts. | |
986 | ||
987 | Directory data is obtained from a file descriptor, as created by the | |
988 | @code{open} function, with or without the @code{O_DIRECTORY} flag. | |
989 | @xref{Opening and Closing Files}. | |
990 | ||
991 | @deftypefun ssize_t getdents64 (int @var{fd}, void *@var{buffer}, size_t @var{length}) | |
b8b3d5a1 | 992 | @standards{Linux, dirent.h} |
51ea67d5 FW |
993 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
994 | The @code{getdents64} function reads at most @var{length} bytes of | |
995 | directory entry data from the file descriptor @var{fd} and stores it | |
996 | into the byte array starting at @var{buffer}. | |
997 | ||
998 | On success, the function returns the number of bytes written to the | |
999 | buffer. This number is zero if @var{fd} is already at the end of the | |
1000 | directory stream. On error, the function returns @code{-1} and sets | |
1001 | @code{errno} to the appropriate error code. | |
1002 | ||
1003 | The data is stored as a sequence of @code{struct dirent64} records, | |
1004 | which can be traversed using the @code{d_reclen} member. The buffer | |
1005 | should be large enough to hold the largest possible directory entry. | |
1006 | Note that some file systems support file names longer than | |
1007 | @code{NAME_MAX} bytes (e.g., because they support up to 255 Unicode | |
1008 | characters), so a buffer size of at least 1024 is recommended. | |
1009 | ||
1010 | This function is specific to Linux. | |
1011 | @end deftypefun | |
1012 | ||
0d8733c4 | 1013 | |
04b9968b UD |
1014 | @node Working with Directory Trees |
1015 | @section Working with Directory Trees | |
f2ea0f5b UD |
1016 | @cindex directory hierarchy |
1017 | @cindex hierarchy, directory | |
2604afb1 UD |
1018 | @cindex tree, directory |
1019 | ||
04b9968b UD |
1020 | The functions described so far for handling the files in a directory |
1021 | have allowed you to either retrieve the information bit by bit, or to | |
1022 | process all the files as a group (see @code{scandir}). Sometimes it is | |
1023 | useful to process whole hierarchies of directories and their contained | |
1024 | files. The X/Open specification defines two functions to do this. The | |
1025 | simpler form is derived from an early definition in @w{System V} systems | |
1026 | and therefore this function is available on SVID-derived systems. The | |
1027 | prototypes and required definitions can be found in the @file{ftw.h} | |
1028 | header. | |
1029 | ||
1030 | There are four functions in this family: @code{ftw}, @code{nftw} and | |
1031 | their 64-bit counterparts @code{ftw64} and @code{nftw64}. These | |
1032 | functions take as one of their arguments a pointer to a callback | |
1033 | function of the appropriate type. | |
2604afb1 UD |
1034 | |
1035 | @deftp {Data Type} __ftw_func_t | |
d08a7e4c | 1036 | @standards{GNU, ftw.h} |
2604afb1 UD |
1037 | |
1038 | @smallexample | |
1039 | int (*) (const char *, const struct stat *, int) | |
1040 | @end smallexample | |
1041 | ||
04b9968b UD |
1042 | The type of callback functions given to the @code{ftw} function. The |
1043 | first parameter points to the file name, the second parameter to an | |
1044 | object of type @code{struct stat} which is filled in for the file named | |
1045 | in the first parameter. | |
2604afb1 UD |
1046 | |
1047 | @noindent | |
04b9968b | 1048 | The last parameter is a flag giving more information about the current |
2604afb1 UD |
1049 | file. It can have the following values: |
1050 | ||
a3a4a74e | 1051 | @vtable @code |
2604afb1 | 1052 | @item FTW_F |
04b9968b UD |
1053 | The item is either a normal file or a file which does not fit into one |
1054 | of the following categories. This could be special files, sockets etc. | |
2604afb1 | 1055 | @item FTW_D |
04b9968b | 1056 | The item is a directory. |
2604afb1 | 1057 | @item FTW_NS |
04b9968b | 1058 | The @code{stat} call failed and so the information pointed to by the |
ef48b196 | 1059 | second parameter is invalid. |
2604afb1 UD |
1060 | @item FTW_DNR |
1061 | The item is a directory which cannot be read. | |
1062 | @item FTW_SL | |
1063 | The item is a symbolic link. Since symbolic links are normally followed | |
1064 | seeing this value in a @code{ftw} callback function means the referenced | |
1065 | file does not exist. The situation for @code{nftw} is different. | |
1066 | ||
1067 | This value is only available if the program is compiled with | |
c941736c | 1068 | @code{_XOPEN_EXTENDED} defined before including |
2604afb1 | 1069 | the first header. The original SVID systems do not have symbolic links. |
a3a4a74e UD |
1070 | @end vtable |
1071 | ||
1072 | If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
04b9968b | 1073 | type is in fact @code{__ftw64_func_t} since this mode changes |
a3a4a74e | 1074 | @code{struct stat} to be @code{struct stat64}. |
2604afb1 UD |
1075 | @end deftp |
1076 | ||
04b9968b | 1077 | For the LFS interface and for use in the function @code{ftw64}, the |
a3a4a74e UD |
1078 | header @file{ftw.h} defines another function type. |
1079 | ||
a3a4a74e | 1080 | @deftp {Data Type} __ftw64_func_t |
d08a7e4c | 1081 | @standards{GNU, ftw.h} |
a3a4a74e UD |
1082 | |
1083 | @smallexample | |
1084 | int (*) (const char *, const struct stat64 *, int) | |
1085 | @end smallexample | |
1086 | ||
1087 | This type is used just like @code{__ftw_func_t} for the callback | |
04b9968b UD |
1088 | function, but this time is called from @code{ftw64}. The second |
1089 | parameter to the function is a pointer to a variable of type | |
a3a4a74e UD |
1090 | @code{struct stat64} which is able to represent the larger values. |
1091 | @end deftp | |
1092 | ||
2604afb1 | 1093 | @deftp {Data Type} __nftw_func_t |
d08a7e4c | 1094 | @standards{GNU, ftw.h} |
2604afb1 UD |
1095 | |
1096 | @smallexample | |
1097 | int (*) (const char *, const struct stat *, int, struct FTW *) | |
1098 | @end smallexample | |
1099 | ||
04b9968b UD |
1100 | The first three arguments are the same as for the @code{__ftw_func_t} |
1101 | type. However for the third argument some additional values are defined | |
1102 | to allow finer differentiation: | |
2fe82ca6 | 1103 | @vtable @code |
2604afb1 UD |
1104 | @item FTW_DP |
1105 | The current item is a directory and all subdirectories have already been | |
1106 | visited and reported. This flag is returned instead of @code{FTW_D} if | |
04b9968b | 1107 | the @code{FTW_DEPTH} flag is passed to @code{nftw} (see below). |
2604afb1 UD |
1108 | @item FTW_SLN |
1109 | The current item is a stale symbolic link. The file it points to does | |
1110 | not exist. | |
2fe82ca6 | 1111 | @end vtable |
2604afb1 UD |
1112 | |
1113 | The last parameter of the callback function is a pointer to a structure | |
1114 | with some extra information as described below. | |
a3a4a74e UD |
1115 | |
1116 | If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
04b9968b | 1117 | type is in fact @code{__nftw64_func_t} since this mode changes |
a3a4a74e | 1118 | @code{struct stat} to be @code{struct stat64}. |
2604afb1 UD |
1119 | @end deftp |
1120 | ||
a3a4a74e UD |
1121 | For the LFS interface there is also a variant of this data type |
1122 | available which has to be used with the @code{nftw64} function. | |
1123 | ||
a3a4a74e | 1124 | @deftp {Data Type} __nftw64_func_t |
d08a7e4c | 1125 | @standards{GNU, ftw.h} |
a3a4a74e UD |
1126 | |
1127 | @smallexample | |
1128 | int (*) (const char *, const struct stat64 *, int, struct FTW *) | |
1129 | @end smallexample | |
1130 | ||
1131 | This type is used just like @code{__nftw_func_t} for the callback | |
04b9968b UD |
1132 | function, but this time is called from @code{nftw64}. The second |
1133 | parameter to the function is this time a pointer to a variable of type | |
a3a4a74e UD |
1134 | @code{struct stat64} which is able to represent the larger values. |
1135 | @end deftp | |
1136 | ||
2604afb1 | 1137 | @deftp {Data Type} {struct FTW} |
d08a7e4c | 1138 | @standards{XPG4.2, ftw.h} |
04b9968b UD |
1139 | The information contained in this structure helps in interpreting the |
1140 | name parameter and gives some information about the current state of the | |
1141 | traversal of the directory hierarchy. | |
2604afb1 UD |
1142 | |
1143 | @table @code | |
1144 | @item int base | |
04b9968b UD |
1145 | The value is the offset into the string passed in the first parameter to |
1146 | the callback function of the beginning of the file name. The rest of | |
1147 | the string is the path of the file. This information is especially | |
1148 | important if the @code{FTW_CHDIR} flag was set in calling @code{nftw} | |
1149 | since then the current directory is the one the current item is found | |
1150 | in. | |
2604afb1 | 1151 | @item int level |
04b9968b UD |
1152 | Whilst processing, the code tracks how many directories down it has gone |
1153 | to find the current file. This nesting level starts at @math{0} for | |
1154 | files in the initial directory (or is zero for the initial file if a | |
1155 | file was passed). | |
2604afb1 UD |
1156 | @end table |
1157 | @end deftp | |
1158 | ||
1159 | ||
2604afb1 | 1160 | @deftypefun int ftw (const char *@var{filename}, __ftw_func_t @var{func}, int @var{descriptors}) |
d08a7e4c | 1161 | @standards{SVID, ftw.h} |
de55fdf4 AO |
1162 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
1163 | @c see nftw for safety details | |
2604afb1 UD |
1164 | The @code{ftw} function calls the callback function given in the |
1165 | parameter @var{func} for every item which is found in the directory | |
1166 | specified by @var{filename} and all directories below. The function | |
1167 | follows symbolic links if necessary but does not process an item twice. | |
04b9968b UD |
1168 | If @var{filename} is not a directory then it itself is the only object |
1169 | returned to the callback function. | |
2604afb1 | 1170 | |
04b9968b UD |
1171 | The file name passed to the callback function is constructed by taking |
1172 | the @var{filename} parameter and appending the names of all passed | |
2604afb1 | 1173 | directories and then the local file name. So the callback function can |
04b9968b UD |
1174 | use this parameter to access the file. @code{ftw} also calls |
1175 | @code{stat} for the file and passes that information on to the callback | |
4ffa3672 | 1176 | function. If this @code{stat} call is not successful the failure is |
04b9968b UD |
1177 | indicated by setting the third argument of the callback function to |
1178 | @code{FTW_NS}. Otherwise it is set according to the description given | |
1179 | in the account of @code{__ftw_func_t} above. | |
2604afb1 UD |
1180 | |
1181 | The callback function is expected to return @math{0} to indicate that no | |
04b9968b UD |
1182 | error occurred and that processing should continue. If an error |
1183 | occurred in the callback function or it wants @code{ftw} to return | |
1184 | immediately, the callback function can return a value other than | |
2604afb1 | 1185 | @math{0}. This is the only correct way to stop the function. The |
04b9968b UD |
1186 | program must not use @code{setjmp} or similar techniques to continue |
1187 | from another place. This would leave resources allocated by the | |
1188 | @code{ftw} function unfreed. | |
1189 | ||
1190 | The @var{descriptors} parameter to @code{ftw} specifies how many file | |
1191 | descriptors it is allowed to consume. The function runs faster the more | |
1192 | descriptors it can use. For each level in the directory hierarchy at | |
1193 | most one descriptor is used, but for very deep ones any limit on open | |
1194 | file descriptors for the process or the system may be exceeded. | |
1195 | Moreover, file descriptor limits in a multi-threaded program apply to | |
1196 | all the threads as a group, and therefore it is a good idea to supply a | |
1197 | reasonable limit to the number of open descriptors. | |
2604afb1 UD |
1198 | |
1199 | The return value of the @code{ftw} function is @math{0} if all callback | |
1200 | function calls returned @math{0} and all actions performed by the | |
04b9968b UD |
1201 | @code{ftw} succeeded. If a function call failed (other than calling |
1202 | @code{stat} on an item) the function returns @math{-1}. If a callback | |
2604afb1 UD |
1203 | function returns a value other than @math{0} this value is returned as |
1204 | the return value of @code{ftw}. | |
a3a4a74e UD |
1205 | |
1206 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
11bf311e | 1207 | 32-bit system this function is in fact @code{ftw64}, i.e., the LFS |
a3a4a74e UD |
1208 | interface transparently replaces the old interface. |
1209 | @end deftypefun | |
1210 | ||
a3a4a74e | 1211 | @deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors}) |
d08a7e4c | 1212 | @standards{Unix98, ftw.h} |
de55fdf4 | 1213 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
a3a4a74e | 1214 | This function is similar to @code{ftw} but it can work on filesystems |
04b9968b UD |
1215 | with large files. File information is reported using a variable of type |
1216 | @code{struct stat64} which is passed by reference to the callback | |
1217 | function. | |
a3a4a74e UD |
1218 | |
1219 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
04b9968b | 1220 | 32-bit system this function is available under the name @code{ftw} and |
a3a4a74e | 1221 | transparently replaces the old implementation. |
2604afb1 UD |
1222 | @end deftypefun |
1223 | ||
2604afb1 | 1224 | @deftypefun int nftw (const char *@var{filename}, __nftw_func_t @var{func}, int @var{descriptors}, int @var{flag}) |
d08a7e4c | 1225 | @standards{XPG4.2, ftw.h} |
de55fdf4 AO |
1226 | @safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}} |
1227 | @c ftw_startup calls alloca, malloc, free, xstat/lxstat, tdestroy, and ftw_dir | |
1228 | @c if FTW_CHDIR, call open, and fchdir, or chdir and getcwd | |
1229 | @c ftw_dir calls open_dir_stream, readdir64, process_entry, closedir | |
1230 | @c if FTW_CHDIR, also calls fchdir | |
1231 | @c open_dir_stream calls malloc, realloc, readdir64, free, closedir, | |
1232 | @c then openat64_not_cancel_3 and fdopendir or opendir, then dirfd. | |
1233 | @c process_entry may cal realloc, fxstatat/lxstat/xstat, ftw_dir, and | |
1234 | @c find_object (tsearch) and add_object (tfind). | |
1235 | @c Since each invocation of *ftw uses its own private search tree, none | |
1236 | @c of the search tree concurrency issues apply. | |
04b9968b UD |
1237 | The @code{nftw} function works like the @code{ftw} functions. They call |
1238 | the callback function @var{func} for all items found in the directory | |
2604afb1 UD |
1239 | @var{filename} and below. At most @var{descriptors} file descriptors |
1240 | are consumed during the @code{nftw} call. | |
1241 | ||
04b9968b UD |
1242 | One difference is that the callback function is of a different type. It |
1243 | is of type @w{@code{struct FTW *}} and provides the callback function | |
1244 | with the extra information described above. | |
2604afb1 | 1245 | |
04b9968b UD |
1246 | A second difference is that @code{nftw} takes a fourth argument, which |
1247 | is @math{0} or a bitwise-OR combination of any of the following values. | |
2604afb1 | 1248 | |
a3a4a74e | 1249 | @vtable @code |
2604afb1 | 1250 | @item FTW_PHYS |
04b9968b UD |
1251 | While traversing the directory symbolic links are not followed. Instead |
1252 | symbolic links are reported using the @code{FTW_SL} value for the type | |
1253 | parameter to the callback function. If the file referenced by a | |
d01d6319 | 1254 | symbolic link does not exist @code{FTW_SLN} is returned instead. |
2604afb1 UD |
1255 | @item FTW_MOUNT |
1256 | The callback function is only called for items which are on the same | |
04b9968b | 1257 | mounted filesystem as the directory given by the @var{filename} |
2604afb1 UD |
1258 | parameter to @code{nftw}. |
1259 | @item FTW_CHDIR | |
1260 | If this flag is given the current working directory is changed to the | |
04b9968b UD |
1261 | directory of the reported object before the callback function is called. |
1262 | When @code{ntfw} finally returns the current directory is restored to | |
1263 | its original value. | |
2604afb1 | 1264 | @item FTW_DEPTH |
04b9968b UD |
1265 | If this option is specified then all subdirectories and files within |
1266 | them are processed before processing the top directory itself | |
1267 | (depth-first processing). This also means the type flag given to the | |
1268 | callback function is @code{FTW_DP} and not @code{FTW_D}. | |
ca10f338 UD |
1269 | @item FTW_ACTIONRETVAL |
1270 | If this option is specified then return values from callbacks | |
1271 | are handled differently. If the callback returns @code{FTW_CONTINUE}, | |
1272 | walking continues normally. @code{FTW_STOP} means walking stops | |
1273 | and @code{FTW_STOP} is returned to the caller. If @code{FTW_SKIP_SUBTREE} | |
1274 | is returned by the callback with @code{FTW_D} argument, the subtree | |
1275 | is skipped and walking continues with next sibling of the directory. | |
1276 | If @code{FTW_SKIP_SIBLINGS} is returned by the callback, all siblings | |
1277 | of the current entry are skipped and walking continues in its parent. | |
1278 | No other return values should be returned from the callbacks if | |
1279 | this option is set. This option is a GNU extension. | |
a3a4a74e | 1280 | @end vtable |
2604afb1 UD |
1281 | |
1282 | The return value is computed in the same way as for @code{ftw}. | |
04b9968b UD |
1283 | @code{nftw} returns @math{0} if no failures occurred and all callback |
1284 | functions returned @math{0}. In case of internal errors, such as memory | |
010fe231 | 1285 | problems, the return value is @math{-1} and @code{errno} is set |
04b9968b UD |
1286 | accordingly. If the return value of a callback invocation was non-zero |
1287 | then that value is returned. | |
a3a4a74e UD |
1288 | |
1289 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
11bf311e | 1290 | 32-bit system this function is in fact @code{nftw64}, i.e., the LFS |
a3a4a74e UD |
1291 | interface transparently replaces the old interface. |
1292 | @end deftypefun | |
1293 | ||
a3a4a74e | 1294 | @deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag}) |
d08a7e4c | 1295 | @standards{Unix98, ftw.h} |
de55fdf4 | 1296 | @safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}} |
a3a4a74e | 1297 | This function is similar to @code{nftw} but it can work on filesystems |
04b9968b UD |
1298 | with large files. File information is reported using a variable of type |
1299 | @code{struct stat64} which is passed by reference to the callback | |
1300 | function. | |
a3a4a74e UD |
1301 | |
1302 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
04b9968b | 1303 | 32-bit system this function is available under the name @code{nftw} and |
a3a4a74e | 1304 | transparently replaces the old implementation. |
2604afb1 UD |
1305 | @end deftypefun |
1306 | ||
1307 | ||
28f540f4 RM |
1308 | @node Hard Links |
1309 | @section Hard Links | |
1310 | @cindex hard link | |
1311 | @cindex link, hard | |
1312 | @cindex multiple names for one file | |
1313 | @cindex file names, multiple | |
1314 | ||
1315 | In POSIX systems, one file can have many names at the same time. All of | |
1316 | the names are equally real, and no one of them is preferred to the | |
1317 | others. | |
1318 | ||
1319 | To add a name to a file, use the @code{link} function. (The new name is | |
1320 | also called a @dfn{hard link} to the file.) Creating a new link to a | |
1321 | file does not copy the contents of the file; it simply makes a new name | |
1322 | by which the file can be known, in addition to the file's existing name | |
1323 | or names. | |
1324 | ||
3081378b | 1325 | One file can have names in several directories, so the organization |
28f540f4 RM |
1326 | of the file system is not a strict hierarchy or tree. |
1327 | ||
1328 | In most implementations, it is not possible to have hard links to the | |
1329 | same file in multiple file systems. @code{link} reports an error if you | |
1330 | try to make a hard link to the file from another file system when this | |
1331 | cannot be done. | |
1332 | ||
1333 | The prototype for the @code{link} function is declared in the header | |
1334 | file @file{unistd.h}. | |
1335 | @pindex unistd.h | |
1336 | ||
28f540f4 | 1337 | @deftypefun int link (const char *@var{oldname}, const char *@var{newname}) |
d08a7e4c | 1338 | @standards{POSIX.1, unistd.h} |
de55fdf4 | 1339 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
1340 | The @code{link} function makes a new link to the existing file named by |
1341 | @var{oldname}, under the new name @var{newname}. | |
1342 | ||
1343 | This function returns a value of @code{0} if it is successful and | |
1344 | @code{-1} on failure. In addition to the usual file name errors | |
1345 | (@pxref{File Name Errors}) for both @var{oldname} and @var{newname}, the | |
1346 | following @code{errno} error conditions are defined for this function: | |
1347 | ||
1348 | @table @code | |
1349 | @item EACCES | |
04b9968b UD |
1350 | You are not allowed to write to the directory in which the new link is |
1351 | to be written. | |
d68171ed | 1352 | @ignore |
28f540f4 RM |
1353 | Some implementations also require that the existing file be accessible |
1354 | by the caller, and use this error to report failure for that reason. | |
1355 | @end ignore | |
1356 | ||
1357 | @item EEXIST | |
1358 | There is already a file named @var{newname}. If you want to replace | |
1359 | this link with a new link, you must remove the old link explicitly first. | |
1360 | ||
1361 | @item EMLINK | |
1362 | There are already too many links to the file named by @var{oldname}. | |
1363 | (The maximum number of links to a file is @w{@code{LINK_MAX}}; see | |
1364 | @ref{Limits for Files}.) | |
1365 | ||
1366 | @item ENOENT | |
1367 | The file named by @var{oldname} doesn't exist. You can't make a link to | |
1368 | a file that doesn't exist. | |
1369 | ||
1370 | @item ENOSPC | |
1371 | The directory or file system that would contain the new link is full | |
1372 | and cannot be extended. | |
1373 | ||
1374 | @item EPERM | |
a7a93d50 JM |
1375 | On @gnulinuxhurdsystems{} and some others, you cannot make links to |
1376 | directories. | |
28f540f4 RM |
1377 | Many systems allow only privileged users to do so. This error |
1378 | is used to report the problem. | |
1379 | ||
1380 | @item EROFS | |
1381 | The directory containing the new link can't be modified because it's on | |
1382 | a read-only file system. | |
1383 | ||
1384 | @item EXDEV | |
1385 | The directory specified in @var{newname} is on a different file system | |
1386 | than the existing file. | |
1387 | ||
1388 | @item EIO | |
1389 | A hardware error occurred while trying to read or write the to filesystem. | |
1390 | @end table | |
1391 | @end deftypefun | |
1392 | ||
bc18a6d3 FW |
1393 | @deftypefun int linkat (int oldfd, const char *@var{oldname}, int newfd, const char *@var{newname}, int flags) |
1394 | @standards{POSIX.1, unistd.h} | |
1395 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
1396 | ||
1397 | The @code{linkat} function is analogous to the @code{link} function, | |
1398 | except that it identifies its source and target using a combination of a | |
3de73f97 FW |
1399 | file descriptor (referring to a directory) and a file name. |
1400 | @xref{Descriptor-Relative Access}. For @code{linkat}, if a file name is | |
1401 | not absolute, it is resolved relative to the corresponding file | |
1402 | descriptor. As usual, the special value @code{AT_FDCWD} denotes the | |
1403 | current directory. | |
bc18a6d3 FW |
1404 | |
1405 | The @var{flags} argument is a combination of the following flags: | |
1406 | ||
1407 | @table @code | |
1408 | @item AT_SYMLINK_FOLLOW | |
1409 | If the source path identified by @var{oldfd} and @var{oldname} is a | |
1410 | symbolic link, @code{linkat} follows the symbolic link and creates a | |
1411 | link to its target. If the flag is not set, a link for the symbolic | |
1412 | link itself is created; this is not supported by all file systems and | |
1413 | @code{linkat} can fail in this case. | |
1414 | ||
1415 | @item AT_EMPTY_PATH | |
1416 | If this flag is specified, @var{oldname} can be an empty string. In | |
1417 | this case, a new link to the file denoted by the descriptor @var{oldfd} | |
1418 | is created, which may have been opened with @code{O_PATH} or | |
1419 | @code{O_TMPFILE}. This flag is a GNU extension. | |
1420 | @end table | |
1421 | @end deftypefun | |
1422 | ||
28f540f4 RM |
1423 | @node Symbolic Links |
1424 | @section Symbolic Links | |
1425 | @cindex soft link | |
1426 | @cindex link, soft | |
1427 | @cindex symbolic link | |
1428 | @cindex link, symbolic | |
1429 | ||
a7a93d50 | 1430 | @gnusystems{} support @dfn{soft links} or @dfn{symbolic links}. This |
28f540f4 RM |
1431 | is a kind of ``file'' that is essentially a pointer to another file |
1432 | name. Unlike hard links, symbolic links can be made to directories or | |
1433 | across file systems with no restrictions. You can also make a symbolic | |
1434 | link to a name which is not the name of any file. (Opening this link | |
1435 | will fail until a file by that name is created.) Likewise, if the | |
1436 | symbolic link points to an existing file which is later deleted, the | |
1437 | symbolic link continues to point to the same file name even though the | |
1438 | name no longer names any file. | |
1439 | ||
1440 | The reason symbolic links work the way they do is that special things | |
1441 | happen when you try to open the link. The @code{open} function realizes | |
1442 | you have specified the name of a link, reads the file name contained in | |
1443 | the link, and opens that file name instead. The @code{stat} function | |
1444 | likewise operates on the file that the symbolic link points to, instead | |
1445 | of on the link itself. | |
1446 | ||
1447 | By contrast, other operations such as deleting or renaming the file | |
1448 | operate on the link itself. The functions @code{readlink} and | |
1449 | @code{lstat} also refrain from following symbolic links, because their | |
04b9968b UD |
1450 | purpose is to obtain information about the link. @code{link}, the |
1451 | function that makes a hard link, does too. It makes a hard link to the | |
28f540f4 RM |
1452 | symbolic link, which one rarely wants. |
1453 | ||
4ffa3672 | 1454 | Some systems have, for some functions operating on files, a limit on |
eacde9d0 UD |
1455 | how many symbolic links are followed when resolving a path name. The |
1456 | limit if it exists is published in the @file{sys/param.h} header file. | |
1457 | ||
eacde9d0 | 1458 | @deftypevr Macro int MAXSYMLINKS |
d08a7e4c | 1459 | @standards{BSD, sys/param.h} |
eacde9d0 UD |
1460 | |
1461 | The macro @code{MAXSYMLINKS} specifies how many symlinks some function | |
1462 | will follow before returning @code{ELOOP}. Not all functions behave the | |
4ffa3672 | 1463 | same and this value is not the same as that returned for |
eacde9d0 UD |
1464 | @code{_SC_SYMLOOP} by @code{sysconf}. In fact, the @code{sysconf} |
1465 | result can indicate that there is no fixed limit although | |
1466 | @code{MAXSYMLINKS} exists and has a finite value. | |
1467 | @end deftypevr | |
1468 | ||
1469 | Prototypes for most of the functions listed in this section are in | |
28f540f4 RM |
1470 | @file{unistd.h}. |
1471 | @pindex unistd.h | |
1472 | ||
28f540f4 | 1473 | @deftypefun int symlink (const char *@var{oldname}, const char *@var{newname}) |
d08a7e4c | 1474 | @standards{BSD, unistd.h} |
de55fdf4 | 1475 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
1476 | The @code{symlink} function makes a symbolic link to @var{oldname} named |
1477 | @var{newname}. | |
1478 | ||
1479 | The normal return value from @code{symlink} is @code{0}. A return value | |
1480 | of @code{-1} indicates an error. In addition to the usual file name | |
1481 | syntax errors (@pxref{File Name Errors}), the following @code{errno} | |
1482 | error conditions are defined for this function: | |
1483 | ||
1484 | @table @code | |
1485 | @item EEXIST | |
1486 | There is already an existing file named @var{newname}. | |
1487 | ||
1488 | @item EROFS | |
1489 | The file @var{newname} would exist on a read-only file system. | |
1490 | ||
1491 | @item ENOSPC | |
1492 | The directory or file system cannot be extended to make the new link. | |
1493 | ||
1494 | @item EIO | |
1495 | A hardware error occurred while reading or writing data on the disk. | |
1496 | ||
28f540f4 | 1497 | @comment not sure about these |
f227c3e0 | 1498 | @ignore |
28f540f4 RM |
1499 | @item ELOOP |
1500 | There are too many levels of indirection. This can be the result of | |
1501 | circular symbolic links to directories. | |
1502 | ||
1503 | @item EDQUOT | |
1504 | The new link can't be created because the user's disk quota has been | |
1505 | exceeded. | |
1506 | @end ignore | |
1507 | @end table | |
1508 | @end deftypefun | |
1509 | ||
8ded91fb | 1510 | @deftypefun ssize_t readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size}) |
d08a7e4c | 1511 | @standards{BSD, unistd.h} |
de55fdf4 | 1512 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
1513 | The @code{readlink} function gets the value of the symbolic link |
1514 | @var{filename}. The file name that the link points to is copied into | |
1515 | @var{buffer}. This file name string is @emph{not} null-terminated; | |
1516 | @code{readlink} normally returns the number of characters copied. The | |
1517 | @var{size} argument specifies the maximum number of characters to copy, | |
1518 | usually the allocation size of @var{buffer}. | |
1519 | ||
1520 | If the return value equals @var{size}, you cannot tell whether or not | |
1521 | there was room to return the entire name. So make a bigger buffer and | |
1522 | call @code{readlink} again. Here is an example: | |
1523 | ||
1524 | @smallexample | |
1525 | char * | |
1054384a | 1526 | readlink_malloc (const char *filename) |
28f540f4 | 1527 | @{ |
bdc674d9 | 1528 | size_t size = 50; |
c0a0f9a3 | 1529 | char *buffer = NULL; |
28f540f4 RM |
1530 | |
1531 | while (1) | |
1532 | @{ | |
bdc674d9 PE |
1533 | buffer = xreallocarray (buffer, size, 2); |
1534 | size *= 2; | |
1535 | ssize_t nchars = readlink (filename, buffer, size); | |
1054384a | 1536 | if (nchars < 0) |
c0a0f9a3 UD |
1537 | @{ |
1538 | free (buffer); | |
1539 | return NULL; | |
1540 | @} | |
28f540f4 RM |
1541 | if (nchars < size) |
1542 | return buffer; | |
28f540f4 RM |
1543 | @} |
1544 | @} | |
1545 | @end smallexample | |
1546 | ||
1547 | @c @group Invalid outside example. | |
1548 | A value of @code{-1} is returned in case of error. In addition to the | |
1549 | usual file name errors (@pxref{File Name Errors}), the following | |
1550 | @code{errno} error conditions are defined for this function: | |
1551 | ||
1552 | @table @code | |
1553 | @item EINVAL | |
1554 | The named file is not a symbolic link. | |
1555 | ||
1556 | @item EIO | |
1557 | A hardware error occurred while reading or writing data on the disk. | |
1558 | @end table | |
1559 | @c @end group | |
1560 | @end deftypefun | |
1561 | ||
120aad54 UD |
1562 | In some situations it is desirable to resolve all the |
1563 | symbolic links to get the real | |
eacde9d0 UD |
1564 | name of a file where no prefix names a symbolic link which is followed |
1565 | and no filename in the path is @code{.} or @code{..}. This is for | |
4ffa3672 | 1566 | instance desirable if files have to be compared in which case different |
eacde9d0 UD |
1567 | names can refer to the same inode. |
1568 | ||
eacde9d0 | 1569 | @deftypefun {char *} canonicalize_file_name (const char *@var{name}) |
d08a7e4c | 1570 | @standards{GNU, stdlib.h} |
de55fdf4 AO |
1571 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
1572 | @c Calls realpath. | |
eacde9d0 UD |
1573 | |
1574 | The @code{canonicalize_file_name} function returns the absolute name of | |
1575 | the file named by @var{name} which contains no @code{.}, @code{..} | |
1576 | components nor any repeated path separators (@code{/}) or symlinks. The | |
1577 | result is passed back as the return value of the function in a block of | |
1578 | memory allocated with @code{malloc}. If the result is not used anymore | |
1579 | the memory should be freed with a call to @code{free}. | |
1580 | ||
4ffa3672 | 1581 | If any of the path components are missing the function returns a NULL |
fd63cc3b AJ |
1582 | pointer. This is also what is returned if the length of the path |
1583 | reaches or exceeds @code{PATH_MAX} characters. In any case | |
1584 | @code{errno} is set accordingly. | |
eacde9d0 UD |
1585 | |
1586 | @table @code | |
1587 | @item ENAMETOOLONG | |
1588 | The resulting path is too long. This error only occurs on systems which | |
1589 | have a limit on the file name length. | |
1590 | ||
1591 | @item EACCES | |
1592 | At least one of the path components is not readable. | |
1593 | ||
1594 | @item ENOENT | |
1595 | The input file name is empty. | |
1596 | ||
1597 | @item ENOENT | |
1598 | At least one of the path components does not exist. | |
1599 | ||
1600 | @item ELOOP | |
1601 | More than @code{MAXSYMLINKS} many symlinks have been followed. | |
1602 | @end table | |
1603 | ||
1604 | This function is a GNU extension and is declared in @file{stdlib.h}. | |
1605 | @end deftypefun | |
1606 | ||
1607 | The Unix standard includes a similar function which differs from | |
1608 | @code{canonicalize_file_name} in that the user has to provide the buffer | |
1609 | where the result is placed in. | |
1610 | ||
eacde9d0 | 1611 | @deftypefun {char *} realpath (const char *restrict @var{name}, char *restrict @var{resolved}) |
d08a7e4c | 1612 | @standards{XPG, stdlib.h} |
de55fdf4 AO |
1613 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
1614 | @c Calls malloc, realloc, getcwd, lxstat64, readlink, alloca. | |
eacde9d0 | 1615 | |
9905e036 UD |
1616 | A call to @code{realpath} where the @var{resolved} parameter is |
1617 | @code{NULL} behaves exactly like @code{canonicalize_file_name}. The | |
1618 | function allocates a buffer for the file name and returns a pointer to | |
1619 | it. If @var{resolved} is not @code{NULL} it points to a buffer into | |
1620 | which the result is copied. It is the callers responsibility to | |
1621 | allocate a buffer which is large enough. On systems which define | |
1622 | @code{PATH_MAX} this means the buffer must be large enough for a | |
1623 | pathname of this size. For systems without limitations on the pathname | |
1624 | length the requirement cannot be met and programs should not call | |
1625 | @code{realpath} with anything but @code{NULL} for the second parameter. | |
1626 | ||
1627 | One other difference is that the buffer @var{resolved} (if nonzero) will | |
1628 | contain the part of the path component which does not exist or is not | |
1629 | readable if the function returns @code{NULL} and @code{errno} is set to | |
eacde9d0 UD |
1630 | @code{EACCES} or @code{ENOENT}. |
1631 | ||
1632 | This function is declared in @file{stdlib.h}. | |
1633 | @end deftypefun | |
1634 | ||
1635 | The advantage of using this function is that it is more widely | |
4ffa3672 | 1636 | available. The drawback is that it reports failures for long paths on |
eacde9d0 UD |
1637 | systems which have no limits on the file name length. |
1638 | ||
28f540f4 RM |
1639 | @node Deleting Files |
1640 | @section Deleting Files | |
1641 | @cindex deleting a file | |
1642 | @cindex removing a file | |
1643 | @cindex unlinking a file | |
1644 | ||
04b9968b | 1645 | You can delete a file with @code{unlink} or @code{remove}. |
28f540f4 RM |
1646 | |
1647 | Deletion actually deletes a file name. If this is the file's only name, | |
04b9968b UD |
1648 | then the file is deleted as well. If the file has other remaining names |
1649 | (@pxref{Hard Links}), it remains accessible under those names. | |
28f540f4 | 1650 | |
28f540f4 | 1651 | @deftypefun int unlink (const char *@var{filename}) |
d08a7e4c | 1652 | @standards{POSIX.1, unistd.h} |
de55fdf4 | 1653 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
1654 | The @code{unlink} function deletes the file name @var{filename}. If |
1655 | this is a file's sole name, the file itself is also deleted. (Actually, | |
1656 | if any process has the file open when this happens, deletion is | |
1657 | postponed until all processes have closed the file.) | |
1658 | ||
1659 | @pindex unistd.h | |
1660 | The function @code{unlink} is declared in the header file @file{unistd.h}. | |
1661 | ||
1662 | This function returns @code{0} on successful completion, and @code{-1} | |
1663 | on error. In addition to the usual file name errors | |
d68171ed | 1664 | (@pxref{File Name Errors}), the following @code{errno} error conditions are |
28f540f4 RM |
1665 | defined for this function: |
1666 | ||
1667 | @table @code | |
1668 | @item EACCES | |
1669 | Write permission is denied for the directory from which the file is to be | |
1670 | removed, or the directory has the sticky bit set and you do not own the file. | |
1671 | ||
1672 | @item EBUSY | |
1673 | This error indicates that the file is being used by the system in such a | |
1674 | way that it can't be unlinked. For example, you might see this error if | |
1675 | the file name specifies the root directory or a mount point for a file | |
1676 | system. | |
1677 | ||
1678 | @item ENOENT | |
1679 | The file name to be deleted doesn't exist. | |
1680 | ||
1681 | @item EPERM | |
04b9968b UD |
1682 | On some systems @code{unlink} cannot be used to delete the name of a |
1683 | directory, or at least can only be used this way by a privileged user. | |
a7a93d50 JM |
1684 | To avoid such problems, use @code{rmdir} to delete directories. (On |
1685 | @gnulinuxhurdsystems{} @code{unlink} can never delete the name of a directory.) | |
28f540f4 RM |
1686 | |
1687 | @item EROFS | |
04b9968b UD |
1688 | The directory containing the file name to be deleted is on a read-only |
1689 | file system and can't be modified. | |
28f540f4 RM |
1690 | @end table |
1691 | @end deftypefun | |
1692 | ||
28f540f4 | 1693 | @deftypefun int rmdir (const char *@var{filename}) |
d08a7e4c | 1694 | @standards{POSIX.1, unistd.h} |
de55fdf4 | 1695 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
1696 | @cindex directories, deleting |
1697 | @cindex deleting a directory | |
1698 | The @code{rmdir} function deletes a directory. The directory must be | |
1699 | empty before it can be removed; in other words, it can only contain | |
1700 | entries for @file{.} and @file{..}. | |
1701 | ||
1702 | In most other respects, @code{rmdir} behaves like @code{unlink}. There | |
1703 | are two additional @code{errno} error conditions defined for | |
1704 | @code{rmdir}: | |
1705 | ||
1706 | @table @code | |
1707 | @item ENOTEMPTY | |
1708 | @itemx EEXIST | |
d68171ed | 1709 | The directory to be deleted is not empty. |
28f540f4 RM |
1710 | @end table |
1711 | ||
1712 | These two error codes are synonymous; some systems use one, and some use | |
a7a93d50 | 1713 | the other. @gnulinuxhurdsystems{} always use @code{ENOTEMPTY}. |
28f540f4 RM |
1714 | |
1715 | The prototype for this function is declared in the header file | |
1716 | @file{unistd.h}. | |
1717 | @pindex unistd.h | |
1718 | @end deftypefun | |
1719 | ||
28f540f4 | 1720 | @deftypefun int remove (const char *@var{filename}) |
d08a7e4c | 1721 | @standards{ISO, stdio.h} |
de55fdf4 AO |
1722 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1723 | @c Calls unlink and rmdir. | |
f65fd747 | 1724 | This is the @w{ISO C} function to remove a file. It works like |
28f540f4 RM |
1725 | @code{unlink} for files and like @code{rmdir} for directories. |
1726 | @code{remove} is declared in @file{stdio.h}. | |
1727 | @pindex stdio.h | |
1728 | @end deftypefun | |
1729 | ||
1730 | @node Renaming Files | |
1731 | @section Renaming Files | |
1732 | ||
1733 | The @code{rename} function is used to change a file's name. | |
1734 | ||
1735 | @cindex renaming a file | |
28f540f4 | 1736 | @deftypefun int rename (const char *@var{oldname}, const char *@var{newname}) |
d08a7e4c | 1737 | @standards{ISO, stdio.h} |
de55fdf4 AO |
1738 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1739 | @c In the absence of a rename syscall, there's an emulation with link | |
1740 | @c and unlink, but it's racy, even more so if newname exists and is | |
1741 | @c unlinked first. | |
04b9968b | 1742 | The @code{rename} function renames the file @var{oldname} to |
28f540f4 | 1743 | @var{newname}. The file formerly accessible under the name |
04b9968b UD |
1744 | @var{oldname} is afterwards accessible as @var{newname} instead. (If |
1745 | the file had any other names aside from @var{oldname}, it continues to | |
1746 | have those names.) | |
28f540f4 | 1747 | |
04b9968b UD |
1748 | The directory containing the name @var{newname} must be on the same file |
1749 | system as the directory containing the name @var{oldname}. | |
28f540f4 RM |
1750 | |
1751 | One special case for @code{rename} is when @var{oldname} and | |
1752 | @var{newname} are two names for the same file. The consistent way to | |
04b9968b UD |
1753 | handle this case is to delete @var{oldname}. However, in this case |
1754 | POSIX requires that @code{rename} do nothing and report success---which | |
1755 | is inconsistent. We don't know what your operating system will do. | |
28f540f4 | 1756 | |
04b9968b | 1757 | If @var{oldname} is not a directory, then any existing file named |
28f540f4 RM |
1758 | @var{newname} is removed during the renaming operation. However, if |
1759 | @var{newname} is the name of a directory, @code{rename} fails in this | |
1760 | case. | |
1761 | ||
04b9968b | 1762 | If @var{oldname} is a directory, then either @var{newname} must not |
28f540f4 RM |
1763 | exist or it must name a directory that is empty. In the latter case, |
1764 | the existing directory named @var{newname} is deleted first. The name | |
1765 | @var{newname} must not specify a subdirectory of the directory | |
1766 | @code{oldname} which is being renamed. | |
1767 | ||
04b9968b UD |
1768 | One useful feature of @code{rename} is that the meaning of @var{newname} |
1769 | changes ``atomically'' from any previously existing file by that name to | |
11bf311e | 1770 | its new meaning (i.e., the file that was called @var{oldname}). There is |
04b9968b UD |
1771 | no instant at which @var{newname} is non-existent ``in between'' the old |
1772 | meaning and the new meaning. If there is a system crash during the | |
1773 | operation, it is possible for both names to still exist; but | |
1774 | @var{newname} will always be intact if it exists at all. | |
28f540f4 RM |
1775 | |
1776 | If @code{rename} fails, it returns @code{-1}. In addition to the usual | |
1777 | file name errors (@pxref{File Name Errors}), the following | |
1778 | @code{errno} error conditions are defined for this function: | |
1779 | ||
1780 | @table @code | |
1781 | @item EACCES | |
1782 | One of the directories containing @var{newname} or @var{oldname} | |
1783 | refuses write permission; or @var{newname} and @var{oldname} are | |
1784 | directories and write permission is refused for one of them. | |
1785 | ||
1786 | @item EBUSY | |
1787 | A directory named by @var{oldname} or @var{newname} is being used by | |
1788 | the system in a way that prevents the renaming from working. This includes | |
1789 | directories that are mount points for filesystems, and directories | |
1790 | that are the current working directories of processes. | |
1791 | ||
1792 | @item ENOTEMPTY | |
1793 | @itemx EEXIST | |
a7a93d50 | 1794 | The directory @var{newname} isn't empty. @gnulinuxhurdsystems{} always return |
28f540f4 RM |
1795 | @code{ENOTEMPTY} for this, but some other systems return @code{EEXIST}. |
1796 | ||
1797 | @item EINVAL | |
04b9968b | 1798 | @var{oldname} is a directory that contains @var{newname}. |
28f540f4 RM |
1799 | |
1800 | @item EISDIR | |
04b9968b | 1801 | @var{newname} is a directory but the @var{oldname} isn't. |
28f540f4 RM |
1802 | |
1803 | @item EMLINK | |
04b9968b UD |
1804 | The parent directory of @var{newname} would have too many links |
1805 | (entries). | |
28f540f4 RM |
1806 | |
1807 | @item ENOENT | |
04b9968b | 1808 | The file @var{oldname} doesn't exist. |
28f540f4 RM |
1809 | |
1810 | @item ENOSPC | |
1811 | The directory that would contain @var{newname} has no room for another | |
1812 | entry, and there is no space left in the file system to expand it. | |
1813 | ||
1814 | @item EROFS | |
1815 | The operation would involve writing to a directory on a read-only file | |
1816 | system. | |
1817 | ||
1818 | @item EXDEV | |
04b9968b | 1819 | The two file names @var{newname} and @var{oldname} are on different |
28f540f4 RM |
1820 | file systems. |
1821 | @end table | |
1822 | @end deftypefun | |
1823 | ||
1824 | @node Creating Directories | |
1825 | @section Creating Directories | |
1826 | @cindex creating a directory | |
1827 | @cindex directories, creating | |
1828 | ||
1829 | @pindex mkdir | |
1830 | Directories are created with the @code{mkdir} function. (There is also | |
1831 | a shell command @code{mkdir} which does the same thing.) | |
1832 | @c !!! umask | |
1833 | ||
28f540f4 | 1834 | @deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode}) |
d08a7e4c | 1835 | @standards{POSIX.1, sys/stat.h} |
de55fdf4 | 1836 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b | 1837 | The @code{mkdir} function creates a new, empty directory with name |
28f540f4 RM |
1838 | @var{filename}. |
1839 | ||
1840 | The argument @var{mode} specifies the file permissions for the new | |
1841 | directory file. @xref{Permission Bits}, for more information about | |
1842 | this. | |
1843 | ||
1844 | A return value of @code{0} indicates successful completion, and | |
1845 | @code{-1} indicates failure. In addition to the usual file name syntax | |
1846 | errors (@pxref{File Name Errors}), the following @code{errno} error | |
1847 | conditions are defined for this function: | |
1848 | ||
1849 | @table @code | |
1850 | @item EACCES | |
1851 | Write permission is denied for the parent directory in which the new | |
1852 | directory is to be added. | |
1853 | ||
1854 | @item EEXIST | |
1855 | A file named @var{filename} already exists. | |
1856 | ||
1857 | @item EMLINK | |
04b9968b | 1858 | The parent directory has too many links (entries). |
28f540f4 RM |
1859 | |
1860 | Well-designed file systems never report this error, because they permit | |
1861 | more links than your disk could possibly hold. However, you must still | |
1862 | take account of the possibility of this error, as it could result from | |
1863 | network access to a file system on another machine. | |
1864 | ||
1865 | @item ENOSPC | |
1866 | The file system doesn't have enough room to create the new directory. | |
1867 | ||
1868 | @item EROFS | |
1869 | The parent directory of the directory being created is on a read-only | |
04b9968b | 1870 | file system and cannot be modified. |
28f540f4 RM |
1871 | @end table |
1872 | ||
1873 | To use this function, your program should include the header file | |
1874 | @file{sys/stat.h}. | |
1875 | @pindex sys/stat.h | |
1876 | @end deftypefun | |
1877 | ||
1878 | @node File Attributes | |
1879 | @section File Attributes | |
1880 | ||
1881 | @pindex ls | |
1882 | When you issue an @samp{ls -l} shell command on a file, it gives you | |
1883 | information about the size of the file, who owns it, when it was last | |
04b9968b UD |
1884 | modified, etc. These are called the @dfn{file attributes}, and are |
1885 | associated with the file itself and not a particular one of its names. | |
28f540f4 RM |
1886 | |
1887 | This section contains information about how you can inquire about and | |
04b9968b | 1888 | modify the attributes of a file. |
28f540f4 RM |
1889 | |
1890 | @menu | |
d68171ed | 1891 | * Attribute Meanings:: The names of the file attributes, |
28f540f4 RM |
1892 | and what their values mean. |
1893 | * Reading Attributes:: How to read the attributes of a file. | |
1894 | * Testing File Type:: Distinguishing ordinary files, | |
95fdc6a0 | 1895 | directories, links@dots{} |
28f540f4 RM |
1896 | * File Owner:: How ownership for new files is determined, |
1897 | and how to change it. | |
1898 | * Permission Bits:: How information about a file's access | |
d68171ed | 1899 | mode is stored. |
28f540f4 RM |
1900 | * Access Permission:: How the system decides who can access a file. |
1901 | * Setting Permissions:: How permissions for new files are assigned, | |
1902 | and how to change them. | |
1903 | * Testing File Access:: How to find out if your process can | |
d68171ed | 1904 | access a file. |
28f540f4 | 1905 | * File Times:: About the time attributes of a file. |
7ce241a0 | 1906 | * File Size:: Manually changing the size of a file. |
7fe9e2e0 | 1907 | * Storage Allocation:: Allocate backing storage for files. |
28f540f4 RM |
1908 | @end menu |
1909 | ||
1910 | @node Attribute Meanings | |
04b9968b | 1911 | @subsection The meaning of the File Attributes |
28f540f4 RM |
1912 | @cindex status of a file |
1913 | @cindex attributes of a file | |
1914 | @cindex file attributes | |
1915 | ||
1916 | When you read the attributes of a file, they come back in a structure | |
1917 | called @code{struct stat}. This section describes the names of the | |
1918 | attributes, their data types, and what they mean. For the functions | |
1919 | to read the attributes of a file, see @ref{Reading Attributes}. | |
1920 | ||
1921 | The header file @file{sys/stat.h} declares all the symbols defined | |
1922 | in this section. | |
1923 | @pindex sys/stat.h | |
1924 | ||
28f540f4 | 1925 | @deftp {Data Type} {struct stat} |
d08a7e4c | 1926 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
1927 | The @code{stat} structure type is used to return information about the |
1928 | attributes of a file. It contains at least the following members: | |
1929 | ||
1930 | @table @code | |
1931 | @item mode_t st_mode | |
1932 | Specifies the mode of the file. This includes file type information | |
1933 | (@pxref{Testing File Type}) and the file permission bits | |
1934 | (@pxref{Permission Bits}). | |
1935 | ||
1936 | @item ino_t st_ino | |
1937 | The file serial number, which distinguishes this file from all other | |
1938 | files on the same device. | |
1939 | ||
1940 | @item dev_t st_dev | |
1941 | Identifies the device containing the file. The @code{st_ino} and | |
1942 | @code{st_dev}, taken together, uniquely identify the file. The | |
1943 | @code{st_dev} value is not necessarily consistent across reboots or | |
1944 | system crashes, however. | |
1945 | ||
1946 | @item nlink_t st_nlink | |
1947 | The number of hard links to the file. This count keeps track of how | |
1948 | many directories have entries for this file. If the count is ever | |
1949 | decremented to zero, then the file itself is discarded as soon as no | |
1950 | process still holds it open. Symbolic links are not counted in the | |
1951 | total. | |
1952 | ||
1953 | @item uid_t st_uid | |
1954 | The user ID of the file's owner. @xref{File Owner}. | |
1955 | ||
1956 | @item gid_t st_gid | |
1957 | The group ID of the file. @xref{File Owner}. | |
1958 | ||
1959 | @item off_t st_size | |
04b9968b UD |
1960 | This specifies the size of a regular file in bytes. For files that are |
1961 | really devices this field isn't usually meaningful. For symbolic links | |
1962 | this specifies the length of the file name the link refers to. | |
28f540f4 RM |
1963 | |
1964 | @item time_t st_atime | |
1965 | This is the last access time for the file. @xref{File Times}. | |
1966 | ||
1967 | @item unsigned long int st_atime_usec | |
1968 | This is the fractional part of the last access time for the file. | |
1969 | @xref{File Times}. | |
1970 | ||
1971 | @item time_t st_mtime | |
1972 | This is the time of the last modification to the contents of the file. | |
1973 | @xref{File Times}. | |
1974 | ||
1975 | @item unsigned long int st_mtime_usec | |
04b9968b | 1976 | This is the fractional part of the time of the last modification to the |
28f540f4 RM |
1977 | contents of the file. @xref{File Times}. |
1978 | ||
1979 | @item time_t st_ctime | |
1980 | This is the time of the last modification to the attributes of the file. | |
1981 | @xref{File Times}. | |
1982 | ||
1983 | @item unsigned long int st_ctime_usec | |
04b9968b | 1984 | This is the fractional part of the time of the last modification to the |
28f540f4 RM |
1985 | attributes of the file. @xref{File Times}. |
1986 | ||
1987 | @c !!! st_rdev | |
a3a4a74e | 1988 | @item blkcnt_t st_blocks |
28f540f4 RM |
1989 | This is the amount of disk space that the file occupies, measured in |
1990 | units of 512-byte blocks. | |
1991 | ||
1992 | The number of disk blocks is not strictly proportional to the size of | |
1993 | the file, for two reasons: the file system may use some blocks for | |
1994 | internal record keeping; and the file may be sparse---it may have | |
1995 | ``holes'' which contain zeros but do not actually take up space on the | |
1996 | disk. | |
1997 | ||
1998 | You can tell (approximately) whether a file is sparse by comparing this | |
1999 | value with @code{st_size}, like this: | |
2000 | ||
2001 | @smallexample | |
2002 | (st.st_blocks * 512 < st.st_size) | |
2003 | @end smallexample | |
2004 | ||
2005 | This test is not perfect because a file that is just slightly sparse | |
2006 | might not be detected as sparse at all. For practical applications, | |
2007 | this is not a problem. | |
2008 | ||
2009 | @item unsigned int st_blksize | |
4ffa3672 RJ |
2010 | The optimal block size for reading or writing this file, in bytes. You |
2011 | might use this size for allocating the buffer space for reading or | |
28f540f4 RM |
2012 | writing the file. (This is unrelated to @code{st_blocks}.) |
2013 | @end table | |
2014 | @end deftp | |
2015 | ||
04b9968b | 2016 | The extensions for the Large File Support (LFS) require, even on 32-bit |
9ceeb279 | 2017 | machines, types which can handle file sizes up to @twoexp{63}. |
04b9968b | 2018 | Therefore a new definition of @code{struct stat} is necessary. |
a3a4a74e | 2019 | |
a3a4a74e | 2020 | @deftp {Data Type} {struct stat64} |
d08a7e4c | 2021 | @standards{LFS, sys/stat.h} |
a3a4a74e UD |
2022 | The members of this type are the same and have the same names as those |
2023 | in @code{struct stat}. The only difference is that the members | |
2024 | @code{st_ino}, @code{st_size}, and @code{st_blocks} have a different | |
2025 | type to support larger values. | |
2026 | ||
2027 | @table @code | |
2028 | @item mode_t st_mode | |
2029 | Specifies the mode of the file. This includes file type information | |
2030 | (@pxref{Testing File Type}) and the file permission bits | |
2031 | (@pxref{Permission Bits}). | |
2032 | ||
2033 | @item ino64_t st_ino | |
2034 | The file serial number, which distinguishes this file from all other | |
2035 | files on the same device. | |
2036 | ||
2037 | @item dev_t st_dev | |
2038 | Identifies the device containing the file. The @code{st_ino} and | |
2039 | @code{st_dev}, taken together, uniquely identify the file. The | |
2040 | @code{st_dev} value is not necessarily consistent across reboots or | |
2041 | system crashes, however. | |
2042 | ||
2043 | @item nlink_t st_nlink | |
2044 | The number of hard links to the file. This count keeps track of how | |
2045 | many directories have entries for this file. If the count is ever | |
2046 | decremented to zero, then the file itself is discarded as soon as no | |
2047 | process still holds it open. Symbolic links are not counted in the | |
2048 | total. | |
2049 | ||
2050 | @item uid_t st_uid | |
2051 | The user ID of the file's owner. @xref{File Owner}. | |
2052 | ||
2053 | @item gid_t st_gid | |
2054 | The group ID of the file. @xref{File Owner}. | |
2055 | ||
2056 | @item off64_t st_size | |
04b9968b UD |
2057 | This specifies the size of a regular file in bytes. For files that are |
2058 | really devices this field isn't usually meaningful. For symbolic links | |
2059 | this specifies the length of the file name the link refers to. | |
a3a4a74e UD |
2060 | |
2061 | @item time_t st_atime | |
2062 | This is the last access time for the file. @xref{File Times}. | |
2063 | ||
2064 | @item unsigned long int st_atime_usec | |
2065 | This is the fractional part of the last access time for the file. | |
2066 | @xref{File Times}. | |
2067 | ||
2068 | @item time_t st_mtime | |
2069 | This is the time of the last modification to the contents of the file. | |
2070 | @xref{File Times}. | |
2071 | ||
2072 | @item unsigned long int st_mtime_usec | |
04b9968b | 2073 | This is the fractional part of the time of the last modification to the |
a3a4a74e UD |
2074 | contents of the file. @xref{File Times}. |
2075 | ||
2076 | @item time_t st_ctime | |
2077 | This is the time of the last modification to the attributes of the file. | |
2078 | @xref{File Times}. | |
2079 | ||
2080 | @item unsigned long int st_ctime_usec | |
04b9968b | 2081 | This is the fractional part of the time of the last modification to the |
a3a4a74e UD |
2082 | attributes of the file. @xref{File Times}. |
2083 | ||
2084 | @c !!! st_rdev | |
2085 | @item blkcnt64_t st_blocks | |
2086 | This is the amount of disk space that the file occupies, measured in | |
2087 | units of 512-byte blocks. | |
2088 | ||
2089 | @item unsigned int st_blksize | |
2090 | The optimal block size for reading of writing this file, in bytes. You | |
2091 | might use this size for allocating the buffer space for reading of | |
2092 | writing the file. (This is unrelated to @code{st_blocks}.) | |
2093 | @end table | |
2094 | @end deftp | |
2095 | ||
fc549258 UD |
2096 | Some of the file attributes have special data type names which exist |
2097 | specifically for those attributes. (They are all aliases for well-known | |
2098 | integer types that you know and love.) These typedef names are defined | |
2099 | in the header file @file{sys/types.h} as well as in @file{sys/stat.h}. | |
2100 | Here is a list of them. | |
2101 | ||
28f540f4 | 2102 | @deftp {Data Type} mode_t |
d08a7e4c | 2103 | @standards{POSIX.1, sys/types.h} |
07e12bb3 JM |
2104 | This is an integer data type used to represent file modes. In |
2105 | @theglibc{}, this is an unsigned type no narrower than @code{unsigned | |
2106 | int}. | |
28f540f4 RM |
2107 | @end deftp |
2108 | ||
2109 | @cindex inode number | |
28f540f4 | 2110 | @deftp {Data Type} ino_t |
d08a7e4c | 2111 | @standards{POSIX.1, sys/types.h} |
07e12bb3 | 2112 | This is an unsigned integer type used to represent file serial numbers. |
28f540f4 | 2113 | (In Unix jargon, these are sometimes called @dfn{inode numbers}.) |
07e12bb3 | 2114 | In @theglibc{}, this type is no narrower than @code{unsigned int}. |
a3a4a74e UD |
2115 | |
2116 | If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type | |
2117 | is transparently replaced by @code{ino64_t}. | |
2118 | @end deftp | |
2119 | ||
a3a4a74e | 2120 | @deftp {Data Type} ino64_t |
d08a7e4c | 2121 | @standards{Unix98, sys/types.h} |
07e12bb3 JM |
2122 | This is an unsigned integer type used to represent file serial numbers |
2123 | for the use in LFS. In @theglibc{}, this type is no narrower than | |
2124 | @code{unsigned int}. | |
a3a4a74e UD |
2125 | |
2126 | When compiling with @code{_FILE_OFFSET_BITS == 64} this type is | |
2127 | available under the name @code{ino_t}. | |
28f540f4 RM |
2128 | @end deftp |
2129 | ||
28f540f4 | 2130 | @deftp {Data Type} dev_t |
d08a7e4c | 2131 | @standards{POSIX.1, sys/types.h} |
28f540f4 | 2132 | This is an arithmetic data type used to represent file device numbers. |
07e12bb3 | 2133 | In @theglibc{}, this is an integer type no narrower than @code{int}. |
28f540f4 RM |
2134 | @end deftp |
2135 | ||
28f540f4 | 2136 | @deftp {Data Type} nlink_t |
d08a7e4c | 2137 | @standards{POSIX.1, sys/types.h} |
07e12bb3 | 2138 | This is an integer type used to represent file link counts. |
28f540f4 RM |
2139 | @end deftp |
2140 | ||
a3a4a74e | 2141 | @deftp {Data Type} blkcnt_t |
d08a7e4c | 2142 | @standards{Unix98, sys/types.h} |
07e12bb3 JM |
2143 | This is a signed integer type used to represent block counts. |
2144 | In @theglibc{}, this type is no narrower than @code{int}. | |
a3a4a74e UD |
2145 | |
2146 | If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type | |
2147 | is transparently replaced by @code{blkcnt64_t}. | |
2148 | @end deftp | |
2149 | ||
a3a4a74e | 2150 | @deftp {Data Type} blkcnt64_t |
d08a7e4c | 2151 | @standards{Unix98, sys/types.h} |
07e12bb3 JM |
2152 | This is a signed integer type used to represent block counts for the |
2153 | use in LFS. In @theglibc{}, this type is no narrower than @code{int}. | |
a3a4a74e UD |
2154 | |
2155 | When compiling with @code{_FILE_OFFSET_BITS == 64} this type is | |
2156 | available under the name @code{blkcnt_t}. | |
2157 | @end deftp | |
2158 | ||
28f540f4 RM |
2159 | @node Reading Attributes |
2160 | @subsection Reading the Attributes of a File | |
2161 | ||
2162 | To examine the attributes of files, use the functions @code{stat}, | |
2163 | @code{fstat} and @code{lstat}. They return the attribute information in | |
2164 | a @code{struct stat} object. All three functions are declared in the | |
2165 | header file @file{sys/stat.h}. | |
2166 | ||
28f540f4 | 2167 | @deftypefun int stat (const char *@var{filename}, struct stat *@var{buf}) |
d08a7e4c | 2168 | @standards{POSIX.1, sys/stat.h} |
de55fdf4 | 2169 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 | 2170 | The @code{stat} function returns information about the attributes of the |
04b9968b | 2171 | file named by @w{@var{filename}} in the structure pointed to by @var{buf}. |
28f540f4 RM |
2172 | |
2173 | If @var{filename} is the name of a symbolic link, the attributes you get | |
2174 | describe the file that the link points to. If the link points to a | |
04b9968b | 2175 | nonexistent file name, then @code{stat} fails reporting a nonexistent |
28f540f4 RM |
2176 | file. |
2177 | ||
04b9968b UD |
2178 | The return value is @code{0} if the operation is successful, or |
2179 | @code{-1} on failure. In addition to the usual file name errors | |
28f540f4 RM |
2180 | (@pxref{File Name Errors}, the following @code{errno} error conditions |
2181 | are defined for this function: | |
2182 | ||
2183 | @table @code | |
2184 | @item ENOENT | |
2185 | The file named by @var{filename} doesn't exist. | |
2186 | @end table | |
a3a4a74e UD |
2187 | |
2188 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
2189 | function is in fact @code{stat64} since the LFS interface transparently | |
2190 | replaces the normal implementation. | |
2191 | @end deftypefun | |
2192 | ||
a3a4a74e | 2193 | @deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf}) |
d08a7e4c | 2194 | @standards{Unix98, sys/stat.h} |
de55fdf4 | 2195 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
a3a4a74e | 2196 | This function is similar to @code{stat} but it is also able to work on |
9ceeb279 | 2197 | files larger than @twoexp{31} bytes on 32-bit systems. To be able to do |
a3a4a74e UD |
2198 | this the result is stored in a variable of type @code{struct stat64} to |
2199 | which @var{buf} must point. | |
2200 | ||
2201 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
2202 | function is available under the name @code{stat} and so transparently | |
04b9968b | 2203 | replaces the interface for small files on 32-bit machines. |
28f540f4 RM |
2204 | @end deftypefun |
2205 | ||
28f540f4 | 2206 | @deftypefun int fstat (int @var{filedes}, struct stat *@var{buf}) |
d08a7e4c | 2207 | @standards{POSIX.1, sys/stat.h} |
de55fdf4 | 2208 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2209 | The @code{fstat} function is like @code{stat}, except that it takes an |
2210 | open file descriptor as an argument instead of a file name. | |
2211 | @xref{Low-Level I/O}. | |
2212 | ||
2213 | Like @code{stat}, @code{fstat} returns @code{0} on success and @code{-1} | |
2214 | on failure. The following @code{errno} error conditions are defined for | |
2215 | @code{fstat}: | |
2216 | ||
2217 | @table @code | |
2218 | @item EBADF | |
2219 | The @var{filedes} argument is not a valid file descriptor. | |
2220 | @end table | |
a3a4a74e UD |
2221 | |
2222 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
2223 | function is in fact @code{fstat64} since the LFS interface transparently | |
2224 | replaces the normal implementation. | |
2225 | @end deftypefun | |
2226 | ||
a3a4a74e | 2227 | @deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf}) |
d08a7e4c | 2228 | @standards{Unix98, sys/stat.h} |
de55fdf4 | 2229 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b UD |
2230 | This function is similar to @code{fstat} but is able to work on large |
2231 | files on 32-bit platforms. For large files the file descriptor | |
2232 | @var{filedes} should be obtained by @code{open64} or @code{creat64}. | |
a3a4a74e UD |
2233 | The @var{buf} pointer points to a variable of type @code{struct stat64} |
2234 | which is able to represent the larger values. | |
2235 | ||
2236 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
2237 | function is available under the name @code{fstat} and so transparently | |
04b9968b | 2238 | replaces the interface for small files on 32-bit machines. |
28f540f4 RM |
2239 | @end deftypefun |
2240 | ||
3de73f97 FW |
2241 | @deftypefun int fstatat (int @var{filedes}, const char *@var{filename}, struct stat *@var{buf}, int @var{flags}) |
2242 | @standards{POSIX.1, sys/stat.h} | |
2243 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
2244 | This function is a descriptor-relative version of the @code{fstat} | |
2245 | function above. @xref{Descriptor-Relative Access}. The @var{flags} | |
2246 | argument can contain a combination of the flags @code{AT_EMPTY_PATH}, | |
2247 | @code{AT_NO_AUTOMOUNT}, @code{AT_SYMLINK_NOFOLLOW}. | |
2248 | ||
2249 | Compared to @code{fstat}, the following additional error conditions can | |
2250 | occur: | |
2251 | ||
2252 | @table @code | |
2253 | @item EBADF | |
2254 | The @var{filedes} argument is not a valid file descriptor. | |
2255 | ||
2256 | @item EINVAL | |
2257 | The @var{flags} argument is not valid for this function. | |
2258 | ||
2259 | @item ENOTDIR | |
2260 | The descriptor @var{filedes} is not associated with a directory, and | |
2261 | @var{filename} is a relative file name. | |
2262 | @end table | |
2263 | ||
2264 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
2265 | function is in fact @code{fstatat64} since the LFS interface transparently | |
2266 | replaces the normal implementation. | |
2267 | @end deftypefun | |
2268 | ||
2269 | @deftypefun int fstatat64 (int @var{filedes}, const char *@var{filename}, struct stat64 *@var{buf}, int @var{flags}) | |
2270 | @standards{GNU, sys/stat.h} | |
2271 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
2272 | This function is the large-file variant of @code{fstatat}, similar to | |
2273 | how @code{fstat64} is the variant of @code{fstat}. | |
2274 | ||
2275 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
2276 | function is available under the name @code{fstatat} and so transparently | |
2277 | replaces the interface for small files on 32-bit machines. | |
2278 | @end deftypefun | |
de55fdf4 | 2279 | |
28f540f4 | 2280 | @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf}) |
d08a7e4c | 2281 | @standards{BSD, sys/stat.h} |
de55fdf4 AO |
2282 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
2283 | @c Direct system call through lxstat, sometimes with an xstat conv call | |
2284 | @c afterwards. | |
28f540f4 RM |
2285 | The @code{lstat} function is like @code{stat}, except that it does not |
2286 | follow symbolic links. If @var{filename} is the name of a symbolic | |
04b9968b | 2287 | link, @code{lstat} returns information about the link itself; otherwise |
28f540f4 | 2288 | @code{lstat} works like @code{stat}. @xref{Symbolic Links}. |
a3a4a74e UD |
2289 | |
2290 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
2291 | function is in fact @code{lstat64} since the LFS interface transparently | |
2292 | replaces the normal implementation. | |
2293 | @end deftypefun | |
2294 | ||
a3a4a74e | 2295 | @deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf}) |
d08a7e4c | 2296 | @standards{Unix98, sys/stat.h} |
de55fdf4 AO |
2297 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
2298 | @c Direct system call through lxstat64, sometimes with an xstat conv | |
2299 | @c call afterwards. | |
a3a4a74e | 2300 | This function is similar to @code{lstat} but it is also able to work on |
9ceeb279 | 2301 | files larger than @twoexp{31} bytes on 32-bit systems. To be able to do |
a3a4a74e UD |
2302 | this the result is stored in a variable of type @code{struct stat64} to |
2303 | which @var{buf} must point. | |
2304 | ||
2305 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this | |
2306 | function is available under the name @code{lstat} and so transparently | |
04b9968b | 2307 | replaces the interface for small files on 32-bit machines. |
28f540f4 RM |
2308 | @end deftypefun |
2309 | ||
2310 | @node Testing File Type | |
2311 | @subsection Testing the Type of a File | |
2312 | ||
2313 | The @dfn{file mode}, stored in the @code{st_mode} field of the file | |
2314 | attributes, contains two kinds of information: the file type code, and | |
2315 | the access permission bits. This section discusses only the type code, | |
04b9968b UD |
2316 | which you can use to tell whether the file is a directory, socket, |
2317 | symbolic link, and so on. For details about access permissions see | |
28f540f4 RM |
2318 | @ref{Permission Bits}. |
2319 | ||
04b9968b UD |
2320 | There are two ways you can access the file type information in a file |
2321 | mode. Firstly, for each file type there is a @dfn{predicate macro} | |
2322 | which examines a given file mode and returns whether it is of that type | |
2323 | or not. Secondly, you can mask out the rest of the file mode to leave | |
2324 | just the file type code, and compare this against constants for each of | |
2325 | the supported file types. | |
28f540f4 RM |
2326 | |
2327 | All of the symbols listed in this section are defined in the header file | |
2328 | @file{sys/stat.h}. | |
2329 | @pindex sys/stat.h | |
2330 | ||
2331 | The following predicate macros test the type of a file, given the value | |
2332 | @var{m} which is the @code{st_mode} field returned by @code{stat} on | |
2333 | that file: | |
2334 | ||
28f540f4 | 2335 | @deftypefn Macro int S_ISDIR (mode_t @var{m}) |
d08a7e4c | 2336 | @standards{POSIX, sys/stat.h} |
de55fdf4 | 2337 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b | 2338 | This macro returns non-zero if the file is a directory. |
28f540f4 RM |
2339 | @end deftypefn |
2340 | ||
28f540f4 | 2341 | @deftypefn Macro int S_ISCHR (mode_t @var{m}) |
d08a7e4c | 2342 | @standards{POSIX, sys/stat.h} |
de55fdf4 | 2343 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b | 2344 | This macro returns non-zero if the file is a character special file (a |
28f540f4 RM |
2345 | device like a terminal). |
2346 | @end deftypefn | |
2347 | ||
28f540f4 | 2348 | @deftypefn Macro int S_ISBLK (mode_t @var{m}) |
d08a7e4c | 2349 | @standards{POSIX, sys/stat.h} |
de55fdf4 | 2350 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b | 2351 | This macro returns non-zero if the file is a block special file (a device |
28f540f4 RM |
2352 | like a disk). |
2353 | @end deftypefn | |
2354 | ||
28f540f4 | 2355 | @deftypefn Macro int S_ISREG (mode_t @var{m}) |
d08a7e4c | 2356 | @standards{POSIX, sys/stat.h} |
de55fdf4 | 2357 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b | 2358 | This macro returns non-zero if the file is a regular file. |
28f540f4 RM |
2359 | @end deftypefn |
2360 | ||
28f540f4 | 2361 | @deftypefn Macro int S_ISFIFO (mode_t @var{m}) |
d08a7e4c | 2362 | @standards{POSIX, sys/stat.h} |
de55fdf4 | 2363 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b | 2364 | This macro returns non-zero if the file is a FIFO special file, or a |
28f540f4 RM |
2365 | pipe. @xref{Pipes and FIFOs}. |
2366 | @end deftypefn | |
2367 | ||
28f540f4 | 2368 | @deftypefn Macro int S_ISLNK (mode_t @var{m}) |
d08a7e4c | 2369 | @standards{GNU, sys/stat.h} |
de55fdf4 | 2370 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b | 2371 | This macro returns non-zero if the file is a symbolic link. |
28f540f4 RM |
2372 | @xref{Symbolic Links}. |
2373 | @end deftypefn | |
2374 | ||
28f540f4 | 2375 | @deftypefn Macro int S_ISSOCK (mode_t @var{m}) |
d08a7e4c | 2376 | @standards{GNU, sys/stat.h} |
de55fdf4 | 2377 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b | 2378 | This macro returns non-zero if the file is a socket. @xref{Sockets}. |
28f540f4 RM |
2379 | @end deftypefn |
2380 | ||
f2ea0f5b | 2381 | An alternate non-POSIX method of testing the file type is supported for |
04b9968b | 2382 | compatibility with BSD. The mode can be bitwise AND-ed with |
28f540f4 | 2383 | @code{S_IFMT} to extract the file type code, and compared to the |
04b9968b | 2384 | appropriate constant. For example, |
28f540f4 RM |
2385 | |
2386 | @smallexample | |
2387 | S_ISCHR (@var{mode}) | |
2388 | @end smallexample | |
2389 | ||
2390 | @noindent | |
2391 | is equivalent to: | |
2392 | ||
2393 | @smallexample | |
2394 | ((@var{mode} & S_IFMT) == S_IFCHR) | |
2395 | @end smallexample | |
2396 | ||
28f540f4 | 2397 | @deftypevr Macro int S_IFMT |
d08a7e4c | 2398 | @standards{BSD, sys/stat.h} |
04b9968b | 2399 | This is a bit mask used to extract the file type code from a mode value. |
28f540f4 RM |
2400 | @end deftypevr |
2401 | ||
2402 | These are the symbolic names for the different file type codes: | |
2403 | ||
2fe82ca6 | 2404 | @vtable @code |
28f540f4 | 2405 | @item S_IFDIR |
d08a7e4c | 2406 | @standards{BSD, sys/stat.h} |
04b9968b | 2407 | This is the file type constant of a directory file. |
28f540f4 | 2408 | |
28f540f4 | 2409 | @item S_IFCHR |
d08a7e4c | 2410 | @standards{BSD, sys/stat.h} |
04b9968b | 2411 | This is the file type constant of a character-oriented device file. |
28f540f4 | 2412 | |
28f540f4 | 2413 | @item S_IFBLK |
d08a7e4c | 2414 | @standards{BSD, sys/stat.h} |
04b9968b | 2415 | This is the file type constant of a block-oriented device file. |
28f540f4 | 2416 | |
28f540f4 | 2417 | @item S_IFREG |
d08a7e4c | 2418 | @standards{BSD, sys/stat.h} |
04b9968b | 2419 | This is the file type constant of a regular file. |
28f540f4 | 2420 | |
28f540f4 | 2421 | @item S_IFLNK |
d08a7e4c | 2422 | @standards{BSD, sys/stat.h} |
04b9968b | 2423 | This is the file type constant of a symbolic link. |
28f540f4 | 2424 | |
28f540f4 | 2425 | @item S_IFSOCK |
d08a7e4c | 2426 | @standards{BSD, sys/stat.h} |
04b9968b | 2427 | This is the file type constant of a socket. |
28f540f4 | 2428 | |
28f540f4 | 2429 | @item S_IFIFO |
d08a7e4c | 2430 | @standards{BSD, sys/stat.h} |
04b9968b | 2431 | This is the file type constant of a FIFO or pipe. |
2fe82ca6 | 2432 | @end vtable |
28f540f4 | 2433 | |
d0db5a44 | 2434 | The POSIX.1b standard introduced a few more objects which possibly can |
4ffa3672 | 2435 | be implemented as objects in the filesystem. These are message queues, |
d0db5a44 | 2436 | semaphores, and shared memory objects. To allow differentiating these |
4ffa3672 RJ |
2437 | objects from other files the POSIX standard introduced three new test |
2438 | macros. But unlike the other macros they do not take the value of the | |
d0db5a44 UD |
2439 | @code{st_mode} field as the parameter. Instead they expect a pointer to |
2440 | the whole @code{struct stat} structure. | |
2441 | ||
f4fe5320 | 2442 | @deftypefn Macro int S_TYPEISMQ (struct stat *@var{s}) |
d08a7e4c | 2443 | @standards{POSIX, sys/stat.h} |
de55fdf4 | 2444 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
4ffa3672 | 2445 | If the system implements POSIX message queues as distinct objects and the |
d0db5a44 UD |
2446 | file is a message queue object, this macro returns a non-zero value. |
2447 | In all other cases the result is zero. | |
2448 | @end deftypefn | |
2449 | ||
f4fe5320 | 2450 | @deftypefn Macro int S_TYPEISSEM (struct stat *@var{s}) |
d08a7e4c | 2451 | @standards{POSIX, sys/stat.h} |
de55fdf4 | 2452 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
4ffa3672 | 2453 | If the system implements POSIX semaphores as distinct objects and the |
d0db5a44 UD |
2454 | file is a semaphore object, this macro returns a non-zero value. |
2455 | In all other cases the result is zero. | |
2456 | @end deftypefn | |
2457 | ||
f4fe5320 | 2458 | @deftypefn Macro int S_TYPEISSHM (struct stat *@var{s}) |
d08a7e4c | 2459 | @standards{POSIX, sys/stat.h} |
de55fdf4 | 2460 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
4ffa3672 | 2461 | If the system implements POSIX shared memory objects as distinct objects |
9dcc8f11 | 2462 | and the file is a shared memory object, this macro returns a non-zero |
d0db5a44 UD |
2463 | value. In all other cases the result is zero. |
2464 | @end deftypefn | |
2465 | ||
28f540f4 RM |
2466 | @node File Owner |
2467 | @subsection File Owner | |
2468 | @cindex file owner | |
2469 | @cindex owner of a file | |
2470 | @cindex group owner of a file | |
2471 | ||
2472 | Every file has an @dfn{owner} which is one of the registered user names | |
04b9968b UD |
2473 | defined on the system. Each file also has a @dfn{group} which is one of |
2474 | the defined groups. The file owner can often be useful for showing you | |
2475 | who edited the file (especially when you edit with GNU Emacs), but its | |
2476 | main purpose is for access control. | |
28f540f4 RM |
2477 | |
2478 | The file owner and group play a role in determining access because the | |
04b9968b UD |
2479 | file has one set of access permission bits for the owner, another set |
2480 | that applies to users who belong to the file's group, and a third set of | |
d01d6319 | 2481 | bits that applies to everyone else. @xref{Access Permission}, for the |
04b9968b UD |
2482 | details of how access is decided based on this data. |
2483 | ||
2484 | When a file is created, its owner is set to the effective user ID of the | |
2485 | process that creates it (@pxref{Process Persona}). The file's group ID | |
2486 | may be set to either the effective group ID of the process, or the group | |
2487 | ID of the directory that contains the file, depending on the system | |
2488 | where the file is stored. When you access a remote file system, it | |
2489 | behaves according to its own rules, not according to the system your | |
28f540f4 | 2490 | program is running on. Thus, your program must be prepared to encounter |
04b9968b | 2491 | either kind of behavior no matter what kind of system you run it on. |
28f540f4 RM |
2492 | |
2493 | @pindex chown | |
2494 | @pindex chgrp | |
2495 | You can change the owner and/or group owner of an existing file using | |
2496 | the @code{chown} function. This is the primitive for the @code{chown} | |
2497 | and @code{chgrp} shell commands. | |
2498 | ||
2499 | @pindex unistd.h | |
2500 | The prototype for this function is declared in @file{unistd.h}. | |
2501 | ||
28f540f4 | 2502 | @deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group}) |
d08a7e4c | 2503 | @standards{POSIX.1, unistd.h} |
de55fdf4 | 2504 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2505 | The @code{chown} function changes the owner of the file @var{filename} to |
2506 | @var{owner}, and its group owner to @var{group}. | |
2507 | ||
2508 | Changing the owner of the file on certain systems clears the set-user-ID | |
04b9968b UD |
2509 | and set-group-ID permission bits. (This is because those bits may not |
2510 | be appropriate for the new owner.) Other file permission bits are not | |
2511 | changed. | |
28f540f4 RM |
2512 | |
2513 | The return value is @code{0} on success and @code{-1} on failure. | |
d68171ed | 2514 | In addition to the usual file name errors (@pxref{File Name Errors}), |
28f540f4 RM |
2515 | the following @code{errno} error conditions are defined for this function: |
2516 | ||
2517 | @table @code | |
2518 | @item EPERM | |
2519 | This process lacks permission to make the requested change. | |
2520 | ||
2521 | Only privileged users or the file's owner can change the file's group. | |
2522 | On most file systems, only privileged users can change the file owner; | |
2523 | some file systems allow you to change the owner if you are currently the | |
2524 | owner. When you access a remote file system, the behavior you encounter | |
2525 | is determined by the system that actually holds the file, not by the | |
2526 | system your program is running on. | |
2527 | ||
2528 | @xref{Options for Files}, for information about the | |
2529 | @code{_POSIX_CHOWN_RESTRICTED} macro. | |
2530 | ||
2531 | @item EROFS | |
2532 | The file is on a read-only file system. | |
2533 | @end table | |
2534 | @end deftypefun | |
2535 | ||
8ded91fb | 2536 | @deftypefun int fchown (int @var{filedes}, uid_t @var{owner}, gid_t @var{group}) |
d08a7e4c | 2537 | @standards{BSD, unistd.h} |
de55fdf4 | 2538 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b UD |
2539 | This is like @code{chown}, except that it changes the owner of the open |
2540 | file with descriptor @var{filedes}. | |
28f540f4 RM |
2541 | |
2542 | The return value from @code{fchown} is @code{0} on success and @code{-1} | |
2543 | on failure. The following @code{errno} error codes are defined for this | |
2544 | function: | |
2545 | ||
2546 | @table @code | |
2547 | @item EBADF | |
2548 | The @var{filedes} argument is not a valid file descriptor. | |
2549 | ||
2550 | @item EINVAL | |
2551 | The @var{filedes} argument corresponds to a pipe or socket, not an ordinary | |
2552 | file. | |
2553 | ||
2554 | @item EPERM | |
04b9968b UD |
2555 | This process lacks permission to make the requested change. For details |
2556 | see @code{chmod} above. | |
28f540f4 RM |
2557 | |
2558 | @item EROFS | |
2559 | The file resides on a read-only file system. | |
2560 | @end table | |
2561 | @end deftypefun | |
2562 | ||
2563 | @node Permission Bits | |
2564 | @subsection The Mode Bits for Access Permission | |
2565 | ||
2566 | The @dfn{file mode}, stored in the @code{st_mode} field of the file | |
2567 | attributes, contains two kinds of information: the file type code, and | |
2568 | the access permission bits. This section discusses only the access | |
2569 | permission bits, which control who can read or write the file. | |
d01d6319 | 2570 | @xref{Testing File Type}, for information about the file type code. |
28f540f4 RM |
2571 | |
2572 | All of the symbols listed in this section are defined in the header file | |
2573 | @file{sys/stat.h}. | |
2574 | @pindex sys/stat.h | |
2575 | ||
2576 | @cindex file permission bits | |
2577 | These symbolic constants are defined for the file mode bits that control | |
2578 | access permission for the file: | |
2579 | ||
2fe82ca6 | 2580 | @vtable @code |
28f540f4 | 2581 | @item S_IRUSR |
28f540f4 | 2582 | @itemx S_IREAD |
d08a7e4c RJ |
2583 | @standards{POSIX.1, sys/stat.h} |
2584 | @standardsx{S_IREAD, BSD, sys/stat.h} | |
04b9968b UD |
2585 | Read permission bit for the owner of the file. On many systems this bit |
2586 | is 0400. @code{S_IREAD} is an obsolete synonym provided for BSD | |
28f540f4 RM |
2587 | compatibility. |
2588 | ||
28f540f4 | 2589 | @item S_IWUSR |
28f540f4 | 2590 | @itemx S_IWRITE |
d08a7e4c RJ |
2591 | @standards{POSIX.1, sys/stat.h} |
2592 | @standardsx{S_IWRITE, BSD, sys/stat.h} | |
28f540f4 RM |
2593 | Write permission bit for the owner of the file. Usually 0200. |
2594 | @w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility. | |
2595 | ||
28f540f4 | 2596 | @item S_IXUSR |
28f540f4 | 2597 | @itemx S_IEXEC |
d08a7e4c RJ |
2598 | @standards{POSIX.1, sys/stat.h} |
2599 | @standardsx{S_IEXEC, BSD, sys/stat.h} | |
28f540f4 RM |
2600 | Execute (for ordinary files) or search (for directories) permission bit |
2601 | for the owner of the file. Usually 0100. @code{S_IEXEC} is an obsolete | |
2602 | synonym provided for BSD compatibility. | |
2603 | ||
28f540f4 | 2604 | @item S_IRWXU |
d08a7e4c | 2605 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
2606 | This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}. |
2607 | ||
28f540f4 | 2608 | @item S_IRGRP |
d08a7e4c | 2609 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
2610 | Read permission bit for the group owner of the file. Usually 040. |
2611 | ||
28f540f4 | 2612 | @item S_IWGRP |
d08a7e4c | 2613 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
2614 | Write permission bit for the group owner of the file. Usually 020. |
2615 | ||
28f540f4 | 2616 | @item S_IXGRP |
d08a7e4c | 2617 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
2618 | Execute or search permission bit for the group owner of the file. |
2619 | Usually 010. | |
2620 | ||
28f540f4 | 2621 | @item S_IRWXG |
d08a7e4c | 2622 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
2623 | This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}. |
2624 | ||
28f540f4 | 2625 | @item S_IROTH |
d08a7e4c | 2626 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
2627 | Read permission bit for other users. Usually 04. |
2628 | ||
28f540f4 | 2629 | @item S_IWOTH |
d08a7e4c | 2630 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
2631 | Write permission bit for other users. Usually 02. |
2632 | ||
28f540f4 | 2633 | @item S_IXOTH |
d08a7e4c | 2634 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
2635 | Execute or search permission bit for other users. Usually 01. |
2636 | ||
28f540f4 | 2637 | @item S_IRWXO |
d08a7e4c | 2638 | @standards{POSIX.1, sys/stat.h} |
28f540f4 RM |
2639 | This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}. |
2640 | ||
28f540f4 | 2641 | @item S_ISUID |
d08a7e4c | 2642 | @standards{POSIX, sys/stat.h} |
d68171ed | 2643 | This is the set-user-ID on execute bit, usually 04000. |
28f540f4 RM |
2644 | @xref{How Change Persona}. |
2645 | ||
28f540f4 | 2646 | @item S_ISGID |
d08a7e4c | 2647 | @standards{POSIX, sys/stat.h} |
28f540f4 RM |
2648 | This is the set-group-ID on execute bit, usually 02000. |
2649 | @xref{How Change Persona}. | |
2650 | ||
2651 | @cindex sticky bit | |
28f540f4 | 2652 | @item S_ISVTX |
d08a7e4c | 2653 | @standards{BSD, sys/stat.h} |
28f540f4 RM |
2654 | This is the @dfn{sticky} bit, usually 01000. |
2655 | ||
04b9968b UD |
2656 | For a directory it gives permission to delete a file in that directory |
2657 | only if you own that file. Ordinarily, a user can either delete all the | |
2658 | files in a directory or cannot delete any of them (based on whether the | |
2659 | user has write permission for the directory). The same restriction | |
2660 | applies---you must have both write permission for the directory and own | |
28f540f4 RM |
2661 | the file you want to delete. The one exception is that the owner of the |
2662 | directory can delete any file in the directory, no matter who owns it | |
2663 | (provided the owner has given himself write permission for the | |
2664 | directory). This is commonly used for the @file{/tmp} directory, where | |
04b9968b | 2665 | anyone may create files but not delete files created by other users. |
28f540f4 RM |
2666 | |
2667 | Originally the sticky bit on an executable file modified the swapping | |
2668 | policies of the system. Normally, when a program terminated, its pages | |
2669 | in core were immediately freed and reused. If the sticky bit was set on | |
2670 | the executable file, the system kept the pages in core for a while as if | |
2671 | the program were still running. This was advantageous for a program | |
2672 | likely to be run many times in succession. This usage is obsolete in | |
2673 | modern systems. When a program terminates, its pages always remain in | |
2674 | core as long as there is no shortage of memory in the system. When the | |
2675 | program is next run, its pages will still be in core if no shortage | |
2676 | arose since the last run. | |
2677 | ||
2678 | On some modern systems where the sticky bit has no useful meaning for an | |
2679 | executable file, you cannot set the bit at all for a non-directory. | |
d68171ed | 2680 | If you try, @code{chmod} fails with @code{EFTYPE}; |
28f540f4 RM |
2681 | @pxref{Setting Permissions}. |
2682 | ||
2683 | Some systems (particularly SunOS) have yet another use for the sticky | |
2684 | bit. If the sticky bit is set on a file that is @emph{not} executable, | |
2685 | it means the opposite: never cache the pages of this file at all. The | |
2686 | main use of this is for the files on an NFS server machine which are | |
2687 | used as the swap area of diskless client machines. The idea is that the | |
2688 | pages of the file will be cached in the client's memory, so it is a | |
04b9968b UD |
2689 | waste of the server's memory to cache them a second time. With this |
2690 | usage the sticky bit also implies that the filesystem may fail to record | |
2691 | the file's modification time onto disk reliably (the idea being that | |
2692 | no-one cares for a swap file). | |
dd7d45e8 UD |
2693 | |
2694 | This bit is only available on BSD systems (and those derived from | |
c941736c JM |
2695 | them). Therefore one has to use the @code{_GNU_SOURCE} feature select |
2696 | macro, or not define any feature test macros, to get the definition | |
2697 | (@pxref{Feature Test Macros}). | |
2fe82ca6 | 2698 | @end vtable |
28f540f4 RM |
2699 | |
2700 | The actual bit values of the symbols are listed in the table above | |
2701 | so you can decode file mode values when debugging your programs. | |
2702 | These bit values are correct for most systems, but they are not | |
2703 | guaranteed. | |
2704 | ||
2705 | @strong{Warning:} Writing explicit numbers for file permissions is bad | |
04b9968b UD |
2706 | practice. Not only is it not portable, it also requires everyone who |
2707 | reads your program to remember what the bits mean. To make your program | |
2708 | clean use the symbolic names. | |
28f540f4 RM |
2709 | |
2710 | @node Access Permission | |
2711 | @subsection How Your Access to a File is Decided | |
2712 | @cindex permission to access a file | |
2713 | @cindex access permission for a file | |
2714 | @cindex file access permission | |
2715 | ||
2716 | Recall that the operating system normally decides access permission for | |
04b9968b | 2717 | a file based on the effective user and group IDs of the process and its |
28f540f4 | 2718 | supplementary group IDs, together with the file's owner, group and |
04b9968b UD |
2719 | permission bits. These concepts are discussed in detail in @ref{Process |
2720 | Persona}. | |
28f540f4 RM |
2721 | |
2722 | If the effective user ID of the process matches the owner user ID of the | |
2723 | file, then permissions for read, write, and execute/search are | |
2724 | controlled by the corresponding ``user'' (or ``owner'') bits. Likewise, | |
2725 | if any of the effective group ID or supplementary group IDs of the | |
2726 | process matches the group owner ID of the file, then permissions are | |
2727 | controlled by the ``group'' bits. Otherwise, permissions are controlled | |
2728 | by the ``other'' bits. | |
2729 | ||
04b9968b UD |
2730 | Privileged users, like @samp{root}, can access any file regardless of |
2731 | its permission bits. As a special case, for a file to be executable | |
2732 | even by a privileged user, at least one of its execute bits must be set. | |
28f540f4 RM |
2733 | |
2734 | @node Setting Permissions | |
2735 | @subsection Assigning File Permissions | |
2736 | ||
2737 | @cindex file creation mask | |
2738 | @cindex umask | |
2739 | The primitive functions for creating files (for example, @code{open} or | |
2740 | @code{mkdir}) take a @var{mode} argument, which specifies the file | |
04b9968b UD |
2741 | permissions to give the newly created file. This mode is modified by |
2742 | the process's @dfn{file creation mask}, or @dfn{umask}, before it is | |
2743 | used. | |
28f540f4 RM |
2744 | |
2745 | The bits that are set in the file creation mask identify permissions | |
2746 | that are always to be disabled for newly created files. For example, if | |
2747 | you set all the ``other'' access bits in the mask, then newly created | |
04b9968b UD |
2748 | files are not accessible at all to processes in the ``other'' category, |
2749 | even if the @var{mode} argument passed to the create function would | |
2750 | permit such access. In other words, the file creation mask is the | |
2751 | complement of the ordinary access permissions you want to grant. | |
28f540f4 RM |
2752 | |
2753 | Programs that create files typically specify a @var{mode} argument that | |
2754 | includes all the permissions that make sense for the particular file. | |
2755 | For an ordinary file, this is typically read and write permission for | |
2756 | all classes of users. These permissions are then restricted as | |
2757 | specified by the individual user's own file creation mask. | |
2758 | ||
2759 | @findex chmod | |
2760 | To change the permission of an existing file given its name, call | |
04b9968b UD |
2761 | @code{chmod}. This function uses the specified permission bits and |
2762 | ignores the file creation mask. | |
28f540f4 RM |
2763 | |
2764 | @pindex umask | |
04b9968b | 2765 | In normal use, the file creation mask is initialized by the user's login |
28f540f4 RM |
2766 | shell (using the @code{umask} shell command), and inherited by all |
2767 | subprocesses. Application programs normally don't need to worry about | |
04b9968b | 2768 | the file creation mask. It will automatically do what it is supposed to |
28f540f4 RM |
2769 | do. |
2770 | ||
04b9968b | 2771 | When your program needs to create a file and bypass the umask for its |
28f540f4 | 2772 | access permissions, the easiest way to do this is to use @code{fchmod} |
04b9968b UD |
2773 | after opening the file, rather than changing the umask. In fact, |
2774 | changing the umask is usually done only by shells. They use the | |
2775 | @code{umask} function. | |
28f540f4 RM |
2776 | |
2777 | The functions in this section are declared in @file{sys/stat.h}. | |
2778 | @pindex sys/stat.h | |
2779 | ||
28f540f4 | 2780 | @deftypefun mode_t umask (mode_t @var{mask}) |
d08a7e4c | 2781 | @standards{POSIX.1, sys/stat.h} |
de55fdf4 | 2782 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2783 | The @code{umask} function sets the file creation mask of the current |
2784 | process to @var{mask}, and returns the previous value of the file | |
2785 | creation mask. | |
2786 | ||
2787 | Here is an example showing how to read the mask with @code{umask} | |
2788 | without changing it permanently: | |
2789 | ||
2790 | @smallexample | |
2791 | mode_t | |
2792 | read_umask (void) | |
2793 | @{ | |
0163d97b | 2794 | mode_t mask = umask (0); |
28f540f4 | 2795 | umask (mask); |
0163d97b | 2796 | return mask; |
28f540f4 RM |
2797 | @} |
2798 | @end smallexample | |
2799 | ||
2800 | @noindent | |
a7a93d50 JM |
2801 | However, on @gnuhurdsystems{} it is better to use @code{getumask} if |
2802 | you just want to read the mask value, because it is reentrant. | |
28f540f4 RM |
2803 | @end deftypefun |
2804 | ||
28f540f4 | 2805 | @deftypefun mode_t getumask (void) |
d08a7e4c | 2806 | @standards{GNU, sys/stat.h} |
de55fdf4 | 2807 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 | 2808 | Return the current value of the file creation mask for the current |
a7a93d50 JM |
2809 | process. This function is a GNU extension and is only available on |
2810 | @gnuhurdsystems{}. | |
28f540f4 RM |
2811 | @end deftypefun |
2812 | ||
28f540f4 | 2813 | @deftypefun int chmod (const char *@var{filename}, mode_t @var{mode}) |
d08a7e4c | 2814 | @standards{POSIX.1, sys/stat.h} |
de55fdf4 | 2815 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2816 | The @code{chmod} function sets the access permission bits for the file |
2817 | named by @var{filename} to @var{mode}. | |
2818 | ||
04b9968b UD |
2819 | If @var{filename} is a symbolic link, @code{chmod} changes the |
2820 | permissions of the file pointed to by the link, not those of the link | |
28f540f4 RM |
2821 | itself. |
2822 | ||
2823 | This function returns @code{0} if successful and @code{-1} if not. In | |
2824 | addition to the usual file name errors (@pxref{File Name | |
2825 | Errors}), the following @code{errno} error conditions are defined for | |
2826 | this function: | |
2827 | ||
2828 | @table @code | |
2829 | @item ENOENT | |
2830 | The named file doesn't exist. | |
2831 | ||
2832 | @item EPERM | |
04b9968b UD |
2833 | This process does not have permission to change the access permissions |
2834 | of this file. Only the file's owner (as judged by the effective user ID | |
2835 | of the process) or a privileged user can change them. | |
28f540f4 RM |
2836 | |
2837 | @item EROFS | |
2838 | The file resides on a read-only file system. | |
2839 | ||
2840 | @item EFTYPE | |
2841 | @var{mode} has the @code{S_ISVTX} bit (the ``sticky bit'') set, | |
2842 | and the named file is not a directory. Some systems do not allow setting the | |
2843 | sticky bit on non-directory files, and some do (and only some of those | |
2844 | assign a useful meaning to the bit for non-directory files). | |
2845 | ||
2846 | You only get @code{EFTYPE} on systems where the sticky bit has no useful | |
2847 | meaning for non-directory files, so it is always safe to just clear the | |
2848 | bit in @var{mode} and call @code{chmod} again. @xref{Permission Bits}, | |
2849 | for full details on the sticky bit. | |
2850 | @end table | |
2851 | @end deftypefun | |
2852 | ||
8ded91fb | 2853 | @deftypefun int fchmod (int @var{filedes}, mode_t @var{mode}) |
d08a7e4c | 2854 | @standards{BSD, sys/stat.h} |
de55fdf4 | 2855 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b UD |
2856 | This is like @code{chmod}, except that it changes the permissions of the |
2857 | currently open file given by @var{filedes}. | |
28f540f4 RM |
2858 | |
2859 | The return value from @code{fchmod} is @code{0} on success and @code{-1} | |
2860 | on failure. The following @code{errno} error codes are defined for this | |
2861 | function: | |
2862 | ||
2863 | @table @code | |
2864 | @item EBADF | |
2865 | The @var{filedes} argument is not a valid file descriptor. | |
2866 | ||
2867 | @item EINVAL | |
2868 | The @var{filedes} argument corresponds to a pipe or socket, or something | |
2869 | else that doesn't really have access permissions. | |
2870 | ||
2871 | @item EPERM | |
04b9968b UD |
2872 | This process does not have permission to change the access permissions |
2873 | of this file. Only the file's owner (as judged by the effective user ID | |
2874 | of the process) or a privileged user can change them. | |
28f540f4 RM |
2875 | |
2876 | @item EROFS | |
2877 | The file resides on a read-only file system. | |
2878 | @end table | |
2879 | @end deftypefun | |
2880 | ||
2881 | @node Testing File Access | |
2882 | @subsection Testing Permission to Access a File | |
2883 | @cindex testing access permission | |
2884 | @cindex access, testing for | |
2885 | @cindex setuid programs and file access | |
2886 | ||
3a4cbb41 UD |
2887 | In some situations it is desirable to allow programs to access files or |
2888 | devices even if this is not possible with the permissions granted to the | |
2889 | user. One possible solution is to set the setuid-bit of the program | |
2890 | file. If such a program is started the @emph{effective} user ID of the | |
2891 | process is changed to that of the owner of the program file. So to | |
2892 | allow write access to files like @file{/etc/passwd}, which normally can | |
2893 | be written only by the super-user, the modifying program will have to be | |
2894 | owned by @code{root} and the setuid-bit must be set. | |
2895 | ||
4ffa3672 | 2896 | But besides the files the program is intended to change the user should |
3a4cbb41 UD |
2897 | not be allowed to access any file to which s/he would not have access |
2898 | anyway. The program therefore must explicitly check whether @emph{the | |
2899 | user} would have the necessary access to a file, before it reads or | |
2900 | writes the file. | |
28f540f4 RM |
2901 | |
2902 | To do this, use the function @code{access}, which checks for access | |
2903 | permission based on the process's @emph{real} user ID rather than the | |
2904 | effective user ID. (The setuid feature does not alter the real user ID, | |
2905 | so it reflects the user who actually ran the program.) | |
2906 | ||
2907 | There is another way you could check this access, which is easy to | |
2908 | describe, but very hard to use. This is to examine the file mode bits | |
2909 | and mimic the system's own access computation. This method is | |
2910 | undesirable because many systems have additional access control | |
2911 | features; your program cannot portably mimic them, and you would not | |
2912 | want to try to keep track of the diverse features that different systems | |
2913 | have. Using @code{access} is simple and automatically does whatever is | |
2914 | appropriate for the system you are using. | |
2915 | ||
4ffa3672 | 2916 | @code{access} is @emph{only} appropriate to use in setuid programs. |
28f540f4 RM |
2917 | A non-setuid program will always use the effective ID rather than the |
2918 | real ID. | |
2919 | ||
2920 | @pindex unistd.h | |
2921 | The symbols in this section are declared in @file{unistd.h}. | |
2922 | ||
28f540f4 | 2923 | @deftypefun int access (const char *@var{filename}, int @var{how}) |
d08a7e4c | 2924 | @standards{POSIX.1, unistd.h} |
de55fdf4 | 2925 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2926 | The @code{access} function checks to see whether the file named by |
2927 | @var{filename} can be accessed in the way specified by the @var{how} | |
2928 | argument. The @var{how} argument either can be the bitwise OR of the | |
2929 | flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test | |
2930 | @code{F_OK}. | |
2931 | ||
04b9968b UD |
2932 | This function uses the @emph{real} user and group IDs of the calling |
2933 | process, rather than the @emph{effective} IDs, to check for access | |
28f540f4 RM |
2934 | permission. As a result, if you use the function from a @code{setuid} |
2935 | or @code{setgid} program (@pxref{How Change Persona}), it gives | |
2936 | information relative to the user who actually ran the program. | |
2937 | ||
2938 | The return value is @code{0} if the access is permitted, and @code{-1} | |
2939 | otherwise. (In other words, treated as a predicate function, | |
2940 | @code{access} returns true if the requested access is @emph{denied}.) | |
2941 | ||
2942 | In addition to the usual file name errors (@pxref{File Name | |
2943 | Errors}), the following @code{errno} error conditions are defined for | |
2944 | this function: | |
2945 | ||
2946 | @table @code | |
2947 | @item EACCES | |
2948 | The access specified by @var{how} is denied. | |
2949 | ||
2950 | @item ENOENT | |
2951 | The file doesn't exist. | |
2952 | ||
2953 | @item EROFS | |
2954 | Write permission was requested for a file on a read-only file system. | |
2955 | @end table | |
2956 | @end deftypefun | |
2957 | ||
2958 | These macros are defined in the header file @file{unistd.h} for use | |
2959 | as the @var{how} argument to the @code{access} function. The values | |
2960 | are integer constants. | |
2961 | @pindex unistd.h | |
2962 | ||
28f540f4 | 2963 | @deftypevr Macro int R_OK |
d08a7e4c | 2964 | @standards{POSIX.1, unistd.h} |
04b9968b | 2965 | Flag meaning test for read permission. |
28f540f4 RM |
2966 | @end deftypevr |
2967 | ||
28f540f4 | 2968 | @deftypevr Macro int W_OK |
d08a7e4c | 2969 | @standards{POSIX.1, unistd.h} |
04b9968b | 2970 | Flag meaning test for write permission. |
28f540f4 RM |
2971 | @end deftypevr |
2972 | ||
28f540f4 | 2973 | @deftypevr Macro int X_OK |
d08a7e4c | 2974 | @standards{POSIX.1, unistd.h} |
04b9968b | 2975 | Flag meaning test for execute/search permission. |
28f540f4 RM |
2976 | @end deftypevr |
2977 | ||
28f540f4 | 2978 | @deftypevr Macro int F_OK |
d08a7e4c | 2979 | @standards{POSIX.1, unistd.h} |
04b9968b | 2980 | Flag meaning test for existence of the file. |
28f540f4 RM |
2981 | @end deftypevr |
2982 | ||
2983 | @node File Times | |
2984 | @subsection File Times | |
2985 | ||
2986 | @cindex file access time | |
2987 | @cindex file modification time | |
2988 | @cindex file attribute modification time | |
f2ea0f5b | 2989 | Each file has three time stamps associated with it: its access time, |
28f540f4 RM |
2990 | its modification time, and its attribute modification time. These |
2991 | correspond to the @code{st_atime}, @code{st_mtime}, and @code{st_ctime} | |
d68171ed | 2992 | members of the @code{stat} structure; see @ref{File Attributes}. |
28f540f4 RM |
2993 | |
2994 | All of these times are represented in calendar time format, as | |
2995 | @code{time_t} objects. This data type is defined in @file{time.h}. | |
2996 | For more information about representation and manipulation of time | |
2997 | values, see @ref{Calendar Time}. | |
2998 | @pindex time.h | |
2999 | ||
3000 | Reading from a file updates its access time attribute, and writing | |
3001 | updates its modification time. When a file is created, all three | |
f2ea0f5b | 3002 | time stamps for that file are set to the current time. In addition, the |
28f540f4 RM |
3003 | attribute change time and modification time fields of the directory that |
3004 | contains the new entry are updated. | |
3005 | ||
3006 | Adding a new name for a file with the @code{link} function updates the | |
3007 | attribute change time field of the file being linked, and both the | |
3008 | attribute change time and modification time fields of the directory | |
3009 | containing the new name. These same fields are affected if a file name | |
04b9968b | 3010 | is deleted with @code{unlink}, @code{remove} or @code{rmdir}. Renaming |
28f540f4 RM |
3011 | a file with @code{rename} affects only the attribute change time and |
3012 | modification time fields of the two parent directories involved, and not | |
3013 | the times for the file being renamed. | |
3014 | ||
04b9968b UD |
3015 | Changing the attributes of a file (for example, with @code{chmod}) |
3016 | updates its attribute change time field. | |
28f540f4 | 3017 | |
f2ea0f5b | 3018 | You can also change some of the time stamps of a file explicitly using |
28f540f4 RM |
3019 | the @code{utime} function---all except the attribute change time. You |
3020 | need to include the header file @file{utime.h} to use this facility. | |
3021 | @pindex utime.h | |
3022 | ||
28f540f4 | 3023 | @deftp {Data Type} {struct utimbuf} |
d08a7e4c | 3024 | @standards{POSIX.1, utime.h} |
28f540f4 RM |
3025 | The @code{utimbuf} structure is used with the @code{utime} function to |
3026 | specify new access and modification times for a file. It contains the | |
3027 | following members: | |
3028 | ||
3029 | @table @code | |
3030 | @item time_t actime | |
3031 | This is the access time for the file. | |
3032 | ||
3033 | @item time_t modtime | |
3034 | This is the modification time for the file. | |
3035 | @end table | |
3036 | @end deftp | |
3037 | ||
28f540f4 | 3038 | @deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times}) |
d08a7e4c | 3039 | @standards{POSIX.1, utime.h} |
de55fdf4 AO |
3040 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3041 | @c In the absence of a utime syscall, it non-atomically converts times | |
3042 | @c to a struct timeval and calls utimes. | |
28f540f4 RM |
3043 | This function is used to modify the file times associated with the file |
3044 | named @var{filename}. | |
3045 | ||
3046 | If @var{times} is a null pointer, then the access and modification times | |
3047 | of the file are set to the current time. Otherwise, they are set to the | |
3048 | values from the @code{actime} and @code{modtime} members (respectively) | |
04b9968b | 3049 | of the @code{utimbuf} structure pointed to by @var{times}. |
28f540f4 RM |
3050 | |
3051 | The attribute modification time for the file is set to the current time | |
f2ea0f5b | 3052 | in either case (since changing the time stamps is itself a modification |
28f540f4 RM |
3053 | of the file attributes). |
3054 | ||
3055 | The @code{utime} function returns @code{0} if successful and @code{-1} | |
3056 | on failure. In addition to the usual file name errors | |
3057 | (@pxref{File Name Errors}), the following @code{errno} error conditions | |
3058 | are defined for this function: | |
3059 | ||
3060 | @table @code | |
3061 | @item EACCES | |
3062 | There is a permission problem in the case where a null pointer was | |
f2ea0f5b | 3063 | passed as the @var{times} argument. In order to update the time stamp on |
28f540f4 | 3064 | the file, you must either be the owner of the file, have write |
04b9968b | 3065 | permission for the file, or be a privileged user. |
28f540f4 RM |
3066 | |
3067 | @item ENOENT | |
3068 | The file doesn't exist. | |
3069 | ||
3070 | @item EPERM | |
3071 | If the @var{times} argument is not a null pointer, you must either be | |
04b9968b | 3072 | the owner of the file or be a privileged user. |
28f540f4 RM |
3073 | |
3074 | @item EROFS | |
3075 | The file lives on a read-only file system. | |
3076 | @end table | |
3077 | @end deftypefun | |
3078 | ||
3079 | Each of the three time stamps has a corresponding microsecond part, | |
3080 | which extends its resolution. These fields are called | |
3081 | @code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec}; | |
3082 | each has a value between 0 and 999,999, which indicates the time in | |
3083 | microseconds. They correspond to the @code{tv_usec} field of a | |
62193c4a | 3084 | @code{timeval} structure; see @ref{Time Types}. |
28f540f4 RM |
3085 | |
3086 | The @code{utimes} function is like @code{utime}, but also lets you specify | |
3087 | the fractional part of the file times. The prototype for this function is | |
3088 | in the header file @file{sys/time.h}. | |
3089 | @pindex sys/time.h | |
3090 | ||
8ded91fb | 3091 | @deftypefun int utimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]}) |
d08a7e4c | 3092 | @standards{BSD, sys/time.h} |
de55fdf4 AO |
3093 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3094 | @c In the absence of a utimes syscall, it non-atomically converts tvp | |
3095 | @c to struct timespec array and issues a utimensat syscall, or to | |
3096 | @c struct utimbuf and calls utime. | |
04b9968b UD |
3097 | This function sets the file access and modification times of the file |
3098 | @var{filename}. The new file access time is specified by | |
28f540f4 | 3099 | @code{@var{tvp}[0]}, and the new modification time by |
20acbc25 RM |
3100 | @code{@var{tvp}[1]}. Similar to @code{utime}, if @var{tvp} is a null |
3101 | pointer then the access and modification times of the file are set to | |
3102 | the current time. This function comes from BSD. | |
28f540f4 RM |
3103 | |
3104 | The return values and error conditions are the same as for the @code{utime} | |
3105 | function. | |
3106 | @end deftypefun | |
3107 | ||
8ded91fb | 3108 | @deftypefun int lutimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]}) |
d08a7e4c | 3109 | @standards{BSD, sys/time.h} |
de55fdf4 AO |
3110 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3111 | @c Since there's no lutimes syscall, it non-atomically converts tvp | |
3112 | @c to struct timespec array and issues a utimensat syscall. | |
20acbc25 RM |
3113 | This function is like @code{utimes}, except that it does not follow |
3114 | symbolic links. If @var{filename} is the name of a symbolic link, | |
3115 | @code{lutimes} sets the file access and modification times of the | |
3116 | symbolic link special file itself (as seen by @code{lstat}; | |
3117 | @pxref{Symbolic Links}) while @code{utimes} sets the file access and | |
3118 | modification times of the file the symbolic link refers to. This | |
3119 | function comes from FreeBSD, and is not available on all platforms (if | |
3120 | not available, it will fail with @code{ENOSYS}). | |
3121 | ||
3122 | The return values and error conditions are the same as for the @code{utime} | |
3123 | function. | |
3124 | @end deftypefun | |
3125 | ||
8ded91fb | 3126 | @deftypefun int futimes (int @var{fd}, const struct timeval @var{tvp}@t{[2]}) |
d08a7e4c | 3127 | @standards{BSD, sys/time.h} |
de55fdf4 AO |
3128 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3129 | @c Since there's no futimes syscall, it non-atomically converts tvp | |
3130 | @c to struct timespec array and issues a utimensat syscall, falling back | |
3131 | @c to utimes on a /proc/self/fd symlink. | |
20acbc25 RM |
3132 | This function is like @code{utimes}, except that it takes an open file |
3133 | descriptor as an argument instead of a file name. @xref{Low-Level | |
3134 | I/O}. This function comes from FreeBSD, and is not available on all | |
3135 | platforms (if not available, it will fail with @code{ENOSYS}). | |
3136 | ||
3137 | Like @code{utimes}, @code{futimes} returns @code{0} on success and @code{-1} | |
3138 | on failure. The following @code{errno} error conditions are defined for | |
3139 | @code{futimes}: | |
3140 | ||
3141 | @table @code | |
3142 | @item EACCES | |
3143 | There is a permission problem in the case where a null pointer was | |
3144 | passed as the @var{times} argument. In order to update the time stamp on | |
3145 | the file, you must either be the owner of the file, have write | |
3146 | permission for the file, or be a privileged user. | |
3147 | ||
3148 | @item EBADF | |
3149 | The @var{filedes} argument is not a valid file descriptor. | |
3150 | ||
3151 | @item EPERM | |
3152 | If the @var{times} argument is not a null pointer, you must either be | |
3153 | the owner of the file or be a privileged user. | |
3154 | ||
3155 | @item EROFS | |
3156 | The file lives on a read-only file system. | |
3157 | @end table | |
3158 | @end deftypefun | |
3159 | ||
7ce241a0 UD |
3160 | @node File Size |
3161 | @subsection File Size | |
3162 | ||
3163 | Normally file sizes are maintained automatically. A file begins with a | |
04b9968b UD |
3164 | size of @math{0} and is automatically extended when data is written past |
3165 | its end. It is also possible to empty a file completely by an | |
7ce241a0 UD |
3166 | @code{open} or @code{fopen} call. |
3167 | ||
04b9968b | 3168 | However, sometimes it is necessary to @emph{reduce} the size of a file. |
7ce241a0 UD |
3169 | This can be done with the @code{truncate} and @code{ftruncate} functions. |
3170 | They were introduced in BSD Unix. @code{ftruncate} was later added to | |
3171 | POSIX.1. | |
3172 | ||
3173 | Some systems allow you to extend a file (creating holes) with these | |
3174 | functions. This is useful when using memory-mapped I/O | |
3175 | (@pxref{Memory-mapped I/O}), where files are not automatically extended. | |
04b9968b UD |
3176 | However, it is not portable but must be implemented if @code{mmap} |
3177 | allows mapping of files (i.e., @code{_POSIX_MAPPED_FILES} is defined). | |
7ce241a0 UD |
3178 | |
3179 | Using these functions on anything other than a regular file gives | |
3180 | @emph{undefined} results. On many systems, such a call will appear to | |
3181 | succeed, without actually accomplishing anything. | |
3182 | ||
3183 | @deftypefun int truncate (const char *@var{filename}, off_t @var{length}) | |
d08a7e4c | 3184 | @standards{X/Open, unistd.h} |
de55fdf4 AO |
3185 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3186 | @c In the absence of a truncate syscall, we use open and ftruncate. | |
7ce241a0 UD |
3187 | |
3188 | The @code{truncate} function changes the size of @var{filename} to | |
fb971363 UD |
3189 | @var{length}. If @var{length} is shorter than the previous length, data |
3190 | at the end will be lost. The file must be writable by the user to | |
3191 | perform this operation. | |
7ce241a0 UD |
3192 | |
3193 | If @var{length} is longer, holes will be added to the end. However, some | |
3194 | systems do not support this feature and will leave the file unchanged. | |
3195 | ||
fb971363 UD |
3196 | When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the |
3197 | @code{truncate} function is in fact @code{truncate64} and the type | |
3198 | @code{off_t} has 64 bits which makes it possible to handle files up to | |
9ceeb279 | 3199 | @twoexp{63} bytes in length. |
fb971363 | 3200 | |
7ce241a0 UD |
3201 | The return value is @math{0} for success, or @math{-1} for an error. In |
3202 | addition to the usual file name errors, the following errors may occur: | |
3203 | ||
3204 | @table @code | |
3205 | ||
3206 | @item EACCES | |
3207 | The file is a directory or not writable. | |
3208 | ||
3209 | @item EINVAL | |
3210 | @var{length} is negative. | |
3211 | ||
3212 | @item EFBIG | |
3213 | The operation would extend the file beyond the limits of the operating system. | |
3214 | ||
3215 | @item EIO | |
04b9968b | 3216 | A hardware I/O error occurred. |
7ce241a0 UD |
3217 | |
3218 | @item EPERM | |
3219 | The file is "append-only" or "immutable". | |
3220 | ||
3221 | @item EINTR | |
3222 | The operation was interrupted by a signal. | |
3223 | ||
3224 | @end table | |
3225 | ||
3226 | @end deftypefun | |
3227 | ||
fb971363 | 3228 | @deftypefun int truncate64 (const char *@var{name}, off64_t @var{length}) |
d08a7e4c | 3229 | @standards{Unix98, unistd.h} |
de55fdf4 AO |
3230 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3231 | @c In the absence of a syscall, try truncate if length fits. | |
fb971363 UD |
3232 | This function is similar to the @code{truncate} function. The |
3233 | difference is that the @var{length} argument is 64 bits wide even on 32 | |
d0db5a44 | 3234 | bits machines, which allows the handling of files with sizes up to |
9ceeb279 | 3235 | @twoexp{63} bytes. |
fb971363 UD |
3236 | |
3237 | When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
3238 | 32 bits machine this function is actually available under the name | |
3239 | @code{truncate} and so transparently replaces the 32 bits interface. | |
3240 | @end deftypefun | |
3241 | ||
7ce241a0 | 3242 | @deftypefun int ftruncate (int @var{fd}, off_t @var{length}) |
d08a7e4c | 3243 | @standards{POSIX, unistd.h} |
de55fdf4 | 3244 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7ce241a0 | 3245 | |
fb971363 UD |
3246 | This is like @code{truncate}, but it works on a file descriptor @var{fd} |
3247 | for an opened file instead of a file name to identify the object. The | |
3248 | file must be opened for writing to successfully carry out the operation. | |
3249 | ||
3250 | The POSIX standard leaves it implementation defined what happens if the | |
3251 | specified new @var{length} of the file is bigger than the original size. | |
3252 | The @code{ftruncate} function might simply leave the file alone and do | |
3253 | nothing or it can increase the size to the desired size. In this later | |
3254 | case the extended area should be zero-filled. So using @code{ftruncate} | |
3255 | is no reliable way to increase the file size but if it is possible it is | |
3256 | probably the fastest way. The function also operates on POSIX shared | |
3257 | memory segments if these are implemented by the system. | |
7ce241a0 UD |
3258 | |
3259 | @code{ftruncate} is especially useful in combination with @code{mmap}. | |
3260 | Since the mapped region must have a fixed size one cannot enlarge the | |
3261 | file by writing something beyond the last mapped page. Instead one has | |
3262 | to enlarge the file itself and then remap the file with the new size. | |
3263 | The example below shows how this works. | |
3264 | ||
fb971363 UD |
3265 | When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the |
3266 | @code{ftruncate} function is in fact @code{ftruncate64} and the type | |
3267 | @code{off_t} has 64 bits which makes it possible to handle files up to | |
9ceeb279 | 3268 | @twoexp{63} bytes in length. |
fb971363 | 3269 | |
7ce241a0 UD |
3270 | The return value is @math{0} for success, or @math{-1} for an error. The |
3271 | following errors may occur: | |
3272 | ||
3273 | @table @code | |
3274 | ||
3275 | @item EBADF | |
3276 | @var{fd} does not correspond to an open file. | |
3277 | ||
3278 | @item EACCES | |
04b9968b | 3279 | @var{fd} is a directory or not open for writing. |
7ce241a0 UD |
3280 | |
3281 | @item EINVAL | |
3282 | @var{length} is negative. | |
3283 | ||
3284 | @item EFBIG | |
3285 | The operation would extend the file beyond the limits of the operating system. | |
3286 | @c or the open() call -- with the not-yet-discussed feature of opening | |
3287 | @c files with extra-large offsets. | |
3288 | ||
3289 | @item EIO | |
04b9968b | 3290 | A hardware I/O error occurred. |
7ce241a0 UD |
3291 | |
3292 | @item EPERM | |
3293 | The file is "append-only" or "immutable". | |
3294 | ||
3295 | @item EINTR | |
3296 | The operation was interrupted by a signal. | |
3297 | ||
3298 | @c ENOENT is also possible on Linux --- however it only occurs if the file | |
3299 | @c descriptor has a `file' structure but no `inode' structure. I'm not | |
3300 | @c sure how such an fd could be created. Perhaps it's a bug. | |
3301 | ||
3302 | @end table | |
3303 | ||
3304 | @end deftypefun | |
3305 | ||
fb971363 | 3306 | @deftypefun int ftruncate64 (int @var{id}, off64_t @var{length}) |
d08a7e4c | 3307 | @standards{Unix98, unistd.h} |
de55fdf4 AO |
3308 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3309 | @c In the absence of a syscall, try ftruncate if length fits. | |
fb971363 UD |
3310 | This function is similar to the @code{ftruncate} function. The |
3311 | difference is that the @var{length} argument is 64 bits wide even on 32 | |
e8b1163e | 3312 | bits machines which allows the handling of files with sizes up to |
9ceeb279 | 3313 | @twoexp{63} bytes. |
fb971363 UD |
3314 | |
3315 | When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
3316 | 32 bits machine this function is actually available under the name | |
3317 | @code{ftruncate} and so transparently replaces the 32 bits interface. | |
3318 | @end deftypefun | |
3319 | ||
04b9968b | 3320 | As announced here is a little example of how to use @code{ftruncate} in |
7ce241a0 UD |
3321 | combination with @code{mmap}: |
3322 | ||
3323 | @smallexample | |
3324 | int fd; | |
3325 | void *start; | |
3326 | size_t len; | |
3327 | ||
3328 | int | |
3329 | add (off_t at, void *block, size_t size) | |
3330 | @{ | |
3331 | if (at + size > len) | |
3332 | @{ | |
3333 | /* Resize the file and remap. */ | |
3334 | size_t ps = sysconf (_SC_PAGESIZE); | |
3335 | size_t ns = (at + size + ps - 1) & ~(ps - 1); | |
3336 | void *np; | |
3337 | if (ftruncate (fd, ns) < 0) | |
3338 | return -1; | |
3339 | np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0); | |
3340 | if (np == MAP_FAILED) | |
3341 | return -1; | |
3342 | start = np; | |
3343 | len = ns; | |
3344 | @} | |
3345 | memcpy ((char *) start + at, block, size); | |
3346 | return 0; | |
3347 | @} | |
3348 | @end smallexample | |
3349 | ||
04b9968b UD |
3350 | The function @code{add} writes a block of memory at an arbitrary |
3351 | position in the file. If the current size of the file is too small it | |
4ffa3672 | 3352 | is extended. Note that it is extended by a whole number of pages. This |
04b9968b UD |
3353 | is a requirement of @code{mmap}. The program has to keep track of the |
3354 | real size, and when it has finished a final @code{ftruncate} call should | |
3355 | set the real size of the file. | |
7ce241a0 | 3356 | |
7fe9e2e0 FW |
3357 | @node Storage Allocation |
3358 | @subsection Storage Allocation | |
3359 | @cindex allocating file storage | |
3360 | @cindex file allocation | |
3361 | @cindex storage allocating | |
3362 | ||
3363 | @cindex file fragmentation | |
3364 | @cindex fragmentation of files | |
3365 | @cindex sparse files | |
3366 | @cindex files, sparse | |
3367 | Most file systems support allocating large files in a non-contiguous | |
3368 | fashion: the file is split into @emph{fragments} which are allocated | |
3369 | sequentially, but the fragments themselves can be scattered across the | |
3370 | disk. File systems generally try to avoid such fragmentation because it | |
3371 | decreases performance, but if a file gradually increases in size, there | |
3372 | might be no other option than to fragment it. In addition, many file | |
3373 | systems support @emph{sparse files} with @emph{holes}: regions of null | |
3374 | bytes for which no backing storage has been allocated by the file | |
3375 | system. When the holes are finally overwritten with data, fragmentation | |
3376 | can occur as well. | |
3377 | ||
3378 | Explicit allocation of storage for yet-unwritten parts of the file can | |
3379 | help the system to avoid fragmentation. Additionally, if storage | |
3380 | pre-allocation fails, it is possible to report the out-of-disk error | |
3381 | early, often without filling up the entire disk. However, due to | |
3382 | deduplication, copy-on-write semantics, and file compression, such | |
3383 | pre-allocation may not reliably prevent the out-of-disk-space error from | |
3384 | occurring later. Checking for write errors is still required, and | |
3385 | writes to memory-mapped regions created with @code{mmap} can still | |
3386 | result in @code{SIGBUS}. | |
3387 | ||
3388 | @deftypefun int posix_fallocate (int @var{fd}, off_t @var{offset}, off_t @var{length}) | |
3389 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
3390 | @c If the file system does not support allocation, | |
3391 | @c @code{posix_fallocate} has a race with file extension (if | |
3392 | @c @var{length} is zero) or with concurrent writes of non-NUL bytes (if | |
3393 | @c @var{length} is positive). | |
3394 | ||
3395 | Allocate backing store for the region of @var{length} bytes starting at | |
3396 | byte @var{offset} in the file for the descriptor @var{fd}. The file | |
3397 | length is increased to @samp{@var{length} + @var{offset}} if necessary. | |
3398 | ||
3399 | @var{fd} must be a regular file opened for writing, or @code{EBADF} is | |
3400 | returned. If there is insufficient disk space to fulfill the allocation | |
3401 | request, @code{ENOSPC} is returned. | |
3402 | ||
3403 | @strong{Note:} If @code{fallocate} is not available (because the file | |
3404 | system does not support it), @code{posix_fallocate} is emulated, which | |
3405 | has the following drawbacks: | |
3406 | ||
3407 | @itemize @bullet | |
3408 | @item | |
3409 | It is very inefficient because all file system blocks in the requested | |
3410 | range need to be examined (even if they have been allocated before) and | |
3411 | potentially rewritten. In contrast, with proper @code{fallocate} | |
3412 | support (see below), the file system can examine the internal file | |
3413 | allocation data structures and eliminate holes directly, maybe even | |
3414 | using unwritten extents (which are pre-allocated but uninitialized on | |
3415 | disk). | |
3416 | ||
3417 | @item | |
3418 | There is a race condition if another thread or process modifies the | |
3419 | underlying file in the to-be-allocated area. Non-null bytes could be | |
3420 | overwritten with null bytes. | |
3421 | ||
032f2250 CD |
3422 | @item |
3423 | If @var{fd} has been opened with the @code{O_WRONLY} flag, the function | |
3424 | will fail with an @code{errno} value of @code{EBADF}. | |
3425 | ||
7fe9e2e0 FW |
3426 | @item |
3427 | If @var{fd} has been opened with the @code{O_APPEND} flag, the function | |
3428 | will fail with an @code{errno} value of @code{EBADF}. | |
3429 | ||
3430 | @item | |
3431 | If @var{length} is zero, @code{ftruncate} is used to increase the file | |
3432 | size as requested, without allocating file system blocks. There is a | |
3433 | race condition which means that @code{ftruncate} can accidentally | |
3434 | truncate the file if it has been extended concurrently. | |
3435 | @end itemize | |
3436 | ||
3437 | On Linux, if an application does not benefit from emulation or if the | |
3438 | emulation is harmful due to its inherent race conditions, the | |
3439 | application can use the Linux-specific @code{fallocate} function, with a | |
3440 | zero flag argument. For the @code{fallocate} function, @theglibc{} does | |
3441 | not perform allocation emulation if the file system does not support | |
3442 | allocation. Instead, an @code{EOPNOTSUPP} is returned to the caller. | |
3443 | ||
3444 | @end deftypefun | |
3445 | ||
b86b4f5e | 3446 | @deftypefun int posix_fallocate64 (int @var{fd}, off64_t @var{offset}, off64_t @var{length}) |
7fe9e2e0 FW |
3447 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3448 | ||
3449 | This function is a variant of @code{posix_fallocate64} which accepts | |
3450 | 64-bit file offsets on all platforms. | |
3451 | ||
3452 | @end deftypefun | |
3453 | ||
28f540f4 RM |
3454 | @node Making Special Files |
3455 | @section Making Special Files | |
3456 | @cindex creating special files | |
3457 | @cindex special files | |
3458 | ||
3459 | The @code{mknod} function is the primitive for making special files, | |
1f77f049 | 3460 | such as files that correspond to devices. @Theglibc{} includes |
28f540f4 RM |
3461 | this function for compatibility with BSD. |
3462 | ||
3463 | The prototype for @code{mknod} is declared in @file{sys/stat.h}. | |
3464 | @pindex sys/stat.h | |
3465 | ||
8ded91fb | 3466 | @deftypefun int mknod (const char *@var{filename}, mode_t @var{mode}, dev_t @var{dev}) |
d08a7e4c | 3467 | @standards{BSD, sys/stat.h} |
de55fdf4 AO |
3468 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3469 | @c Instead of issuing the syscall directly, we go through xmknod. | |
3470 | @c Although the internal xmknod takes a dev_t*, that could lead to | |
3471 | @c @mtsrace races, it's passed a pointer to mknod's dev. | |
28f540f4 RM |
3472 | The @code{mknod} function makes a special file with name @var{filename}. |
3473 | The @var{mode} specifies the mode of the file, and may include the various | |
3474 | special file bits, such as @code{S_IFCHR} (for a character special file) | |
3475 | or @code{S_IFBLK} (for a block special file). @xref{Testing File Type}. | |
3476 | ||
3477 | The @var{dev} argument specifies which device the special file refers to. | |
3478 | Its exact interpretation depends on the kind of special file being created. | |
3479 | ||
3480 | The return value is @code{0} on success and @code{-1} on error. In addition | |
3481 | to the usual file name errors (@pxref{File Name Errors}), the | |
3482 | following @code{errno} error conditions are defined for this function: | |
3483 | ||
3484 | @table @code | |
3485 | @item EPERM | |
3486 | The calling process is not privileged. Only the superuser can create | |
3487 | special files. | |
3488 | ||
3489 | @item ENOSPC | |
3490 | The directory or file system that would contain the new file is full | |
3491 | and cannot be extended. | |
3492 | ||
3493 | @item EROFS | |
3494 | The directory containing the new file can't be modified because it's on | |
3495 | a read-only file system. | |
3496 | ||
3497 | @item EEXIST | |
3498 | There is already a file named @var{filename}. If you want to replace | |
3499 | this file, you must remove the old file explicitly first. | |
3500 | @end table | |
3501 | @end deftypefun | |
3502 | ||
3503 | @node Temporary Files | |
3504 | @section Temporary Files | |
3505 | ||
3506 | If you need to use a temporary file in your program, you can use the | |
3507 | @code{tmpfile} function to open it. Or you can use the @code{tmpnam} | |
04b9968b UD |
3508 | (better: @code{tmpnam_r}) function to provide a name for a temporary |
3509 | file and then you can open it in the usual way with @code{fopen}. | |
28f540f4 RM |
3510 | |
3511 | The @code{tempnam} function is like @code{tmpnam} but lets you choose | |
3512 | what directory temporary files will go in, and something about what | |
04b9968b UD |
3513 | their file names will look like. Important for multi-threaded programs |
3514 | is that @code{tempnam} is reentrant, while @code{tmpnam} is not since it | |
d68171ed | 3515 | returns a pointer to a static buffer. |
28f540f4 RM |
3516 | |
3517 | These facilities are declared in the header file @file{stdio.h}. | |
3518 | @pindex stdio.h | |
3519 | ||
28f540f4 | 3520 | @deftypefun {FILE *} tmpfile (void) |
d08a7e4c | 3521 | @standards{ISO, stdio.h} |
de55fdf4 AO |
3522 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} |
3523 | @c The unsafety issues are those of fdopen, plus @acsfd because of the | |
3524 | @c open. | |
3525 | @c __path_search (internal buf, !dir, const pfx, !try_tmpdir) ok | |
3526 | @c libc_secure_genenv only if try_tmpdir | |
3527 | @c xstat64, strlen, strcmp, sprintf | |
3528 | @c __gen_tempname (internal tmpl, __GT_FILE) ok | |
3529 | @c strlen, memcmp, getpid, open/mkdir/lxstat64 ok | |
3530 | @c HP_TIMING_NOW if available ok | |
3531 | @c gettimeofday (!tz) first time, or every time if no HP_TIMING_NOW ok | |
3532 | @c static value is used and modified without synchronization ok | |
3533 | @c but the use is as a source of non-cryptographic randomness | |
3534 | @c with retries in case of collision, so it should be safe | |
3535 | @c unlink, fdopen | |
28f540f4 RM |
3536 | This function creates a temporary binary file for update mode, as if by |
3537 | calling @code{fopen} with mode @code{"wb+"}. The file is deleted | |
3538 | automatically when it is closed or when the program terminates. (On | |
f65fd747 | 3539 | some other @w{ISO C} systems the file may fail to be deleted if the program |
28f540f4 | 3540 | terminates abnormally). |
d68171ed UD |
3541 | |
3542 | This function is reentrant. | |
a3a4a74e UD |
3543 | |
3544 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
11bf311e | 3545 | 32-bit system this function is in fact @code{tmpfile64}, i.e., the LFS |
04b9968b | 3546 | interface transparently replaces the old interface. |
a3a4a74e UD |
3547 | @end deftypefun |
3548 | ||
a3a4a74e | 3549 | @deftypefun {FILE *} tmpfile64 (void) |
d08a7e4c | 3550 | @standards{Unix98, stdio.h} |
de55fdf4 | 3551 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} |
04b9968b UD |
3552 | This function is similar to @code{tmpfile}, but the stream it returns a |
3553 | pointer to was opened using @code{tmpfile64}. Therefore this stream can | |
9ceeb279 | 3554 | be used for files larger than @twoexp{31} bytes on 32-bit machines. |
a3a4a74e UD |
3555 | |
3556 | Please note that the return type is still @code{FILE *}. There is no | |
3557 | special @code{FILE} type for the LFS interface. | |
3558 | ||
3559 | If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 | |
3560 | bits machine this function is available under the name @code{tmpfile} | |
3561 | and so transparently replaces the old interface. | |
28f540f4 RM |
3562 | @end deftypefun |
3563 | ||
28f540f4 | 3564 | @deftypefun {char *} tmpnam (char *@var{result}) |
d08a7e4c | 3565 | @standards{ISO, stdio.h} |
de55fdf4 AO |
3566 | @safety{@prelim{}@mtunsafe{@mtasurace{:tmpnam/!result}}@asunsafe{}@acsafe{}} |
3567 | @c The passed-in buffer should not be modified concurrently with the | |
3568 | @c call. | |
3569 | @c __path_search (static or passed-in buf, !dir, !pfx, !try_tmpdir) ok | |
3570 | @c __gen_tempname (internal tmpl, __GT_NOCREATE) ok | |
04b9968b UD |
3571 | This function constructs and returns a valid file name that does not |
3572 | refer to any existing file. If the @var{result} argument is a null | |
3573 | pointer, the return value is a pointer to an internal static string, | |
3574 | which might be modified by subsequent calls and therefore makes this | |
3575 | function non-reentrant. Otherwise, the @var{result} argument should be | |
3576 | a pointer to an array of at least @code{L_tmpnam} characters, and the | |
3577 | result is written into that array. | |
d68171ed UD |
3578 | |
3579 | It is possible for @code{tmpnam} to fail if you call it too many times | |
04b9968b UD |
3580 | without removing previously-created files. This is because the limited |
3581 | length of the temporary file names gives room for only a finite number | |
3582 | of different names. If @code{tmpnam} fails it returns a null pointer. | |
3583 | ||
3584 | @strong{Warning:} Between the time the pathname is constructed and the | |
3585 | file is created another process might have created a file with the same | |
3586 | name using @code{tmpnam}, leading to a possible security hole. The | |
3587 | implementation generates names which can hardly be predicted, but when | |
3588 | opening the file you should use the @code{O_EXCL} flag. Using | |
e5448d7a | 3589 | @code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem. |
d68171ed UD |
3590 | @end deftypefun |
3591 | ||
d68171ed | 3592 | @deftypefun {char *} tmpnam_r (char *@var{result}) |
d08a7e4c | 3593 | @standards{GNU, stdio.h} |
de55fdf4 | 3594 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
04b9968b UD |
3595 | This function is nearly identical to the @code{tmpnam} function, except |
3596 | that if @var{result} is a null pointer it returns a null pointer. | |
d68171ed | 3597 | |
04b9968b | 3598 | This guarantees reentrancy because the non-reentrant situation of |
d68171ed | 3599 | @code{tmpnam} cannot happen here. |
e5448d7a UD |
3600 | |
3601 | @strong{Warning}: This function has the same security problems as | |
3602 | @code{tmpnam}. | |
28f540f4 RM |
3603 | @end deftypefun |
3604 | ||
28f540f4 | 3605 | @deftypevr Macro int L_tmpnam |
d08a7e4c | 3606 | @standards{ISO, stdio.h} |
04b9968b UD |
3607 | The value of this macro is an integer constant expression that |
3608 | represents the minimum size of a string large enough to hold a file name | |
3609 | generated by the @code{tmpnam} function. | |
28f540f4 RM |
3610 | @end deftypevr |
3611 | ||
28f540f4 | 3612 | @deftypevr Macro int TMP_MAX |
d08a7e4c | 3613 | @standards{ISO, stdio.h} |
28f540f4 RM |
3614 | The macro @code{TMP_MAX} is a lower bound for how many temporary names |
3615 | you can create with @code{tmpnam}. You can rely on being able to call | |
3616 | @code{tmpnam} at least this many times before it might fail saying you | |
3617 | have made too many temporary file names. | |
3618 | ||
1f77f049 | 3619 | With @theglibc{}, you can create a very large number of temporary |
04b9968b UD |
3620 | file names. If you actually created the files, you would probably run |
3621 | out of disk space before you ran out of names. Some other systems have | |
3622 | a fixed, small limit on the number of temporary files. The limit is | |
3623 | never less than @code{25}. | |
28f540f4 RM |
3624 | @end deftypevr |
3625 | ||
28f540f4 | 3626 | @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix}) |
d08a7e4c | 3627 | @standards{SVID, stdio.h} |
de55fdf4 AO |
3628 | @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} |
3629 | @c There's no way (short of being setuid) to avoid getenv("TMPDIR"), | |
3630 | @c even with a non-NULL dir. | |
3631 | @c | |
3632 | @c __path_search (internal buf, dir, pfx, try_tmpdir) unsafe getenv | |
3633 | @c __gen_tempname (internal tmpl, __GT_NOCREATE) ok | |
3634 | @c strdup | |
04b9968b UD |
3635 | This function generates a unique temporary file name. If @var{prefix} |
3636 | is not a null pointer, up to five characters of this string are used as | |
3637 | a prefix for the file name. The return value is a string newly | |
3638 | allocated with @code{malloc}, so you should release its storage with | |
3639 | @code{free} when it is no longer needed. | |
28f540f4 | 3640 | |
d68171ed UD |
3641 | Because the string is dynamically allocated this function is reentrant. |
3642 | ||
04b9968b UD |
3643 | The directory prefix for the temporary file name is determined by |
3644 | testing each of the following in sequence. The directory must exist and | |
3645 | be writable. | |
28f540f4 RM |
3646 | |
3647 | @itemize @bullet | |
3648 | @item | |
d68171ed UD |
3649 | The environment variable @code{TMPDIR}, if it is defined. For security |
3650 | reasons this only happens if the program is not SUID or SGID enabled. | |
28f540f4 RM |
3651 | |
3652 | @item | |
3653 | The @var{dir} argument, if it is not a null pointer. | |
3654 | ||
3655 | @item | |
3656 | The value of the @code{P_tmpdir} macro. | |
3657 | ||
3658 | @item | |
3659 | The directory @file{/tmp}. | |
3660 | @end itemize | |
3661 | ||
3662 | This function is defined for SVID compatibility. | |
e5448d7a UD |
3663 | |
3664 | @strong{Warning:} Between the time the pathname is constructed and the | |
3665 | file is created another process might have created a file with the same | |
3666 | name using @code{tempnam}, leading to a possible security hole. The | |
3667 | implementation generates names which can hardly be predicted, but when | |
3668 | opening the file you should use the @code{O_EXCL} flag. Using | |
3669 | @code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem. | |
28f540f4 RM |
3670 | @end deftypefun |
3671 | @cindex TMPDIR environment variable | |
3672 | ||
f227c3e0 | 3673 | @c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not?? |
28f540f4 | 3674 | @deftypevr {SVID Macro} {char *} P_tmpdir |
d08a7e4c | 3675 | @standards{SVID, stdio.h} |
28f540f4 RM |
3676 | This macro is the name of the default directory for temporary files. |
3677 | @end deftypevr | |
3678 | ||
3679 | Older Unix systems did not have the functions just described. Instead | |
3680 | they used @code{mktemp} and @code{mkstemp}. Both of these functions | |
3681 | work by modifying a file name template string you pass. The last six | |
3682 | characters of this string must be @samp{XXXXXX}. These six @samp{X}s | |
3683 | are replaced with six characters which make the whole string a unique | |
3684 | file name. Usually the template string is something like | |
3685 | @samp{/tmp/@var{prefix}XXXXXX}, and each program uses a unique @var{prefix}. | |
3686 | ||
48b22986 | 3687 | @strong{NB:} Because @code{mktemp} and @code{mkstemp} modify the |
28f540f4 RM |
3688 | template string, you @emph{must not} pass string constants to them. |
3689 | String constants are normally in read-only storage, so your program | |
3690 | would crash when @code{mktemp} or @code{mkstemp} tried to modify the | |
72ef277e UD |
3691 | string. These functions are declared in the header file @file{stdlib.h}. |
3692 | @pindex stdlib.h | |
28f540f4 | 3693 | |
28f540f4 | 3694 | @deftypefun {char *} mktemp (char *@var{template}) |
d08a7e4c | 3695 | @standards{Unix, stdlib.h} |
de55fdf4 AO |
3696 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3697 | @c __gen_tempname (caller tmpl, __GT_NOCREATE) ok | |
28f540f4 RM |
3698 | The @code{mktemp} function generates a unique file name by modifying |
3699 | @var{template} as described above. If successful, it returns | |
3700 | @var{template} as modified. If @code{mktemp} cannot find a unique file | |
3701 | name, it makes @var{template} an empty string and returns that. If | |
3702 | @var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a | |
3703 | null pointer. | |
4bca4c17 | 3704 | |
04b9968b UD |
3705 | @strong{Warning:} Between the time the pathname is constructed and the |
3706 | file is created another process might have created a file with the same | |
3707 | name using @code{mktemp}, leading to a possible security hole. The | |
3708 | implementation generates names which can hardly be predicted, but when | |
3709 | opening the file you should use the @code{O_EXCL} flag. Using | |
4bca4c17 | 3710 | @code{mkstemp} is a safe way to avoid this problem. |
28f540f4 RM |
3711 | @end deftypefun |
3712 | ||
28f540f4 | 3713 | @deftypefun int mkstemp (char *@var{template}) |
d08a7e4c | 3714 | @standards{BSD, stdlib.h} |
de55fdf4 AO |
3715 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} |
3716 | @c __gen_tempname (caller tmpl, __GT_FILE) ok | |
28f540f4 RM |
3717 | The @code{mkstemp} function generates a unique file name just as |
3718 | @code{mktemp} does, but it also opens the file for you with @code{open} | |
3719 | (@pxref{Opening and Closing Files}). If successful, it modifies | |
04b9968b | 3720 | @var{template} in place and returns a file descriptor for that file open |
28f540f4 | 3721 | for reading and writing. If @code{mkstemp} cannot create a |
b4751608 AS |
3722 | uniquely-named file, it returns @code{-1}. If @var{template} does not |
3723 | end with @samp{XXXXXX}, @code{mkstemp} returns @code{-1} and does not | |
3724 | modify @var{template}. | |
54fce91d UD |
3725 | |
3726 | The file is opened using mode @code{0600}. If the file is meant to be | |
04b9968b | 3727 | used by other users this mode must be changed explicitly. |
28f540f4 RM |
3728 | @end deftypefun |
3729 | ||
3730 | Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a | |
3731 | unique file that cannot possibly clash with any other program trying to | |
3732 | create a temporary file. This is because it works by calling | |
04b9968b UD |
3733 | @code{open} with the @code{O_EXCL} flag, which says you want to create a |
3734 | new file and get an error if the file already exists. | |
2e65ca2b | 3735 | |
2e65ca2b | 3736 | @deftypefun {char *} mkdtemp (char *@var{template}) |
d08a7e4c | 3737 | @standards{BSD, stdlib.h} |
de55fdf4 AO |
3738 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
3739 | @c __gen_tempname (caller tmpl, __GT_DIR) ok | |
2e65ca2b UD |
3740 | The @code{mkdtemp} function creates a directory with a unique name. If |
3741 | it succeeds, it overwrites @var{template} with the name of the | |
3742 | directory, and returns @var{template}. As with @code{mktemp} and | |
3743 | @code{mkstemp}, @var{template} should be a string ending with | |
3744 | @samp{XXXXXX}. | |
3745 | ||
3746 | If @code{mkdtemp} cannot create an uniquely named directory, it returns | |
010fe231 | 3747 | @code{NULL} and sets @code{errno} appropriately. If @var{template} does |
2e65ca2b | 3748 | not end with @samp{XXXXXX}, @code{mkdtemp} returns @code{NULL} and does |
010fe231 | 3749 | not modify @var{template}. @code{errno} will be set to @code{EINVAL} in |
2e65ca2b UD |
3750 | this case. |
3751 | ||
3752 | The directory is created using mode @code{0700}. | |
3753 | @end deftypefun | |
3754 | ||
3755 | The directory created by @code{mkdtemp} cannot clash with temporary | |
3756 | files or directories created by other users. This is because directory | |
3757 | creation always works like @code{open} with @code{O_EXCL}. | |
3758 | @xref{Creating Directories}. | |
3759 | ||
3760 | The @code{mkdtemp} function comes from OpenBSD. | |
de55fdf4 AO |
3761 | |
3762 | @c FIXME these are undocumented: | |
3763 | @c faccessat | |
3764 | @c fchmodat | |
3765 | @c fchownat | |
3766 | @c futimesat | |
3767 | @c fstatat (there's a commented-out safety assessment for this one) | |
fd70af45 | 3768 | @c statx |
de55fdf4 AO |
3769 | @c mkdirat |
3770 | @c mkfifoat | |
3771 | @c name_to_handle_at | |
3772 | @c openat | |
3773 | @c open_by_handle_at | |
3774 | @c readlinkat | |
3775 | @c renameat | |
d6da5cb6 | 3776 | @c renameat2 |
de55fdf4 AO |
3777 | @c scandirat |
3778 | @c symlinkat | |
3779 | @c unlinkat | |
3780 | @c utimensat | |
3781 | @c mknodat |