link(S)

link -- link to a file

Synopsis

   #include <unistd.h>
   
   int link(const char path1, const char path2);

Description

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

For security reasons, if the ``sticky bit'' (see chmod(S)) is set on the directory in which the link is being created, either the directory or the object being linked from must be owned by the calling user ID.

Return values

On success, link returns 0 and 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. On failure, link returns -1, sets errno to identify the error, and no link is created.

In the following conditions, link fails and sets errno to:

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: The file pointed to by path1 has discrete privileges and write permission is denied.
EEXIST: The link named by path2 exists.
EFAULT: path 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 path.
EMLINK: The maximum number of links to a file would be exceeded.
EMULTIHOP: Components of path require hopping to multiple remote machines and file system type does not allow it.
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 pathname.
ENOENT: A component of either path prefix does not exist.
ENOENT: The file named by path1 does not exist.
ENOLINK: path 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; hard links may not refer to directories.
EPERM: The ``sticky bit'' (see chmod(S)) is set on the directory in which the link is being created, and neither that directory nor the object named in path1 is owned by the calling user ID. The P_OWNER privilege is required to override this restriction.
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).

References

realpath(S), symlink(S), unlink(S)