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