Go to main content

man pages section 2: System Calls

Exit Print View

Updated: Thursday, June 13, 2019
 
 

linkat(2)

Name

link, linkat - link to a file

Synopsis

#include <unistd.h>

int link(const char *path1, const char *path2);
int linkat(int fd1, const char *path1, int fd2, const char *path2,
     int flag);

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. No process can make a link to a directory, 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; this implementation prohibits links to directories.

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.

The file named by path1 is read-only because of the mwac(7) policy.

EXDEV

The link named by path2 and the file named by path1 are on different logical devices (file systems).

The linkat() function will fail if:

EBADF

The path1 or path2 argument does not specify an absolute path and the fd1 or fd2 argument, respectively, is neither AT_FDCWD nor a valid file descriptor open for reading.

The link() and linkat() functions may fail if:

ELOOP

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

ENAMETOOLONG

The length of a pathname exceeds {PATH_MAX}, or pathname resolution of a symbolic link produced an intermediate result with a length that exceeds {PATH_MAX}.

EXDEV

The link named by path2 and the file named by path1 are on different logical devices (file systems).

The linkat() function may fail if:

EINVAL

The value of the flag argument is not valid.

ENOTDIR

The path1 or path2 argument is not an absolute path and fd1 or fd2, respectively, is neither AT_FDCWD nor a file descriptor associated with a directory.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Async-Signal-Safe
Standard

See Also

symlink(2), unlink(2), mwac(7), attributes(7), privileges(7), standards(7)