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