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