(Directory Entries): Comment out xref to sockets section not yet there.
[kopensolaris-gnu/glibc.git] / manual / filesys.texi
1 @node File System Interface, Pipes and FIFOs, Low-Level I/O, Top
2 @chapter File System Interface
3
4 This chapter describes the GNU C library's functions for manipulating
5 files.  Unlike the input and output functions described in
6 @ref{I/O on Streams} and @ref{Low-Level I/O}, these
7 functions are concerned with operating on the files themselves, rather
8 than on their contents.
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.
20 * Hard Links::                  Adding alternate names to a file.
21 * Symbolic Links::              A file that ``points to'' a file name.
22 * Deleting Files::              How to delete a file, and what that means.
23 * Renaming Files::              Changing a file's name.
24 * Creating Directories::        A system call just for creating a directory.
25 * File Attributes::             Attributes of individual files.
26 * Making Special Files::        How to create special files.
27 * Temporary Files::             Naming and creating temporary files.
28 @end menu
29
30 @node Working Directory
31 @section Working Directory
32
33 @cindex current working directory
34 @cindex working directory
35 @cindex change working directory
36 Each process has associated with it a directory, called its @dfn{current
37 working directory} or simply @dfn{working directory}, that is used in
38 the resolution of relative file names (@pxref{File Name Resolution}).
39
40 When you log in and begin a new session, your working directory is
41 initially set to the home directory associated with your login account
42 in the system user database.  You can find any user's home directory
43 using the @code{getpwuid} or @code{getpwnam} functions; see @ref{User
44 Database}.
45
46 Users can change the working directory using shell commands like
47 @code{cd}.  The functions described in this section are the primitives
48 used by those commands and by other programs for examining and changing
49 the working directory.
50 @pindex cd
51
52 Prototypes for these functions are declared in the header file
53 @file{unistd.h}.
54 @pindex unistd.h
55
56 @comment unistd.h
57 @comment POSIX.1
58 @deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size})
59 The @code{getcwd} function returns an absolute file name representing
60 the current working directory, storing it in the character array
61 @var{buffer} that you provide.  The @var{size} argument is how you tell
62 the system the allocation size of @var{buffer}.
63
64 The GNU library version of this function also permits you to specify a
65 null pointer for the @var{buffer} argument.  Then @code{getcwd}
66 allocates a buffer automatically, as with @code{malloc}
67 (@pxref{Unconstrained Allocation}).  If the @var{size} is greater than
68 zero, then the buffer is that large; otherwise, the buffer is as large
69 as necessary to hold the result.
70
71 The return value is @var{buffer} on success and a null pointer on failure.
72 The following @code{errno} error conditions are defined for this function:
73
74 @table @code
75 @item EINVAL
76 The @var{size} argument is zero and @var{buffer} is not a null pointer.
77
78 @item ERANGE
79 The @var{size} argument is less than the length of the working directory
80 name.  You need to allocate a bigger array and try again.
81
82 @item EACCES
83 Permission to read or search a component of the file name was denied.
84 @end table
85 @end deftypefun
86
87 Here is an example showing how you could implement the behavior of GNU's
88 @w{@code{getcwd (NULL, 0)}} using only the standard behavior of
89 @code{getcwd}:
90
91 @smallexample
92 char *
93 gnu_getcwd ()
94 @{
95   int size = 100;
96   char *buffer = (char *) xmalloc (size);
97
98   while (1)
99     @{
100       char *value = getcwd (buffer, size);
101       if (value != 0)
102         return buffer;
103       size *= 2;
104       free (buffer);
105       buffer = (char *) xmalloc (size);
106     @}
107 @}
108 @end smallexample
109
110 @noindent
111 @xref{Malloc Examples}, for information about @code{xmalloc}, which is
112 not a library function but is a customary name used in most GNU
113 software.
114
115 @comment unistd.h
116 @comment BSD
117 @deftypefun {char *} getwd (char *@var{buffer})
118 This is similar to @code{getcwd}, but has no way to specify the size of
119 the buffer.  The GNU library provides @code{getwd} only
120 for backwards compatibility with BSD.
121
122 The @var{buffer} argument should be a pointer to an array at least
123 @code{PATH_MAX} bytes long (@pxref{Limits for Files}).  In the GNU
124 system there is no limit to the size of a file name, so this is not
125 necessarily enough space to contain the directory name.  That is why
126 this function is deprecated.
127 @end deftypefun
128
129 @comment unistd.h
130 @comment POSIX.1
131 @deftypefun int chdir (const char *@var{filename})
132 This function is used to set the process's working directory to
133 @var{filename}.
134
135 The normal, successful return value from @code{chdir} is @code{0}.  A
136 value of @code{-1} is returned to indicate an error.  The @code{errno}
137 error conditions defined for this function are the usual file name
138 syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the
139 file @var{filename} is not a directory.
140 @end deftypefun
141
142
143 @node Accessing Directories
144 @section Accessing Directories
145 @cindex accessing directories
146 @cindex reading from a directory
147 @cindex directories, accessing
148
149 The facilities described in this section let you read the contents of a
150 directory file.  This is useful if you want your program to list all the
151 files in a directory, perhaps as part of a menu.
152
153 @cindex directory stream
154 The @code{opendir} function opens a @dfn{directory stream} whose
155 elements are directory entries.  You use the @code{readdir} function on
156 the directory stream to retrieve these entries, represented as
157 @w{@code{struct dirent}} objects.  The name of the file for each entry is
158 stored in the @code{d_name} member of this structure.  There are obvious
159 parallels here to the stream facilities for ordinary files, described in
160 @ref{I/O on Streams}.
161
162 @menu
163 * Directory Entries::           Format of one directory entry.
164 * Opening a Directory::         How to open a directory stream.
165 * Reading/Closing Directory::   How to read directory entries from the stream.
166 * Simple Directory Lister::     A very simple directory listing program.
167 * Random Access Directory::     Rereading part of the directory
168                                  already read with the same stream.
169 @end menu
170
171 @node Directory Entries
172 @subsection Format of a Directory Entry
173
174 @pindex dirent.h
175 This section describes what you find in a single directory entry, as you
176 might obtain it from a directory stream.  All the symbols are declared
177 in the header file @file{dirent.h}.
178
179 @comment dirent.h
180 @comment POSIX.1
181 @deftp {Data Type} {struct dirent}
182 This is a structure type used to return information about directory
183 entries.  It contains the following fields:
184
185 @table @code
186 @item char d_name[]
187 This is the null-terminated file name component.  This is the only
188 field you can count on in all POSIX systems.
189
190 @item ino_t d_fileno
191 This is the file serial number.  For BSD compatibility, you can also
192 refer to this member as @code{d_ino}.  In the GNU system and most POSIX
193 systems, for most files this the same as the @code{st_ino} member that
194 @code{stat} will return for the file.  @xref{File Attributes}.
195
196 @item unsigned char d_namlen
197 This is the length of the file name, not including the terminating null
198 character.  Its type is @code{unsigned char} because that is the integer
199 type of the appropriate size
200
201 @item unsigned char d_type
202 This is the type of the file, possibly unknown.  The following constants
203 are defined for its value:
204
205 @table @code
206 @item DT_UNKNOWN
207 The type is unknown.  On some systems this is the only value returned.
208
209 @item DT_REG
210 A regular file.
211
212 @item DT_DIR
213 A directory.
214
215 @item DT_FIFO
216 A named pipe, or FIFO.  @xref{FIFO Special Files}.
217
218 @item DT_SOCK
219 A local-domain socket.  @c !!! @xref{Local Domain}.
220
221 @item DT_CHR
222 A character device.
223
224 @item DT_BLK
225 A block device.
226 @end table
227
228 This member is a BSD extension.  Each value except DT_UNKNOWN
229 corresponds to the file type bits in the @code{st_mode} member of
230 @code{struct statbuf}.  These two macros convert between @code{d_type}
231 values and @code{st_mode} values:
232
233 @deftypefun int IFTODT (mode_t @var{mode})
234 This returns the @code{d_type} value corresponding to @var{mode}.
235 @end deftypefun
236
237 @deftypefun mode_t DTTOIF (int @var{dirtype})
238 This returns the @code{st_mode} value corresponding to @var{dirtype}.
239 @end deftypefun
240 @end table
241
242 This structure may contain additional members in the future.
243
244 When a file has multiple names, each name has its own directory entry.
245 The only way you can tell that the directory entries belong to a
246 single file is that they have the same value for the @code{d_fileno}
247 field.
248
249 File attributes such as size, modification times, and the like are part
250 of the file itself, not any particular directory entry.  @xref{File
251 Attributes}.
252 @end deftp
253
254 @node Opening a Directory
255 @subsection Opening a Directory Stream
256
257 @pindex dirent.h
258 This section describes how to open a directory stream.  All the symbols
259 are declared in the header file @file{dirent.h}.
260
261 @comment dirent.h
262 @comment POSIX.1
263 @deftp {Data Type} DIR
264 The @code{DIR} data type represents a directory stream.  
265 @end deftp
266
267 You shouldn't ever allocate objects of the @code{struct dirent} or
268 @code{DIR} data types, since the directory access functions do that for
269 you.  Instead, you refer to these objects using the pointers returned by
270 the following functions.
271
272 @comment dirent.h
273 @comment POSIX.1
274 @deftypefun {DIR *} opendir (const char *@var{dirname})
275 The @code{opendir} function opens and returns a directory stream for
276 reading the directory whose file name is @var{dirname}.  The stream has
277 type @code{DIR *}.
278
279 If unsuccessful, @code{opendir} returns a null pointer.  In addition to
280 the usual file name syntax errors (@pxref{File Name Errors}), the
281 following @code{errno} error conditions are defined for this function:
282
283 @table @code
284 @item EACCES
285 Read permission is denied for the directory named by @code{dirname}.
286
287 @item EMFILE
288 The process has too many files open.
289
290 @item ENFILE
291 The entire system, or perhaps the file system which contains the
292 directory, cannot support any additional open files at the moment.
293 (This problem cannot happen on the GNU system.)
294 @end table
295
296 The @code{DIR} type is typically implemented using a file descriptor,
297 and the @code{opendir} function in terms of the @code{open} function.
298 @xref{Low-Level I/O}.  Directory streams and the underlying
299 file descriptors are closed on @code{exec} (@pxref{Executing a File}).
300 @end deftypefun
301
302 @node Reading/Closing Directory
303 @subsection Reading and Closing a Directory Stream
304
305 @pindex dirent.h
306 This section describes how to read directory entries from a directory
307 stream, and how to close the stream when you are done with it.  All the
308 symbols are declared in the header file @file{dirent.h}.
309
310 @comment dirent.h
311 @comment POSIX.1
312 @deftypefun {struct dirent *} readdir (DIR *@var{dirstream})
313 This function reads the next entry from the directory.  It normally
314 returns a pointer to a structure containing information about the file.
315 This structure is statically allocated and can be rewritten by a
316 subsequent call.
317
318 @strong{Portability Note:} On some systems, @code{readdir} may not
319 return entries for @file{.} and @file{..}, even though these are always
320 valid file names in any directory.  @xref{File Name Resolution}.
321
322 If there are no more entries in the directory or an error is detected,
323 @code{readdir} returns a null pointer.  The following @code{errno} error
324 conditions are defined for this function:
325
326 @table @code
327 @item EBADF
328 The @var{dirstream} argument is not valid.
329 @end table
330 @end deftypefun
331
332 @comment dirent.h
333 @comment POSIX.1
334 @deftypefun int closedir (DIR *@var{dirstream})
335 This function closes the directory stream @var{dirstream}.  It returns
336 @code{0} on success and @code{-1} on failure.  
337
338 The following @code{errno} error conditions are defined for this
339 function:
340
341 @table @code
342 @item EBADF
343 The @var{dirstream} argument is not valid.
344 @end table
345 @end deftypefun
346
347 @node Simple Directory Lister
348 @subsection Simple Program to List a Directory
349
350 Here's a simple program that prints the names of the files in
351 the current working directory:
352
353 @smallexample
354 @include dir.c.texi
355 @end smallexample
356
357 The order in which files appear in a directory tends to be fairly
358 random.  A more useful program would sort the entries (perhaps by
359 alphabetizing them) before printing them; see @ref{Array Sort Function}.
360
361 @c ??? not documented: scandir, alphasort
362
363 @node Random Access Directory
364 @subsection Random Access in a Directory Stream
365
366 @pindex dirent.h
367 This section describes how to reread parts of a directory that you have
368 already read from an open directory stream.  All the symbols are
369 declared in the header file @file{dirent.h}.
370
371 @comment dirent.h
372 @comment POSIX.1
373 @deftypefun void rewinddir (DIR *@var{dirstream})
374 The @code{rewinddir} function is used to reinitialize the directory
375 stream @var{dirstream}, so that if you call @code{readdir} it
376 returns information about the first entry in the directory again.  This
377 function also notices if files have been added or removed to the
378 directory since it was opened with @code{opendir}.  (Entries for these
379 files might or might not be returned by @code{readdir} if they were
380 added or removed since you last called @code{opendir} or
381 @code{rewinddir}.)
382 @end deftypefun
383
384 @comment dirent.h
385 @comment BSD
386 @deftypefun off_t telldir (DIR *@var{dirstream})
387 The @code{telldir} function returns the file position of the directory
388 stream @var{dirstream}.  You can use this value with @code{seekdir} to
389 restore the directory stream to that position.
390 @end deftypefun
391
392 @comment dirent.h
393 @comment BSD
394 @deftypefun void seekdir (DIR *@var{dirstream}, off_t @var{pos})
395 The @code{seekdir} function sets the file position of the directory
396 stream @var{dirstream} to @var{pos}.  The value @var{pos} must be the
397 result of a previous call to @code{telldir} on this particular stream;
398 closing and reopening the directory can invalidate values returned by
399 @code{telldir}.
400 @end deftypefun
401
402 @node Hard Links
403 @section Hard Links
404 @cindex hard link
405 @cindex link, hard
406 @cindex multiple names for one file
407 @cindex file names, multiple
408
409 In POSIX systems, one file can have many names at the same time.  All of
410 the names are equally real, and no one of them is preferred to the
411 others.
412
413 To add a name to a file, use the @code{link} function.  (The new name is
414 also called a @dfn{hard link} to the file.)  Creating a new link to a
415 file does not copy the contents of the file; it simply makes a new name
416 by which the file can be known, in addition to the file's existing name
417 or names.
418
419 One file can have names in several directories, so the the organization
420 of the file system is not a strict hierarchy or tree.
421
422 In most implementations, it is not possible to have hard links to the
423 same file in multiple file systems.  @code{link} reports an error if you
424 try to make a hard link to the file from another file system when this
425 cannot be done.
426
427 The prototype for the @code{link} function is declared in the header
428 file @file{unistd.h}.
429 @pindex unistd.h
430
431 @comment unistd.h
432 @comment POSIX.1
433 @deftypefun int link (const char *@var{oldname}, const char *@var{newname})
434 The @code{link} function makes a new link to the existing file named by
435 @var{oldname}, under the new name @var{newname}.
436
437 This function returns a value of @code{0} if it is successful and
438 @code{-1} on failure.  In addition to the usual file name syntax errors
439 (@pxref{File Name Errors}) for both @var{oldname} and @var{newname}, the
440 following @code{errno} error conditions are defined for this function:
441
442 @table @code
443 @item EACCES
444 The directory in which the new link is to be written is not writable.
445 @ignore 
446 Some implementations also require that the existing file be accessible
447 by the caller, and use this error to report failure for that reason.
448 @end ignore
449
450 @item EEXIST
451 There is already a file named @var{newname}.  If you want to replace
452 this link with a new link, you must remove the old link explicitly first.
453
454 @item EMLINK
455 There are already too many links to the file named by @var{oldname}.
456 (The maximum number of links to a file is @code{LINK_MAX}; see
457 @ref{Limits for Files}.)
458
459 Well-designed file systems never report this error, because they permit
460 more links than your disk could possibly hold.  However, you must still
461 take account of the possibility of this error, as it could result from
462 network access to a file system on another machine.
463
464 @item ENOENT
465 The file named by @var{oldname} doesn't exist.  You can't make a link to
466 a file that doesn't exist.
467
468 @item ENOSPC
469 The directory or file system that would contain the new link is ``full''
470 and cannot be extended.
471
472 @item EPERM
473 In the GNU system and some others, you cannot make links to directories.
474 many systems allow only privileged users to do so.  This error
475 is used to report the problem.
476
477 @item EROFS
478 The directory containing the new link can't be modified because it's on
479 a read-only file system.
480
481 @item EXDEV
482 The directory specified in @var{newname} is on a different file system
483 than the existing file.
484 @end table
485 @end deftypefun
486
487 @node Symbolic Links
488 @section Symbolic Links
489 @cindex soft link
490 @cindex link, soft
491 @cindex symbolic link
492 @cindex link, symbolic
493
494 The GNU system supports @dfn{soft links} or @dfn{symbolic links}.  This
495 is a kind of ``file'' that is essentially a pointer to another file
496 name.  Unlike hard links, symbolic links can be made to directories or
497 across file systems with no restrictions.  You can also make a symbolic
498 link to a name which is not the name of any file.  (Opening this link
499 will fail until a file by that name is created.)  Likewise, if the
500 symbolic link points to an existing file which is later deleted, the
501 symbolic link continues to point to the same file name even though the
502 name no longer names any file.
503
504 The reason symbolic links work the way they do is that special things
505 happen when you try to open the link.  The @code{open} function realizes
506 you have specified the name of a link, reads the file name contained in
507 the link, and opens that file name instead.  The @code{stat} function
508 likewise operates on the file that the symbolic link points to, instead
509 of on the link itself.
510
511 By contrast, other operations such as deleting or renaming the file
512 operate on the link itself.  The functions @code{readlink} and
513 @code{lstat} also refrain from following symbolic links, because their
514 purpose is to obtain information about the link.  So does @code{link},
515 the function that makes a hard link--it makes a hard link to the
516 symbolic link, which one rarely wants.
517
518 Prototypes for the functions listed in this section are in
519 @file{unistd.h}.
520 @pindex unistd.h
521
522 @comment unistd.h
523 @comment BSD
524 @deftypefun int symlink (const char *@var{oldname}, const char *@var{newname})
525 The @code{symlink} function makes a symbolic link to @var{oldname} named
526 @var{newname}.
527
528 The normal return value from @code{symlink} is @code{0}.  A return value
529 of @code{-1} indicates an error.  In addition to the usual file name
530 syntax errors (@pxref{File Name Errors}), the following @code{errno}
531 error conditions are defined for this function:
532
533 @table @code
534 @item EEXIST
535 There is already an existing file named @var{newname}.
536
537 @item EROFS
538 The file @var{newname} would exist on a read-only file system.
539
540 @item ENOSPC
541 The directory or file system cannot be extended to make the new link.
542
543 @item EIO
544 A hardware error occurred while reading or writing data on the disk.
545
546 @ignore
547 @comment not sure about these
548 @item ELOOP
549 There are too many levels of indirection.  This can be the result of
550 circular symbolic links to directories.
551
552 @item EDQUOT
553 The new link can't be created because the user's disk quota has been
554 exceeded.
555 @end ignore
556 @end table
557 @end deftypefun
558
559 @comment unistd.h
560 @comment BSD
561 @deftypefun int readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size})
562 The @code{readlink} function gets the value of the symbolic link
563 @var{filename}.  The file name that the link points to is copied into
564 @var{buffer}.  This file name string is @emph{not} null-terminated;
565 @code{readlink} normally returns the number of characters copied.  The
566 @var{size} argument specifies the maximum number of characters to copy,
567 usually the allocation size of @var{buffer}.
568
569 If the return value equals @var{size}, you cannot tell whether or not
570 there was room to return the entire name.  So make a bigger buffer and
571 call @code{readlink} again.  Here is an example:
572
573 @smallexample
574 char *
575 readlink_malloc (char *filename)
576 @{
577   int size = 100;
578
579   while (1)
580     @{
581       char *buffer = (char *) xmalloc (size);
582       int nchars = readlink (filename, buffer, size);
583       if (nchars < size)
584         return buffer;
585       free (buffer);
586       size *= 2;
587     @}
588 @}
589 @end smallexample
590
591 @c @group  Invalid outside example.
592 A value of @code{-1} is returned in case of error.  In addition to the
593 usual file name syntax errors (@pxref{File Name Errors}), the following
594 @code{errno} error conditions are defined for this function:
595
596 @table @code
597 @item EINVAL
598 The named file is not a symbolic link.
599
600 @item EIO
601 A hardware error occurred while reading or writing data on the disk.
602 @end table
603 @c @end group
604 @end deftypefun
605
606 @node Deleting Files
607 @section Deleting Files
608 @cindex deleting a file
609 @cindex removing a file
610 @cindex unlinking a file
611
612 You can delete a file with the functions @code{unlink} or @code{remove}.
613
614 Deletion actually deletes a file name.  If this is the file's only name,
615 then the file is deleted as well.  If the file has other names as well
616 (@pxref{Hard Links}), it remains accessible under its other names.
617
618 @comment unistd.h
619 @comment POSIX.1
620 @deftypefun int unlink (const char *@var{filename})
621 The @code{unlink} function deletes the file name @var{filename}.  If
622 this is a file's sole name, the file itself is also deleted.  (Actually,
623 if any process has the file open when this happens, deletion is
624 postponed until all processes have closed the file.)
625
626 @pindex unistd.h
627 The function @code{unlink} is declared in the header file @file{unistd.h}.
628
629 This function returns @code{0} on successful completion, and @code{-1}
630 on error.  In addition to the usual file name syntax errors
631 (@pxref{File Name Errors}), the following @code{errno} error conditions are 
632 defined for this function:
633
634 @table @code
635 @item EACCES
636 Write permission is denied for the directory from which the file is to be
637 removed.
638
639 @item EBUSY
640 This error indicates that the file is being used by the system in such a
641 way that it can't be unlinked.  For example, you might see this error if
642 the file name specifies the root directory or a mount point for a file
643 system.
644
645 @item ENOENT
646 The file name to be deleted doesn't exist.
647
648 @item EPERM
649 On some systems, @code{unlink} cannot be used to delete the name of a
650 directory, or can only be used this way by a privileged user.
651 To avoid such problems, use @code{rmdir} to delete directories.
652 The GNU system 
653
654 @item EROFS
655 The directory in which the file name is to be deleted is on a read-only
656 file system, and can't be modified.
657 @end table
658 @end deftypefun
659
660 @comment unistd.h
661 @comment POSIX.1
662 @deftypefun int rmdir (const char *@var{filename})
663 @cindex directories, deleting
664 @cindex deleting a directory
665 The @code{rmdir} function deletes a directory.  The directory must be
666 empty before it can be removed; in other words, it can only contain
667 entries for @file{.} and @file{..}.
668
669 In most other respects, @code{rmdir} behaves like @code{unlink}.  There
670 are two additional @code{errno} error conditions defined for
671 @code{rmdir}:
672
673 @table @code
674 @item ENOTEMPTY
675 @itemx EEXIST
676 The directory to be deleted is not empty.  
677 @end table
678
679 These two error codes are synonymous; some systems use one, and some use
680 the other.  The GNU system always uses @code{ENOTEMPTY}.
681
682 The prototype for this function is declared in the header file
683 @file{unistd.h}.
684 @pindex unistd.h
685 @end deftypefun
686
687 @comment stdio.h
688 @comment ANSI
689 @deftypefun int remove (const char *@var{filename})
690 This is the ANSI C function to remove a file.  It works like
691 @code{unlink} for files and like @code{rmdir} for directories.
692 @code{remove} is declared in @file{stdio.h}.
693 @pindex stdio.h
694 @end deftypefun
695
696 @node Renaming Files
697 @section Renaming Files
698
699 The @code{rename} function is used to change a file's name.
700
701 @cindex renaming a file
702 @comment stdio.h
703 @comment ANSI
704 @deftypefun int rename (const char *@var{oldname}, const char *@var{newname})
705 The @code{rename} function renames the file name @var{oldname} with
706 @var{newname}.  The file formerly accessible under the name
707 @var{oldname} is afterward accessible as @var{newname} instead.  (If the
708 file had any other names aside from @var{oldname}, it continues to have
709 those names.)
710
711 The directory containing the name @var{newname} must be on the same
712 file system as the file (as indicated by the name @var{oldname}).
713
714 One special case for @code{rename} is when @var{oldname} and
715 @var{newname} are two names for the same file.  The consistent way to
716 handle this case is to delete @var{oldname}.  However, POSIX requires
717 that in this case @code{rename} do nothing and report success---which is
718 inconsistent.  We don't know what your operating system will do.
719
720 If the @var{oldname} is not a directory, then any existing file named
721 @var{newname} is removed during the renaming operation.  However, if
722 @var{newname} is the name of a directory, @code{rename} fails in this
723 case.
724
725 If the @var{oldname} is a directory, then either @var{newname} must not
726 exist or it must name a directory that is empty.  In the latter case,
727 the existing directory named @var{newname} is deleted first.  The name
728 @var{newname} must not specify a subdirectory of the directory
729 @code{oldname} which is being renamed.
730
731 One useful feature of @code{rename} is that the meaning of the name
732 @var{newname} changes ``atomically'' from any previously existing file
733 by that name to its new meaning (the file that was called
734 @var{oldname}).  There is no instant at which @var{newname} is
735 nonexistent ``in between'' the old meaning and the new meaning.  If
736 there is a system crash during the operation, it is possible for both
737 names to still exist; but @var{newname} will always be intact if it
738 exists at all.
739
740 If @code{rename} fails, it returns @code{-1}.  In addition to the usual
741 file name syntax errors (@pxref{File Name Errors}), the following
742 @code{errno} error conditions are defined for this function:
743
744 @table @code
745 @item EACCES
746 One of the directories containing @var{newname} or @var{oldname}
747 refuses write permission; or @var{newname} and @var{oldname} are
748 directories and write permission is refused for one of them.
749
750 @item EBUSY
751 A directory named by @var{oldname} or @var{newname} is being used by
752 the system in a way that prevents the renaming from working.  This includes
753 directories that are mount points for filesystems, and directories
754 that are the current working directories of processes.
755
756 @item ENOTEMPTY
757 @itemx EEXIST
758 The directory @var{newname} isn't empty.  The GNU system always returns
759 @code{ENOTEMPTY} for this, but some other systems return @code{EEXIST}.
760
761 @item EINVAL
762 The @var{oldname} is a directory that contains @var{newname}.
763
764 @item EISDIR
765 The @var{newname} names a directory, but the @var{oldname} doesn't.
766
767 @item EMLINK
768 The parent directory of @var{newname} would have too many links.
769
770 Well-designed file systems never report this error, because they permit
771 more links than your disk could possibly hold.  However, you must still
772 take account of the possibility of this error, as it could result from
773 network access to a file system on another machine.
774
775 @item ENOENT
776 The file named by @var{oldname} doesn't exist.
777
778 @item ENOSPC
779 The directory that would contain @var{newname} has no room for another
780 entry, and there is no space left in the file system to expand it.
781
782 @item EROFS
783 The operation would involve writing to a directory on a read-only file
784 system.
785
786 @item EXDEV
787 The two file names @var{newname} and @var{oldnames} are on different
788 file systems.
789 @end table
790 @end deftypefun
791
792 @node Creating Directories
793 @section Creating Directories
794 @cindex creating a directory
795 @cindex directories, creating
796
797 @pindex mkdir
798 Directories are created with the @code{mkdir} function.  (There is also
799 a shell command @code{mkdir} which does the same thing.)
800
801 @comment sys/stat.h
802 @comment POSIX.1
803 @deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode})
804 The @code{mkdir} function creates a new, empty directory whose name is
805 @var{filename}.
806
807 The argument @var{mode} specifies the file permissions for the new
808 directory file.  @xref{Permission Bits}, for more information about
809 this.
810
811 A return value of @code{0} indicates successful completion, and
812 @code{-1} indicates failure.  In addition to the usual file name syntax
813 errors (@pxref{File Name Errors}), the following @code{errno} error
814 conditions are defined for this function:
815
816 @table @code
817 @item EACCES
818 Write permission is denied for the parent directory in which the new
819 directory is to be added.
820
821 @item EEXIST
822 A file named @var{filename} already exists.
823
824 @item EMLINK
825 The parent directory has too many links.
826
827 Well-designed file systems never report this error, because they permit
828 more links than your disk could possibly hold.  However, you must still
829 take account of the possibility of this error, as it could result from
830 network access to a file system on another machine.
831
832 @item ENOSPC
833 The file system doesn't have enough room to create the new directory.
834
835 @item EROFS
836 The parent directory of the directory being created is on a read-only
837 file system, and cannot be modified.
838 @end table
839
840 To use this function, your program should include the header file
841 @file{sys/stat.h}.
842 @pindex sys/stat.h
843 @end deftypefun
844
845 @node File Attributes
846 @section File Attributes
847
848 @pindex ls
849 When you issue an @samp{ls -l} shell command on a file, it gives you
850 information about the size of the file, who owns it, when it was last
851 modified, and the like.  This kind of information is called the
852 @dfn{file attributes}; it is associated with the file itself and not a
853 particular one of its names.
854
855 This section contains information about how you can inquire about and
856 modify these attributes of files.
857
858 @menu
859 * Attribute Meanings::          The names of the file attributes, 
860                                  and what their values mean.
861 * Reading Attributes::          How to read the attributes of a file.
862 * Testing File Type::           Distinguishing ordinary files,
863                                  directories, links... 
864 * File Owner::                  How ownership for new files is determined,
865                                  and how to change it.
866 * Permission Bits::             How information about a file's access
867                                  mode is stored. 
868 * Access Permission::           How the system decides who can access a file.
869 * Setting Permissions::         How permissions for new files are assigned,
870                                  and how to change them.
871 * Testing File Access::         How to find out if your process can
872                                  access a file. 
873 * File Times::                  About the time attributes of a file.
874 @end menu
875
876 @node Attribute Meanings
877 @subsection What the File Attribute Values Mean
878 @cindex status of a file
879 @cindex attributes of a file
880 @cindex file attributes
881
882 When you read the attributes of a file, they come back in a structure
883 called @code{struct stat}.  This section describes the names of the
884 attributes, their data types, and what they mean.  For the functions
885 to read the attributes of a file, see @ref{Reading Attributes}.
886
887 The header file @file{sys/stat.h} declares all the symbols defined
888 in this section.
889 @pindex sys/stat.h
890
891 @comment sys/stat.h
892 @comment POSIX.1
893 @deftp {Data Type} {struct stat}
894 The @code{stat} structure type is used to return information about the
895 attributes of a file.  It contains at least the following members:
896
897 @table @code
898 @item mode_t st_mode
899 Specifies the mode of the file.  This includes file type information
900 (@pxref{Testing File Type}) and the file permission bits
901 (@pxref{Permission Bits}).
902
903 @item ino_t st_ino
904 The file serial number, which distinguishes this file from all other
905 files on the same device.
906
907 @item dev_t st_dev
908 Identifies the device containing the file.  The @code{st_ino} and
909 @code{st_dev}, taken together, uniquely identify the file.  The
910 @code{st_dev} value is not necessarily consistent across reboots or
911 system crashes, however.
912
913 @item nlink_t st_nlink
914 The number of hard links to the file.  This count keeps track of how many
915 directories have entries for this file.  If the count is ever
916 decremented to zero, then the file itself is discarded.  Symbolic links
917 are not counted in the total.
918
919 @item uid_t st_uid
920 The user ID of the file's owner.  @xref{File Owner}.
921
922 @item gid_t st_gid
923 The group ID of the file.  @xref{File Owner}.
924
925 @item off_t st_size
926 This specifies the size of a regular file in bytes.  For files that
927 are really devices and the like, this field isn't usually meaningful.
928
929 @item time_t st_atime
930 This is the last access time for the file.  @xref{File Times}.
931
932 @item unsigned long int st_atime_usec
933 This is the fractional part of the last access time for the file.
934 @xref{File Times}.
935
936 @item time_t st_mtime
937 This is the time of the last modification to the contents of the file.
938 @xref{File Times}.
939
940 @item unsigned long int st_mtime_usec
941 This is the fractional part of the time of last modification to the
942 contents of the file.  @xref{File Times}.
943
944 @item time_t st_ctime
945 This is the time of the last modification to the attributes of the file.
946 @xref{File Times}.
947
948 @item unsigned long int st_ctime_usec
949 This is the fractional part of the time of last modification to the
950 attributes of the file.  @xref{File Times}.
951
952 @item unsigned int st_nblocks
953 This is the amount of disk space that the file occupies, measured in
954 units of 512-byte blocks.
955
956 The number of disk blocks is not strictly proportional to the size of
957 the file, for two reasons: the file system may use some blocks for
958 internal record keeping; and the file may be sparse---it may have
959 ``holes'' which contain zeros but do not actually take up space on the
960 disk.
961
962 You can tell (approximately) whether a file is sparse by comparing this
963 value with @code{st_size}, like this:
964
965 @smallexample
966 (st.st_blocks * 512 < st.st_size)
967 @end smallexample
968
969 This test is not perfect because a file that is just slightly sparse
970 might not be detected as sparse at all.  For practical applications,
971 this is not a problem.
972
973 @item unsigned int st_blksize
974 The optimal block size for reading of writing this file, in bytes.  You
975 might use this size for allocating the buffer space for reading of
976 writing the file.  (This is unrelated to @code{st_blocks}.)
977 @end table
978 @end deftp
979
980   Some of the file attributes have special data type names which exist
981 specifically for those attributes.  (They are all aliases for well-known
982 integer types that you know and love.)  These typedef names are defined
983 in the header file @file{sys/types.h} as well as in @file{sys/stat.h}.
984 Here is a list of them.
985
986 @comment sys/types.h
987 @comment POSIX.1
988 @deftp {Data Type} mode_t
989 This is an integer data type used to represent file modes.  In the
990 GNU system, this is equivalent to @code{unsigned int}.
991 @end deftp
992
993 @cindex inode number
994 @comment sys/types.h
995 @comment POSIX.1
996 @deftp {Data Type} ino_t
997 This is an arithmetic data type used to represent file serial numbers.
998 (In Unix jargon, these are sometimes called @dfn{inode numbers}.)
999 In the GNU system, this type is equivalent to @code{unsigned long int}.
1000 @end deftp
1001
1002 @comment sys/types.h
1003 @comment POSIX.1
1004 @deftp {Data Type} dev_t
1005 This is an arithmetic data type used to represent file device numbers.
1006 In the GNU system, this is equivalent to @code{int}.
1007 @end deftp
1008
1009 @comment sys/types.h
1010 @comment POSIX.1
1011 @deftp {Data Type} nlink_t
1012 This is an arithmetic data type used to represent file link counts.
1013 In the GNU system, this is equivalent to @code{unsigned short int}.
1014 @end deftp
1015
1016 @node Reading Attributes
1017 @subsection Reading the Attributes of a File
1018
1019 To examine the attributes of files, use the functions @code{stat},
1020 @code{fstat} and @code{lstat}.  They return the attribute information in
1021 a @code{struct stat} object.  All three functions are declared in the
1022 header file @file{sys/stat.h}.
1023
1024 @comment sys/stat.h
1025 @comment POSIX.1
1026 @deftypefun int stat (const char *@var{filename}, struct stat *@var{buf})
1027 The @code{stat} function returns information about the attributes of the
1028 file named by @w{@var{filename}} in the structure pointed at by @var{buf}.
1029
1030 If @var{filename} is the name of a symbolic link, the attributes you get
1031 describe the file that the link points to.  If the link points to a
1032 nonexistent file name, then @code{stat} fails, reporting a nonexistent
1033 file.
1034
1035 The return value is @code{0} if the operation is successful, and @code{-1}
1036 on failure.  In addition to the usual file name syntax errors
1037 (@pxref{File Name Errors}, the following @code{errno} error conditions
1038 are defined for this function:
1039
1040 @table @code
1041 @item ENOENT
1042 The file named by @var{filename} doesn't exist.
1043 @end table
1044 @end deftypefun
1045
1046 @comment sys/stat.h
1047 @comment POSIX.1
1048 @deftypefun int fstat (int @var{filedes}, struct stat *@var{buf})
1049 The @code{fstat} function is like @code{stat}, except that it takes an
1050 open file descriptor as an argument instead of a file name.
1051 @xref{Low-Level I/O}.
1052
1053 Like @code{stat}, @code{fstat} returns @code{0} on success and @code{-1}
1054 on failure.  The following @code{errno} error conditions are defined for
1055 @code{fstat}:
1056
1057 @table @code
1058 @item EBADF
1059 The @var{filedes} argument is not a valid file descriptor.
1060 @end table
1061 @end deftypefun
1062
1063 @comment sys/stat.h
1064 @comment BSD
1065 @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
1066 The @code{lstat} function is like @code{stat}, except that it does not
1067 follow symbolic links.  If @var{filename} is the name of a symbolic
1068 link, @code{lstat} returns information about the link itself; otherwise,
1069 @code{lstat} works like @code{stat}.  @xref{Symbolic Links}.
1070 @end deftypefun
1071
1072 @node Testing File Type
1073 @subsection Testing the Type of a File
1074
1075 The @dfn{file mode}, stored in the @code{st_mode} field of the file
1076 attributes, contains two kinds of information: the file type code, and
1077 the access permission bits.  This section discusses only the type code,
1078 which you can use to tell whether the file is a directory, whether it is
1079 a socket, and so on.  For information about the access permission,
1080 @ref{Permission Bits}.
1081
1082 There are two predefined ways you can access the file type portion of
1083 the file mode.  First of all, for each type of file, there is a 
1084 @dfn{predicate macro} which examines a file mode value and returns
1085 true or false---is the file of that type, or not.  Secondly, you can
1086 mask out the rest of the file mode to get just a file type code.
1087 You can compare this against various constants for the supported file
1088 types.
1089
1090 All of the symbols listed in this section are defined in the header file
1091 @file{sys/stat.h}.
1092 @pindex sys/stat.h
1093
1094 The following predicate macros test the type of a file, given the value
1095 @var{m} which is the @code{st_mode} field returned by @code{stat} on
1096 that file:
1097
1098 @comment sys/stat.h
1099 @comment POSIX
1100 @deftypefn Macro int S_ISDIR (mode_t @var{m})
1101 This macro returns nonzero if the file is a directory.
1102 @end deftypefn
1103
1104 @comment sys/stat.h
1105 @comment POSIX
1106 @deftypefn Macro int S_ISCHR (mode_t @var{m})
1107 This macro returns nonzero if the file is a character special file (a
1108 device like a terminal).
1109 @end deftypefn
1110
1111 @comment sys/stat.h
1112 @comment POSIX
1113 @deftypefn Macro int S_ISBLK (mode_t @var{m})
1114 This macro returns nonzero if the file is a block special file (a device
1115 like a disk).
1116 @end deftypefn
1117
1118 @comment sys/stat.h
1119 @comment POSIX
1120 @deftypefn Macro int S_ISREG (mode_t @var{m})
1121 This macro returns nonzero if the file is a regular file.
1122 @end deftypefn
1123
1124 @comment sys/stat.h
1125 @comment POSIX
1126 @deftypefn Macro int S_ISFIFO (mode_t @var{m})
1127 This macro returns nonzero if the file is a FIFO special file, or a
1128 pipe.  @xref{Pipes and FIFOs}.
1129 @end deftypefn
1130
1131 @comment sys/stat.h
1132 @comment GNU
1133 @deftypefn Macro int S_ISLNK (mode_t @var{m})
1134 This macro returns nonzero if the file is a symbolic link.
1135 @xref{Symbolic Links}.
1136 @end deftypefn
1137
1138 @comment sys/stat.h
1139 @comment GNU
1140 @deftypefn Macro int S_ISSOCK (mode_t @var{m})
1141 This macro returns nonzero if the file is a socket.  @xref{Sockets}.
1142 @end deftypefn
1143
1144 An alterate non-POSIX method of testing the file type is supported for
1145 compatibility with BSD.  The mode can be bitwise ANDed with
1146 @code{S_IFMT} to extract the file type code, and compared to the
1147 appropriate type code constant.  For example,
1148
1149 @smallexample
1150 S_ISCHR (@var{mode})
1151 @end smallexample
1152
1153 @noindent
1154 is equivalent to:
1155
1156 @smallexample
1157 ((@var{mode} & S_IFMT) == S_IFCHR)
1158 @end smallexample
1159
1160 @comment sys/stat.h
1161 @comment BSD
1162 @deftypevr Macro int S_IFMT
1163 This is a bit mask used to extract the file type code portion of a mode
1164 value.
1165 @end deftypevr
1166
1167 These are the symbolic names for the different file type codes:
1168
1169 @table @code
1170 @comment sys/stat.h
1171 @comment BSD
1172 @item S_IFDIR
1173 @vindex S_IFDIR
1174 This macro represents the value of the file type code for a directory file.
1175
1176 @comment sys/stat.h
1177 @comment BSD
1178 @item S_IFCHR
1179 @vindex S_IFCHR
1180 This macro represents the value of the file type code for a
1181 character-oriented device file.
1182
1183 @comment sys/stat.h
1184 @comment BSD
1185 @item S_IFBLK
1186 @vindex S_IFBLK
1187 This macro represents the value of the file type code for a block-oriented
1188 device file.
1189
1190 @comment sys/stat.h
1191 @comment BSD
1192 @item S_IFREG
1193 @vindex S_IFREG
1194 This macro represents the value of the file type code for a regular file.
1195
1196 @comment sys/stat.h
1197 @comment BSD
1198 @item S_IFLNK
1199 @vindex S_IFLNK
1200 This macro represents the value of the file type code for a symbolic link.
1201
1202 @comment sys/stat.h
1203 @comment BSD
1204 @item S_IFSOCK
1205 @vindex S_IFSOCK
1206 This macro represents the value of the file type code for a socket.
1207
1208 @comment sys/stat.h
1209 @comment BSD
1210 @item S_IFIFO
1211 @vindex S_IFIFO
1212 This macro represents the value of the file type code for a FIFO or pipe.
1213 @end table
1214
1215 @node File Owner
1216 @subsection File Owner
1217 @cindex file owner
1218 @cindex owner of a file
1219 @cindex group owner of a file
1220
1221 Every file has an @dfn{owner} which is one of the registered user names
1222 defined on the system.  Each file also has a @dfn{group}, which is one
1223 of the defined groups.  The file owner can often be useful for showing
1224 you who edited the file (especially when you edit with GNU Emacs), but
1225 its main purpose is for access control.
1226
1227 The file owner and group play a role in determining access because the
1228 file has one set of access permission bits for the user that is the
1229 owner, another set that apply to users who belong to the file's group,
1230 and a third set of bits that apply to everyone else.  @xref{Access
1231 Permission}, for the details of how access is decided based on this
1232 data.
1233
1234 When a file is created, its owner is set from the effective user ID of
1235 the process that creates it (@pxref{Process Persona}).  The file's group
1236 ID may be set from either effective group ID of the process, or the
1237 group ID of the directory that contains the file, depending on the
1238 system where the file is stored.  When you access a remote file system,
1239 it behaves according to its own rule, not according to the system your
1240 program is running on.  Thus, your program must be prepared to encounter
1241 either kind of behavior, no matter what kind of system you run it on.
1242
1243 @pindex chown
1244 @pindex chgrp
1245 You can change the owner and/or group owner of an existing file using
1246 the @code{chown} function.  This is the primitive for the @code{chown}
1247 and @code{chgrp} shell commands.
1248
1249 @pindex unistd.h
1250 The prototype for this function is declared in @file{unistd.h}.
1251
1252 @comment unistd.h
1253 @comment POSIX.1
1254 @deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group})
1255 The @code{chown} function changes the owner of the file @var{filename} to
1256 @var{owner}, and its group owner to @var{group}.
1257
1258 Changing the owner of the file on certain systems clears the set-user-ID
1259 and set-group-ID bits of the file's permissions.  (This is because those
1260 bits may not be appropriate for the new owner.)  The other file
1261 permission bits are not changed.
1262
1263 The return value is @code{0} on success and @code{-1} on failure.
1264 In addition to the usual file name syntax errors (@pxref{File Name Errors}), 
1265 the following @code{errno} error conditions are defined for this function:
1266
1267 @table @code
1268 @item EPERM
1269 This process lacks permission to make the requested change.
1270
1271 Only privileged users or the file's owner can change the file's group.
1272 On most file systems, only privileged users can change the file owner;
1273 some file systems allow you to change the owner if you are currently the
1274 owner.  When you access a remote file system, the behavior you encounter
1275 is determined by the system that actually holds the file, not by the
1276 system your program is running on.
1277
1278 @xref{Options for Files}, for information about the
1279 @code{_POSIX_CHOWN_RESTRICTED} macro.
1280
1281 @item EROFS
1282 The file is on a read-only file system.
1283 @end table
1284 @end deftypefun
1285
1286 @comment unistd.h
1287 @comment BSD
1288 @deftypefun int fchown (int @var{filedes}, int @var{owner}, int @var{group})
1289 This is like @code{chown}, except that it changes the owner of the file
1290 with open file descriptor @var{filedes}.
1291
1292 The return value from @code{fchown} is @code{0} on success and @code{-1}
1293 on failure.  The following @code{errno} error codes are defined for this
1294 function:
1295
1296 @table @code
1297 @item EBADF
1298 The @var{filedes} argument is not a valid file descriptor.
1299
1300 @item EINVAL
1301 The @var{filedes} argument corresponds to a pipe or socket, not an ordinary
1302 file.
1303
1304 @item EPERM
1305 This process lacks permission to make the requested change.  For
1306 details, see @code{chmod}, above.
1307
1308 @item EROFS
1309 The file resides on a read-only file system.
1310 @end table
1311 @end deftypefun
1312
1313 @node Permission Bits
1314 @subsection The Mode Bits for Access Permission
1315
1316 The @dfn{file mode}, stored in the @code{st_mode} field of the file
1317 attributes, contains two kinds of information: the file type code, and
1318 the access permission bits.  This section discusses only the access
1319 permission bits, which control who can read or write the file.
1320 @xref{Testing File Type}, for information about the file type code.
1321
1322 All of the symbols listed in this section are defined in the header file
1323 @file{sys/stat.h}.
1324 @pindex sys/stat.h
1325
1326 @cindex file permission bits
1327 These symbolic constants are defined for the file mode bits that control
1328 access permission for the file:
1329
1330 @table @code
1331 @comment sys/stat.h
1332 @comment POSIX.1
1333 @item S_IRUSR
1334 @vindex S_IRUSR
1335 @comment sys/stat.h
1336 @comment BSD
1337 @itemx S_IREAD
1338 @vindex S_IREAD
1339 Read permission bit for the owner of the file.  On many systems, this
1340 bit is 0400.  @code{S_IREAD} is an obsolete synonym provided for BSD
1341 compatibility.
1342
1343 @comment sys/stat.h
1344 @comment POSIX.1
1345 @item S_IWUSR
1346 @vindex S_IWUSR
1347 @comment sys/stat.h
1348 @comment BSD
1349 @itemx S_IWRITE
1350 @vindex S_IWRITE
1351 Write permission bit for the owner of the file.  Usually 0200.
1352 @code{S_IWRITE} is an obsolete synonym provided for BSD compatibility.
1353
1354 @comment sys/stat.h
1355 @comment POSIX.1
1356 @item S_IXUSR
1357 @vindex S_IXUSR
1358 @comment sys/stat.h
1359 @comment BSD
1360 @itemx S_IEXEC
1361 @vindex S_IEXEC
1362 Execute (for ordinary files) or search (for directories) permission bit
1363 for the owner of the file.  Usually 0100.  @code{S_IEXEC} is an obsolete
1364 synonym provided for BSD compatibility.
1365
1366 @comment sys/stat.h
1367 @comment POSIX.1
1368 @item S_IRWXU
1369 @vindex S_IRWXU
1370 This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}.
1371
1372 @comment sys/stat.h
1373 @comment POSIX.1
1374 @item S_IRGRP
1375 @vindex S_IRGRP
1376 Read permission bit for the group owner of the file.  Usually 040.
1377
1378 @comment sys/stat.h
1379 @comment POSIX.1
1380 @item S_IWGRP
1381 @vindex S_IWGRP
1382 Write permission bit for the group owner of the file.  Usually 020.
1383
1384 @comment sys/stat.h
1385 @comment POSIX.1
1386 @item S_IXGRP
1387 @vindex S_IXGRP
1388 Execute or search permission bit for the group owner of the file.
1389 Usually 010.
1390
1391 @comment sys/stat.h
1392 @comment POSIX.1
1393 @item S_IRWXG
1394 @vindex S_IRWXG
1395 This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}.
1396
1397 @comment sys/stat.h
1398 @comment POSIX.1
1399 @item S_IROTH
1400 @vindex S_IROTH
1401 Read permission bit for other users.  Usually 04.
1402
1403 @comment sys/stat.h
1404 @comment POSIX.1
1405 @item S_IWOTH
1406 @vindex S_IWOTH
1407 Write permission bit for other users.  Usually 02.
1408
1409 @comment sys/stat.h
1410 @comment POSIX.1
1411 @item S_IXOTH
1412 @vindex S_IXOTH
1413 Execute or search permission bit for other users.  Usually 01.
1414
1415 @comment sys/stat.h
1416 @comment POSIX.1
1417 @item S_IRWXO
1418 @vindex S_IRWXO
1419 This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}.
1420
1421 @comment sys/stat.h
1422 @comment POSIX
1423 @item S_ISUID
1424 @vindex S_ISUID
1425 This is the set-user-ID on execute bit, usually 04000. 
1426 @xref{How Change Persona}.
1427
1428 @comment sys/stat.h
1429 @comment POSIX
1430 @item S_ISGID
1431 @vindex S_ISGID
1432 This is the set-group-ID on execute bit, usually 02000.
1433 @xref{How Change Persona}.
1434
1435 @cindex sticky bit
1436 @comment sys/stat.h
1437 @comment BSD
1438 @item S_ISVTX
1439 @vindex S_ISVTX
1440 This is the @dfn{sticky} bit, usually 01000.
1441
1442 On an executable file, it modifies the swapping policies of the system.
1443 Normally, when a program terminates, its pages in core are immediately
1444 freed and reused.  If the sticky bit is set on the executable file, the
1445 system keeps the pages in core for a while as if the program were still
1446 running.  This is advantageous for a program that is likely to be run
1447 many times in succession.
1448 @c !!! obsolete in all modern systems (but ask mib to be sure)
1449
1450 On a directory, the sticky bit gives permission to delete a file in the
1451 directory only if you own that file.  Ordinarily, a user either can
1452 delete all the files in the directory or cannot delete any of them
1453 (based on whether the user has write permission for the directory).
1454 This is commonly used for the @file{/tmp} directory, where anyone may
1455 create files, but not delete files created by other users.
1456 @end table
1457
1458 The actual bit values of the symbols are listed in the table above
1459 so you can decode file mode values when debugging your programs.
1460 These bit values are correct for most systems, but they are not
1461 guaranteed.
1462
1463 @strong{Warning:} Writing explicit numbers for file permissions is bad
1464 practice.  It is not only nonportable, it also requires everyone who
1465 reads your program to remember what the bits mean.  To make your
1466 program clean, use the symbolic names.
1467
1468 @node Access Permission
1469 @subsection How Your Access to a File is Decided
1470 @cindex permission to access a file
1471 @cindex access permission for a file
1472 @cindex file access permission
1473
1474 Recall that the operating system normally decides access permission for
1475 a file based on the effective user and group IDs of the process, and its
1476 supplementary group IDs, together with the file's owner, group and
1477 permission bits.  These concepts are discussed in detail in
1478 @ref{Process Persona}.
1479
1480 If the effective user ID of the process matches the owner user ID of the
1481 file, then permissions for read, write, and execute/search are
1482 controlled by the corresponding ``user'' (or ``owner'') bits.  Likewise,
1483 if any of the effective group ID or supplementary group IDs of the
1484 process matches the group owner ID of the file, then permissions are
1485 controlled by the ``group'' bits.  Otherwise, permissions are controlled
1486 by the ``other'' bits.
1487
1488 Privileged users, like @samp{root}, can access any file, regardless of
1489 its file permission bits.  As a special case, for a file to be
1490 executable even for a privileged user, at least one of its execute bits
1491 must be set.
1492
1493 @node Setting Permissions
1494 @subsection Assigning File Permissions
1495
1496 @cindex file creation mask
1497 @cindex umask
1498 The primitive functions for creating files (for example, @code{open} or
1499 @code{mkdir}) take a @var{mode} argument, which specifies the file
1500 permissions for the newly created file.  But the specified mode is
1501 modified by the process's @dfn{file creation mask}, or @dfn{umask},
1502 before it is used.
1503
1504 The bits that are set in the file creation mask identify permissions
1505 that are always to be disabled for newly created files.  For example, if
1506 you set all the ``other'' access bits in the mask, then newly created
1507 files are not accessible at all to processes in the ``other''
1508 category, even if the @var{mode} argument specified to the creation 
1509 function would permit such access.  In other words, the file creation
1510 mask is the complement of the ordinary access permissions you want to
1511 grant.
1512
1513 Programs that create files typically specify a @var{mode} argument that
1514 includes all the permissions that make sense for the particular file.
1515 For an ordinary file, this is typically read and write permission for
1516 all classes of users.  These permissions are then restricted as
1517 specified by the individual user's own file creation mask.
1518
1519 @findex chmod
1520 To change the permission of an existing file given its name, call
1521 @code{chmod}.  This function ignores the file creation mask; it uses
1522 exactly the specified permission bits.
1523
1524 @pindex umask
1525 In normal use, the file creation mask is initialized in the user's login
1526 shell (using the @code{umask} shell command), and inherited by all
1527 subprocesses.  Application programs normally don't need to worry about
1528 the file creation mask.  It will do automatically what it is supposed to
1529 do.
1530
1531 When your program should create a file and bypass the umask for its
1532 access permissions, the easiest way to do this is to use @code{fchmod}
1533 after opening the file, rather than changing the umask.
1534
1535 In fact, changing the umask is usually done only by shells.  They use
1536 the @code{umask} function.
1537
1538 The functions in this section are declared in @file{sys/stat.h}.
1539 @pindex sys/stat.h
1540
1541 @comment sys/stat.h
1542 @comment POSIX.1
1543 @deftypefun mode_t umask (mode_t @var{mask})
1544 The @code{umask} function sets the file creation mask of the current
1545 process to @var{mask}, and returns the previous value of the file
1546 creation mask.
1547
1548 Here is an example showing how to read the mask with @code{umask}
1549 without changing it permanently:
1550
1551 @smallexample
1552 mode_t
1553 read_umask (void)
1554 @{
1555   mask = umask (0);
1556   umask (mask);
1557 @}
1558 @end smallexample
1559
1560 @noindent
1561 However, it is better to use @code{getumask} if you just want to read
1562 the mask value, because that is reentrant (at least if you use the GNU
1563 operating system).
1564 @end deftypefun
1565
1566 @comment sys/stat.h
1567 @comment GNU
1568 @deftypefun mode_t getumask (void)
1569 Return the current value of the file creation mask for the current
1570 process.  This function is a GNU extension.
1571 @end deftypefun
1572
1573 @comment sys/stat.h
1574 @comment POSIX.1
1575 @deftypefun int chmod (const char *@var{filename}, mode_t @var{mode})
1576 The @code{chmod} function sets the access permission bits for the file
1577 named by @var{filename} to @var{mode}.
1578
1579 If the @var{filename} names a symbolic link, @code{chmod} changes the
1580 permission of the file pointed to by the link, not those of the link
1581 itself.
1582
1583 This function returns @code{0} if successful and @code{-1} if not.  In
1584 addition to the usual file name syntax errors (@pxref{File Name
1585 Errors}), the following @code{errno} error conditions are defined for
1586 this function:
1587
1588 @table @code
1589 @item ENOENT
1590 The named file doesn't exist.
1591
1592 @item EPERM
1593 This process does not have permission to change the access permission of
1594 this file.  Only the file's owner (as judged by the effective user ID of
1595 the process) or a privileged user can change them.
1596
1597 @item EROFS
1598 The file resides on a read-only file system.
1599 @end table
1600 @end deftypefun
1601
1602 @comment sys/stat.h
1603 @comment BSD
1604 @deftypefun int fchmod (int @var{filedes}, int @var{mode})
1605 This is like @code{chmod}, except that it changes the permissions of
1606 the file currently open via descriptor @var{filedes}.
1607
1608 The return value from @code{fchmod} is @code{0} on success and @code{-1}
1609 on failure.  The following @code{errno} error codes are defined for this
1610 function:
1611
1612 @table @code
1613 @item EBADF
1614 The @var{filedes} argument is not a valid file descriptor.
1615
1616 @item EINVAL
1617 The @var{filedes} argument corresponds to a pipe or socket, or something
1618 else that doesn't really have access permissions.
1619
1620 @item EPERM
1621 This process does not have permission to change the access permission of
1622 this file.  Only the file's owner (as judged by the effective user ID of
1623 the process) or a privileged user can change them.
1624
1625 @item EROFS
1626 The file resides on a read-only file system.
1627 @end table
1628 @end deftypefun
1629
1630 @node Testing File Access
1631 @subsection Testing Permission to Access a File
1632 @cindex testing access permission
1633 @cindex access, testing for
1634 @cindex setuid programs and file access
1635
1636 When a program runs as a privileged user, this permits it to access
1637 files off-limits to ordinary users---for example, to modify
1638 @file{/etc/passwd}.  Programs designed to be run by ordinary users but
1639 access such files use the setuid bit feature so that they always run
1640 with @code{root} as the effective user ID.
1641  
1642 Such a program may also access files specified by the user, files which
1643 conceptually are being accessed explicitly by the user.  Since the
1644 program runs as @code{root}, it has permission to access whatever file
1645 the user specifies---but usually the desired behavior is to permit only
1646 those files which the user could ordinarily access.
1647
1648 The program therefore must explicitly check whether @emph{the user}
1649 would have the necessary access to a file, before it reads or writes the
1650 file.
1651
1652 To do this, use the function @code{access}, which checks for access
1653 permission based on the process's @emph{real} user ID rather than the
1654 effective user ID.  (The setuid feature does not alter the real user ID,
1655 so it reflects the user who actually ran the program.)
1656
1657 There is another way you could check this access, which is easy to
1658 describe, but very hard to use.  This is to examine the file mode bits
1659 and mimic the system's own access computation.  This method is
1660 undesirable because many systems have additional access control
1661 features; your program cannot portably mimic them, and you would not
1662 want to try to keep track of the diverse features that different systems
1663 have.  Using @code{access} is simple and automatically does whatever is
1664 appropriate for the system you are using.
1665
1666 @code{access} is @emph{only} only appropriate to use in setuid programs.
1667 A non-setuid program will always use the effective ID rather than the
1668 real ID.
1669
1670 @pindex unistd.h
1671 The symbols in this section are declared in @file{unistd.h}.
1672
1673 @comment unistd.h
1674 @comment POSIX.1
1675 @deftypefun int access (const char *@var{filename}, int @var{how})
1676 The @code{access} function checks to see whether the file named by
1677 @var{filename} can be accessed in the way specified by the @var{how}
1678 argument.  The @var{how} argument either can be the bitwise OR of the
1679 flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test
1680 @code{F_OK}.
1681
1682 This function uses the @emph{real} user and group ID's of the calling
1683 process, rather than the @emph{effective} ID's, to check for access
1684 permission.  As a result, if you use the function from a @code{setuid}
1685 or @code{setgid} program (@pxref{How Change Persona}), it gives
1686 information relative to the user who actually ran the program.
1687
1688 The return value is @code{0} if the access is permitted, and @code{-1}
1689 otherwise.  (In other words, treated as a predicate function,
1690 @code{access} returns true if the requested access is @emph{denied}.)
1691
1692 In addition to the usual file name syntax errors (@pxref{File Name
1693 Errors}), the following @code{errno} error conditions are defined for
1694 this function:
1695
1696 @table @code
1697 @item EACCES
1698 The access specified by @var{how} is denied.
1699
1700 @item ENOENT
1701 The file doesn't exist.
1702
1703 @item EROFS
1704 Write permission was requested for a file on a read-only file system.
1705 @end table
1706 @end deftypefun
1707
1708 These macros are defined in the header file @file{unistd.h} for use
1709 as the @var{how} argument to the @code{access} function.  The values
1710 are integer constants.
1711 @pindex unistd.h
1712
1713 @comment unistd.h
1714 @comment POSIX.1
1715 @deftypevr Macro int R_OK
1716 Argument that means, test for read permission.
1717 @end deftypevr
1718
1719 @comment unistd.h
1720 @comment POSIX.1
1721 @deftypevr Macro int W_OK
1722 Argument that means, test for write permission.
1723 @end deftypevr
1724
1725 @comment unistd.h
1726 @comment POSIX.1
1727 @deftypevr Macro int X_OK
1728 Argument that means, test for execute/search permission.
1729 @end deftypevr
1730
1731 @comment unistd.h
1732 @comment POSIX.1
1733 @deftypevr Macro int F_OK
1734 Argument that means, test for existence of the file.
1735 @end deftypevr
1736
1737 @node File Times
1738 @subsection File Times
1739
1740 @cindex file access time
1741 @cindex file modification time
1742 @cindex file attribute modification time
1743 Each file has three timestamps associated with it:  its access time,
1744 its modification time, and its attribute modification time.  These
1745 correspond to the @code{st_atime}, @code{st_mtime}, and @code{st_ctime}
1746 members of the @code{stat} structure; see @ref{File Attributes}.  
1747
1748 All of these times are represented in calendar time format, as
1749 @code{time_t} objects.  This data type is defined in @file{time.h}.
1750 For more information about representation and manipulation of time
1751 values, see @ref{Calendar Time}.
1752 @pindex time.h
1753
1754 When an existing file is opened, its attribute change time and
1755 modification time fields are updated.  Reading from a file updates its
1756 access time attribute, and writing updates its modification time.
1757
1758 When a file is created, all three timestamps for that file are set to
1759 the current time.  In addition, the attribute change time and
1760 modification time fields of the directory that contains the new entry
1761 are updated.
1762
1763 Adding a new name for a file with the @code{link} function updates the
1764 attribute change time field of the file being linked, and both the
1765 attribute change time and modification time fields of the directory
1766 containing the new name.  These same fields are affected if a file name
1767 is deleted with @code{unlink}, @code{remove}, or @code{rmdir}.  Renaming
1768 a file with @code{rename} affects only the attribute change time and
1769 modification time fields of the two parent directories involved, and not
1770 the times for the file being renamed.
1771
1772 Changing attributes of a file (for example, with @code{chmod}) updates
1773 its attribute change time field.
1774
1775 You can also change some of the timestamps of a file explicitly using
1776 the @code{utime} function---all except the attribute change time.  You
1777 need to include the header file @file{utime.h} to use this facility.
1778 @pindex utime.h
1779
1780 @comment time.h
1781 @comment POSIX.1
1782 @deftp {Data Type} {struct utimbuf}
1783 The @code{utimbuf} structure is used with the @code{utime} function to
1784 specify new access and modification times for a file.  It contains the
1785 following members:
1786
1787 @table @code
1788 @item time_t actime
1789 This is the access time for the file.
1790
1791 @item time_t modtime
1792 This is the modification time for the file.
1793 @end table
1794 @end deftp
1795
1796 @comment time.h
1797 @comment POSIX.1
1798 @deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times})
1799 This function is used to modify the file times associated with the file
1800 named @var{filename}.
1801
1802 If @var{times} is a null pointer, then the access and modification times
1803 of the file are set to the current time.  Otherwise, they are set to the
1804 values from the @code{actime} and @code{modtime} members (respectively)
1805 of the @code{utimbuf} structure pointed at by @var{times}.  
1806
1807 The attribute modification time for the file is set to the current time
1808 in either case (since changing the timestamps is itself a modification
1809 of the file attributes).
1810
1811 The @code{utime} function returns @code{0} if successful and @code{-1}
1812 on failure.  In addition to the usual file name syntax errors
1813 (@pxref{File Name Errors}), the following @code{errno} error conditions
1814 are defined for this function:
1815
1816 @table @code
1817 @item EACCES
1818 There is a permission problem in the case where a null pointer was
1819 passed as the @var{times} argument.  In order to update the timestamp on
1820 the file, you must either be the owner of the file, have write
1821 permission on the file, or be a privileged user.
1822
1823 @item ENOENT
1824 The file doesn't exist.
1825
1826 @item EPERM
1827 If the @var{times} argument is not a null pointer, you must either be
1828 the owner of the file or be a privileged user.  This error is used to
1829 report the problem.
1830
1831 @item EROFS
1832 The file lives on a read-only file system.
1833 @end table
1834 @end deftypefun
1835
1836 Each of the three time stamps has a corresponding microsecond part,
1837 which extends its resolution.  These fields are called
1838 @code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec};
1839 each has a value between 0 and 999,999, which indicates the time in
1840 microseconds.  They correspond to the @code{tv_usec} field of a
1841 @code{timeval} structure; see @ref{High-Resolution Calendar}.
1842
1843 The @code{utimes} function is like @code{utime}, but also lets you specify
1844 the fractional part of the file times.  The prototype for this function is
1845 in the header file @file{sys/time.h}.
1846 @pindex sys/time.h
1847
1848 @comment sys/time.h
1849 @comment BSD
1850 @deftypefun int utimes (const char *@var{filename}, struct timeval @var{tvp}@t{[2]})
1851 This function sets the file access and modification times for the file
1852 named by @var{filename}.  The new file access time is specified by
1853 @code{@var{tvp}[0]}, and the new modification time by
1854 @code{@var{tvp}[1]}.  This function comes from BSD.
1855
1856 The return values and error conditions are the same as for the @code{utime}
1857 function.
1858 @end deftypefun
1859
1860 @node Making Special Files
1861 @section Making Special Files
1862 @cindex creating special files
1863 @cindex special files
1864
1865 The @code{mknod} function is the primitive for making special files,
1866 such as files that correspond to devices.  The GNU library includes
1867 this function for compatibility with BSD.
1868
1869 The prototype for @code{mknod} is declared in @file{sys/stat.h}.
1870 @pindex sys/stat.h
1871
1872 @comment sys/stat.h
1873 @comment BSD
1874 @deftypefun int mknod (const char *@var{filename}, int @var{mode}, int @var{dev})
1875 The @code{mknod} function makes a special file with name @var{filename}.
1876 The @var{mode} specifies the mode of the file, and may include the various
1877 special file bits, such as @code{S_IFCHR} (for a character special file)
1878 or @code{S_IFBLK} (for a block special file).  @xref{Testing File Type}.
1879
1880 The @var{dev} argument specifies which device the special file refers to.
1881 Its exact interpretation depends on the kind of special file being created.
1882
1883 The return value is @code{0} on success and @code{-1} on error.  In addition
1884 to the usual file name syntax errors (@pxref{File Name Errors}), the
1885 following @code{errno} error conditions are defined for this function:
1886
1887 @table @code
1888 @item EPERM
1889 The calling process is not privileged.  Only the superuser can create
1890 special files.
1891
1892 @item ENOSPC
1893 The directory or file system that would contain the new file is ``full''
1894 and cannot be extended.
1895
1896 @item EROFS
1897 The directory containing the new file can't be modified because it's on
1898 a read-only file system.
1899
1900 @item EEXIST
1901 There is already a file named @var{filename}.  If you want to replace
1902 this file, you must remove the old file explicitly first.
1903 @end table
1904 @end deftypefun
1905
1906 @node Temporary Files
1907 @section Temporary Files
1908
1909 If you need to use a temporary file in your program, you can use the
1910 @code{tmpfile} function to open it.  Or you can use the @code{tmpnam}
1911 function make a name for a temporary file and then open it in the usual
1912 way with @code{fopen}.
1913
1914 The @code{tempnam} function is like @code{tmpnam} but lets you choose
1915 what directory temporary files will go in, and something about what
1916 their file names will look like.
1917
1918 These facilities are declared in the header file @file{stdio.h}.
1919 @pindex stdio.h
1920
1921 @comment stdio.h
1922 @comment ANSI
1923 @deftypefun {FILE *} tmpfile (void)
1924 This function creates a temporary binary file for update mode, as if by
1925 calling @code{fopen} with mode @code{"wb+"}.  The file is deleted
1926 automatically when it is closed or when the program terminates.  (On
1927 some other ANSI C systems the file may fail to be deleted if the program
1928 terminates abnormally).
1929 @end deftypefun
1930
1931 @comment stdio.h
1932 @comment ANSI
1933 @deftypefun {char *} tmpnam (char *@var{result})
1934 This function constructs and returns a file name that is a valid file
1935 name and that does not name any existing file.  If the @var{result}
1936 argument is a null pointer, the return value is a pointer to an internal
1937 static string, which might be modified by subsequent calls.  Otherwise,
1938 the @var{result} argument should be a pointer to an array of at least
1939 @code{L_tmpnam} characters, and the result is written into that array.
1940
1941 It is possible for @code{tmpnam} to fail if you call it too many times.
1942 This is because the fixed length of a temporary file name gives room for
1943 only a finite number of different names.  If @code{tmpnam} fails, it
1944 returns a null pointer.
1945 @end deftypefun
1946
1947 @comment stdio.h
1948 @comment ANSI
1949 @deftypevr Macro int L_tmpnam
1950 The value of this macro is an integer constant expression that represents
1951 the minimum allocation size of a string large enough to hold the
1952 file name generated by the @code{tmpnam} function.
1953 @end deftypevr
1954
1955 @comment stdio.h
1956 @comment ANSI
1957 @deftypevr Macro int TMP_MAX
1958 The macro @code{TMP_MAX} is a lower bound for how many temporary names
1959 you can create with @code{tmpnam}.  You can rely on being able to call
1960 @code{tmpnam} at least this many times before it might fail saying you
1961 have made too many temporary file names.
1962
1963 With the GNU library, you can create a very large number of temporary
1964 file names---if you actually create the files, you will probably run out
1965 of disk space before you run out of names.  Some other systems have a
1966 fixed, small limit on the number of temporary files.  The limit is never
1967 less than @code{25}.
1968 @end deftypevr
1969
1970 @comment stdio.h
1971 @comment SVID
1972 @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix})
1973 This function generates a unique temporary filename.  If @var{prefix} is
1974 not a null pointer, up to five characters of this string are used as a
1975 prefix for the file name.  The return value is a string newly allocated
1976 with @code{malloc}; you should release its storage with @code{free} when
1977 it is no longer needed.
1978
1979 The directory prefix for the temporary file name is determined by testing
1980 each of the following, in sequence.  The directory must exist and be
1981 writable.
1982
1983 @itemize @bullet
1984 @item
1985 The environment variable @code{TMPDIR}, if it is defined.
1986
1987 @item
1988 The @var{dir} argument, if it is not a null pointer.
1989
1990 @item
1991 The value of the @code{P_tmpdir} macro.
1992
1993 @item
1994 The directory @file{/tmp}.
1995 @end itemize
1996
1997 This function is defined for SVID compatibility.
1998 @end deftypefun
1999 @cindex TMPDIR environment variable
2000
2001 @comment stdio.h
2002 @comment SVID
2003 @c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not??
2004 @deftypevr {SVID Macro} {char *} P_tmpdir
2005 This macro is the name of the default directory for temporary files.
2006 @end deftypevr
2007
2008 Older Unix systems did not have the functions just described.  Instead
2009 they used @code{mktemp} and @code{mkstemp}.  Both of these functions
2010 work by modifying a file name template string you pass.  The last six
2011 characters of this string must be @samp{XXXXXX}.  These six @samp{X}s
2012 are replaced with six characters which make the whole string a unique
2013 file name.  Usually the template string is something like
2014 @samp{/tmp/@var{prefix}XXXXXX}, and each program uses a unique @var{prefix}.
2015
2016 @strong{Note:} Because @code{mktemp} and @code{mkstemp} modify the
2017 template string, you @emph{must not} pass string constants to them.
2018 String constants are normally in read-only storage, so your program
2019 would crash when @code{mktemp} or @code{mkstemp} tried to modify the
2020 string.
2021
2022 @comment unistd.h
2023 @comment Unix
2024 @deftypefun {char *} mktemp (char *@var{template})
2025 The @code{mktemp} function generates a unique file name by modifying
2026 @var{template} as described above.  If successful, it returns
2027 @var{template} as modified.  If @code{mktemp} cannot find a unique file
2028 name, it makes @var{template} an empty string and returns that.  If
2029 @var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a
2030 null pointer.
2031 @end deftypefun
2032
2033 @comment unistd.h
2034 @comment BSD
2035 @deftypefun int mkstemp (char *@var{template})
2036 The @code{mkstemp} function generates a unique file name just as
2037 @code{mktemp} does, but it also opens the file for you with @code{open}
2038 (@pxref{Opening and Closing Files}).  If successful, it modifies
2039 @var{template} in place and returns a file descriptor open on that file
2040 for reading and writing.  If @code{mkstemp} cannot create a
2041 uniquely-named file, it makes @var{template} an empty string and returns
2042 @code{-1}.  If @var{template} does not end with @samp{XXXXXX},
2043 @code{mkstemp} returns @code{-1} and does not modify @var{template}.
2044 @end deftypefun
2045
2046 Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a
2047 unique file that cannot possibly clash with any other program trying to
2048 create a temporary file.  This is because it works by calling
2049 @code{open} with the @code{O_EXCL} flag bit, which says you want to
2050 always create a new file, and get an error if the file already exists.