System Calls link(2)
NAME
link, linkat - link to a file
SYNOPSIS
#include
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. 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 thest_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 descriptorwas opened without O_SEARCH, the function checks whether
directory searches are permitted using the current permis-
sions of the directory underlying the file descriptor. Ifthe file descriptor was opened with O_SEARCH, the function
does not perform the check.SunOS 5.11 Last change: 6 Jul 2010 1
System Calls link(2)Values for flag are constructed by a bitwise-inclusive OR of
flags from the following list, defined in. 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 valueAT_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 charac-
ters and the file system accepts only file names where all characters are part of theUTF-8 character codeset.
SunOS 5.11 Last change: 6 Jul 2010 2
System Calls link(2) 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 path-
name; 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 andthe {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 adirectory on a read-only file system.
SunOS 5.11 Last change: 6 Jul 2010 3
System Calls link(2) 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 anabsolute path and the fd1 or fd2 argument, respec-
tively, 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 alength that exceeds {PATH_MAX}.
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 neitherAT_FDCWD nor a file descriptor associated with a
directory.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 6 Jul 2010 4
System Calls link(2)____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Async-Signal-Safe |
|_____________________________|_____________________________|
| Standard | See standards(5). ||_____________________________|_____________________________|
SEE ALSO
symlink(2), unlink(2), attributes(5), privileges(5), stan-
dards(5)SunOS 5.11 Last change: 6 Jul 2010 5