symlink(2) symlink(2)
NAME
symlink - make a symbolic link to a file
SYNOPSIS
#include <unistd.h>
int symlink(const char *name1, const char *name2);
DESCRIPTION
symlink() creates a symbolic link name2 to the file name1. Either name
may be an arbitrary pathname, the files need not be on the same file
system, and name1 may be nonexistent.
The file to which the symbolic link points is used when an open(2)
operation is performed on the link. A stat(2) on a symbolic link
returns the linked-to file, while an lstat(2) returns information
about the link itself. This can lead to surprising results when a sym-
bolic link is made to a directory. To avoid confusion in programs, the
readlink(2) call can be used to read the contents of a symbolic link.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
The symbolic link is made unless one or more of the following apply:
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 name2.
EDQUOT The directory in which the entry for the new symbolic
link is being placed cannot be extended because the
user's quota of disk blocks on the file system contain-
ing the directory has been exhausted.
EDQUOT The new symbolic link cannot be created because the
user's quota of disk blocks on the file system which
will contain the link has been exhausted.
EDQUOT The user's quota of inodes on the file system on which
the file is being created has been exhausted.
EEXIST The file referred to by name2 already exists.
EFAULT name1 or name2 points outside the allocated address
space for the process.
EIO An I/O error occurs while reading from or writing to the
file system.
ELOOP Too many symbolic links are encountered in translating
name2.
Page 1 Reliant UNIX 5.44 Printed 11/98
symlink(2) symlink(2)
ENAMETOOLONG The length of the name1 or name2 argument exceeds
PATHMAX, or the length of a name1 or name2 component
exceeds NAMEMAX.
ENOENT A component of the path prefix of name2 does not exist.
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.
ENOSPC The new symbolic link cannot be created because no space
is left on the file system which will contain the link.
ENOSPC There are no free inodes on the file system on which the
file is being created.
ENOSYS The file system does not support symbolic links.
ENOTDIR A component of the path prefix of name2 is not a direc-
tory.
EROFS The file name2 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 PATHMAX.
RESULT
Upon successful completion symlink() returns a value of 0; otherwise,
it returns -1 and places an error code in errno.
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 name1 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.
SEE ALSO
cp(1), lchown(2), link(2), lstat(2), open(2), readlink(2), unlink(2),
unistd(4).
Page 2 Reliant UNIX 5.44 Printed 11/98