   This file documents the GNU C library.

   This is Edition 0.03, last updated 19 May 1993, of
`The GNU C Library Reference Manual', for Version 1.06 Beta.

   Copyright (C) 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translations of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.

File Locks
==========

   The remaining `fcntl' commands are used to support "record locking",
which permits multiple cooperating programs to prevent each other from
simultaneously accessing parts of a file in error-prone ways.

   An "exclusive" or "write" lock gives a process exclusive access for
writing to the specified part of the file.  While a write lock is in
place, no other process can lock that part of the file.

   A "shared" or "read" lock prohibits any other process from
requesting a write lock on the specified part of the file.  However,
other processes can request read locks.

   The `read' and `write' functions do not actually check to see
whether there are any locks in place.  If you want to implement a
locking protocol for a file shared by multiple processes, your
application must do explicit `fcntl' calls to request and clear locks
at the appropriate points.

   Locks are associated with processes.  A process can only have one
kind of lock set for each byte of a given file.  When any file
descriptor for that file is closed by the process, all of the locks
that process holds on that file are released, even if the locks were
made using other descriptors that remain open.  Likewise, locks are
released when a process exits, and are not inherited by child processes
created using `fork' (see Creating a Process.).

   When making a lock, use a `struct flock' to specify what kind of
lock and where.  This data type and the associated macros for the
`fcntl' function are declared in the header file `fcntl.h'.

 -- struct Type: flock
     This structure is used with the `fcntl' function to describe a file
     lock.  It has these members:

    `short int l_type'
          Specifies the type of the lock; one of `F_RDLCK', `F_WRLCK',
          or `F_UNLCK'.

    `short int l_whence'
          This corresponds to the WHENCE argument to `fseek' or
          `lseek', and specifies what the offset is relative to.  Its
          value can be one of `SEEK_SET', `SEEK_CUR', or `SEEK_END'.

    `off_t l_start'
          This specifies the offset of the start of the region to which
          the lock applies, and is given in bytes relative to the point
          specified by `l_whence' member.

    `off_t l_len'
          This specifies the length of the region to be locked.  A
          value of `0' is treated specially; it means the region
          extends to the end of the file.

    `pid_t l_pid'
          This field is the process ID (see Process Creation Concepts.)
          of the process holding the lock.  It is filled
          in by calling `fcntl' with the `F_GETLK' command, but is
          ignored when making a lock.

 -- Macro: int F_GETLK
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should get information about a lock.  This command
     requires a third argument of type `struct flock *' to be passed to
     `fcntl', so that the form of the call is:

          fcntl (FILEDES, F_GETLK, LOCKP)

     If there is a lock already in place that would block the lock
     described by the LOCKP argument, information about that lock
     overwrites `*LOCKP'.  Existing locks are not reported if they are
     compatible with making a new lock as specified.  Thus, you should
     specify a lock type of `F_WRLCK' if you want to find out about both
     read and write locks, or `F_RDLCK' if you want to find out about
     write locks only.

     There might be more than one lock affecting the region specified
     by the LOCKP argument, but `fcntl' only returns information about
     one of them.  The `l_whence' member of the LOCKP structure is set
     to `SEEK_SET' and the `l_start' and `l_len' fields set to identify
     the locked region.

     If no lock applies, the only change to the LOCKP structure is to
     update the `l_type' to a value of `F_UNLCK'.

     The normal return value from `fcntl' with this command is an
     unspecified value other than `-1', which is reserved to indicate an
     error.  The following `errno' error conditions are defined for
     this command:

    `EBADF'
          The FILEDES argument is invalid.

    `EINVAL'
          Either the LOCKP argument doesn't specify valid lock
          information, or the file associated with FILEDES doesn't
          support locks.

 -- Macro: int F_SETLK
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should set or clear a lock.  This command requires a third
     argument of type `struct flock *' to be passed to `fcntl', so that
     the form of the call is:

          fcntl (FILEDES, F_SETLK, LOCKP)

     If the process already has a lock on any part of the region, the
     old lock on that part is replaced with the new lock.  You can
     remove a lock by specifying the a lock type of `F_UNLCK'.

     If the lock cannot be set, `fcntl' returns immediately with a value
     of `-1'.  This function does not block waiting for other processes
     to release locks.  If `fcntl' succeeds, it return a value other
     than `-1'.

     The following `errno' error conditions are defined for this
     function:

    `EACCES'
    `EAGAIN'
          The lock cannot be set because it is blocked by an existing
          lock on the file.  Some systems use `EAGAIN' in this case,
          and other systems use `EACCES'; your program should treat
          them alike, after `F_SETLK'.

    `EBADF'
          Either: the FILEDES argument is invalid; you requested a read
          lock but the FILEDES is not open for read access; or, you
          requested a write lock but the FILEDES is not open for write
          access.

    `EINVAL'
          Either the LOCKP argument doesn't specify valid lock
          information, or the file associated with FILEDES doesn't
          support locks.

    `ENOLCK'
          The system has run out of file lock resources; there are
          already too many file locks in place.

          Well-designed file systems never report this error, because
          they have no limitation on the number of locks.  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.

 -- Macro: int F_SETLKW
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should set or clear a lock.  It is just like the `F_SETLK'
     command, but causes the process to block (or wait) until the
     request can be specified.

     This command requires a third argument of type `struct flock *', as
     for the `F_SETLK' command.

     The `fcntl' return values and errors are the same as for the
     `F_SETLK' command, but these additional `errno' error conditions
     are defined for this command:

    `EINTR'
          The function was interrupted by a signal while it was waiting.
          See Interrupted Primitives.

    `EDEADLK'
          A deadlock condition was detected.  This can happen if two
          processes each already controlling a locked region request a
          lock on the same region locked by the other process.

   The following macros are defined for use as values for the `l_type'
member of the `flock' structure.  The values are integer constants.

`F_RDLCK'
     This macro is used to specify a read (or shared) lock.

`F_WRLCK'
     This macro is used to specify a write (or exclusive) lock.

`F_UNLCK'
     This macro is used to specify that the region is unlocked.

   As an example of a situation where file locking is useful, consider a
program that can be run simultaneously by several different users, that
logs status information to a common file.  One example of such a program
might be a game that uses a file to keep track of high scores.  Another
example might be a program that records usage or accounting information
for billing purposes.

   Having multiple copies of the program simultaneously writing to the
file could cause the contents of the file to become mixed up.  But you
can prevent this kind of problem by setting a write lock on the file
before actually writing to the file.

   If the program also needs to read the file and wants to make sure
that the contents of the file are in a consistent state, then it can
also use a read lock.  While the read lock is set, no other process can
lock that part of the file for writing.

   Remember that file locks are only a *voluntary* protocol for
controlling access to a file.  There is still potential for access to
the file by programs that don't use the lock protocol.

Interrupt-Driven Input
======================

   If you set the `FASYNC' status flag on a file descriptor (see File Status Flags.),
a `SIGIO' signal is sent whenever input or output
becomes possible on that file descriptor.  The process or process group
to receive the signal can be selected by using the `F_SETOWN' command
to the `fcntl' function.  If the file descriptor is a socket, this also
selects the recipient of `SIGURG' signals that are delivered when
out-of-band data arrives on that socket; see Out-of-Band Data.

   If the file descriptor corresponds to a terminal device, then `SIGIO'
signals are sent to the foreground process group of the terminal. See
Job Control.

   The symbols in this section are defined in the header file `fcntl.h'.

 -- Macro: int F_GETOWN
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should get information about the process or process group
     to which `SIGIO' signals are sent.  (For a terminal, this is
     actually the foreground process group ID, which you can get using
     `tcgetpgrp'; see Terminal Access Functions.)

     The return value is interpreted as a process ID; if negative, its
     absolute value is the process group ID.

     The following `errno' error condition is defined for this command:

    `EBADF'
          The FILEDES argument is invalid.

 -- Macro: int F_SETOWN
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should set the process or process group to which `SIGIO'
     signals are sent.  This command requires a third argument of type
     `pid_t' to be passed to `fcntl', so that the form of the call is:

          fcntl (FILEDES, F_SETOWN, PID)

     The PID argument should be a process ID.  You can also pass a
     negative number whose absolute value is a process group ID.

     The return value from `fcntl' with this command is `-1' in case of
     error and some other value if successful.  The following `errno'
     error conditions are defined for this command:

    `EBADF'
          The FILEDES argument is invalid.

    `ESRCH'
          There is no process or process group corresponding to PID.

File System Interface
*********************

   This chapter describes the GNU C library's functions for manipulating
files.  Unlike the input and output functions described in I/O on Streams
and 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.

Working Directory
=================

   Each process has associated with it a directory, called its "current
working directory" or simply "working directory", that is used in the
resolution of relative file names (see 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 `getpwuid' or `getpwnam' functions; see User Database.

   Users can change the working directory using shell commands like
`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.

   Prototypes for these functions are declared in the header file
`unistd.h'.

 -- Function: char * getcwd (char *BUFFER, size_t SIZE)
     The `getcwd' function returns an absolute file name representing
     the current working directory, storing it in the character array
     BUFFER that you provide.  The SIZE argument is how you tell the
     system the allocation size of BUFFER.

     The GNU library version of this function also permits you to
     specify a null pointer for the BUFFER argument.  Then `getcwd'
     allocates a buffer automatically, as with `malloc' (see
     Unconstrained Allocation.).  If the 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 BUFFER on success and a null pointer on
     failure. The following `errno' error conditions are defined for
     this function:

    `EINVAL'
          The SIZE argument is zero and BUFFER is not a null pointer.

    `ERANGE'
          The SIZE argument is less than the length of the working
          directory name.  You need to allocate a bigger array and try
          again.

    `EACCES'
          Permission to read or search a component of the file name was
          denied.

   Here is an example showing how you could implement the behavior of
GNU's `getcwd (NULL, 0)' using only the standard behavior of `getcwd':

     char *
     gnu_getcwd ()
     {
       int size = 100;
       char *buffer = (char *) xmalloc (size);

       while (1)
         {
           char *value = getcwd (buffer, size);
           if (value != 0)
             return buffer;
           size *= 2;
           free (buffer);
           buffer = (char *) xmalloc (size);
         }
     }

See Malloc Examples, for information about `xmalloc', which is not
a library function but is a customary name used in most GNU software.

 -- Function: char * getwd (char *BUFFER)
     This is similar to `getcwd'.  The GNU library provides `getwd' for
     backwards compatibility with BSD.  The BUFFER should be a pointer
     to an array at least `PATH_MAX' bytes long.

 -- Function: int chdir (const char *FILENAME)
     This function is used to set the process's working directory to
     FILENAME.

     The normal, successful return value from `chdir' is `0'.  A value
     of `-1' is returned to indicate an error.  The `errno' error
     conditions defined for this function are the usual file name
     syntax errors (see File Name Errors.), plus `ENOTDIR' if the
     file FILENAME is not a directory.

Accessing Directories
=====================

   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.

   The `opendir' function opens a "directory stream" whose elements are
directory entries.  You use the `readdir' function on the directory
stream to retrieve these entries, represented as `struct dirent'
objects.  The name of the file for each entry is stored in the `d_name'
member of this structure.  There are obvious parallels here to the
stream facilities for ordinary files, described in I/O on Streams.

Format of a Directory Entry
---------------------------

   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 `dirent.h'.

 -- Data Type: struct dirent
     This is a structure type used to return information about directory
     entries.  It contains the following fields:

    `char *d_name'
          This is the null-terminated file name component.  This is the
          only field you can count on in all POSIX systems.

    `ino_t d_fileno'
          This is the file serial number.  For BSD compatibility, you
          can also refer to this member as `d_ino'.

    `size_t d_namlen'
          This is the length of the file name, not including the
          terminating null character.

     This structure may contain additional members in the future.

     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
     `d_fileno' field.

     File attributes such as size, modification times, and the like are
     part of the file itself, not any particular directory entry.
     See File Attributes.

Opening a Directory Stream
--------------------------

   This section describes how to open a directory stream.  All the
symbols are declared in the header file `dirent.h'.

 -- Data Type: DIR
     The `DIR' data type represents a directory stream.

   You shouldn't ever allocate objects of the `struct dirent' or `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.

 -- Function: DIR * opendir (const char *DIRNAME)
     The `opendir' function opens and returns a directory stream for
     reading the directory whose file name is DIRNAME.  The stream has
     type `DIR *'.

     If unsuccessful, `opendir' returns a null pointer.  In addition to
     the usual file name syntax errors (see File Name Errors.), the
     following `errno' error conditions are defined for this function:

    `EACCES'
          Read permission is denied for the directory named by
          `dirname'.

    `EMFILE'
          The process has too many files open.

    `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 the GNU system.)

     The `DIR' type is typically implemented using a file descriptor,
     and the `opendir' function in terms of the `open' function. See
     Low-Level I/O.  Directory streams and the underlying file
     descriptors are closed on `exec' (see Executing a File.).

Reading and Closing a Directory Stream
--------------------------------------

   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 `dirent.h'.

 -- Function: struct dirent * readdir (DIR *DIRSTREAM)
     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 statically allocated and can be rewritten
     by a subsequent call.

     *Portability Note:* On some systems, `readdir' may not return
     entries for `.' and `..'.  See File Name Resolution.

     If there are no more entries in the directory or an error is
     detected, `readdir' returns a null pointer.  The following `errno'
     error conditions are defined for this function:

    `EBADF'
          The DIRSTREAM argument is not valid.

 -- Function: int closedir (DIR *DIRSTREAM)
     This function closes the directory stream DIRSTREAM.  It returns
     `0' on success and `-1' on failure.

     The following `errno' error conditions are defined for this
     function:

    `EBADF'
          The DIRSTREAM argument is not valid.

Simple Program to List a Directory
----------------------------------

   Here's a simple program that prints the names of the files in the
current working directory:

     #include <stddef.h>
     #include <stdio.h>
     #include <sys/types.h>
     #include <dirent.h>

     int
     main (void)
     {
       DIR *dp;
       struct dirent *ep;

       dp = opendir ("./");
       if (dp != NULL)
         {
           while (ep = readdir (dp))
     	puts (ep->d_name);
           (void) closedir (dp);
         }
       else
         puts ("Couldn't open the directory.");

       return 0;
     }

   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 Array Sort Function

Random Access in a Directory Stream
-----------------------------------

   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 `dirent.h'.

 -- Function: void rewinddir (DIR *DIRSTREAM)
     The `rewinddir' function is used to reinitialize the directory
     stream DIRSTREAM, so that if you call `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 `opendir'.  (Entries for these
     files might or might not be returned by `readdir' if they were
     added or removed since you last called `opendir' or `rewinddir'.)

 -- Function: off_t telldir (DIR *DIRSTREAM)
     The `telldir' function returns the file position of the directory
     stream DIRSTREAM.  You can use this value with `seekdir' to
     restore the directory stream to that position.

 -- Function: void seekdir (DIR *DIRSTREAM, off_t POS)
     The `seekdir' function sets the file position of the directory
     stream DIRSTREAM to POS.  The value POS must be the result of a
     previous call to `telldir' on this particular stream; closing and
     reopening the directory can invalidate values returned by
     `telldir'.

Hard Links
==========

   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 `link' function.  (The new name is
also called a "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 the
organization of the file system is not a strict hierarchy or tree.

   Since a particular file exists within a single file system, all its
names must be in directories in that file system.  `link' reports an
error if you try to make a hard link to the file from another file
system.

   The prototype for the `link' function is declared in the header file
`unistd.h'.

 -- Function: int link (const char *OLDNAME, const char *NEWNAME)
     The `link' function makes a new link to the existing file named by
     OLDNAME, under the new name NEWNAME.

     This function returns a value of `0' if it is successful and `-1'
     on failure.  In addition to the usual file name syntax errors
     (see File Name Errors.) for both OLDNAME and NEWNAME, the
     following `errno' error conditions are defined for this function:

    `EACCES'
          The directory in which the new link is to be written is not
          writable.

    `EEXIST'
          There is already a file named NEWNAME.  If you want to replace
          this link with a new link, you must remove the old link
          explicitly first.

    `EMLINK'
          There are already too many links to the file named by OLDNAME.
          (The maximum number of links to a file is `LINK_MAX'; see
          Limits for Files.)

          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.

    `ENOENT'
          The file named by OLDNAME doesn't exist.  You can't make a
          link to a file that doesn't exist.

    `ENOSPC'
          The directory or file system that would contain the new link
          is "full" and cannot be extended.

    `EPERM'
          Some implementations only allow privileged users to make
          links to directories, and others prohibit this operation
          entirely.  This error is used to report the problem.

    `EROFS'
          The directory containing the new link can't be modified
          because it's on a read-only file system.

    `EXDEV'
          The directory specified in NEWNAME is on a different file
          system than the existing file.

Symbolic Links
==============

   The GNU system supports "soft links" or "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 `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 `stat' function likewise
operates on the file that the symbolic link points to, instead of on
the link itself.  So does `link', the function that makes a hard link.

   By contrast, other operations such as deleting or renaming the file
operate on the link itself.  The functions `readlink' and `lstat' also
refrain from following symbolic links, because their purpose is to
obtain information about the link.

   Prototypes for the functions listed in this section are in
`unistd.h'.

 -- Function: int symlink (const char *OLDNAME, const char *NEWNAME)
     The `symlink' function makes a symbolic link to OLDNAME named
     NEWNAME.

     The normal return value from `symlink' is `0'.  A return value of
     `-1' indicates an error.  In addition to the usual file name
     syntax errors (see File Name Errors.), the following `errno'
     error conditions are defined for this function:

    `EEXIST'
          There is already an existing file named NEWNAME.

    `EROFS'
          The file NEWNAME would exist on a read-only file system.

    `ENOSPC'
          The directory or file system cannot be extended to make the
          new link.

    `EIO'
          A hardware error occurred while reading or writing data on
          the disk.

 -- Function: int readlink (const char *FILENAME, char *BUFFER, size_t
          SIZE)
     The `readlink' function gets the value of the symbolic link
     FILENAME.  The file name that the link points to is copied into
     BUFFER.  This file name string is *not* null-terminated;
     `readlink' normally returns the number of characters copied.  The
     SIZE argument specifies the maximum number of characters to copy,
     usually the allocation size of BUFFER.

     If the return value equals SIZE, you cannot tell whether or not
     there was room to return the entire name.  So make a bigger buffer
     and call `readlink' again.  Here is an example:

          char *
          readlink_malloc (char *filename)
          {
            int size = 100;

            while (1)
              {
                char *buffer = (char *) xmalloc (size);
                int nchars = readlink (filename, buffer, size);
                if (nchars < size)
                  return buffer;
                free (buffer);
                size *= 2;
              }
          }

     A value of `-1' is returned in case of error.  In addition to the
     usual file name syntax errors (see File Name Errors.), the
     following `errno' error conditions are defined for this function:

    `EINVAL'
          The named file is not a symbolic link.

    `EIO'
          A hardware error occurred while reading or writing data on
          the disk.

Deleting Files
==============

   You can delete a file with the functions `unlink' or `remove'.
(These names are synonymous.)

   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 names as
well (see Hard Links.), it remains accessible under its other names.

 -- Function: int unlink (const char *FILENAME)
     The `unlink' function deletes the file name 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.)

     The function `unlink' is declared in the header file `unistd.h'.

     This function returns `0' on successful completion, and `-1' on
     error.  In addition to the usual file name syntax errors (see
     File Name Errors.), the following `errno' error conditions are
     defined for this function:

    `EACCESS'
          Write permission is denied for the directory from which the
          file is to be removed.

    `EBUSY'
          This error indicates that the file is being used by the
          system in such a way that it can't be unlinked.  Examples of
          situations where you might see this error are if the file
          name specifies the root directory or a mount point for a file
          system.

    `ENOENT'
          The file name to be deleted doesn't exist.

    `EPERM'
          On some systems, `unlink' cannot be used to delete the name
          of a directory, or can only be used this way by a privileged
          user. To avoid such problems, use `rmdir' to delete
          directories.

    `EROFS'
          The directory in which the file name is to be deleted is on a
          read-only file system, and can't be modified.

 -- Function: int remove (const char *FILENAME)
     The `remove' function is another name for `unlink'. `remove' is
     the ANSI C name, whereas `unlink' is the POSIX.1 name.  The name
     `remove' is declared in `stdio.h'.

 -- Function: int rmdir (const char *FILENAME)
     The `rmdir' function deletes a directory.  The directory must be
     empty before it can be removed; in other words, it can only contain
     entries for `.' and `..'.

     In most other respects, `rmdir' behaves like `unlink'.  There are
     two additional `errno' error conditions defined for `rmdir':

    `EEXIST'
    `ENOTEMPTY'
          The directory to be deleted is not empty.

     These two error codes are synonymous; some systems use one, and
     some use the other.

     The prototype for this function is declared in the header file
     `unistd.h'.

Renaming Files
==============

   The `rename' function is used to change a file's name.

 -- Function: int rename (const char *OLDNAME, const char *NEWNAME)
     The `rename' function renames the file name OLDNAME with NEWNAME.
     The file formerly accessible under the name OLDNAME is afterward
     accessible as NEWNAME instead.  (If the file had any other names
     aside from OLDNAME, it continues to have those names.)

     The directory containing the name NEWNAME must be on the same file
     system as the file (as indicated by the name OLDNAME).

     One special case for `rename' is when OLDNAME and NEWNAME are two
     names for the same file.  The consistent way to handle this case
     is to delete OLDNAME.  However, POSIX says that in this case
     `rename' does nothing and reports success--which is inconsistent.
     We don't know what your operating system will do.  The GNU system,
     when completed, will probably do the right thing (delete OLDNAME)
     unless you explicitly request strict POSIX compatibility "even
     when it hurts".

     If the OLDNAME is not a directory, then any existing file named
     NEWNAME is removed during the renaming operation.  However, if
     NEWNAME is the name of a directory, `rename' fails in this case.

     If the OLDNAME is a directory, then either NEWNAME must not exist
     or it must name a directory that is empty.  In the latter case,
     the existing directory named NEWNAME is deleted first.  The name
     NEWNAME must not specify a subdirectory of the directory `oldname'
     which is being renamed.

     One useful feature of `rename' is that the meaning of the name
     NEWNAME changes "atomically" from any previously existing file by
     that name to its new meaning (the file that was called OLDNAME).
     There is no instant at which NEWNAME is nonexistent "in between"
     the old meaning and the new meaning.

     If `rename' fails, it returns `-1'.  In addition to the usual file
     name syntax errors (see File Name Errors.), the following
     `errno' error conditions are defined for this function:

    `EACCES'
          One of the directories containing NEWNAME or OLDNAME refuses
          write permission; or NEWNAME and OLDNAME are directories and
          write permission is refused for one of them.

    `EBUSY'
          A directory named by OLDNAME or 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.

    `EEXIST'
          The directory NEWNAME isn't empty.

    `ENOTEMPTY'
          The directory NEWNAME isn't empty.

    `EINVAL'
          The OLDNAME is a directory that contains NEWNAME.

    `EISDIR'
          The NEWNAME names a directory, but the OLDNAME doesn't.

    `EMLINK'
          The parent directory of NEWNAME would have too many links.

          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.

    `ENOENT'
          The file named by OLDNAME doesn't exist.

    `ENOSPC'
          The directory that would contain NEWNAME has no room for
          another entry, and there is no space left in the file system
          to expand it.

    `EROFS'
          The operation would involve writing to a directory on a
          read-only file system.

    `EXDEV'
          The two file names NEWNAME and OLDNAMES are on different file
          systems.

Creating Directories
====================

   Directories are created with the `mkdir' function.  (There is also a
shell command `mkdir' which does the same thing.)

 -- Function: int mkdir (const char *FILENAME, mode_t MODE)
     The `mkdir' function creates a new, empty directory whose name is
     FILENAME.

     The argument MODE specifies the file permissions for the new
     directory file.  See Permission Bits, for more information
     about this.

     A return value of `0' indicates successful completion, and `-1'
     indicates failure.  In addition to the usual file name syntax
     errors (see File Name Errors.), the following `errno' error
     conditions are defined for this function:

    `EACCES'
          Write permission is denied for the parent directory in which
          the new directory is to be added.

    `EEXIST'
          A file named FILENAME already exists.

    `EMLINK'
          The parent directory has too many links.

          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.

    `ENOSPC'
          The file system doesn't have enough room to create the new
          directory.

    `EROFS'
          The parent directory of the directory being created is on a
          read-only file system, and cannot be modified.

     To use this function, your program should include the header file
     `sys/stat.h'.

File Attributes
===============

   When you issue an `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, and the like.  This kind of information is called the "file
attributes"; it is 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 these attributes of files.

What the File Attribute Values Mean
-----------------------------------

   When you read the attributes of a file, they come back in a structure
called `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 Reading Attributes.

   The header file `sys/stat.h' declares all the symbols defined in
this section.

 -- Data Type: struct stat
     The `stat' structure type is used to return information about the
     attributes of a file.  It contains at least the following members:

    `mode_t st_mode'
          Specifies the mode of the file.  This includes file type
          information (see Testing File Type.) and the file
          permission bits (see Permission Bits.).

    `ino_t st_ino'
          The file serial number, which distinguishes this file from
          all other files on the same device.

    `dev_t st_dev'
          Identifies the device containing the file.  The `st_ino' and
          `st_dev', taken together, uniquely identify the file.

    `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.  Symbolic links are not counted in the total.

    `uid_t st_uid'
          The user ID of the file's owner.  See File Owner.

    `gid_t st_gid'
          The group ID of the file.  See File Owner.

    `off_t st_size'
          This specifies the size of a regular file in bytes.  For
          files that are really devices and the like, this field isn't
          usually meaningful.

    `time_t st_atime'
          This is the last access time for the file.  See File Times.

    `unsigned long int st_atime_usec'
          This is the fractional part of the last access time for the
          file. See File Times.

    `time_t st_mtime'
          This is the time of the last modification to the contents of
          the file. See File Times.

    `unsigned long int st_mtime_usec'
          This is the fractional part of the time of last modification
          to the contents of the file.  See File Times.

    `time_t st_ctime'
          This is the time of the last modification to the attributes
          of the file. See File Times.

    `unsigned long int st_ctime_usec'
          This is the fractional part of the time of last modification
          to the attributes of the file.  See File Times.

    `unsigned int st_nblocks'
          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 `st_size', like this:

               (st.st_blocks * 512 < st.st_size)

          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.

    `unsigned int st_blksize'
          The optimal block size for reading of writing this file.  You
          might use this size for allocating the buffer space for
          reading of writing the file.

   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 `sys/types.h' as well as in `sys/stat.h'. Here is a
list of them.

 -- Data Type: mode_t
     This is an integer data type used to represent file modes.  In the
     GNU system, this is equivalent to `unsigned int'.

 -- Data Type: ino_t
     This is an arithmetic data type used to represent file serial
     numbers. (In Unix jargon, these are sometimes called "inode
     numbers".) In the GNU system, this type is equivalent to `unsigned
     long int'.

 -- Data Type: dev_t
     This is an arithmetic data type used to represent file device
     numbers. In the GNU system, this is equivalent to `int'.

 -- Data Type: nlink_t
     This is an arithmetic data type used to represent file link counts.
     In the GNU system, this is equivalent to `unsigned short int'.

Reading the Attributes of a File
--------------------------------

   To examine the attributes of files, use the functions `stat',
`fstat' and `lstat'.  They return the attribute information in a
`struct stat' object.  All three functions are declared in the header
file `sys/stat.h'.

 -- Function: int stat (const char *FILENAME, struct stat *BUF)
     The `stat' function returns information about the attributes of the
     file named by FILENAME in the structure pointed at by BUF.

     If 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 `stat' fails, reporting a nonexistent
     file.

     The return value is `0' if the operation is successful, and `-1'
     on failure.  In addition to the usual file name syntax errors
     (see File Name Errors., the following `errno' error conditions
     are defined for this function:

    `ENOENT'
          The file named by FILENAME doesn't exist.

 -- Function: int fstat (int FILEDES, struct stat *BUF)
     The `fstat' function is like `stat', except that it takes an open
     file descriptor as an argument instead of a file name. See
     Low-Level I/O.

     Like `stat', `fstat' returns `0' on success and `-1' on failure.
     The following `errno' error conditions are defined for `fstat':

    `EBADF'
          The FILEDES argument is not a valid file descriptor.

 -- Function: int lstat (const char *FILENAME, struct stat *BUF)
     The `lstat' function is like `stat', except that it does not
     follow symbolic links.  If FILENAME is the name of a symbolic
     link, `lstat' returns information about the link itself; otherwise,
     `lstat' works like `stat'.  See Symbolic Links.