SYMLINK(P) POSIX Programmer's Manual SYMLINK(P)NAMEsymlink - make a symbolic link to a file
SYNOPSIS
#include <unistd.h>
int symlink(const char *path1, const char *path2);
DESCRIPTION
The symlink() function shall create a symbolic link called path2 that
contains the string pointed to by path1 ( path2 is the name of the sym‐
bolic link created, path1 is the string contained in the symbolic
link).
The string pointed to by path1 shall be treated only as a character
string and shall not be validated as a pathname.
If the symlink() function fails for any reason other than [EIO], any
file named by path2 shall be unaffected.
RETURN VALUE
Upon successful completion, symlink() shall return 0; otherwise, it
shall return -1 and set errno to indicate the error.
ERRORS
The symlink() function shall fail if:
EACCES Write permission is denied in the directory where the symbolic
link is being created, or search permission is denied for a com‐
ponent of the path prefix of path2.
EEXIST The path2 argument names an existing file or symbolic link.
EIO An I/O error occurs while reading from or writing to the file
system.
ELOOP A loop exists in symbolic links encountered during resolution of
the path2 argument.
ENAMETOOLONG
The length of the path2 argument exceeds {PATH_MAX} or a path‐
name component is longer than {NAME_MAX} or the length of the
path1 argument is longer than {SYMLINK_MAX}.
ENOENT A component of path2 does not name an existing file or path2 is
an empty string.
ENOSPC The directory in which the entry for the new symbolic link is
being placed cannot be extended because no space is left on the
file system containing the directory, or the new symbolic link
cannot be created because no space is left on the file system
which shall contain the link, or the file system is out of file-
allocation resources.
ENOTDIR
A component of the path prefix of path2 is not a directory.
EROFS The new symbolic link would reside on a read-only file system.
The symlink() function may fail if:
ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the path2 argument.
ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the
path2 argument, the length of the substituted pathname string
exceeded {PATH_MAX} bytes (including the terminating null byte),
or the length of the string pointed to by path1 exceeded {SYM‐
LINK_MAX}.
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
Like a hard link, a symbolic link allows a file to have multiple logi‐
cal 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 argu‐
ment need not exist when the link is created. A symbolic link can cross
file system boundaries.
Normal permission checks are made on each component of the symbolic
link pathname during its resolution.
RATIONALE
Since IEEE Std 1003.1-2001 does not require any association of file
times with symbolic links, there is no requirement that file times be
updated by symlink().
FUTURE DIRECTIONS
None.
SEE ALSOlchown() , link() , lstat() , open() , readlink() , unlink() , the Base
Definitions volume of IEEE Std 1003.1-2001, <unistd.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online
at http://www.opengroup.org/unix/online.html .
IEEE/The Open Group 2003 SYMLINK(P)
