link

, linkat

Synopsis

Description

The link() function creates a new link (directory entry) for the existing
file and increments its link count by one. The path1 argument
points to a path name naming an existing file. The path2
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. Privileged processes can make multiple links to
a directory. Unless the caller is privileged, the file named by path1
must not be a directory.

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.

If link() fails, no link is created and the link count of
the file remains unchanged.

The linkat() function is equivalent to link() except in the case where
either path1 or path2 or both are relative paths. In this case
a relative path path1 is interpreted relative to the directory associated with the
file descriptor fd1 instead of the current working directory and similarly for
path2 and the file descriptor fd2. If the file descriptor was opened
without O_SEARCH, the function checks whether directory searches are permitted using the current
permissions of the directory underlying the file descriptor. If the file descriptor
was opened with O_SEARCH, the function does not perform the check.

Values for flag are constructed by a bitwise-inclusive OR of flags from
the following list, defined in <fcntl.h>.

AT_SYMLINK_FOLLOW

If path1 names a symbolic link, a new link for the target of the symbolic link is created.

If linkat() is passed the special value AT_FDCWD in the fd1 or
fd2 parameter, the current working directory is used for the respective path
argument. If both fd1 and fd2 have value AT_FDCWD, the behavior is identical
to a call to link().

If the AT_SYMLINK_FOLLOW flag is clear in the flag argument and the
path1 argument names a symbolic link, a new link is created for
the symbolic link path1 and not its target.

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() and linkat() functions will fail if:

EACCES

A component of either path prefix denies search permission, 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 path2 exists.

EFAULT

The path1 or path2 argument points to an illegal address.

EILSEQ

The path argument includes non-UTF8 characters and the file system accepts only file names where all characters are part of the UTF-8 character codeset.

EINTR

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

ELOOP

Too many symbolic links were encountered in translating path.

EMLINK

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

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.

ENOENT

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

ENOLINK

The path1 or path2 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 path1 is a directory and the {PRIV_SYS_LINKDIR} privilege is not asserted in the effective set of the calling process.

The effective user ID does not match the owner of the file and the {PRIV_FILE_LINK_ANY} privilege is not asserted in the effective set of the calling process.

EROFS

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