about summary refs log tree commit diff
path: root/REORG.TODO/manual/filesys.texi
diff options
context:
space:
mode:
Diffstat (limited to 'REORG.TODO/manual/filesys.texi')
-rw-r--r--REORG.TODO/manual/filesys.texi3657
1 files changed, 3657 insertions, 0 deletions
diff --git a/REORG.TODO/manual/filesys.texi b/REORG.TODO/manual/filesys.texi
new file mode 100644
index 0000000000..e3fe323f47
--- /dev/null
+++ b/REORG.TODO/manual/filesys.texi
@@ -0,0 +1,3657 @@
+@node File System Interface, Pipes and FIFOs, Low-Level I/O, Top
+@c %MENU% Functions for manipulating files
+@chapter File System Interface
+
+This chapter describes @theglibc{}'s functions for manipulating
+files.  Unlike the input and output functions (@pxref{I/O on Streams};
+@pxref{Low-Level I/O}), these functions are concerned with operating
+on the files themselves rather than on their contents.
+
+Among the facilities described in this chapter are functions for
+examining or modifying directories, functions for renaming and deleting
+files, and functions for examining and setting file attributes such as
+access permissions and modification times.
+
+@menu
+* Working Directory::           This is used to resolve relative
+				 file names.
+* Accessing Directories::       Finding out what files a directory
+				 contains.
+* Working with Directory Trees:: Apply actions to all files or a selectable
+                                 subset of a directory hierarchy.
+* Hard Links::                  Adding alternate names to a file.
+* Symbolic Links::              A file that ``points to'' a file name.
+* Deleting Files::              How to delete a file, and what that means.
+* Renaming Files::              Changing a file's name.
+* Creating Directories::        A system call just for creating a directory.
+* File Attributes::             Attributes of individual files.
+* Making Special Files::        How to create special files.
+* Temporary Files::             Naming and creating temporary files.
+@end menu
+
+@node Working Directory
+@section Working Directory
+
+@cindex current working directory
+@cindex working directory
+@cindex change working directory
+Each process has associated with it a directory, called its @dfn{current
+working directory} or simply @dfn{working directory}, that is used in
+the resolution of relative file names (@pxref{File Name Resolution}).
+
+When you log in and begin a new session, your working directory is
+initially set to the home directory associated with your login account
+in the system user database.  You can find any user's home directory
+using the @code{getpwuid} or @code{getpwnam} functions; see @ref{User
+Database}.
+
+Users can change the working directory using shell commands like
+@code{cd}.  The functions described in this section are the primitives
+used by those commands and by other programs for examining and changing
+the working directory.
+@pindex cd
+
+Prototypes for these functions are declared in the header file
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c If buffer is NULL, this function calls malloc and realloc, and, in
+@c case of error, free.  Linux offers a getcwd syscall that we use on
+@c GNU/Linux systems, but it may fail if the pathname is too long.  As a
+@c fallback, and on other systems, the generic implementation opens each
+@c parent directory with opendir, which allocates memory for the
+@c directory stream with malloc.  If a fstatat64 syscall is not
+@c available, very deep directory trees may also have to malloc to build
+@c longer sequences of ../../../... than those supported by a global
+@c const read-only string.
+
+@c linux/__getcwd
+@c  posix/__getcwd
+@c   malloc/realloc/free if buffer is NULL, or if dir is too deep
+@c   lstat64 -> see its own entry
+@c   fstatat64
+@c     direct syscall if possible, alloca+snprintf+*stat64 otherwise
+@c   openat64_not_cancel_3, close_not_cancel_no_status
+@c   __fdopendir, __opendir, __readdir, rewinddir
+The @code{getcwd} function returns an absolute file name representing
+the current working directory, storing it in the character array
+@var{buffer} that you provide.  The @var{size} argument is how you tell
+the system the allocation size of @var{buffer}.
+
+The @glibcadj{} version of this function also permits you to specify a
+null pointer for the @var{buffer} argument.  Then @code{getcwd}
+allocates a buffer automatically, as with @code{malloc}
+(@pxref{Unconstrained Allocation}).  If the @var{size} is greater than
+zero, then the buffer is that large; otherwise, the buffer is as large
+as necessary to hold the result.
+
+The return value is @var{buffer} on success and a null pointer on failure.
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The @var{size} argument is zero and @var{buffer} is not a null pointer.
+
+@item ERANGE
+The @var{size} argument is less than the length of the working directory
+name.  You need to allocate a bigger array and try again.
+
+@item EACCES
+Permission to read or search a component of the file name was denied.
+@end table
+@end deftypefun
+
+You could implement the behavior of GNU's @w{@code{getcwd (NULL, 0)}}
+using only the standard behavior of @code{getcwd}:
+
+@smallexample
+char *
+gnu_getcwd ()
+@{
+  size_t size = 100;
+
+  while (1)
+    @{
+      char *buffer = (char *) xmalloc (size);
+      if (getcwd (buffer, size) == buffer)
+        return buffer;
+      free (buffer);
+      if (errno != ERANGE)
+        return 0;
+      size *= 2;
+    @}
+@}
+@end smallexample
+
+@noindent
+@xref{Malloc Examples}, for information about @code{xmalloc}, which is
+not a library function but is a customary name used in most GNU
+software.
+
+@comment unistd.h
+@comment BSD
+@deftypefn {Deprecated Function} {char *} getwd (char *@var{buffer})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Besides the getcwd safety issues, it calls strerror_r on error, which
+@c brings in all of the i18n issues.
+This is similar to @code{getcwd}, but has no way to specify the size of
+the buffer.  @Theglibc{} provides @code{getwd} only
+for backwards compatibility with BSD.
+
+The @var{buffer} argument should be a pointer to an array at least
+@code{PATH_MAX} bytes long (@pxref{Limits for Files}).  On @gnuhurdsystems{}
+there is no limit to the size of a file name, so this is not
+necessarily enough space to contain the directory name.  That is why
+this function is deprecated.
+@end deftypefn
+
+@comment unistd.h
+@comment GNU
+@deftypefun {char *} get_current_dir_name (void)
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Besides getcwd, which this function calls as a fallback, it calls
+@c getenv, with the potential thread-safety issues that brings about.
+@vindex PWD
+This @code{get_current_dir_name} function is basically equivalent to
+@w{@code{getcwd (NULL, 0)}}.  The only difference is that the value of
+the @code{PWD} variable is returned if this value is correct.  This is a
+subtle difference which is visible if the path described by the
+@code{PWD} value is using one or more symbol links in which case the
+value returned by @code{getcwd} can resolve the symbol links and
+therefore yield a different result.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int chdir (const char *@var{filename})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is used to set the process's working directory to
+@var{filename}.
+
+The normal, successful return value from @code{chdir} is @code{0}.  A
+value of @code{-1} is returned to indicate an error.  The @code{errno}
+error conditions defined for this function are the usual file name
+syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the
+file @var{filename} is not a directory.
+@end deftypefun
+
+@comment unistd.h
+@comment XPG
+@deftypefun int fchdir (int @var{filedes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is used to set the process's working directory to
+directory associated with the file descriptor @var{filedes}.
+
+The normal, successful return value from @code{fchdir} is @code{0}.  A
+value of @code{-1} is returned to indicate an error.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EACCES
+Read permission is denied for the directory named by @code{dirname}.
+
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENOTDIR
+The file descriptor @var{filedes} is not associated with a directory.
+
+@item EINTR
+The function call was interrupt by a signal.
+
+@item EIO
+An I/O error occurred.
+@end table
+@end deftypefun
+
+
+@node Accessing Directories
+@section Accessing Directories
+@cindex accessing directories
+@cindex reading from a directory
+@cindex directories, accessing
+
+The facilities described in this section let you read the contents of a
+directory file.  This is useful if you want your program to list all the
+files in a directory, perhaps as part of a menu.
+
+@cindex directory stream
+The @code{opendir} function opens a @dfn{directory stream} whose
+elements are directory entries.  Alternatively @code{fdopendir} can be
+used which can have advantages if the program needs to have more
+control over the way the directory is opened for reading.  This
+allows, for instance, to pass the @code{O_NOATIME} flag to
+@code{open}.
+
+You use the @code{readdir} function on the directory stream to
+retrieve these entries, represented as @w{@code{struct dirent}}
+objects.  The name of the file for each entry is stored in the
+@code{d_name} member of this structure.  There are obvious parallels
+here to the stream facilities for ordinary files, described in
+@ref{I/O on Streams}.
+
+@menu
+* Directory Entries::           Format of one directory entry.
+* Opening a Directory::         How to open a directory stream.
+* Reading/Closing Directory::   How to read directory entries from the stream.
+* Simple Directory Lister::     A very simple directory listing program.
+* Random Access Directory::     Rereading part of the directory
+                                 already read with the same stream.
+* Scanning Directory Content::  Get entries for user selected subset of
+                                 contents in given directory.
+* Simple Directory Lister Mark II::  Revised version of the program.
+@end menu
+
+@node Directory Entries
+@subsection Format of a Directory Entry
+
+@pindex dirent.h
+This section describes what you find in a single directory entry, as you
+might obtain it from a directory stream.  All the symbols are declared
+in the header file @file{dirent.h}.
+
+@comment dirent.h
+@comment POSIX.1
+@deftp {Data Type} {struct dirent}
+This is a structure type used to return information about directory
+entries.  It contains the following fields:
+
+@table @code
+@item char d_name[]
+This is the null-terminated file name component.  This is the only
+field you can count on in all POSIX systems.
+
+@item ino_t d_fileno
+This is the file serial number.  For BSD compatibility, you can also
+refer to this member as @code{d_ino}.  On @gnulinuxhurdsystems{} and most POSIX
+systems, for most files this the same as the @code{st_ino} member that
+@code{stat} will return for the file.  @xref{File Attributes}.
+
+@item unsigned char d_namlen
+This is the length of the file name, not including the terminating
+null character.  Its type is @code{unsigned char} because that is the
+integer type of the appropriate size.  This member is a BSD extension.
+The symbol @code{_DIRENT_HAVE_D_NAMLEN} is defined if this member is
+available.
+
+@item unsigned char d_type
+This is the type of the file, possibly unknown.  The following constants
+are defined for its value:
+
+@vtable @code
+@item DT_UNKNOWN
+The type is unknown.  Only some filesystems have full support to
+return the type of the file, others might always return this value.
+
+@item DT_REG
+A regular file.
+
+@item DT_DIR
+A directory.
+
+@item DT_FIFO
+A named pipe, or FIFO.  @xref{FIFO Special Files}.
+
+@item DT_SOCK
+A local-domain socket.  @c !!! @xref{Local Domain}.
+
+@item DT_CHR
+A character device.
+
+@item DT_BLK
+A block device.
+
+@item DT_LNK
+A symbolic link.
+@end vtable
+
+This member is a BSD extension.  The symbol @code{_DIRENT_HAVE_D_TYPE}
+is defined if this member is available.  On systems where it is used, it
+corresponds to the file type bits in the @code{st_mode} member of
+@code{struct stat}.  If the value cannot be determined the member
+value is DT_UNKNOWN.  These two macros convert between @code{d_type}
+values and @code{st_mode} values:
+
+@comment dirent.h
+@comment BSD
+@deftypefun int IFTODT (mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This returns the @code{d_type} value corresponding to @var{mode}.
+@end deftypefun
+
+@comment dirent.h
+@comment BSD
+@deftypefun mode_t DTTOIF (int @var{dtype})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This returns the @code{st_mode} value corresponding to @var{dtype}.
+@end deftypefun
+@end table
+
+This structure may contain additional members in the future.  Their
+availability is always announced in the compilation environment by a
+macro named @code{_DIRENT_HAVE_D_@var{xxx}} where @var{xxx} is replaced
+by the name of the new member.  For instance, the member @code{d_reclen}
+available on some systems is announced through the macro
+@code{_DIRENT_HAVE_D_RECLEN}.
+
+When a file has multiple names, each name has its own directory entry.
+The only way you can tell that the directory entries belong to a
+single file is that they have the same value for the @code{d_fileno}
+field.
+
+File attributes such as size, modification times etc., are part of the
+file itself, not of any particular directory entry.  @xref{File
+Attributes}.
+@end deftp
+
+@node Opening a Directory
+@subsection Opening a Directory Stream
+
+@pindex dirent.h
+This section describes how to open a directory stream.  All the symbols
+are declared in the header file @file{dirent.h}.
+
+@comment dirent.h
+@comment POSIX.1
+@deftp {Data Type} DIR
+The @code{DIR} data type represents a directory stream.
+@end deftp
+
+You shouldn't ever allocate objects of the @code{struct dirent} or
+@code{DIR} data types, since the directory access functions do that for
+you.  Instead, you refer to these objects using the pointers returned by
+the following functions.
+
+@comment dirent.h
+@comment POSIX.1
+@deftypefun {DIR *} opendir (const char *@var{dirname})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Besides the safe syscall, we have to allocate the DIR object with
+@c __alloc_dir, that calls malloc.
+The @code{opendir} function opens and returns a directory stream for
+reading the directory whose file name is @var{dirname}.  The stream has
+type @code{DIR *}.
+
+If unsuccessful, @code{opendir} returns a null pointer.  In addition to
+the usual file name errors (@pxref{File Name Errors}), the
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EACCES
+Read permission is denied for the directory named by @code{dirname}.
+
+@item EMFILE
+The process has too many files open.
+
+@item ENFILE
+The entire system, or perhaps the file system which contains the
+directory, cannot support any additional open files at the moment.
+(This problem cannot happen on @gnuhurdsystems{}.)
+
+@item ENOMEM
+Not enough memory available.
+@end table
+
+The @code{DIR} type is typically implemented using a file descriptor,
+and the @code{opendir} function in terms of the @code{open} function.
+@xref{Low-Level I/O}.  Directory streams and the underlying
+file descriptors are closed on @code{exec} (@pxref{Executing a File}).
+@end deftypefun
+
+The directory which is opened for reading by @code{opendir} is
+identified by the name.  In some situations this is not sufficient.
+Or the way @code{opendir} implicitly creates a file descriptor for the
+directory is not the way a program might want it.  In these cases an
+alternative interface can be used.
+
+@comment dirent.h
+@comment GNU
+@deftypefun {DIR *} fdopendir (int @var{fd})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c The DIR object is allocated with __alloc_dir, that calls malloc.
+The @code{fdopendir} function works just like @code{opendir} but
+instead of taking a file name and opening a file descriptor for the
+directory the caller is required to provide a file descriptor.  This
+file descriptor is then used in subsequent uses of the returned
+directory stream object.
+
+The caller must make sure the file descriptor is associated with a
+directory and it allows reading.
+
+If the @code{fdopendir} call returns successfully the file descriptor
+is now under the control of the system.  It can be used in the same
+way the descriptor implicitly created by @code{opendir} can be used
+but the program must not close the descriptor.
+
+In case the function is unsuccessful it returns a null pointer and the
+file descriptor remains to be usable by the program.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The file descriptor is not valid.
+
+@item ENOTDIR
+The file descriptor is not associated with a directory.
+
+@item EINVAL
+The descriptor does not allow reading the directory content.
+
+@item ENOMEM
+Not enough memory available.
+@end table
+@end deftypefun
+
+In some situations it can be desirable to get hold of the file
+descriptor which is created by the @code{opendir} call.  For instance,
+to switch the current working directory to the directory just read the
+@code{fchdir} function could be used.  Historically the @code{DIR} type
+was exposed and programs could access the fields.  This does not happen
+in @theglibc{}.  Instead a separate function is provided to allow
+access.
+
+@comment dirent.h
+@comment GNU
+@deftypefun int dirfd (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{dirfd} returns the file descriptor associated with
+the directory stream @var{dirstream}.  This descriptor can be used until
+the directory is closed with @code{closedir}.  If the directory stream
+implementation is not using file descriptors the return value is
+@code{-1}.
+@end deftypefun
+
+@node Reading/Closing Directory
+@subsection Reading and Closing a Directory Stream
+
+@pindex dirent.h
+This section describes how to read directory entries from a directory
+stream, and how to close the stream when you are done with it.  All the
+symbols are declared in the header file @file{dirent.h}.
+
+@comment dirent.h
+@comment POSIX.1
+@deftypefun {struct dirent *} readdir (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c This function holds dirstream's non-recursive lock, which brings
+@c about the usual issues with locks and async signals and cancellation,
+@c but the lock taking is not enough to make the returned value safe to
+@c use, since it points to a stream's internal buffer that can be
+@c overwritten by subsequent calls or even released by closedir.
+This function reads the next entry from the directory.  It normally
+returns a pointer to a structure containing information about the
+file.  This structure is associated with the @var{dirstream} handle
+and can be rewritten by a subsequent call.
+
+@strong{Portability Note:} On some systems @code{readdir} may not
+return entries for @file{.} and @file{..}, even though these are always
+valid file names in any directory.  @xref{File Name Resolution}.
+
+If there are no more entries in the directory or an error is detected,
+@code{readdir} returns a null pointer.  The following @code{errno} error
+conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{dirstream} argument is not valid.
+@end table
+
+To distinguish between an end-of-directory condition or an error, you
+must set @code{errno} to zero before calling @code{readdir}.  To avoid
+entering an infinite loop, you should stop reading from the directory
+after the first error.
+
+@strong{Caution:} The pointer returned by @code{readdir} points to
+a buffer within the @code{DIR} object.  The data in that buffer will
+be overwritten by the next call to @code{readdir}.  You must take care,
+for instance, to copy the @code{d_name} string if you need it later.
+
+Because of this, it is not safe to share a @code{DIR} object among
+multiple threads, unless you use your own locking to ensure that
+no thread calls @code{readdir} while another thread is still using the
+data from the previous call.  In @theglibc{}, it is safe to call
+@code{readdir} from multiple threads as long as each thread uses
+its own @code{DIR} object.  POSIX.1-2008 does not require this to
+be safe, but we are not aware of any operating systems where it
+does not work.
+
+@code{readdir_r} allows you to provide your own buffer for the
+@code{struct dirent}, but it is less portable than @code{readdir}, and
+has problems with very long filenames (see below).  We recommend
+you use @code{readdir}, but do not share @code{DIR} objects.
+@end deftypefun
+
+@comment dirent.h
+@comment GNU
+@deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+This function is a version of @code{readdir} which performs internal
+locking.  Like @code{readdir} it returns the next entry from the
+directory.  To prevent conflicts between simultaneously running
+threads the result is stored inside the @var{entry} object.
+
+@strong{Portability Note:} @code{readdir_r} is deprecated.  It is
+recommended to use @code{readdir} instead of @code{readdir_r} for the
+following reasons:
+
+@itemize @bullet
+@item
+On systems which do not define @code{NAME_MAX}, it may not be possible
+to use @code{readdir_r} safely because the caller does not specify the
+length of the buffer for the directory entry.
+
+@item
+On some systems, @code{readdir_r} cannot read directory entries with
+very long names.  If such a name is encountered, @theglibc{}
+implementation of @code{readdir_r} returns with an error code of
+@code{ENAMETOOLONG} after the final directory entry has been read.  On
+other systems, @code{readdir_r} may return successfully, but the
+@code{d_name} member may not be NUL-terminated or may be truncated.
+
+@item
+POSIX-1.2008 does not guarantee that @code{readdir} is thread-safe,
+even when access to the same @var{dirstream} is serialized.  But in
+current implementations (including @theglibc{}), it is safe to call
+@code{readdir} concurrently on different @var{dirstream}s, so there is
+no need to use @code{readdir_r} in most multi-threaded programs.  In
+the rare case that multiple threads need to read from the same
+@var{dirstream}, it is still better to use @code{readdir} and external
+synchronization.
+
+@item
+It is expected that future versions of POSIX will obsolete
+@code{readdir_r} and mandate the level of thread safety for
+@code{readdir} which is provided by @theglibc{} and other
+implementations today.
+@end itemize
+
+Normally @code{readdir_r} returns zero and sets @code{*@var{result}}
+to @var{entry}.  If there are no more entries in the directory or an
+error is detected, @code{readdir_r} sets @code{*@var{result}} to a
+null pointer and returns a nonzero error code, also stored in
+@code{errno}, as described for @code{readdir}.
+
+It is also important to look at the definition of the @code{struct
+dirent} type.  Simply passing a pointer to an object of this type for
+the second parameter of @code{readdir_r} might not be enough.  Some
+systems don't define the @code{d_name} element sufficiently long.  In
+this case the user has to provide additional space.  There must be room
+for at least @code{NAME_MAX + 1} characters in the @code{d_name} array.
+Code to call @code{readdir_r} could look like this:
+
+@smallexample
+  union
+  @{
+    struct dirent d;
+    char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];
+  @} u;
+
+  if (readdir_r (dir, &u.d, &res) == 0)
+    @dots{}
+@end smallexample
+@end deftypefun
+
+To support large filesystems on 32-bit machines there are LFS variants
+of the last two functions.
+
+@comment dirent.h
+@comment LFS
+@deftypefun {struct dirent64 *} readdir64 (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The @code{readdir64} function is just like the @code{readdir} function
+except that it returns a pointer to a record of type @code{struct
+dirent64}.  Some of the members of this data type (notably @code{d_ino})
+might have a different size to allow large filesystems.
+
+In all other aspects this function is equivalent to @code{readdir}.
+@end deftypefun
+
+@comment dirent.h
+@comment LFS
+@deftypefun int readdir64_r (DIR *@var{dirstream}, struct dirent64 *@var{entry}, struct dirent64 **@var{result})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The deprecated @code{readdir64_r} function is equivalent to the
+@code{readdir_r} function except that it takes parameters of base type
+@code{struct dirent64} instead of @code{struct dirent} in the second and
+third position.  The same precautions mentioned in the documentation of
+@code{readdir_r} also apply here.
+@end deftypefun
+
+@comment dirent.h
+@comment POSIX.1
+@deftypefun int closedir (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@acsmem{} @acsfd{} @aculock{/hurd}}}
+@c No synchronization in the posix implementation, only in the hurd
+@c one.  This is regarded as safe because it is undefined behavior if
+@c other threads could still be using the dir stream while it's closed.
+This function closes the directory stream @var{dirstream}.  It returns
+@code{0} on success and @code{-1} on failure.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EBADF
+The @var{dirstream} argument is not valid.
+@end table
+@end deftypefun
+
+@node Simple Directory Lister
+@subsection Simple Program to List a Directory
+
+Here's a simple program that prints the names of the files in
+the current working directory:
+
+@smallexample
+@include dir.c.texi
+@end smallexample
+
+The order in which files appear in a directory tends to be fairly
+random.  A more useful program would sort the entries (perhaps by
+alphabetizing them) before printing them; see
+@ref{Scanning Directory Content}, and @ref{Array Sort Function}.
+
+
+@node Random Access Directory
+@subsection Random Access in a Directory Stream
+
+@pindex dirent.h
+This section describes how to reread parts of a directory that you have
+already read from an open directory stream.  All the symbols are
+declared in the header file @file{dirent.h}.
+
+@comment dirent.h
+@comment POSIX.1
+@deftypefun void rewinddir (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The @code{rewinddir} function is used to reinitialize the directory
+stream @var{dirstream}, so that if you call @code{readdir} it
+returns information about the first entry in the directory again.  This
+function also notices if files have been added or removed to the
+directory since it was opened with @code{opendir}.  (Entries for these
+files might or might not be returned by @code{readdir} if they were
+added or removed since you last called @code{opendir} or
+@code{rewinddir}.)
+@end deftypefun
+
+@comment dirent.h
+@comment BSD
+@deftypefun {long int} telldir (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}}
+@c The implementation is safe on most platforms, but on BSD it uses
+@c cookies, buckets and records, and the global array of pointers to
+@c dynamically allocated records is guarded by a non-recursive lock.
+The @code{telldir} function returns the file position of the directory
+stream @var{dirstream}.  You can use this value with @code{seekdir} to
+restore the directory stream to that position.
+@end deftypefun
+
+@comment dirent.h
+@comment BSD
+@deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}}
+@c The implementation is safe on most platforms, but on BSD it uses
+@c cookies, buckets and records, and the global array of pointers to
+@c dynamically allocated records is guarded by a non-recursive lock.
+The @code{seekdir} function sets the file position of the directory
+stream @var{dirstream} to @var{pos}.  The value @var{pos} must be the
+result of a previous call to @code{telldir} on this particular stream;
+closing and reopening the directory can invalidate values returned by
+@code{telldir}.
+@end deftypefun
+
+
+@node Scanning Directory Content
+@subsection Scanning the Content of a Directory
+
+A higher-level interface to the directory handling functions is the
+@code{scandir} function.  With its help one can select a subset of the
+entries in a directory, possibly sort them and get a list of names as
+the result.
+
+@comment dirent.h
+@comment BSD, SVID
+@deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const struct dirent **, const struct dirent **))
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c The scandir function calls __opendirat, __readdir, and __closedir to
+@c go over the named dir; malloc and realloc to allocate the namelist
+@c and copies of each selected dirent, besides the selector, if given,
+@c and qsort and the cmp functions if the latter is given.  In spite of
+@c the cleanup handler that releases memory and the file descriptor in
+@c case of synchronous cancellation, an asynchronous cancellation may
+@c still leak memory and a file descriptor.  Although readdir is unsafe
+@c in general, the use of an internal dir stream for sequential scanning
+@c of the directory with copying of dirents before subsequent calls
+@c makes the use safe, and the fact that the dir stream is private to
+@c each scandir call does away with the lock issues in readdir and
+@c closedir.
+
+The @code{scandir} function scans the contents of the directory selected
+by @var{dir}.  The result in *@var{namelist} is an array of pointers to
+structures of type @code{struct dirent} which describe all selected
+directory entries and which is allocated using @code{malloc}.  Instead
+of always getting all directory entries returned, the user supplied
+function @var{selector} can be used to decide which entries are in the
+result.  Only the entries for which @var{selector} returns a non-zero
+value are selected.
+
+Finally the entries in *@var{namelist} are sorted using the
+user-supplied function @var{cmp}.  The arguments passed to the @var{cmp}
+function are of type @code{struct dirent **}, therefore one cannot
+directly use the @code{strcmp} or @code{strcoll} functions; instead see
+the functions @code{alphasort} and @code{versionsort} below.
+
+The return value of the function is the number of entries placed in
+*@var{namelist}.  If it is @code{-1} an error occurred (either the
+directory could not be opened for reading or the malloc call failed) and
+the global variable @code{errno} contains more information on the error.
+@end deftypefun
+
+As described above, the fourth argument to the @code{scandir} function
+must be a pointer to a sorting function.  For the convenience of the
+programmer @theglibc{} contains implementations of functions which
+are very helpful for this purpose.
+
+@comment dirent.h
+@comment BSD, SVID
+@deftypefun int alphasort (const struct dirent **@var{a}, const struct dirent **@var{b})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c Calls strcoll.
+The @code{alphasort} function behaves like the @code{strcoll} function
+(@pxref{String/Array Comparison}).  The difference is that the arguments
+are not string pointers but instead they are of type
+@code{struct dirent **}.
+
+The return value of @code{alphasort} is less than, equal to, or greater
+than zero depending on the order of the two entries @var{a} and @var{b}.
+@end deftypefun
+
+@comment dirent.h
+@comment GNU
+@deftypefun int versionsort (const struct dirent **@var{a}, const struct dirent **@var{b})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Calls strverscmp, which will accesses the locale object multiple
+@c times.
+The @code{versionsort} function is like @code{alphasort} except that it
+uses the @code{strverscmp} function internally.
+@end deftypefun
+
+If the filesystem supports large files we cannot use the @code{scandir}
+anymore since the @code{dirent} structure might not able to contain all
+the information.  The LFS provides the new type @w{@code{struct
+dirent64}}.  To use this we need a new function.
+
+@comment dirent.h
+@comment GNU
+@deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const struct dirent64 **, const struct dirent64 **))
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c See scandir.
+The @code{scandir64} function works like the @code{scandir} function
+except that the directory entries it returns are described by elements
+of type @w{@code{struct dirent64}}.  The function pointed to by
+@var{selector} is again used to select the desired entries, except that
+@var{selector} now must point to a function which takes a
+@w{@code{struct dirent64 *}} parameter.
+
+Similarly the @var{cmp} function should expect its two arguments to be
+of type @code{struct dirent64 **}.
+@end deftypefun
+
+As @var{cmp} is now a function of a different type, the functions
+@code{alphasort} and @code{versionsort} cannot be supplied for that
+argument.  Instead we provide the two replacement functions below.
+
+@comment dirent.h
+@comment GNU
+@deftypefun int alphasort64 (const struct dirent64 **@var{a}, const struct dirent **@var{b})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c See alphasort.
+The @code{alphasort64} function behaves like the @code{strcoll} function
+(@pxref{String/Array Comparison}).  The difference is that the arguments
+are not string pointers but instead they are of type
+@code{struct dirent64 **}.
+
+Return value of @code{alphasort64} is less than, equal to, or greater
+than zero depending on the order of the two entries @var{a} and @var{b}.
+@end deftypefun
+
+@comment dirent.h
+@comment GNU
+@deftypefun int versionsort64 (const struct dirent64 **@var{a}, const struct dirent64 **@var{b})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c See versionsort.
+The @code{versionsort64} function is like @code{alphasort64}, excepted that it
+uses the @code{strverscmp} function internally.
+@end deftypefun
+
+It is important not to mix the use of @code{scandir} and the 64-bit
+comparison functions or vice versa.  There are systems on which this
+works but on others it will fail miserably.
+
+@node Simple Directory Lister Mark II
+@subsection Simple Program to List a Directory, Mark II
+
+Here is a revised version of the directory lister found above
+(@pxref{Simple Directory Lister}).  Using the @code{scandir} function we
+can avoid the functions which work directly with the directory contents.
+After the call the returned entries are available for direct use.
+
+@smallexample
+@include dir2.c.texi
+@end smallexample
+
+Note the simple selector function in this example.  Since we want to see
+all directory entries we always return @code{1}.
+
+
+@node Working with Directory Trees
+@section Working with Directory Trees
+@cindex directory hierarchy
+@cindex hierarchy, directory
+@cindex tree, directory
+
+The functions described so far for handling the files in a directory
+have allowed you to either retrieve the information bit by bit, or to
+process all the files as a group (see @code{scandir}).  Sometimes it is
+useful to process whole hierarchies of directories and their contained
+files.  The X/Open specification defines two functions to do this.  The
+simpler form is derived from an early definition in @w{System V} systems
+and therefore this function is available on SVID-derived systems.  The
+prototypes and required definitions can be found in the @file{ftw.h}
+header.
+
+There are four functions in this family: @code{ftw}, @code{nftw} and
+their 64-bit counterparts @code{ftw64} and @code{nftw64}.  These
+functions take as one of their arguments a pointer to a callback
+function of the appropriate type.
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __ftw_func_t
+
+@smallexample
+int (*) (const char *, const struct stat *, int)
+@end smallexample
+
+The type of callback functions given to the @code{ftw} function.  The
+first parameter points to the file name, the second parameter to an
+object of type @code{struct stat} which is filled in for the file named
+in the first parameter.
+
+@noindent
+The last parameter is a flag giving more information about the current
+file.  It can have the following values:
+
+@vtable @code
+@item FTW_F
+The item is either a normal file or a file which does not fit into one
+of the following categories.  This could be special files, sockets etc.
+@item FTW_D
+The item is a directory.
+@item FTW_NS
+The @code{stat} call failed and so the information pointed to by the
+second parameter is invalid.
+@item FTW_DNR
+The item is a directory which cannot be read.
+@item FTW_SL
+The item is a symbolic link.  Since symbolic links are normally followed
+seeing this value in a @code{ftw} callback function means the referenced
+file does not exist.  The situation for @code{nftw} is different.
+
+This value is only available if the program is compiled with
+@code{_XOPEN_EXTENDED} defined before including
+the first header.  The original SVID systems do not have symbolic links.
+@end vtable
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+type is in fact @code{__ftw64_func_t} since this mode changes
+@code{struct stat} to be @code{struct stat64}.
+@end deftp
+
+For the LFS interface and for use in the function @code{ftw64}, the
+header @file{ftw.h} defines another function type.
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __ftw64_func_t
+
+@smallexample
+int (*) (const char *, const struct stat64 *, int)
+@end smallexample
+
+This type is used just like @code{__ftw_func_t} for the callback
+function, but this time is called from @code{ftw64}.  The second
+parameter to the function is a pointer to a variable of type
+@code{struct stat64} which is able to represent the larger values.
+@end deftp
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __nftw_func_t
+
+@smallexample
+int (*) (const char *, const struct stat *, int, struct FTW *)
+@end smallexample
+
+The first three arguments are the same as for the @code{__ftw_func_t}
+type.  However for the third argument some additional values are defined
+to allow finer differentiation:
+@vtable @code
+@item FTW_DP
+The current item is a directory and all subdirectories have already been
+visited and reported.  This flag is returned instead of @code{FTW_D} if
+the @code{FTW_DEPTH} flag is passed to @code{nftw} (see below).
+@item FTW_SLN
+The current item is a stale symbolic link.  The file it points to does
+not exist.
+@end vtable
+
+The last parameter of the callback function is a pointer to a structure
+with some extra information as described below.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+type is in fact @code{__nftw64_func_t} since this mode changes
+@code{struct stat} to be @code{struct stat64}.
+@end deftp
+
+For the LFS interface there is also a variant of this data type
+available which has to be used with the @code{nftw64} function.
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __nftw64_func_t
+
+@smallexample
+int (*) (const char *, const struct stat64 *, int, struct FTW *)
+@end smallexample
+
+This type is used just like @code{__nftw_func_t} for the callback
+function, but this time is called from @code{nftw64}.  The second
+parameter to the function is this time a pointer to a variable of type
+@code{struct stat64} which is able to represent the larger values.
+@end deftp
+
+@comment ftw.h
+@comment XPG4.2
+@deftp {Data Type} {struct FTW}
+The information contained in this structure helps in interpreting the
+name parameter and gives some information about the current state of the
+traversal of the directory hierarchy.
+
+@table @code
+@item int base
+The value is the offset into the string passed in the first parameter to
+the callback function of the beginning of the file name.  The rest of
+the string is the path of the file.  This information is especially
+important if the @code{FTW_CHDIR} flag was set in calling @code{nftw}
+since then the current directory is the one the current item is found
+in.
+@item int level
+Whilst processing, the code tracks how many directories down it has gone
+to find the current file.  This nesting level starts at @math{0} for
+files in the initial directory (or is zero for the initial file if a
+file was passed).
+@end table
+@end deftp
+
+
+@comment ftw.h
+@comment SVID
+@deftypefun int ftw (const char *@var{filename}, __ftw_func_t @var{func}, int @var{descriptors})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c see nftw for safety details
+The @code{ftw} function calls the callback function given in the
+parameter @var{func} for every item which is found in the directory
+specified by @var{filename} and all directories below.  The function
+follows symbolic links if necessary but does not process an item twice.
+If @var{filename} is not a directory then it itself is the only object
+returned to the callback function.
+
+The file name passed to the callback function is constructed by taking
+the @var{filename} parameter and appending the names of all passed
+directories and then the local file name.  So the callback function can
+use this parameter to access the file.  @code{ftw} also calls
+@code{stat} for the file and passes that information on to the callback
+function.  If this @code{stat} call is not successful the failure is
+indicated by setting the third argument of the callback function to
+@code{FTW_NS}.  Otherwise it is set according to the description given
+in the account of @code{__ftw_func_t} above.
+
+The callback function is expected to return @math{0} to indicate that no
+error occurred and that processing should continue.  If an error
+occurred in the callback function or it wants @code{ftw} to return
+immediately, the callback function can return a value other than
+@math{0}.  This is the only correct way to stop the function.  The
+program must not use @code{setjmp} or similar techniques to continue
+from another place.  This would leave resources allocated by the
+@code{ftw} function unfreed.
+
+The @var{descriptors} parameter to @code{ftw} specifies how many file
+descriptors it is allowed to consume.  The function runs faster the more
+descriptors it can use.  For each level in the directory hierarchy at
+most one descriptor is used, but for very deep ones any limit on open
+file descriptors for the process or the system may be exceeded.
+Moreover, file descriptor limits in a multi-threaded program apply to
+all the threads as a group, and therefore it is a good idea to supply a
+reasonable limit to the number of open descriptors.
+
+The return value of the @code{ftw} function is @math{0} if all callback
+function calls returned @math{0} and all actions performed by the
+@code{ftw} succeeded.  If a function call failed (other than calling
+@code{stat} on an item) the function returns @math{-1}.  If a callback
+function returns a value other than @math{0} this value is returned as
+the return value of @code{ftw}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is in fact @code{ftw64}, i.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment ftw.h
+@comment Unix98
+@deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+This function is similar to @code{ftw} but it can work on filesystems
+with large files.  File information is reported using a variable of type
+@code{struct stat64} which is passed by reference to the callback
+function.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is available under the name @code{ftw} and
+transparently replaces the old implementation.
+@end deftypefun
+
+@comment ftw.h
+@comment XPG4.2
+@deftypefun int nftw (const char *@var{filename}, __nftw_func_t @var{func}, int @var{descriptors}, int @var{flag})
+@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}}
+@c ftw_startup calls alloca, malloc, free, xstat/lxstat, tdestroy, and ftw_dir
+@c  if FTW_CHDIR, call open, and fchdir, or chdir and getcwd
+@c ftw_dir calls open_dir_stream, readdir64, process_entry, closedir
+@c  if FTW_CHDIR, also calls fchdir
+@c open_dir_stream calls malloc, realloc, readdir64, free, closedir,
+@c  then openat64_not_cancel_3 and fdopendir or opendir, then dirfd.
+@c process_entry may cal realloc, fxstatat/lxstat/xstat, ftw_dir, and
+@c  find_object (tsearch) and add_object (tfind).
+@c Since each invocation of *ftw uses its own private search tree, none
+@c  of the search tree concurrency issues apply.
+The @code{nftw} function works like the @code{ftw} functions.  They call
+the callback function @var{func} for all items found in the directory
+@var{filename} and below.  At most @var{descriptors} file descriptors
+are consumed during the @code{nftw} call.
+
+One difference is that the callback function is of a different type.  It
+is of type @w{@code{struct FTW *}} and provides the callback function
+with the extra information described above.
+
+A second difference is that @code{nftw} takes a fourth argument, which
+is @math{0} or a bitwise-OR combination of any of the following values.
+
+@vtable @code
+@item FTW_PHYS
+While traversing the directory symbolic links are not followed.  Instead
+symbolic links are reported using the @code{FTW_SL} value for the type
+parameter to the callback function.  If the file referenced by a
+symbolic link does not exist @code{FTW_SLN} is returned instead.
+@item FTW_MOUNT
+The callback function is only called for items which are on the same
+mounted filesystem as the directory given by the @var{filename}
+parameter to @code{nftw}.
+@item FTW_CHDIR
+If this flag is given the current working directory is changed to the
+directory of the reported object before the callback function is called.
+When @code{ntfw} finally returns the current directory is restored to
+its original value.
+@item FTW_DEPTH
+If this option is specified then all subdirectories and files within
+them are processed before processing the top directory itself
+(depth-first processing).  This also means the type flag given to the
+callback function is @code{FTW_DP} and not @code{FTW_D}.
+@item FTW_ACTIONRETVAL
+If this option is specified then return values from callbacks
+are handled differently.  If the callback returns @code{FTW_CONTINUE},
+walking continues normally.  @code{FTW_STOP} means walking stops
+and @code{FTW_STOP} is returned to the caller.  If @code{FTW_SKIP_SUBTREE}
+is returned by the callback with @code{FTW_D} argument, the subtree
+is skipped and walking continues with next sibling of the directory.
+If @code{FTW_SKIP_SIBLINGS} is returned by the callback, all siblings
+of the current entry are skipped and walking continues in its parent.
+No other return values should be returned from the callbacks if
+this option is set.  This option is a GNU extension.
+@end vtable
+
+The return value is computed in the same way as for @code{ftw}.
+@code{nftw} returns @math{0} if no failures occurred and all callback
+functions returned @math{0}.  In case of internal errors, such as memory
+problems, the return value is @math{-1} and @var{errno} is set
+accordingly.  If the return value of a callback invocation was non-zero
+then that value is returned.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is in fact @code{nftw64}, i.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment ftw.h
+@comment Unix98
+@deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag})
+@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}}
+This function is similar to @code{nftw} but it can work on filesystems
+with large files.  File information is reported using a variable of type
+@code{struct stat64} which is passed by reference to the callback
+function.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is available under the name @code{nftw} and
+transparently replaces the old implementation.
+@end deftypefun
+
+
+@node Hard Links
+@section Hard Links
+@cindex hard link
+@cindex link, hard
+@cindex multiple names for one file
+@cindex file names, multiple
+
+In POSIX systems, one file can have many names at the same time.  All of
+the names are equally real, and no one of them is preferred to the
+others.
+
+To add a name to a file, use the @code{link} function.  (The new name is
+also called a @dfn{hard link} to the file.)  Creating a new link to a
+file does not copy the contents of the file; it simply makes a new name
+by which the file can be known, in addition to the file's existing name
+or names.
+
+One file can have names in several directories, so the organization
+of the file system is not a strict hierarchy or tree.
+
+In most implementations, it is not possible to have hard links to the
+same file in multiple file systems.  @code{link} reports an error if you
+try to make a hard link to the file from another file system when this
+cannot be done.
+
+The prototype for the @code{link} function is declared in the header
+file @file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int link (const char *@var{oldname}, const char *@var{newname})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{link} function makes a new link to the existing file named by
+@var{oldname}, under the new name @var{newname}.
+
+This function returns a value of @code{0} if it is successful and
+@code{-1} on failure.  In addition to the usual file name errors
+(@pxref{File Name Errors}) for both @var{oldname} and @var{newname}, the
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EACCES
+You are not allowed to write to the directory in which the new link is
+to be written.
+@ignore
+Some implementations also require that the existing file be accessible
+by the caller, and use this error to report failure for that reason.
+@end ignore
+
+@item EEXIST
+There is already a file named @var{newname}.  If you want to replace
+this link with a new link, you must remove the old link explicitly first.
+
+@item EMLINK
+There are already too many links to the file named by @var{oldname}.
+(The maximum number of links to a file is @w{@code{LINK_MAX}}; see
+@ref{Limits for Files}.)
+
+@item ENOENT
+The file named by @var{oldname} doesn't exist.  You can't make a link to
+a file that doesn't exist.
+
+@item ENOSPC
+The directory or file system that would contain the new link is full
+and cannot be extended.
+
+@item EPERM
+On @gnulinuxhurdsystems{} and some others, you cannot make links to
+directories.
+Many systems allow only privileged users to do so.  This error
+is used to report the problem.
+
+@item EROFS
+The directory containing the new link can't be modified because it's on
+a read-only file system.
+
+@item EXDEV
+The directory specified in @var{newname} is on a different file system
+than the existing file.
+
+@item EIO
+A hardware error occurred while trying to read or write the to filesystem.
+@end table
+@end deftypefun
+
+@node Symbolic Links
+@section Symbolic Links
+@cindex soft link
+@cindex link, soft
+@cindex symbolic link
+@cindex link, symbolic
+
+@gnusystems{} support @dfn{soft links} or @dfn{symbolic links}.  This
+is a kind of ``file'' that is essentially a pointer to another file
+name.  Unlike hard links, symbolic links can be made to directories or
+across file systems with no restrictions.  You can also make a symbolic
+link to a name which is not the name of any file.  (Opening this link
+will fail until a file by that name is created.)  Likewise, if the
+symbolic link points to an existing file which is later deleted, the
+symbolic link continues to point to the same file name even though the
+name no longer names any file.
+
+The reason symbolic links work the way they do is that special things
+happen when you try to open the link.  The @code{open} function realizes
+you have specified the name of a link, reads the file name contained in
+the link, and opens that file name instead.  The @code{stat} function
+likewise operates on the file that the symbolic link points to, instead
+of on the link itself.
+
+By contrast, other operations such as deleting or renaming the file
+operate on the link itself.  The functions @code{readlink} and
+@code{lstat} also refrain from following symbolic links, because their
+purpose is to obtain information about the link.  @code{link}, the
+function that makes a hard link, does too.  It makes a hard link to the
+symbolic link, which one rarely wants.
+
+Some systems have, for some functions operating on files, a limit on
+how many symbolic links are followed when resolving a path name.  The
+limit if it exists is published in the @file{sys/param.h} header file.
+
+@comment sys/param.h
+@comment BSD
+@deftypevr Macro int MAXSYMLINKS
+
+The macro @code{MAXSYMLINKS} specifies how many symlinks some function
+will follow before returning @code{ELOOP}.  Not all functions behave the
+same and this value is not the same as that returned for
+@code{_SC_SYMLOOP} by @code{sysconf}.  In fact, the @code{sysconf}
+result can indicate that there is no fixed limit although
+@code{MAXSYMLINKS} exists and has a finite value.
+@end deftypevr
+
+Prototypes for most of the functions listed in this section are in
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment BSD
+@deftypefun int symlink (const char *@var{oldname}, const char *@var{newname})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{symlink} function makes a symbolic link to @var{oldname} named
+@var{newname}.
+
+The normal return value from @code{symlink} is @code{0}.  A return value
+of @code{-1} indicates an error.  In addition to the usual file name
+syntax errors (@pxref{File Name Errors}), the following @code{errno}
+error conditions are defined for this function:
+
+@table @code
+@item EEXIST
+There is already an existing file named @var{newname}.
+
+@item EROFS
+The file @var{newname} would exist on a read-only file system.
+
+@item ENOSPC
+The directory or file system cannot be extended to make the new link.
+
+@item EIO
+A hardware error occurred while reading or writing data on the disk.
+
+@comment not sure about these
+@ignore
+@item ELOOP
+There are too many levels of indirection.  This can be the result of
+circular symbolic links to directories.
+
+@item EDQUOT
+The new link can't be created because the user's disk quota has been
+exceeded.
+@end ignore
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun ssize_t readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{readlink} function gets the value of the symbolic link
+@var{filename}.  The file name that the link points to is copied into
+@var{buffer}.  This file name string is @emph{not} null-terminated;
+@code{readlink} normally returns the number of characters copied.  The
+@var{size} argument specifies the maximum number of characters to copy,
+usually the allocation size of @var{buffer}.
+
+If the return value equals @var{size}, you cannot tell whether or not
+there was room to return the entire name.  So make a bigger buffer and
+call @code{readlink} again.  Here is an example:
+
+@smallexample
+char *
+readlink_malloc (const char *filename)
+@{
+  int size = 100;
+  char *buffer = NULL;
+
+  while (1)
+    @{
+      buffer = (char *) xrealloc (buffer, size);
+      int nchars = readlink (filename, buffer, size);
+      if (nchars < 0)
+        @{
+          free (buffer);
+          return NULL;
+        @}
+      if (nchars < size)
+        return buffer;
+      size *= 2;
+    @}
+@}
+@end smallexample
+
+@c @group  Invalid outside example.
+A value of @code{-1} is returned in case of error.  In addition to the
+usual file name errors (@pxref{File Name Errors}), the following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The named file is not a symbolic link.
+
+@item EIO
+A hardware error occurred while reading or writing data on the disk.
+@end table
+@c @end group
+@end deftypefun
+
+In some situations it is desirable to resolve all the
+symbolic links to get the real
+name of a file where no prefix names a symbolic link which is followed
+and no filename in the path is @code{.} or @code{..}.  This is for
+instance desirable if files have to be compared in which case different
+names can refer to the same inode.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun {char *} canonicalize_file_name (const char *@var{name})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Calls realpath.
+
+The @code{canonicalize_file_name} function returns the absolute name of
+the file named by @var{name} which contains no @code{.}, @code{..}
+components nor any repeated path separators (@code{/}) or symlinks.  The
+result is passed back as the return value of the function in a block of
+memory allocated with @code{malloc}.  If the result is not used anymore
+the memory should be freed with a call to @code{free}.
+
+If any of the path components are missing the function returns a NULL
+pointer.  This is also what is returned if the length of the path
+reaches or exceeds @code{PATH_MAX} characters.  In any case
+@code{errno} is set accordingly.
+
+@table @code
+@item ENAMETOOLONG
+The resulting path is too long.  This error only occurs on systems which
+have a limit on the file name length.
+
+@item EACCES
+At least one of the path components is not readable.
+
+@item ENOENT
+The input file name is empty.
+
+@item ENOENT
+At least one of the path components does not exist.
+
+@item ELOOP
+More than @code{MAXSYMLINKS} many symlinks have been followed.
+@end table
+
+This function is a GNU extension and is declared in @file{stdlib.h}.
+@end deftypefun
+
+The Unix standard includes a similar function which differs from
+@code{canonicalize_file_name} in that the user has to provide the buffer
+where the result is placed in.
+
+@comment stdlib.h
+@comment XPG
+@deftypefun {char *} realpath (const char *restrict @var{name}, char *restrict @var{resolved})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Calls malloc, realloc, getcwd, lxstat64, readlink, alloca.
+
+A call to @code{realpath} where the @var{resolved} parameter is
+@code{NULL} behaves exactly like @code{canonicalize_file_name}.  The
+function allocates a buffer for the file name and returns a pointer to
+it.  If @var{resolved} is not @code{NULL} it points to a buffer into
+which the result is copied.  It is the callers responsibility to
+allocate a buffer which is large enough.  On systems which define
+@code{PATH_MAX} this means the buffer must be large enough for a
+pathname of this size.  For systems without limitations on the pathname
+length the requirement cannot be met and programs should not call
+@code{realpath} with anything but @code{NULL} for the second parameter.
+
+One other difference is that the buffer @var{resolved} (if nonzero) will
+contain the part of the path component which does not exist or is not
+readable if the function returns @code{NULL} and @code{errno} is set to
+@code{EACCES} or @code{ENOENT}.
+
+This function is declared in @file{stdlib.h}.
+@end deftypefun
+
+The advantage of using this function is that it is more widely
+available.  The drawback is that it reports failures for long paths on
+systems which have no limits on the file name length.
+
+@node Deleting Files
+@section Deleting Files
+@cindex deleting a file
+@cindex removing a file
+@cindex unlinking a file
+
+You can delete a file with @code{unlink} or @code{remove}.
+
+Deletion actually deletes a file name.  If this is the file's only name,
+then the file is deleted as well.  If the file has other remaining names
+(@pxref{Hard Links}), it remains accessible under those names.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int unlink (const char *@var{filename})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{unlink} function deletes the file name @var{filename}.  If
+this is a file's sole name, the file itself is also deleted.  (Actually,
+if any process has the file open when this happens, deletion is
+postponed until all processes have closed the file.)
+
+@pindex unistd.h
+The function @code{unlink} is declared in the header file @file{unistd.h}.
+
+This function returns @code{0} on successful completion, and @code{-1}
+on error.  In addition to the usual file name errors
+(@pxref{File Name Errors}), the following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EACCES
+Write permission is denied for the directory from which the file is to be
+removed, or the directory has the sticky bit set and you do not own the file.
+
+@item EBUSY
+This error indicates that the file is being used by the system in such a
+way that it can't be unlinked.  For example, you might see this error if
+the file name specifies the root directory or a mount point for a file
+system.
+
+@item ENOENT
+The file name to be deleted doesn't exist.
+
+@item EPERM
+On some systems @code{unlink} cannot be used to delete the name of a
+directory, or at least can only be used this way by a privileged user.
+To avoid such problems, use @code{rmdir} to delete directories.  (On
+@gnulinuxhurdsystems{} @code{unlink} can never delete the name of a directory.)
+
+@item EROFS
+The directory containing the file name to be deleted is on a read-only
+file system and can't be modified.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int rmdir (const char *@var{filename})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@cindex directories, deleting
+@cindex deleting a directory
+The @code{rmdir} function deletes a directory.  The directory must be
+empty before it can be removed; in other words, it can only contain
+entries for @file{.} and @file{..}.
+
+In most other respects, @code{rmdir} behaves like @code{unlink}.  There
+are two additional @code{errno} error conditions defined for
+@code{rmdir}:
+
+@table @code
+@item ENOTEMPTY
+@itemx EEXIST
+The directory to be deleted is not empty.
+@end table
+
+These two error codes are synonymous; some systems use one, and some use
+the other.  @gnulinuxhurdsystems{} always use @code{ENOTEMPTY}.
+
+The prototype for this function is declared in the header file
+@file{unistd.h}.
+@pindex unistd.h
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int remove (const char *@var{filename})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Calls unlink and rmdir.
+This is the @w{ISO C} function to remove a file.  It works like
+@code{unlink} for files and like @code{rmdir} for directories.
+@code{remove} is declared in @file{stdio.h}.
+@pindex stdio.h
+@end deftypefun
+
+@node Renaming Files
+@section Renaming Files
+
+The @code{rename} function is used to change a file's name.
+
+@cindex renaming a file
+@comment stdio.h
+@comment ISO
+@deftypefun int rename (const char *@var{oldname}, const char *@var{newname})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a rename syscall, there's an emulation with link
+@c and unlink, but it's racy, even more so if newname exists and is
+@c unlinked first.
+The @code{rename} function renames the file @var{oldname} to
+@var{newname}.  The file formerly accessible under the name
+@var{oldname} is afterwards accessible as @var{newname} instead.  (If
+the file had any other names aside from @var{oldname}, it continues to
+have those names.)
+
+The directory containing the name @var{newname} must be on the same file
+system as the directory containing the name @var{oldname}.
+
+One special case for @code{rename} is when @var{oldname} and
+@var{newname} are two names for the same file.  The consistent way to
+handle this case is to delete @var{oldname}.  However, in this case
+POSIX requires that @code{rename} do nothing and report success---which
+is inconsistent.  We don't know what your operating system will do.
+
+If @var{oldname} is not a directory, then any existing file named
+@var{newname} is removed during the renaming operation.  However, if
+@var{newname} is the name of a directory, @code{rename} fails in this
+case.
+
+If @var{oldname} is a directory, then either @var{newname} must not
+exist or it must name a directory that is empty.  In the latter case,
+the existing directory named @var{newname} is deleted first.  The name
+@var{newname} must not specify a subdirectory of the directory
+@code{oldname} which is being renamed.
+
+One useful feature of @code{rename} is that the meaning of @var{newname}
+changes ``atomically'' from any previously existing file by that name to
+its new meaning (i.e., the file that was called @var{oldname}).  There is
+no instant at which @var{newname} is non-existent ``in between'' the old
+meaning and the new meaning.  If there is a system crash during the
+operation, it is possible for both names to still exist; but
+@var{newname} will always be intact if it exists at all.
+
+If @code{rename} fails, it returns @code{-1}.  In addition to the usual
+file name errors (@pxref{File Name Errors}), the following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EACCES
+One of the directories containing @var{newname} or @var{oldname}
+refuses write permission; or @var{newname} and @var{oldname} are
+directories and write permission is refused for one of them.
+
+@item EBUSY
+A directory named by @var{oldname} or @var{newname} is being used by
+the system in a way that prevents the renaming from working.  This includes
+directories that are mount points for filesystems, and directories
+that are the current working directories of processes.
+
+@item ENOTEMPTY
+@itemx EEXIST
+The directory @var{newname} isn't empty.  @gnulinuxhurdsystems{} always return
+@code{ENOTEMPTY} for this, but some other systems return @code{EEXIST}.
+
+@item EINVAL
+@var{oldname} is a directory that contains @var{newname}.
+
+@item EISDIR
+@var{newname} is a directory but the @var{oldname} isn't.
+
+@item EMLINK
+The parent directory of @var{newname} would have too many links
+(entries).
+
+@item ENOENT
+The file @var{oldname} doesn't exist.
+
+@item ENOSPC
+The directory that would contain @var{newname} has no room for another
+entry, and there is no space left in the file system to expand it.
+
+@item EROFS
+The operation would involve writing to a directory on a read-only file
+system.
+
+@item EXDEV
+The two file names @var{newname} and @var{oldname} are on different
+file systems.
+@end table
+@end deftypefun
+
+@node Creating Directories
+@section Creating Directories
+@cindex creating a directory
+@cindex directories, creating
+
+@pindex mkdir
+Directories are created with the @code{mkdir} function.  (There is also
+a shell command @code{mkdir} which does the same thing.)
+@c !!! umask
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{mkdir} function creates a new, empty directory with name
+@var{filename}.
+
+The argument @var{mode} specifies the file permissions for the new
+directory file.  @xref{Permission Bits}, for more information about
+this.
+
+A return value of @code{0} indicates successful completion, and
+@code{-1} indicates failure.  In addition to the usual file name syntax
+errors (@pxref{File Name Errors}), the following @code{errno} error
+conditions are defined for this function:
+
+@table @code
+@item EACCES
+Write permission is denied for the parent directory in which the new
+directory is to be added.
+
+@item EEXIST
+A file named @var{filename} already exists.
+
+@item EMLINK
+The parent directory has too many links (entries).
+
+Well-designed file systems never report this error, because they permit
+more links than your disk could possibly hold.  However, you must still
+take account of the possibility of this error, as it could result from
+network access to a file system on another machine.
+
+@item ENOSPC
+The file system doesn't have enough room to create the new directory.
+
+@item EROFS
+The parent directory of the directory being created is on a read-only
+file system and cannot be modified.
+@end table
+
+To use this function, your program should include the header file
+@file{sys/stat.h}.
+@pindex sys/stat.h
+@end deftypefun
+
+@node File Attributes
+@section File Attributes
+
+@pindex ls
+When you issue an @samp{ls -l} shell command on a file, it gives you
+information about the size of the file, who owns it, when it was last
+modified, etc.  These are called the @dfn{file attributes}, and are
+associated with the file itself and not a particular one of its names.
+
+This section contains information about how you can inquire about and
+modify the attributes of a file.
+
+@menu
+* Attribute Meanings::          The names of the file attributes,
+                                 and what their values mean.
+* Reading Attributes::          How to read the attributes of a file.
+* Testing File Type::           Distinguishing ordinary files,
+                                 directories, links@dots{}
+* File Owner::                  How ownership for new files is determined,
+			         and how to change it.
+* Permission Bits::             How information about a file's access
+                                 mode is stored.
+* Access Permission::           How the system decides who can access a file.
+* Setting Permissions::         How permissions for new files are assigned,
+			         and how to change them.
+* Testing File Access::         How to find out if your process can
+                                 access a file.
+* File Times::                  About the time attributes of a file.
+* File Size::			Manually changing the size of a file.
+* Storage Allocation::          Allocate backing storage for files.
+@end menu
+
+@node Attribute Meanings
+@subsection The meaning of the File Attributes
+@cindex status of a file
+@cindex attributes of a file
+@cindex file attributes
+
+When you read the attributes of a file, they come back in a structure
+called @code{struct stat}.  This section describes the names of the
+attributes, their data types, and what they mean.  For the functions
+to read the attributes of a file, see @ref{Reading Attributes}.
+
+The header file @file{sys/stat.h} declares all the symbols defined
+in this section.
+@pindex sys/stat.h
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftp {Data Type} {struct stat}
+The @code{stat} structure type is used to return information about the
+attributes of a file.  It contains at least the following members:
+
+@table @code
+@item mode_t st_mode
+Specifies the mode of the file.  This includes file type information
+(@pxref{Testing File Type}) and the file permission bits
+(@pxref{Permission Bits}).
+
+@item ino_t st_ino
+The file serial number, which distinguishes this file from all other
+files on the same device.
+
+@item dev_t st_dev
+Identifies the device containing the file.  The @code{st_ino} and
+@code{st_dev}, taken together, uniquely identify the file.  The
+@code{st_dev} value is not necessarily consistent across reboots or
+system crashes, however.
+
+@item nlink_t st_nlink
+The number of hard links to the file.  This count keeps track of how
+many directories have entries for this file.  If the count is ever
+decremented to zero, then the file itself is discarded as soon as no
+process still holds it open.  Symbolic links are not counted in the
+total.
+
+@item uid_t st_uid
+The user ID of the file's owner.  @xref{File Owner}.
+
+@item gid_t st_gid
+The group ID of the file.  @xref{File Owner}.
+
+@item off_t st_size
+This specifies the size of a regular file in bytes.  For files that are
+really devices this field isn't usually meaningful.  For symbolic links
+this specifies the length of the file name the link refers to.
+
+@item time_t st_atime
+This is the last access time for the file.  @xref{File Times}.
+
+@item unsigned long int st_atime_usec
+This is the fractional part of the last access time for the file.
+@xref{File Times}.
+
+@item time_t st_mtime
+This is the time of the last modification to the contents of the file.
+@xref{File Times}.
+
+@item unsigned long int st_mtime_usec
+This is the fractional part of the time of the last modification to the
+contents of the file.  @xref{File Times}.
+
+@item time_t st_ctime
+This is the time of the last modification to the attributes of the file.
+@xref{File Times}.
+
+@item unsigned long int st_ctime_usec
+This is the fractional part of the time of the last modification to the
+attributes of the file.  @xref{File Times}.
+
+@c !!! st_rdev
+@item blkcnt_t st_blocks
+This is the amount of disk space that the file occupies, measured in
+units of 512-byte blocks.
+
+The number of disk blocks is not strictly proportional to the size of
+the file, for two reasons: the file system may use some blocks for
+internal record keeping; and the file may be sparse---it may have
+``holes'' which contain zeros but do not actually take up space on the
+disk.
+
+You can tell (approximately) whether a file is sparse by comparing this
+value with @code{st_size}, like this:
+
+@smallexample
+(st.st_blocks * 512 < st.st_size)
+@end smallexample
+
+This test is not perfect because a file that is just slightly sparse
+might not be detected as sparse at all.  For practical applications,
+this is not a problem.
+
+@item unsigned int st_blksize
+The optimal block size for reading or writing this file, in bytes.  You
+might use this size for allocating the buffer space for reading or
+writing the file.  (This is unrelated to @code{st_blocks}.)
+@end table
+@end deftp
+
+The extensions for the Large File Support (LFS) require, even on 32-bit
+machines, types which can handle file sizes up to @twoexp{63}.
+Therefore a new definition of @code{struct stat} is necessary.
+
+@comment sys/stat.h
+@comment LFS
+@deftp {Data Type} {struct stat64}
+The members of this type are the same and have the same names as those
+in @code{struct stat}.  The only difference is that the members
+@code{st_ino}, @code{st_size}, and @code{st_blocks} have a different
+type to support larger values.
+
+@table @code
+@item mode_t st_mode
+Specifies the mode of the file.  This includes file type information
+(@pxref{Testing File Type}) and the file permission bits
+(@pxref{Permission Bits}).
+
+@item ino64_t st_ino
+The file serial number, which distinguishes this file from all other
+files on the same device.
+
+@item dev_t st_dev
+Identifies the device containing the file.  The @code{st_ino} and
+@code{st_dev}, taken together, uniquely identify the file.  The
+@code{st_dev} value is not necessarily consistent across reboots or
+system crashes, however.
+
+@item nlink_t st_nlink
+The number of hard links to the file.  This count keeps track of how
+many directories have entries for this file.  If the count is ever
+decremented to zero, then the file itself is discarded as soon as no
+process still holds it open.  Symbolic links are not counted in the
+total.
+
+@item uid_t st_uid
+The user ID of the file's owner.  @xref{File Owner}.
+
+@item gid_t st_gid
+The group ID of the file.  @xref{File Owner}.
+
+@item off64_t st_size
+This specifies the size of a regular file in bytes.  For files that are
+really devices this field isn't usually meaningful.  For symbolic links
+this specifies the length of the file name the link refers to.
+
+@item time_t st_atime
+This is the last access time for the file.  @xref{File Times}.
+
+@item unsigned long int st_atime_usec
+This is the fractional part of the last access time for the file.
+@xref{File Times}.
+
+@item time_t st_mtime
+This is the time of the last modification to the contents of the file.
+@xref{File Times}.
+
+@item unsigned long int st_mtime_usec
+This is the fractional part of the time of the last modification to the
+contents of the file.  @xref{File Times}.
+
+@item time_t st_ctime
+This is the time of the last modification to the attributes of the file.
+@xref{File Times}.
+
+@item unsigned long int st_ctime_usec
+This is the fractional part of the time of the last modification to the
+attributes of the file.  @xref{File Times}.
+
+@c !!! st_rdev
+@item blkcnt64_t st_blocks
+This is the amount of disk space that the file occupies, measured in
+units of 512-byte blocks.
+
+@item unsigned int st_blksize
+The optimal block size for reading of writing this file, in bytes.  You
+might use this size for allocating the buffer space for reading of
+writing the file.  (This is unrelated to @code{st_blocks}.)
+@end table
+@end deftp
+
+Some of the file attributes have special data type names which exist
+specifically for those attributes.  (They are all aliases for well-known
+integer types that you know and love.)  These typedef names are defined
+in the header file @file{sys/types.h} as well as in @file{sys/stat.h}.
+Here is a list of them.
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} mode_t
+This is an integer data type used to represent file modes.  In
+@theglibc{}, this is an unsigned type no narrower than @code{unsigned
+int}.
+@end deftp
+
+@cindex inode number
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} ino_t
+This is an unsigned integer type used to represent file serial numbers.
+(In Unix jargon, these are sometimes called @dfn{inode numbers}.)
+In @theglibc{}, this type is no narrower than @code{unsigned int}.
+
+If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
+is transparently replaced by @code{ino64_t}.
+@end deftp
+
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} ino64_t
+This is an unsigned integer type used to represent file serial numbers
+for the use in LFS.  In @theglibc{}, this type is no narrower than
+@code{unsigned int}.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
+available under the name @code{ino_t}.
+@end deftp
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} dev_t
+This is an arithmetic data type used to represent file device numbers.
+In @theglibc{}, this is an integer type no narrower than @code{int}.
+@end deftp
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} nlink_t
+This is an integer type used to represent file link counts.
+@end deftp
+
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} blkcnt_t
+This is a signed integer type used to represent block counts.
+In @theglibc{}, this type is no narrower than @code{int}.
+
+If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
+is transparently replaced by @code{blkcnt64_t}.
+@end deftp
+
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} blkcnt64_t
+This is a signed integer type used to represent block counts for the
+use in LFS.  In @theglibc{}, this type is no narrower than @code{int}.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
+available under the name @code{blkcnt_t}.
+@end deftp
+
+@node Reading Attributes
+@subsection Reading the Attributes of a File
+
+To examine the attributes of files, use the functions @code{stat},
+@code{fstat} and @code{lstat}.  They return the attribute information in
+a @code{struct stat} object.  All three functions are declared in the
+header file @file{sys/stat.h}.
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun int stat (const char *@var{filename}, struct stat *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{stat} function returns information about the attributes of the
+file named by @w{@var{filename}} in the structure pointed to by @var{buf}.
+
+If @var{filename} is the name of a symbolic link, the attributes you get
+describe the file that the link points to.  If the link points to a
+nonexistent file name, then @code{stat} fails reporting a nonexistent
+file.
+
+The return value is @code{0} if the operation is successful, or
+@code{-1} on failure.  In addition to the usual file name errors
+(@pxref{File Name Errors}, the following @code{errno} error conditions
+are defined for this function:
+
+@table @code
+@item ENOENT
+The file named by @var{filename} doesn't exist.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{stat64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment sys/stat.h
+@comment Unix98
+@deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{stat} but it is also able to work on
+files larger than @twoexp{31} bytes on 32-bit systems.  To be able to do
+this the result is stored in a variable of type @code{struct stat64} to
+which @var{buf} must point.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{stat} and so transparently
+replaces the interface for small files on 32-bit machines.
+@end deftypefun
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun int fstat (int @var{filedes}, struct stat *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fstat} function is like @code{stat}, except that it takes an
+open file descriptor as an argument instead of a file name.
+@xref{Low-Level I/O}.
+
+Like @code{stat}, @code{fstat} returns @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error conditions are defined for
+@code{fstat}:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{fstat64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment sys/stat.h
+@comment Unix98
+@deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{fstat} but is able to work on large
+files on 32-bit platforms.  For large files the file descriptor
+@var{filedes} should be obtained by @code{open64} or @code{creat64}.
+The @var{buf} pointer points to a variable of type @code{struct stat64}
+which is able to represent the larger values.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{fstat} and so transparently
+replaces the interface for small files on 32-bit machines.
+@end deftypefun
+
+@c fstatat will call alloca and snprintf if the syscall is not
+@c available.
+@c @safety{@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+
+@comment sys/stat.h
+@comment BSD
+@deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct system call through lxstat, sometimes with an xstat conv call
+@c afterwards.
+The @code{lstat} function is like @code{stat}, except that it does not
+follow symbolic links.  If @var{filename} is the name of a symbolic
+link, @code{lstat} returns information about the link itself; otherwise
+@code{lstat} works like @code{stat}.  @xref{Symbolic Links}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{lstat64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment sys/stat.h
+@comment Unix98
+@deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct system call through lxstat64, sometimes with an xstat conv
+@c call afterwards.
+This function is similar to @code{lstat} but it is also able to work on
+files larger than @twoexp{31} bytes on 32-bit systems.  To be able to do
+this the result is stored in a variable of type @code{struct stat64} to
+which @var{buf} must point.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{lstat} and so transparently
+replaces the interface for small files on 32-bit machines.
+@end deftypefun
+
+@node Testing File Type
+@subsection Testing the Type of a File
+
+The @dfn{file mode}, stored in the @code{st_mode} field of the file
+attributes, contains two kinds of information: the file type code, and
+the access permission bits.  This section discusses only the type code,
+which you can use to tell whether the file is a directory, socket,
+symbolic link, and so on.  For details about access permissions see
+@ref{Permission Bits}.
+
+There are two ways you can access the file type information in a file
+mode.  Firstly, for each file type there is a @dfn{predicate macro}
+which examines a given file mode and returns whether it is of that type
+or not.  Secondly, you can mask out the rest of the file mode to leave
+just the file type code, and compare this against constants for each of
+the supported file types.
+
+All of the symbols listed in this section are defined in the header file
+@file{sys/stat.h}.
+@pindex sys/stat.h
+
+The following predicate macros test the type of a file, given the value
+@var{m} which is the @code{st_mode} field returned by @code{stat} on
+that file:
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISDIR (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a directory.
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISCHR (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a character special file (a
+device like a terminal).
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISBLK (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a block special file (a device
+like a disk).
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISREG (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a regular file.
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISFIFO (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a FIFO special file, or a
+pipe.  @xref{Pipes and FIFOs}.
+@end deftypefn
+
+@comment sys/stat.h
+@comment GNU
+@deftypefn Macro int S_ISLNK (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a symbolic link.
+@xref{Symbolic Links}.
+@end deftypefn
+
+@comment sys/stat.h
+@comment GNU
+@deftypefn Macro int S_ISSOCK (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a socket.  @xref{Sockets}.
+@end deftypefn
+
+An alternate non-POSIX method of testing the file type is supported for
+compatibility with BSD.  The mode can be bitwise AND-ed with
+@code{S_IFMT} to extract the file type code, and compared to the
+appropriate constant.  For example,
+
+@smallexample
+S_ISCHR (@var{mode})
+@end smallexample
+
+@noindent
+is equivalent to:
+
+@smallexample
+((@var{mode} & S_IFMT) == S_IFCHR)
+@end smallexample
+
+@comment sys/stat.h
+@comment BSD
+@deftypevr Macro int S_IFMT
+This is a bit mask used to extract the file type code from a mode value.
+@end deftypevr
+
+These are the symbolic names for the different file type codes:
+
+@vtable @code
+@comment sys/stat.h
+@comment BSD
+@item S_IFDIR
+This is the file type constant of a directory file.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFCHR
+This is the file type constant of a character-oriented device file.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFBLK
+This is the file type constant of a block-oriented device file.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFREG
+This is the file type constant of a regular file.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFLNK
+This is the file type constant of a symbolic link.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFSOCK
+This is the file type constant of a socket.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFIFO
+This is the file type constant of a FIFO or pipe.
+@end vtable
+
+The POSIX.1b standard introduced a few more objects which possibly can
+be implemented as objects in the filesystem.  These are message queues,
+semaphores, and shared memory objects.  To allow differentiating these
+objects from other files the POSIX standard introduced three new test
+macros.  But unlike the other macros they do not take the value of the
+@code{st_mode} field as the parameter.  Instead they expect a pointer to
+the whole @code{struct stat} structure.
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_TYPEISMQ (struct stat *@var{s})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If the system implements POSIX message queues as distinct objects and the
+file is a message queue object, this macro returns a non-zero value.
+In all other cases the result is zero.
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_TYPEISSEM (struct stat *@var{s})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If the system implements POSIX semaphores as distinct objects and the
+file is a semaphore object, this macro returns a non-zero value.
+In all other cases the result is zero.
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_TYPEISSHM (struct stat *@var{s})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If the system implements POSIX shared memory objects as distinct objects
+and the file is a shared memory object, this macro returns a non-zero
+value.  In all other cases the result is zero.
+@end deftypefn
+
+@node File Owner
+@subsection File Owner
+@cindex file owner
+@cindex owner of a file
+@cindex group owner of a file
+
+Every file has an @dfn{owner} which is one of the registered user names
+defined on the system.  Each file also has a @dfn{group} which is one of
+the defined groups.  The file owner can often be useful for showing you
+who edited the file (especially when you edit with GNU Emacs), but its
+main purpose is for access control.
+
+The file owner and group play a role in determining access because the
+file has one set of access permission bits for the owner, another set
+that applies to users who belong to the file's group, and a third set of
+bits that applies to everyone else.  @xref{Access Permission}, for the
+details of how access is decided based on this data.
+
+When a file is created, its owner is set to the effective user ID of the
+process that creates it (@pxref{Process Persona}).  The file's group ID
+may be set to either the effective group ID of the process, or the group
+ID of the directory that contains the file, depending on the system
+where the file is stored.  When you access a remote file system, it
+behaves according to its own rules, not according to the system your
+program is running on.  Thus, your program must be prepared to encounter
+either kind of behavior no matter what kind of system you run it on.
+
+@pindex chown
+@pindex chgrp
+You can change the owner and/or group owner of an existing file using
+the @code{chown} function.  This is the primitive for the @code{chown}
+and @code{chgrp} shell commands.
+
+@pindex unistd.h
+The prototype for this function is declared in @file{unistd.h}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{chown} function changes the owner of the file @var{filename} to
+@var{owner}, and its group owner to @var{group}.
+
+Changing the owner of the file on certain systems clears the set-user-ID
+and set-group-ID permission bits.  (This is because those bits may not
+be appropriate for the new owner.)  Other file permission bits are not
+changed.
+
+The return value is @code{0} on success and @code{-1} on failure.
+In addition to the usual file name errors (@pxref{File Name Errors}),
+the following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EPERM
+This process lacks permission to make the requested change.
+
+Only privileged users or the file's owner can change the file's group.
+On most file systems, only privileged users can change the file owner;
+some file systems allow you to change the owner if you are currently the
+owner.  When you access a remote file system, the behavior you encounter
+is determined by the system that actually holds the file, not by the
+system your program is running on.
+
+@xref{Options for Files}, for information about the
+@code{_POSIX_CHOWN_RESTRICTED} macro.
+
+@item EROFS
+The file is on a read-only file system.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun int fchown (int @var{filedes}, uid_t @var{owner}, gid_t @var{group})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is like @code{chown}, except that it changes the owner of the open
+file with descriptor @var{filedes}.
+
+The return value from @code{fchown} is @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error codes are defined for this
+function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The @var{filedes} argument corresponds to a pipe or socket, not an ordinary
+file.
+
+@item EPERM
+This process lacks permission to make the requested change.  For details
+see @code{chmod} above.
+
+@item EROFS
+The file resides on a read-only file system.
+@end table
+@end deftypefun
+
+@node Permission Bits
+@subsection The Mode Bits for Access Permission
+
+The @dfn{file mode}, stored in the @code{st_mode} field of the file
+attributes, contains two kinds of information: the file type code, and
+the access permission bits.  This section discusses only the access
+permission bits, which control who can read or write the file.
+@xref{Testing File Type}, for information about the file type code.
+
+All of the symbols listed in this section are defined in the header file
+@file{sys/stat.h}.
+@pindex sys/stat.h
+
+@cindex file permission bits
+These symbolic constants are defined for the file mode bits that control
+access permission for the file:
+
+@vtable @code
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRUSR
+@comment sys/stat.h
+@comment BSD
+@itemx S_IREAD
+Read permission bit for the owner of the file.  On many systems this bit
+is 0400.  @code{S_IREAD} is an obsolete synonym provided for BSD
+compatibility.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IWUSR
+@comment sys/stat.h
+@comment BSD
+@itemx S_IWRITE
+Write permission bit for the owner of the file.  Usually 0200.
+@w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IXUSR
+@comment sys/stat.h
+@comment BSD
+@itemx S_IEXEC
+Execute (for ordinary files) or search (for directories) permission bit
+for the owner of the file.  Usually 0100.  @code{S_IEXEC} is an obsolete
+synonym provided for BSD compatibility.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRWXU
+This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRGRP
+Read permission bit for the group owner of the file.  Usually 040.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IWGRP
+Write permission bit for the group owner of the file.  Usually 020.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IXGRP
+Execute or search permission bit for the group owner of the file.
+Usually 010.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRWXG
+This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IROTH
+Read permission bit for other users.  Usually 04.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IWOTH
+Write permission bit for other users.  Usually 02.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IXOTH
+Execute or search permission bit for other users.  Usually 01.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRWXO
+This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}.
+
+@comment sys/stat.h
+@comment POSIX
+@item S_ISUID
+This is the set-user-ID on execute bit, usually 04000.
+@xref{How Change Persona}.
+
+@comment sys/stat.h
+@comment POSIX
+@item S_ISGID
+This is the set-group-ID on execute bit, usually 02000.
+@xref{How Change Persona}.
+
+@cindex sticky bit
+@comment sys/stat.h
+@comment BSD
+@item S_ISVTX
+This is the @dfn{sticky} bit, usually 01000.
+
+For a directory it gives permission to delete a file in that directory
+only if you own that file.  Ordinarily, a user can either delete all the
+files in a directory or cannot delete any of them (based on whether the
+user has write permission for the directory).  The same restriction
+applies---you must have both write permission for the directory and own
+the file you want to delete.  The one exception is that the owner of the
+directory can delete any file in the directory, no matter who owns it
+(provided the owner has given himself write permission for the
+directory).  This is commonly used for the @file{/tmp} directory, where
+anyone may create files but not delete files created by other users.
+
+Originally the sticky bit on an executable file modified the swapping
+policies of the system.  Normally, when a program terminated, its pages
+in core were immediately freed and reused.  If the sticky bit was set on
+the executable file, the system kept the pages in core for a while as if
+the program were still running.  This was advantageous for a program
+likely to be run many times in succession.  This usage is obsolete in
+modern systems.  When a program terminates, its pages always remain in
+core as long as there is no shortage of memory in the system.  When the
+program is next run, its pages will still be in core if no shortage
+arose since the last run.
+
+On some modern systems where the sticky bit has no useful meaning for an
+executable file, you cannot set the bit at all for a non-directory.
+If you try, @code{chmod} fails with @code{EFTYPE};
+@pxref{Setting Permissions}.
+
+Some systems (particularly SunOS) have yet another use for the sticky
+bit.  If the sticky bit is set on a file that is @emph{not} executable,
+it means the opposite: never cache the pages of this file at all.  The
+main use of this is for the files on an NFS server machine which are
+used as the swap area of diskless client machines.  The idea is that the
+pages of the file will be cached in the client's memory, so it is a
+waste of the server's memory to cache them a second time.  With this
+usage the sticky bit also implies that the filesystem may fail to record
+the file's modification time onto disk reliably (the idea being that
+no-one cares for a swap file).
+
+This bit is only available on BSD systems (and those derived from
+them).  Therefore one has to use the @code{_GNU_SOURCE} feature select
+macro, or not define any feature test macros, to get the definition
+(@pxref{Feature Test Macros}).
+@end vtable
+
+The actual bit values of the symbols are listed in the table above
+so you can decode file mode values when debugging your programs.
+These bit values are correct for most systems, but they are not
+guaranteed.
+
+@strong{Warning:} Writing explicit numbers for file permissions is bad
+practice.  Not only is it not portable, it also requires everyone who
+reads your program to remember what the bits mean.  To make your program
+clean use the symbolic names.
+
+@node Access Permission
+@subsection How Your Access to a File is Decided
+@cindex permission to access a file
+@cindex access permission for a file
+@cindex file access permission
+
+Recall that the operating system normally decides access permission for
+a file based on the effective user and group IDs of the process and its
+supplementary group IDs, together with the file's owner, group and
+permission bits.  These concepts are discussed in detail in @ref{Process
+Persona}.
+
+If the effective user ID of the process matches the owner user ID of the
+file, then permissions for read, write, and execute/search are
+controlled by the corresponding ``user'' (or ``owner'') bits.  Likewise,
+if any of the effective group ID or supplementary group IDs of the
+process matches the group owner ID of the file, then permissions are
+controlled by the ``group'' bits.  Otherwise, permissions are controlled
+by the ``other'' bits.
+
+Privileged users, like @samp{root}, can access any file regardless of
+its permission bits.  As a special case, for a file to be executable
+even by a privileged user, at least one of its execute bits must be set.
+
+@node Setting Permissions
+@subsection Assigning File Permissions
+
+@cindex file creation mask
+@cindex umask
+The primitive functions for creating files (for example, @code{open} or
+@code{mkdir}) take a @var{mode} argument, which specifies the file
+permissions to give the newly created file.  This mode is modified by
+the process's @dfn{file creation mask}, or @dfn{umask}, before it is
+used.
+
+The bits that are set in the file creation mask identify permissions
+that are always to be disabled for newly created files.  For example, if
+you set all the ``other'' access bits in the mask, then newly created
+files are not accessible at all to processes in the ``other'' category,
+even if the @var{mode} argument passed to the create function would
+permit such access.  In other words, the file creation mask is the
+complement of the ordinary access permissions you want to grant.
+
+Programs that create files typically specify a @var{mode} argument that
+includes all the permissions that make sense for the particular file.
+For an ordinary file, this is typically read and write permission for
+all classes of users.  These permissions are then restricted as
+specified by the individual user's own file creation mask.
+
+@findex chmod
+To change the permission of an existing file given its name, call
+@code{chmod}.  This function uses the specified permission bits and
+ignores the file creation mask.
+
+@pindex umask
+In normal use, the file creation mask is initialized by the user's login
+shell (using the @code{umask} shell command), and inherited by all
+subprocesses.  Application programs normally don't need to worry about
+the file creation mask.  It will automatically do what it is supposed to
+do.
+
+When your program needs to create a file and bypass the umask for its
+access permissions, the easiest way to do this is to use @code{fchmod}
+after opening the file, rather than changing the umask.  In fact,
+changing the umask is usually done only by shells.  They use the
+@code{umask} function.
+
+The functions in this section are declared in @file{sys/stat.h}.
+@pindex sys/stat.h
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun mode_t umask (mode_t @var{mask})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{umask} function sets the file creation mask of the current
+process to @var{mask}, and returns the previous value of the file
+creation mask.
+
+Here is an example showing how to read the mask with @code{umask}
+without changing it permanently:
+
+@smallexample
+mode_t
+read_umask (void)
+@{
+  mode_t mask = umask (0);
+  umask (mask);
+  return mask;
+@}
+@end smallexample
+
+@noindent
+However, on @gnuhurdsystems{} it is better to use @code{getumask} if
+you just want to read the mask value, because it is reentrant.
+@end deftypefun
+
+@comment sys/stat.h
+@comment GNU
+@deftypefun mode_t getumask (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Return the current value of the file creation mask for the current
+process.  This function is a GNU extension and is only available on
+@gnuhurdsystems{}.
+@end deftypefun
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun int chmod (const char *@var{filename}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{chmod} function sets the access permission bits for the file
+named by @var{filename} to @var{mode}.
+
+If @var{filename} is a symbolic link, @code{chmod} changes the
+permissions of the file pointed to by the link, not those of the link
+itself.
+
+This function returns @code{0} if successful and @code{-1} if not.  In
+addition to the usual file name errors (@pxref{File Name
+Errors}), the following @code{errno} error conditions are defined for
+this function:
+
+@table @code
+@item ENOENT
+The named file doesn't exist.
+
+@item EPERM
+This process does not have permission to change the access permissions
+of this file.  Only the file's owner (as judged by the effective user ID
+of the process) or a privileged user can change them.
+
+@item EROFS
+The file resides on a read-only file system.
+
+@item EFTYPE
+@var{mode} has the @code{S_ISVTX} bit (the ``sticky bit'') set,
+and the named file is not a directory.  Some systems do not allow setting the
+sticky bit on non-directory files, and some do (and only some of those
+assign a useful meaning to the bit for non-directory files).
+
+You only get @code{EFTYPE} on systems where the sticky bit has no useful
+meaning for non-directory files, so it is always safe to just clear the
+bit in @var{mode} and call @code{chmod} again.  @xref{Permission Bits},
+for full details on the sticky bit.
+@end table
+@end deftypefun
+
+@comment sys/stat.h
+@comment BSD
+@deftypefun int fchmod (int @var{filedes}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is like @code{chmod}, except that it changes the permissions of the
+currently open file given by @var{filedes}.
+
+The return value from @code{fchmod} is @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error codes are defined for this
+function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The @var{filedes} argument corresponds to a pipe or socket, or something
+else that doesn't really have access permissions.
+
+@item EPERM
+This process does not have permission to change the access permissions
+of this file.  Only the file's owner (as judged by the effective user ID
+of the process) or a privileged user can change them.
+
+@item EROFS
+The file resides on a read-only file system.
+@end table
+@end deftypefun
+
+@node Testing File Access
+@subsection Testing Permission to Access a File
+@cindex testing access permission
+@cindex access, testing for
+@cindex setuid programs and file access
+
+In some situations it is desirable to allow programs to access files or
+devices even if this is not possible with the permissions granted to the
+user.  One possible solution is to set the setuid-bit of the program
+file.  If such a program is started the @emph{effective} user ID of the
+process is changed to that of the owner of the program file.  So to
+allow write access to files like @file{/etc/passwd}, which normally can
+be written only by the super-user, the modifying program will have to be
+owned by @code{root} and the setuid-bit must be set.
+
+But besides the files the program is intended to change the user should
+not be allowed to access any file to which s/he would not have access
+anyway.  The program therefore must explicitly check whether @emph{the
+user} would have the necessary access to a file, before it reads or
+writes the file.
+
+To do this, use the function @code{access}, which checks for access
+permission based on the process's @emph{real} user ID rather than the
+effective user ID.  (The setuid feature does not alter the real user ID,
+so it reflects the user who actually ran the program.)
+
+There is another way you could check this access, which is easy to
+describe, but very hard to use.  This is to examine the file mode bits
+and mimic the system's own access computation.  This method is
+undesirable because many systems have additional access control
+features; your program cannot portably mimic them, and you would not
+want to try to keep track of the diverse features that different systems
+have.  Using @code{access} is simple and automatically does whatever is
+appropriate for the system you are using.
+
+@code{access} is @emph{only} appropriate to use in setuid programs.
+A non-setuid program will always use the effective ID rather than the
+real ID.
+
+@pindex unistd.h
+The symbols in this section are declared in @file{unistd.h}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int access (const char *@var{filename}, int @var{how})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{access} function checks to see whether the file named by
+@var{filename} can be accessed in the way specified by the @var{how}
+argument.  The @var{how} argument either can be the bitwise OR of the
+flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test
+@code{F_OK}.
+
+This function uses the @emph{real} user and group IDs of the calling
+process, rather than the @emph{effective} IDs, to check for access
+permission.  As a result, if you use the function from a @code{setuid}
+or @code{setgid} program (@pxref{How Change Persona}), it gives
+information relative to the user who actually ran the program.
+
+The return value is @code{0} if the access is permitted, and @code{-1}
+otherwise.  (In other words, treated as a predicate function,
+@code{access} returns true if the requested access is @emph{denied}.)
+
+In addition to the usual file name errors (@pxref{File Name
+Errors}), the following @code{errno} error conditions are defined for
+this function:
+
+@table @code
+@item EACCES
+The access specified by @var{how} is denied.
+
+@item ENOENT
+The file doesn't exist.
+
+@item EROFS
+Write permission was requested for a file on a read-only file system.
+@end table
+@end deftypefun
+
+These macros are defined in the header file @file{unistd.h} for use
+as the @var{how} argument to the @code{access} function.  The values
+are integer constants.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int R_OK
+Flag meaning test for read permission.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int W_OK
+Flag meaning test for write permission.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int X_OK
+Flag meaning test for execute/search permission.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int F_OK
+Flag meaning test for existence of the file.
+@end deftypevr
+
+@node File Times
+@subsection File Times
+
+@cindex file access time
+@cindex file modification time
+@cindex file attribute modification time
+Each file has three time stamps associated with it:  its access time,
+its modification time, and its attribute modification time.  These
+correspond to the @code{st_atime}, @code{st_mtime}, and @code{st_ctime}
+members of the @code{stat} structure; see @ref{File Attributes}.
+
+All of these times are represented in calendar time format, as
+@code{time_t} objects.  This data type is defined in @file{time.h}.
+For more information about representation and manipulation of time
+values, see @ref{Calendar Time}.
+@pindex time.h
+
+Reading from a file updates its access time attribute, and writing
+updates its modification time.  When a file is created, all three
+time stamps for that file are set to the current time.  In addition, the
+attribute change time and modification time fields of the directory that
+contains the new entry are updated.
+
+Adding a new name for a file with the @code{link} function updates the
+attribute change time field of the file being linked, and both the
+attribute change time and modification time fields of the directory
+containing the new name.  These same fields are affected if a file name
+is deleted with @code{unlink}, @code{remove} or @code{rmdir}.  Renaming
+a file with @code{rename} affects only the attribute change time and
+modification time fields of the two parent directories involved, and not
+the times for the file being renamed.
+
+Changing the attributes of a file (for example, with @code{chmod})
+updates its attribute change time field.
+
+You can also change some of the time stamps of a file explicitly using
+the @code{utime} function---all except the attribute change time.  You
+need to include the header file @file{utime.h} to use this facility.
+@pindex utime.h
+
+@comment utime.h
+@comment POSIX.1
+@deftp {Data Type} {struct utimbuf}
+The @code{utimbuf} structure is used with the @code{utime} function to
+specify new access and modification times for a file.  It contains the
+following members:
+
+@table @code
+@item time_t actime
+This is the access time for the file.
+
+@item time_t modtime
+This is the modification time for the file.
+@end table
+@end deftp
+
+@comment utime.h
+@comment POSIX.1
+@deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a utime syscall, it non-atomically converts times
+@c to a struct timeval and calls utimes.
+This function is used to modify the file times associated with the file
+named @var{filename}.
+
+If @var{times} is a null pointer, then the access and modification times
+of the file are set to the current time.  Otherwise, they are set to the
+values from the @code{actime} and @code{modtime} members (respectively)
+of the @code{utimbuf} structure pointed to by @var{times}.
+
+The attribute modification time for the file is set to the current time
+in either case (since changing the time stamps is itself a modification
+of the file attributes).
+
+The @code{utime} function returns @code{0} if successful and @code{-1}
+on failure.  In addition to the usual file name errors
+(@pxref{File Name Errors}), the following @code{errno} error conditions
+are defined for this function:
+
+@table @code
+@item EACCES
+There is a permission problem in the case where a null pointer was
+passed as the @var{times} argument.  In order to update the time stamp on
+the file, you must either be the owner of the file, have write
+permission for the file, or be a privileged user.
+
+@item ENOENT
+The file doesn't exist.
+
+@item EPERM
+If the @var{times} argument is not a null pointer, you must either be
+the owner of the file or be a privileged user.
+
+@item EROFS
+The file lives on a read-only file system.
+@end table
+@end deftypefun
+
+Each of the three time stamps has a corresponding microsecond part,
+which extends its resolution.  These fields are called
+@code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec};
+each has a value between 0 and 999,999, which indicates the time in
+microseconds.  They correspond to the @code{tv_usec} field of a
+@code{timeval} structure; see @ref{High-Resolution Calendar}.
+
+The @code{utimes} function is like @code{utime}, but also lets you specify
+the fractional part of the file times.  The prototype for this function is
+in the header file @file{sys/time.h}.
+@pindex sys/time.h
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int utimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a utimes syscall, it non-atomically converts tvp
+@c to struct timespec array and issues a utimensat syscall, or to
+@c struct utimbuf and calls utime.
+This function sets the file access and modification times of the file
+@var{filename}.  The new file access time is specified by
+@code{@var{tvp}[0]}, and the new modification time by
+@code{@var{tvp}[1]}.  Similar to @code{utime}, if @var{tvp} is a null
+pointer then the access and modification times of the file are set to
+the current time.  This function comes from BSD.
+
+The return values and error conditions are the same as for the @code{utime}
+function.
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int lutimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Since there's no lutimes syscall, it non-atomically converts tvp
+@c to struct timespec array and issues a utimensat syscall.
+This function is like @code{utimes}, except that it does not follow
+symbolic links.  If @var{filename} is the name of a symbolic link,
+@code{lutimes} sets the file access and modification times of the
+symbolic link special file itself (as seen by @code{lstat};
+@pxref{Symbolic Links}) while @code{utimes} sets the file access and
+modification times of the file the symbolic link refers to.  This
+function comes from FreeBSD, and is not available on all platforms (if
+not available, it will fail with @code{ENOSYS}).
+
+The return values and error conditions are the same as for the @code{utime}
+function.
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int futimes (int @var{fd}, const struct timeval @var{tvp}@t{[2]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Since there's no futimes syscall, it non-atomically converts tvp
+@c to struct timespec array and issues a utimensat syscall, falling back
+@c to utimes on a /proc/self/fd symlink.
+This function is like @code{utimes}, except that it takes an open file
+descriptor as an argument instead of a file name.  @xref{Low-Level
+I/O}.  This function comes from FreeBSD, and is not available on all
+platforms (if not available, it will fail with @code{ENOSYS}).
+
+Like @code{utimes}, @code{futimes} returns @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error conditions are defined for
+@code{futimes}:
+
+@table @code
+@item EACCES
+There is a permission problem in the case where a null pointer was
+passed as the @var{times} argument.  In order to update the time stamp on
+the file, you must either be the owner of the file, have write
+permission for the file, or be a privileged user.
+
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EPERM
+If the @var{times} argument is not a null pointer, you must either be
+the owner of the file or be a privileged user.
+
+@item EROFS
+The file lives on a read-only file system.
+@end table
+@end deftypefun
+
+@node File Size
+@subsection File Size
+
+Normally file sizes are maintained automatically.  A file begins with a
+size of @math{0} and is automatically extended when data is written past
+its end.  It is also possible to empty a file completely by an
+@code{open} or @code{fopen} call.
+
+However, sometimes it is necessary to @emph{reduce} the size of a file.
+This can be done with the @code{truncate} and @code{ftruncate} functions.
+They were introduced in BSD Unix.  @code{ftruncate} was later added to
+POSIX.1.
+
+Some systems allow you to extend a file (creating holes) with these
+functions.  This is useful when using memory-mapped I/O
+(@pxref{Memory-mapped I/O}), where files are not automatically extended.
+However, it is not portable but must be implemented if @code{mmap}
+allows mapping of files (i.e., @code{_POSIX_MAPPED_FILES} is defined).
+
+Using these functions on anything other than a regular file gives
+@emph{undefined} results.  On many systems, such a call will appear to
+succeed, without actually accomplishing anything.
+
+@comment unistd.h
+@comment X/Open
+@deftypefun int truncate (const char *@var{filename}, off_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a truncate syscall, we use open and ftruncate.
+
+The @code{truncate} function changes the size of @var{filename} to
+@var{length}.  If @var{length} is shorter than the previous length, data
+at the end will be lost.  The file must be writable by the user to
+perform this operation.
+
+If @var{length} is longer, holes will be added to the end.  However, some
+systems do not support this feature and will leave the file unchanged.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{truncate} function is in fact @code{truncate64} and the type
+@code{off_t} has 64 bits which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is @math{0} for success, or @math{-1} for an error.  In
+addition to the usual file name errors, the following errors may occur:
+
+@table @code
+
+@item EACCES
+The file is a directory or not writable.
+
+@item EINVAL
+@var{length} is negative.
+
+@item EFBIG
+The operation would extend the file beyond the limits of the operating system.
+
+@item EIO
+A hardware I/O error occurred.
+
+@item EPERM
+The file is "append-only" or "immutable".
+
+@item EINTR
+The operation was interrupted by a signal.
+
+@end table
+
+@end deftypefun
+
+@comment unistd.h
+@comment Unix98
+@deftypefun int truncate64 (const char *@var{name}, off64_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a syscall, try truncate if length fits.
+This function is similar to the @code{truncate} function.  The
+difference is that the @var{length} argument is 64 bits wide even on 32
+bits machines, which allows the handling of files with sizes up to
+@twoexp{63} bytes.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{truncate} and so transparently replaces the 32 bits interface.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX
+@deftypefun int ftruncate (int @var{fd}, off_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This is like @code{truncate}, but it works on a file descriptor @var{fd}
+for an opened file instead of a file name to identify the object.  The
+file must be opened for writing to successfully carry out the operation.
+
+The POSIX standard leaves it implementation defined what happens if the
+specified new @var{length} of the file is bigger than the original size.
+The @code{ftruncate} function might simply leave the file alone and do
+nothing or it can increase the size to the desired size.  In this later
+case the extended area should be zero-filled.  So using @code{ftruncate}
+is no reliable way to increase the file size but if it is possible it is
+probably the fastest way.  The function also operates on POSIX shared
+memory segments if these are implemented by the system.
+
+@code{ftruncate} is especially useful in combination with @code{mmap}.
+Since the mapped region must have a fixed size one cannot enlarge the
+file by writing something beyond the last mapped page.  Instead one has
+to enlarge the file itself and then remap the file with the new size.
+The example below shows how this works.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{ftruncate} function is in fact @code{ftruncate64} and the type
+@code{off_t} has 64 bits which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is @math{0} for success, or @math{-1} for an error.  The
+following errors may occur:
+
+@table @code
+
+@item EBADF
+@var{fd} does not correspond to an open file.
+
+@item EACCES
+@var{fd} is a directory or not open for writing.
+
+@item EINVAL
+@var{length} is negative.
+
+@item EFBIG
+The operation would extend the file beyond the limits of the operating system.
+@c or the open() call -- with the not-yet-discussed feature of opening
+@c files with extra-large offsets.
+
+@item EIO
+A hardware I/O error occurred.
+
+@item EPERM
+The file is "append-only" or "immutable".
+
+@item EINTR
+The operation was interrupted by a signal.
+
+@c ENOENT is also possible on Linux --- however it only occurs if the file
+@c descriptor has a `file' structure but no `inode' structure.  I'm not
+@c sure how such an fd could be created.  Perhaps it's a bug.
+
+@end table
+
+@end deftypefun
+
+@comment unistd.h
+@comment Unix98
+@deftypefun int ftruncate64 (int @var{id}, off64_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a syscall, try ftruncate if length fits.
+This function is similar to the @code{ftruncate} function.  The
+difference is that the @var{length} argument is 64 bits wide even on 32
+bits machines which allows the handling of files with sizes up to
+@twoexp{63} bytes.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{ftruncate} and so transparently replaces the 32 bits interface.
+@end deftypefun
+
+As announced here is a little example of how to use @code{ftruncate} in
+combination with @code{mmap}:
+
+@smallexample
+int fd;
+void *start;
+size_t len;
+
+int
+add (off_t at, void *block, size_t size)
+@{
+  if (at + size > len)
+    @{
+      /* Resize the file and remap.  */
+      size_t ps = sysconf (_SC_PAGESIZE);
+      size_t ns = (at + size + ps - 1) & ~(ps - 1);
+      void *np;
+      if (ftruncate (fd, ns) < 0)
+        return -1;
+      np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
+      if (np == MAP_FAILED)
+        return -1;
+      start = np;
+      len = ns;
+    @}
+  memcpy ((char *) start + at, block, size);
+  return 0;
+@}
+@end smallexample
+
+The function @code{add} writes a block of memory at an arbitrary
+position in the file.  If the current size of the file is too small it
+is extended.  Note that it is extended by a whole number of pages.  This
+is a requirement of @code{mmap}.  The program has to keep track of the
+real size, and when it has finished a final @code{ftruncate} call should
+set the real size of the file.
+
+@node Storage Allocation
+@subsection Storage Allocation
+@cindex allocating file storage
+@cindex file allocation
+@cindex storage allocating
+
+@cindex file fragmentation
+@cindex fragmentation of files
+@cindex sparse files
+@cindex files, sparse
+Most file systems support allocating large files in a non-contiguous
+fashion: the file is split into @emph{fragments} which are allocated
+sequentially, but the fragments themselves can be scattered across the
+disk.  File systems generally try to avoid such fragmentation because it
+decreases performance, but if a file gradually increases in size, there
+might be no other option than to fragment it.  In addition, many file
+systems support @emph{sparse files} with @emph{holes}: regions of null
+bytes for which no backing storage has been allocated by the file
+system.  When the holes are finally overwritten with data, fragmentation
+can occur as well.
+
+Explicit allocation of storage for yet-unwritten parts of the file can
+help the system to avoid fragmentation.  Additionally, if storage
+pre-allocation fails, it is possible to report the out-of-disk error
+early, often without filling up the entire disk.  However, due to
+deduplication, copy-on-write semantics, and file compression, such
+pre-allocation may not reliably prevent the out-of-disk-space error from
+occurring later.  Checking for write errors is still required, and
+writes to memory-mapped regions created with @code{mmap} can still
+result in @code{SIGBUS}.
+
+@deftypefun int posix_fallocate (int @var{fd}, off_t @var{offset}, off_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c If the file system does not support allocation,
+@c @code{posix_fallocate} has a race with file extension (if
+@c @var{length} is zero) or with concurrent writes of non-NUL bytes (if
+@c @var{length} is positive).
+
+Allocate backing store for the region of @var{length} bytes starting at
+byte @var{offset} in the file for the descriptor @var{fd}.  The file
+length is increased to @samp{@var{length} + @var{offset}} if necessary.
+
+@var{fd} must be a regular file opened for writing, or @code{EBADF} is
+returned.  If there is insufficient disk space to fulfill the allocation
+request, @code{ENOSPC} is returned.
+
+@strong{Note:} If @code{fallocate} is not available (because the file
+system does not support it), @code{posix_fallocate} is emulated, which
+has the following drawbacks:
+
+@itemize @bullet
+@item
+It is very inefficient because all file system blocks in the requested
+range need to be examined (even if they have been allocated before) and
+potentially rewritten.  In contrast, with proper @code{fallocate}
+support (see below), the file system can examine the internal file
+allocation data structures and eliminate holes directly, maybe even
+using unwritten extents (which are pre-allocated but uninitialized on
+disk).
+
+@item
+There is a race condition if another thread or process modifies the
+underlying file in the to-be-allocated area.  Non-null bytes could be
+overwritten with null bytes.
+
+@item
+If @var{fd} has been opened with the @code{O_WRONLY} flag, the function
+will fail with an @code{errno} value of @code{EBADF}.
+
+@item
+If @var{fd} has been opened with the @code{O_APPEND} flag, the function
+will fail with an @code{errno} value of @code{EBADF}.
+
+@item
+If @var{length} is zero, @code{ftruncate} is used to increase the file
+size as requested, without allocating file system blocks.  There is a
+race condition which means that @code{ftruncate} can accidentally
+truncate the file if it has been extended concurrently.
+@end itemize
+
+On Linux, if an application does not benefit from emulation or if the
+emulation is harmful due to its inherent race conditions, the
+application can use the Linux-specific @code{fallocate} function, with a
+zero flag argument.  For the @code{fallocate} function, @theglibc{} does
+not perform allocation emulation if the file system does not support
+allocation.  Instead, an @code{EOPNOTSUPP} is returned to the caller.
+
+@end deftypefun
+
+@deftypefun int posix_fallocate64 (int @var{fd}, off64_t @var{offset}, off64_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function is a variant of @code{posix_fallocate64} which accepts
+64-bit file offsets on all platforms.
+
+@end deftypefun
+
+@node Making Special Files
+@section Making Special Files
+@cindex creating special files
+@cindex special files
+
+The @code{mknod} function is the primitive for making special files,
+such as files that correspond to devices.  @Theglibc{} includes
+this function for compatibility with BSD.
+
+The prototype for @code{mknod} is declared in @file{sys/stat.h}.
+@pindex sys/stat.h
+
+@comment sys/stat.h
+@comment BSD
+@deftypefun int mknod (const char *@var{filename}, mode_t @var{mode}, dev_t @var{dev})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Instead of issuing the syscall directly, we go through xmknod.
+@c Although the internal xmknod takes a dev_t*, that could lead to
+@c @mtsrace races, it's passed a pointer to mknod's dev.
+The @code{mknod} function makes a special file with name @var{filename}.
+The @var{mode} specifies the mode of the file, and may include the various
+special file bits, such as @code{S_IFCHR} (for a character special file)
+or @code{S_IFBLK} (for a block special file).  @xref{Testing File Type}.
+
+The @var{dev} argument specifies which device the special file refers to.
+Its exact interpretation depends on the kind of special file being created.
+
+The return value is @code{0} on success and @code{-1} on error.  In addition
+to the usual file name errors (@pxref{File Name Errors}), the
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EPERM
+The calling process is not privileged.  Only the superuser can create
+special files.
+
+@item ENOSPC
+The directory or file system that would contain the new file is full
+and cannot be extended.
+
+@item EROFS
+The directory containing the new file can't be modified because it's on
+a read-only file system.
+
+@item EEXIST
+There is already a file named @var{filename}.  If you want to replace
+this file, you must remove the old file explicitly first.
+@end table
+@end deftypefun
+
+@node Temporary Files
+@section Temporary Files
+
+If you need to use a temporary file in your program, you can use the
+@code{tmpfile} function to open it.  Or you can use the @code{tmpnam}
+(better: @code{tmpnam_r}) function to provide a name for a temporary
+file and then you can open it in the usual way with @code{fopen}.
+
+The @code{tempnam} function is like @code{tmpnam} but lets you choose
+what directory temporary files will go in, and something about what
+their file names will look like.  Important for multi-threaded programs
+is that @code{tempnam} is reentrant, while @code{tmpnam} is not since it
+returns a pointer to a static buffer.
+
+These facilities are declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun {FILE *} tmpfile (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
+@c The unsafety issues are those of fdopen, plus @acsfd because of the
+@c open.
+@c __path_search (internal buf, !dir, const pfx, !try_tmpdir) ok
+@c  libc_secure_genenv only if try_tmpdir
+@c  xstat64, strlen, strcmp, sprintf
+@c __gen_tempname (internal tmpl, __GT_FILE) ok
+@c  strlen, memcmp, getpid, open/mkdir/lxstat64 ok
+@c  HP_TIMING_NOW if available ok
+@c  gettimeofday (!tz) first time, or every time if no HP_TIMING_NOW ok
+@c  static value is used and modified without synchronization ok
+@c   but the use is as a source of non-cryptographic randomness
+@c   with retries in case of collision, so it should be safe
+@c unlink, fdopen
+This function creates a temporary binary file for update mode, as if by
+calling @code{fopen} with mode @code{"wb+"}.  The file is deleted
+automatically when it is closed or when the program terminates.  (On
+some other @w{ISO C} systems the file may fail to be deleted if the program
+terminates abnormally).
+
+This function is reentrant.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is in fact @code{tmpfile64}, i.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun {FILE *} tmpfile64 (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
+This function is similar to @code{tmpfile}, but the stream it returns a
+pointer to was opened using @code{tmpfile64}.  Therefore this stream can
+be used for files larger than @twoexp{31} bytes on 32-bit machines.
+
+Please note that the return type is still @code{FILE *}.  There is no
+special @code{FILE} type for the LFS interface.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{tmpfile}
+and so transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun {char *} tmpnam (char *@var{result})
+@safety{@prelim{}@mtunsafe{@mtasurace{:tmpnam/!result}}@asunsafe{}@acsafe{}}
+@c The passed-in buffer should not be modified concurrently with the
+@c call.
+@c __path_search (static or passed-in buf, !dir, !pfx, !try_tmpdir) ok
+@c __gen_tempname (internal tmpl, __GT_NOCREATE) ok
+This function constructs and returns a valid file name that does not
+refer to any existing file.  If the @var{result} argument is a null
+pointer, the return value is a pointer to an internal static string,
+which might be modified by subsequent calls and therefore makes this
+function non-reentrant.  Otherwise, the @var{result} argument should be
+a pointer to an array of at least @code{L_tmpnam} characters, and the
+result is written into that array.
+
+It is possible for @code{tmpnam} to fail if you call it too many times
+without removing previously-created files.  This is because the limited
+length of the temporary file names gives room for only a finite number
+of different names.  If @code{tmpnam} fails it returns a null pointer.
+
+@strong{Warning:} Between the time the pathname is constructed and the
+file is created another process might have created a file with the same
+name using @code{tmpnam}, leading to a possible security hole.  The
+implementation generates names which can hardly be predicted, but when
+opening the file you should use the @code{O_EXCL} flag.  Using
+@code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun {char *} tmpnam_r (char *@var{result})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is nearly identical to the @code{tmpnam} function, except
+that if @var{result} is a null pointer it returns a null pointer.
+
+This guarantees reentrancy because the non-reentrant situation of
+@code{tmpnam} cannot happen here.
+
+@strong{Warning}: This function has the same security problems as
+@code{tmpnam}.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int L_tmpnam
+The value of this macro is an integer constant expression that
+represents the minimum size of a string large enough to hold a file name
+generated by the @code{tmpnam} function.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int TMP_MAX
+The macro @code{TMP_MAX} is a lower bound for how many temporary names
+you can create with @code{tmpnam}.  You can rely on being able to call
+@code{tmpnam} at least this many times before it might fail saying you
+have made too many temporary file names.
+
+With @theglibc{}, you can create a very large number of temporary
+file names.  If you actually created the files, you would probably run
+out of disk space before you ran out of names.  Some other systems have
+a fixed, small limit on the number of temporary files.  The limit is
+never less than @code{25}.
+@end deftypevr
+
+@comment stdio.h
+@comment SVID
+@deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c There's no way (short of being setuid) to avoid getenv("TMPDIR"),
+@c even with a non-NULL dir.
+@c
+@c __path_search (internal buf, dir, pfx, try_tmpdir) unsafe getenv
+@c __gen_tempname (internal tmpl, __GT_NOCREATE) ok
+@c strdup
+This function generates a unique temporary file name.  If @var{prefix}
+is not a null pointer, up to five characters of this string are used as
+a prefix for the file name.  The return value is a string newly
+allocated with @code{malloc}, so you should release its storage with
+@code{free} when it is no longer needed.
+
+Because the string is dynamically allocated this function is reentrant.
+
+The directory prefix for the temporary file name is determined by
+testing each of the following in sequence.  The directory must exist and
+be writable.
+
+@itemize @bullet
+@item
+The environment variable @code{TMPDIR}, if it is defined.  For security
+reasons this only happens if the program is not SUID or SGID enabled.
+
+@item
+The @var{dir} argument, if it is not a null pointer.
+
+@item
+The value of the @code{P_tmpdir} macro.
+
+@item
+The directory @file{/tmp}.
+@end itemize
+
+This function is defined for SVID compatibility.
+
+@strong{Warning:} Between the time the pathname is constructed and the
+file is created another process might have created a file with the same
+name using @code{tempnam}, leading to a possible security hole.  The
+implementation generates names which can hardly be predicted, but when
+opening the file you should use the @code{O_EXCL} flag.  Using
+@code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem.
+@end deftypefun
+@cindex TMPDIR environment variable
+
+@c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not??
+@comment stdio.h
+@comment SVID
+@deftypevr {SVID Macro} {char *} P_tmpdir
+This macro is the name of the default directory for temporary files.
+@end deftypevr
+
+Older Unix systems did not have the functions just described.  Instead
+they used @code{mktemp} and @code{mkstemp}.  Both of these functions
+work by modifying a file name template string you pass.  The last six
+characters of this string must be @samp{XXXXXX}.  These six @samp{X}s
+are replaced with six characters which make the whole string a unique
+file name.  Usually the template string is something like
+@samp{/tmp/@var{prefix}XXXXXX}, and each program uses a unique @var{prefix}.
+
+@strong{NB:} Because @code{mktemp} and @code{mkstemp} modify the
+template string, you @emph{must not} pass string constants to them.
+String constants are normally in read-only storage, so your program
+would crash when @code{mktemp} or @code{mkstemp} tried to modify the
+string.  These functions are declared in the header file @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment Unix
+@deftypefun {char *} mktemp (char *@var{template})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c __gen_tempname (caller tmpl, __GT_NOCREATE) ok
+The @code{mktemp} function generates a unique file name by modifying
+@var{template} as described above.  If successful, it returns
+@var{template} as modified.  If @code{mktemp} cannot find a unique file
+name, it makes @var{template} an empty string and returns that.  If
+@var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a
+null pointer.
+
+@strong{Warning:} Between the time the pathname is constructed and the
+file is created another process might have created a file with the same
+name using @code{mktemp}, leading to a possible security hole.  The
+implementation generates names which can hardly be predicted, but when
+opening the file you should use the @code{O_EXCL} flag.  Using
+@code{mkstemp} is a safe way to avoid this problem.
+@end deftypefun
+
+@comment stdlib.h
+@comment BSD
+@deftypefun int mkstemp (char *@var{template})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+@c __gen_tempname (caller tmpl, __GT_FILE) ok
+The @code{mkstemp} function generates a unique file name just as
+@code{mktemp} does, but it also opens the file for you with @code{open}
+(@pxref{Opening and Closing Files}).  If successful, it modifies
+@var{template} in place and returns a file descriptor for that file open
+for reading and writing.  If @code{mkstemp} cannot create a
+uniquely-named file, it returns @code{-1}.  If @var{template} does not
+end with @samp{XXXXXX}, @code{mkstemp} returns @code{-1} and does not
+modify @var{template}.
+
+The file is opened using mode @code{0600}.  If the file is meant to be
+used by other users this mode must be changed explicitly.
+@end deftypefun
+
+Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a
+unique file that cannot possibly clash with any other program trying to
+create a temporary file.  This is because it works by calling
+@code{open} with the @code{O_EXCL} flag, which says you want to create a
+new file and get an error if the file already exists.
+
+@comment stdlib.h
+@comment BSD
+@deftypefun {char *} mkdtemp (char *@var{template})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c __gen_tempname (caller tmpl, __GT_DIR) ok
+The @code{mkdtemp} function creates a directory with a unique name.  If
+it succeeds, it overwrites @var{template} with the name of the
+directory, and returns @var{template}.  As with @code{mktemp} and
+@code{mkstemp}, @var{template} should be a string ending with
+@samp{XXXXXX}.
+
+If @code{mkdtemp} cannot create an uniquely named directory, it returns
+@code{NULL} and sets @var{errno} appropriately.  If @var{template} does
+not end with @samp{XXXXXX}, @code{mkdtemp} returns @code{NULL} and does
+not modify @var{template}.  @var{errno} will be set to @code{EINVAL} in
+this case.
+
+The directory is created using mode @code{0700}.
+@end deftypefun
+
+The directory created by @code{mkdtemp} cannot clash with temporary
+files or directories created by other users.  This is because directory
+creation always works like @code{open} with @code{O_EXCL}.
+@xref{Creating Directories}.
+
+The @code{mkdtemp} function comes from OpenBSD.
+
+@c FIXME these are undocumented:
+@c faccessat
+@c fchmodat
+@c fchownat
+@c futimesat
+@c fstatat (there's a commented-out safety assessment for this one)
+@c linkat
+@c mkdirat
+@c mkfifoat
+@c name_to_handle_at
+@c openat
+@c open_by_handle_at
+@c readlinkat
+@c renameat
+@c scandirat
+@c symlinkat
+@c unlinkat
+@c utimensat
+@c mknodat