SYNOPSIS
       #include <unistd.h>

       int link(const char *path1, const char *path2);


DESCRIPTION
       The  link()  function shall create a new link (directory entry) for the
       existing file, path1.

       The path1 argument points to a pathname naming an existing  file.   The
       path2  argument  points to a pathname naming the new directory entry to
       be created. The link() function shall atomically create a new link  for
       the  existing  file and the link count of the file shall be incremented
       by one.

       If path1 names a directory, link() shall fail unless  the  process  has
       appropriate  privileges and the implementation supports using link() on
       directories.

       Upon successful completion, link() shall mark for update  the  st_ctime
       field of the file. Also, the st_ctime and st_mtime fields of the direc-
       tory that contains the new entry shall be marked for update.

       If link() fails, no link shall be created and the  link  count  of  the
       file shall remain unchanged.

       The  implementation may require that the calling process has permission
       to access the existing file.

RETURN VALUE
       Upon successful completion, 0 shall be returned. Otherwise, -1 shall be
       returned and errno set to indicate the error.

ERRORS
       The link() function shall fail if:

       EACCES A  component  of either path prefix denies search permission, or
              the requested link requires writing in a directory  that  denies
              write  permission,  or the calling process does not have permis-
              sion to access the existing file and this  is  required  by  the
              implementation.

       EEXIST The  path2  argument resolves to an existing file or refers to a
              symbolic link.

       ELOOP  A loop exists in symbolic links encountered during resolution of
              the path1 or path2 argument.

       EMLINK The  number  of  links  to  the file named by path1 would exceed
              {LINK_MAX}.

       ENAMETOOLONG
       EPERM  The  file  named  by path1 is a directory and either the calling
              process does not have appropriate privileges or the  implementa-
              tion prohibits using link() on directories.

       EROFS  The  requested  link  requires writing in a directory on a read-
              only file system.

       EXDEV  The link named by path2 and the file named by path1 are on  dif-
              ferent  file  systems  and  the  implementation does not support
              links between file systems.

       EXDEV  path1 refers to a named STREAM.


       The link() function may fail if:

       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
              resolution of the path1 or path2 argument.

       ENAMETOOLONG
              As a result of encountering a symbolic link in resolution of the
              path1 or path2 argument, the length of the substituted  pathname
              string exceeded {PATH_MAX}.


       The following sections are informative.

EXAMPLES
   Creating a Link to a File
       The  following  example  shows  how  to  create  a link to a file named
       /home/cnd/mod1 by creating a new directory entry named /modules/pass1.


              #include <unistd.h>


              char *path1 = "/home/cnd/mod1";
              char *path2 = "/modules/pass1";
              int   status;
              ...
              status = link (path1, path2);

   Creating a Link to a File Within a Program
       In the  following  program  example,  the  link()  function  links  the
       /etc/passwd  file  (defined as PASSWDFILE) to a file named /etc/opasswd
       (defined as SAVEFILE), which is used to save the current password file.
       Then, after removing the current password file (defined as PASSWDFILE),
       the new password file is saved as the current password file  using  the
       link() function again.


              #include <unistd.h>


              /* Save new password file as current password file. */
              link (LOCKFILE,PASSWDFILE);

APPLICATION USAGE
       Some implementations do allow links between file systems.

RATIONALE
       Linking  to a directory is restricted to the superuser in most histori-
       cal implementations because this capability may produce  loops  in  the
       file  hierarchy  or  otherwise corrupt the file system.  This volume of
       IEEE Std 1003.1-2001 continues that philosophy  by  prohibiting  link()
       and unlink() from doing this. Other functions could do it if the imple-
       mentor designed such an extension.

       Some historical implementations allow linking  of  files  on  different
       file  systems.  Wording  was  added  to  explicitly allow this optional
       behavior.

       The exception for cross-file system links is intended to apply only  to
       links that are programmatically indistinguishable from "hard" links.

FUTURE DIRECTIONS
       None.

SEE ALSO
       symlink()    ,    unlink()   ,   the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001, <unistd.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .