link(2)

NAME

     link - link to a file

SYNOPSIS

     #include <unistd.h>

     int link(const char *existing, const char *new);

DESCRIPTION

     The link() function creates a new link (directory entry) for
     the existing file and increments its link count by one.  The
     existing argument points to a path name naming  an  existing
     file.   The new argument points to a pathname naming the new
     directory entry to be created.

     To create hard links, both files must be on  the  same  file
     system. Both the old and the new link share equal access and
     rights to the underlying object.  The  super-user  may  make
     multiple  links  to  a  directory.  Unless the caller is the
     super-user, the file named by existing must not be a  direc-
     tory.

     Upon successful completion,  link()  marks  for  update  the
     st_ctime  field of the file. Also, the st_ctime and st_mtime
     fields of the directory that  contains  the  new  entry  are
     marked for update.

RETURN VALUES

     Upon successful completion, 0 is returned. Otherwise, -1  is
     returned,  no  link is created, and errno is set to indicate
     the error.

ERRORS

     The link() function will fail if:

     EACCES
           A component of either path prefix denies  search  per-
           mission,  or  the requested link requires writing in a
           directory with a mode that denies write permission.

     EDQUOT
           The directory where the entry  for  the  new  link  is
           being  placed  cannot  be  extended because the user's
           quota of disk blocks on  that  file  system  has  been
           exhausted.

     EEXIST
           The link named by new exists.

     EFAULT
           The existing or new  argument  points  to  an  illegal
           address.

     EINTR A signal was caught during the execution of the link()
           function.

     ELOOP Too many symbolic links were encountered in  translat-
           ing path.

     EMLINK
           The maximum  number  of  links  to  a  file  would  be
           exceeded.

     ENAMETOOLONG
           The length of the existing  or  new  argument  exceeds
           PATH_MAX, or the length of a existing or new component
           exceeds NAME_MAX while _POSIX_NO_TRUNC is in effect.

     ENOENT
           The existing or new argument is  a  null  pathname;  a
           component of either path prefix does not exist; or the
           file named by existing does not exist.

     ENOLINK
           The existing  or  new  argument  points  to  a  remote
           machine  and  the  link  to  that machine is no longer
           active.

     ENOSPC
           The directory that would contain the  link  cannot  be
           extended.

     ENOTDIR
           A component of either path prefix is not a directory.

     EPERM The file named by existing  is  a  directory  and  the
           effective  user  of  the calling process is not super-
           user.

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

     EXDEV The link named by new and the file named  by  existing
           are on different logical devices (file systems).

USAGE

     When a UFS file system is mounted with logging enabled, file
     system  transactions  that  free blocks from files might not
     actually add those freed blocks to the  file  system's  free
     list  until  some  unspecified  time  in  the  future.  This
     behavior improves file system performance but does not  con-
     form  to the POSIX, Single UNIX Specification, SPARC Confor-
     mance Definition, System  V  Application  Binary  Interface,
     System  V Interface Definition, and X/Open Portability Guide
     Standards, which  require  that  freed  space  be  available
     immediately.  To enable standards conformance regarding file
     deletions or to address the problem of  not  being  able  to
     grow  files  on a relatively full UFS file system even after
     files  have  been  deleted,   disable   UFS   logging   (see
     mount_ufs(1M).

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|

SEE ALSO

     mount_ufs(1M), symlink(2), unlink(2), attributes(5)