symlink(2)symlink(2)NAMEsymlink - Make a symbolic link to a file
SYNOPSIS
#include <unistd.h>
int symlink(
const char *path1,
const char *path2 );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
symlink(): XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the contents of the symbolic link to create. Names the sym‐
bolic link to be created.
DESCRIPTION
The symlink() function creates a symbolic link with the name specified
by the path2 parameter which refers to the file named by the path1
parameter.
Like a hard link, which is described in link(2), 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. Unlike
hard links, a symbolic link can cross file system boundaries.
When a component of a pathname refers to a symbolic link rather than a
directory, the pathname contained in the symbolic link is resolved. If
the pathname in the symbolic link starts with a / (slash), the symbolic
link pathname is resolved relative to the process root directory. If
the pathname in the symbolic link does not start with a / (slash), the
symbolic link pathname is resolved relative to the directory that con‐
tains the symbolic link.
If the symbolic link is the last component of the original pathname,
remaining components of the original pathname are appended to the con‐
tents of the link and pathname resolution continues.
The symbolic link pathname may or may not be traversed, depending on
which function is being performed. Most functions traverse the link.
The functions which refer only to the symbolic link itself, rather than
to the object to which the link refers, are: An error is returned if a
symbolic link is named by the path2 parameter. If the file specified
is a symbolic link, the status of the link itself is returned. An
error is returned if a symbolic link is named as the path parameter.
This call applies only to symbolic links. A symbolic link can be
removed by invoking the remove() function. If the file to be renamed
is a symbolic link, the symbolic link is renamed. If the new name
refers to an existing symbolic link, the symbolic link is destroyed.
An error is returned if a symbolic link is named as the path parameter.
An error is returned if the 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. A symbolic link can be removed by invoking unlink().
Search access to the symbolic link is required to traverse the pathname
contained therein. Normal permission checks are made on each component
of the symbolic link pathname during its resolution.
[Tru64 UNIX] A Context Dependent Symbolic Link (CDSL) is a symbolic
link that has a variable in the pathname. The variable is resolved dif‐
ferently for each member system in a cluster. If the system is not a
member of a cluster, the variable is resolved as if it were member0 of
a cluster. See hier(5) for more information about CDSLs and the
cdslinvchk(8) reference page for information about checking the CDSL
file inventory.
RETURN VALUES
Upon successful completion, the symlink() function returns a value of 0
(zero). If the symlink() function fails, a value of -1 is returned and
errno is set to indicate the error.
ERRORS
If the symlink() function fails, errno may be set to one of the follow‐
ing values: The requested operation requires writing in a directory
with a mode that denies write permission, or search permission is
denied on a component of path2. [Tru64 UNIX] The directory in which
the entry for the symbolic link is being placed cannot be extended
because the user's quota of disk blocks on the file system containing
the directory has been exhausted. The path specified by the path2
parameter already exists. Too many symbolic links are found in trans‐
lating path2. The length of the path1 parameter or path2 parameter
exceeds PATH_MAX, or a pathname component of path2 is longer than
NAME_MAX while _POSIX_NO_TRUNC is in effect.
Pathname resolution of a symbolic link produced an intermediate
result whose length exceeds PATH_MAX. The path2 parameter
points to a null pathname, or a component of path2 does not
exist. 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.
The new symbolic link cannot be created because there is no
space left on the file system which would contain the link.
There are no free inodes on the file system on which the file is
being created. [Tru64 UNIX] The operation is not applicable
for this file system type. A component of path2 is not a direc‐
tory. The requested operation requires writing in a directory
on a read-only file system.
[Tru64 UNIX] For NFS file access, if the symlink() function fails,
errno may also be set to one of the following values: Indicates either
that the system file table is full, or that there are too many files
currently open in the system. Indicates a stale NFS file handle. An
opened file was deleted by the server or another client; a client can‐
not open a file because the server has unmounted or unexported the
remote directory; or the directory that contains an opened file was
either unmounted or unexported by the server.
SEE ALSO
Commands: ln(1), cdslinvchk(8)
Functions: link(2), readlink(2), unlink(2)
Others: hier(5), standards(5)symlink(2)