symlink or symlinkat Subroutine
Purpose
Makes a symbolic link to a file.
Library
Standard C Library (libc.a)
Syntax
int symlink ( Path1, Path2)
const char *Path1;
const char *Path2;
int symlinkat ( Path1, DirFileDescriptor, Path2)
const char * Path1;
int DirFileDescriptor;
const char * Path2;
Description
The symlink and symlinkat subroutines create a symbolic link with the file named by the Path2 parameter, which refers to the file named by the Path1 parameter.
As with a hard link (described in the link subroutine), a symbolic link allows a file to have multiple names. The presence of a hard link guarantees the existence of a file, even after the original name has been removed. A symbolic link provides no such assurance. In fact, the file named by the Path1 parameter need not exist when the link is created. In addition, a symbolic link can cross file system boundaries.
When a component of a path name refers to a symbolic link rather than a directory, the path name contained in the symbolic link is resolved. If the path name in the symbolic link starts with a / (slash), it is resolved relative to the root directory of the process. If the path name in the symbolic link does not start with / (slash), it is resolved relative to the directory that contains the symbolic link.
If the symbolic link is not the last component of the original path name, remaining components of the original path name are resolved from the symbolic-link point.
If the last component of the path name supplied to a subroutine refers to a symbolic link, the symbolic link path name may or may not be traversed. Most subroutines always traverse the link; for example, the chmod, chown, link, and open subroutines. The statx subroutine takes an argument that determines whether the link is to be traversed.
The following subroutines refer only to the symbolic link itself, rather than to the object to which the link refers:
| Item | Description |
|---|---|
| mkdir | Fails with the EEXIST error code if the target is a symbolic link. |
| mknod | Fails with the EEXIST error code if a symbolic link exists with the same name as the target file as specified by the Path parameter in the mknod and mkfifo subroutines. |
| open | Fails with EEXIST error code when the O_CREAT and O_EXCL flags are specified and a symbolic link exists for the path name specified. |
| readlink (readlink or readlinkat Subroutine) | Applies only to symbolic links. |
| rename (rename or renameat Subroutine) | Renames the symbolic link if the file to be renamed (the FromPath parameter for the rename subroutine) is a symbolic link. If the new name (the ToPath parameter for the rename subroutine) refers to an existing symbolic link, the symbolic link is destroyed. |
| rmdir (rmdir Subroutine) | Fails with the ENOTDIR error code if the target is a symbolic link. |
| symlink | Running this subroutine causes an error if a symbolic link named by the Path2 parameter already exists. A symbolic link can be created that refers to another symbolic link; that is, the Path1 parameter can refer to a symbolic link. |
| unlink (unlink or unlinkat Subroutine) | Removes the symbolic link. |
Since the mode of a symbolic link cannot be changed, its mode is ignored during the lookup process. Any files and directories referenced by a symbolic link are checked for access normally.
The symlinkat subroutine is equivalent to the symlink subroutine if the DirFileDescriptor parameter is set to AT_FDCWD or if the Path2 parameter is an absolute path name. If the DirFileDescriptor parameter is a valid file descriptor of an open directory and the Path2 parameter is a relative path name, the Path2 parameter is considered as the relative path to the directory that is associated with the DirFileDescriptor parameter instead of the current working directory.
If the DirFileDescriptor parameter is opened without the O_SEARCH open flag, the subroutine checks whether directory searches are permitted for that directory using the current permissions of the directory. If the directory is opened with the O_SEARCH open flag, the subroutine does not perform the check for that directory.
Parameters
| Item | Description |
|---|---|
| Path1 | Specifies the contents of the Path2 symbolic link. This value is a null-terminated string representing the object to which the symbolic link will point. Path1 cannot be the null value and cannot be more than PATH_MAX characters long. PATH_MAX is defined in the limits.h file. |
| DirFileDescriptor | Specifies the file descriptor of an open directory. |
| Path2 | Names the symbolic link to be created. If DirFileDescriptor is specified and Path2 is a relative path name, then Path2 is considered relative to the directory specified by DirFileDescriptor. |
Return Values
Upon successful completion, the symlink and symlinkat subroutines return a value of 0. If the symlink or the symlinkat subroutine fails, a value of -1 is returned and the errno global variable is set to indicate the error.
Error Codes
The symlink and symlinkat subroutines fail if one or more of the following are true:
| Item | Description |
|---|---|
| EEXIST | Path2 already exists. |
| EACCES | The requested operation requires writing in a directory with a mode that denies write permission. |
| EROFS | The requested operation requires writing in a directory on a read-only file system. |
| ENOSPC | The directory in which the entry for the symbolic link is being placed cannot be extended because there is no space left on the file system containing the directory. |
| EDQUOT | The directory in which the entry for the new symbolic link is being placed cannot be extended or disk blocks could not be allocated for the symbolic link because the user's or group's quota of disk blocks on the file system containing the directory has been exhausted. |
The symlinkat subroutine is unsuccessful if one or more of the following settings are true:
| Item | Description |
|---|---|
| EBADF | The Path2 parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a valid file descriptor. |
| ENOTDIR | The Path2 parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a file descriptor associated with a directory. |
The symlink and symlinkat subroutines can be unsuccessful for other reasons.