link and linkat Subroutine
Purpose
Creates an additional directory entry for an existing file.
Library
Standard C Library (libc.a)
Syntax
#include <unistd.h>int link ( Path1, Path2)
const char *Path1, *Path2;
int linkat ( DirFileDescriptor1,Path1,DirFileDescriptor2,Path2,Flag)
int DirFileDescriptor1, DirFileDescriptor2;
const char *Path1, *Path2;
int Flag;Description
The link and linkat subroutines create an additional hard link (directory entry) for an existing file. Both the old and the new links share equal access rights to the underlying object.
The linkat subroutine is equivalent to the link subroutine if the Flag parameter has the AT_SYMLINK_FOLLOW bit set and if both the DirFileDescriptor1 and DirFileDescriptor2 parameters are AT_FDCWD or both the Path1 and Path2 parameters are absolute path names. If DirFileDescriptor1 is a valid file descriptor of an open directory and Path1 is a relative path name, Path1 is considered to be relative to the directory that is associated with the DirFileDescriptor1 parameter instead of the current working directory. The same applies to the DirFileDescriptor2 and Path2 parameters.
If either directory in the linkat subroutine was opened without the O_SEARCH open flag, the subroutine checks to determine whether directory searches are permitted for that directory by using the current permissions of the directory. If either directory was opened with the O_SEARCH open flag, the subroutine does not perform the check for that directory.
If the Flag parameter of the linkat subroutine does not have the AT_SYMLINK_FOLLOW bit set and the Path1 parameter specifies a symbolic link, the subroutine creates a link to the symbolic link, not its target.
Parameters
| Item | Description |
|---|---|
| Path1 | Points to the path name of an existing file. If DirFileDescriptor1 is specified and Path1 is a relative path name, then Path1 is considered relative to the directory specified by DirFileDescriptor1. |
| Path2 | Points to the path name of the directory entry to be created. If DirFileDescriptor2 is specified and Path2 is a relative path name, then Path2 is considered relative to the directory specified by DirFileDescriptor2. |
| DirFileDescriptor1 | Specifies the file descriptor of an open directory. |
| DirFileDescriptor2 | Specifies the file descriptor of an open directory. |
| Flag | Specifies a bit field. If it contains the AT_SYMLINK_FOLLOW bit and Path1 points to a symbolic link, then the link is created to the file the symbolic link points at, else the link is created to the symbolic link. |
- If Network File System (NFS) is installed on your system, these paths can cross into another node.
- With hard links, both the Path1 and Path2 parameters must reside on the same file system. Creating links to directories requires root user authority.
Return Values
Upon successful completion, the link and linkat subroutines return a value of 0. Otherwise, a value of -1 is returned, and the errno global variable is set to indicate the error.
Error Codes
The link and linkat subroutines are unsuccessful if one of the following is true:
| Item | Description |
|---|---|
| EACCES | Indicates the requested link requires writing in a directory that denies write permission. |
| EDQUOT | Indicates the directory in which the entry for the new link is being placed cannot be extended, or disk blocks could not be allocated for the link because the user or group quota of disk blocks or i-nodes on the file system containing the directory has been exhausted. |
| EEXIST | Indicates the link named by the Path2 parameter already exists. |
| EMLINK | Indicates the file already has the maximum number of links. |
| ENOENT | Indicates the file named by the Path1 parameter does not exist. |
| ENOSPC | Indicates 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. |
| EPERM | Indicates the file named by the Path1 parameter is a directory, and the calling process does not have root user authority. |
| EROFS | Indicates the requested link requires writing in a directory on a read-only file system. |
| EXDEV | Indicates the link named by the Path2 parameter and the file named by the Path1 parameter are on different file systems, or the file named by Path1 refers to a named STREAM. |
The linkat subroutine is unsuccessful if one or more of the following is true:
| Item | Description |
|---|---|
| EBADF | The Path1 or Path2 parameter does not specify an absolute path and the corresponding DirFileDescriptor1 or DirFileDescriptor2 parameter is neither AT_FDCWD nor a valid file descriptor. |
| ENOTDIR | The Path1 or Path2 parameter does not specify an absolute path and the corresponding DirFileDescriptor1 or DirFileDescriptor2 parameter is neither AT_FDCWD nor a file descriptor associated with a directory. |
| EINVAL | The value of the Flag parameter is not valid. |
The link and linkat subroutines can be unsuccessful for other reasons.
If NFS is installed on the system, the link and linkat subroutines are unsuccessful if the following is true:
| Item | Description |
|---|---|
| ETIMEDOUT | Indicates the connection timed out. |