link()

NAME

link() - make a hard file link

SYNOPSIS

#include <unistd.h>

int link (const char *oldname, const char *newname)

DESCRIPTION

The link(2) function call atomically creates the specified directory entry (hard link) newname with the attributes of the underlying object pointed at by oldname If the link is successful: the link count of the underlying object is incremented; oldname and newname share equal access and rights to the underlying object.

If oldname is removed, the file newname is not deleted and the link count of the underlying object is decremented.

Oldname must exist for the hard link to succeed and both oldname and newname must be in the same file system. Oldname may not be a directory; NTFS does not support hard-linking a directory. FAT file systems do not support links at all.

You cannot use link(2) on a FAT file system.

RETURN VALUES

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

ERRORS

The link(2) call will fail and no link will be created if:

[EACCES]
A component of either path prefix denies search permission.
[EACCES]
The requested link requires writing in a directory with a mode that denies write permission.
[EEXIST]
The link named by newname does exist.
[EFAULT]
One of the pathnames specified is outside the process's allocated address space.
[EINVAL]
Either pathname contains a character with the high-order bit set, or the file resides on a device that does not support the link(2) operation.
[EIO]
An I/O error occurred while reading from or writing to the file system to make the directory entry.
[ELOOP]
Too many symbolic links were encountered in translating one of the pathnames.
[ENAMETOOLONG]
A component of either pathname exceeded {NAME_MAX} characters, or entire length of either pathname exceeded {PATH_MAX} characters.
[ENOENT]
A component of either path prefix does not exist.
[ENOENT]
The file named by oldname does not exist.
[ENOSPC]
The directory in which the entry for the new link is being placed cannot be extended because there is no space left on the file system containing the directory.
[ENOTDIR]
A component of either path prefix is not a directory.
[EPERM]
The file named by oldname is a directory.
[EROFS]
The requested link requires writing in a directory on a read-only file system.
[EXDEV]
The link named by newname and the file named by oldname are on different file systems.

SEE ALSO

remove(3)

unlink(2)