link(2)                                                                link(2)


NAME
     link, linkfollow - link to a file

C SYNOPSIS
     #include <unistd.h>

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

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

DESCRIPTION
     path1 points to a path name naming an existing file.  path2 points to a
     path name naming the new directory entry to be created.  link creates a
     new link (directory entry) for the existing file and increments its link
     count by one.

     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.

     linkfollow is identical to link unless path1 refers to a symbolic link.
     If path1 is a symbolic link, link will make a link to the symbolic link;
     linkfollow will make a link to the object that the symbolic link refers
     to, and will fail if the symbolic link does not refer to any object.

     link will fail and no link will be created if one or more of the
     following are true:

     EACCES              Search permission is denied on a component of one of
                         the path prefixes.

     EACCES              Write permission is denied on the directory in which
                         the link is to be created.

     EACCES              Write permission is denied on the file named by
                         path1.

     EEXIST              The link named by path2 exists.

     EFAULT              path1 or path2 points outside the allocated address
                         space of the process.

     EINTR               A signal was caught during the link system call.

     ELOOP               Too many symbolic links were encountered in
                         translating path1 or path2.

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


     EMULTIHOP           Components of path1 or path2 require hopping to
                         multiple remote machines and file system type does
                         not allow it.

     ETIMEDOUT           A component of path1 or path2 is located on a remote
                         file system which is not available [see intro(2)].

     ENAMETOOLONG        The length of the path1 or path2 argument exceeds
                         {PATH_MAX}, or the length of a path1 or path2
                         component exceeds {NAME_MAX} while _POSIX_NO_TRUNC is
                         in effect.

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

     ENOENT              path1 or path2 is a null path name.

     ENOENT              A component of either path prefix does not exist.

     ENOENT              The file named by path1 does not exist.

     ENOLINK             path1 or path2 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.

     EPERM               The file named by path1 is a directory.

     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 different logical devices (file systems).

SEE ALSO
     symlink(2), unlink(2), realpath(3).

DIAGNOSTICS
     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.


                                                                        Page 2