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