NAME
symlink — make symbolic link to a file
SYNOPSIS
#include <unistd.h>
int symlink(const char *path1, const char *path2);
DESCRIPTION
The
symlink()
function creates a symbolic link. Its
name is the pathname pointed to by
path2,
which must be a pathname that does not name an existing file or
symbolic link. The contents of the symbolic link
are the string pointed to by
path1.
RETURN VALUE
Upon successful completion,
symlink()
returns 0. Otherwise, it returns -1 and sets
errno
to indicate the error.
ERRORS
The
symlink()
function will fail if:
- [EACCES]
Write permission is denied in the
directory where the symbolic link is
being created, or search permission
is denied for a component 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]
Too many symbolic links were encountered in resolving
path2.
- [ENAMETOOLONG]
The length of the
path2
argument exceeds
{PATH_MAX},
or a pathname component is longer than
{NAME_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 will 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:
- [ENAMETOOLONG]
Pathname resolution of a symbolic link produced an intermediate result
whose length exceeds
{PATH_MAX}.
APPLICATION USAGE
Like a hard link, a symbolic link allows a file to
have multiple logical 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
argument 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.
CHANGE HISTORY
First released in Issue 4, Version 2.
ERRORS
If
symlink()
fails,
errno
is set to one of the following values.
- [EFAULT]
path1
or
path2
points outside the process's allocated address space.
The reliable detection of this error is implementation-dependent.
- [EIO]
An I/O error occurred while making the directory entry for
path2,
allocating the inode for
path2,
or writing out the link contents of
path2.
- [EIO]
An I/O error occurred while making the directory entry or allocating the inode.
AUTHOR
symlink()
was developed by the University of California, Berkeley.
STANDARDS CONFORMANCE
symlink(): AES, SVID3
