symlink(2)                                                          symlink(2)


NAME
     symlink - make a symbolic link to a file

C 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 returns information about the link
     itself.  This can lead to surprising results when a symbolic 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.

     If the file named by name2 does not exist, it is created.  The permission
     mode of name2 is 777, subject to the restrictions of the  process's file
     mode creation mask.  [see umask(1), umask(2) and creat(2).]

     Control checks depend on the security level of the referenced file when
     following a symbolic link, while the level of the symbolic link is
     ignored.

     The symbolic link is made unless one or more of the following are true:

     EACCES              Search permission is denied for a component of the
                         path prefix of name2.

     EACCES              Write access is denied on the directory in which the
                         new file is to be created.

     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
                         containing 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.

     ENAMETOOLONG        The length of the name1 or name2 argument exceeds
                         {PATH_MAX}, or the length of a name1 or name2
                         component exceeds {NAME_MAX} while (_POSIX_NO_TRUNC)
                         is in effect.

     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
                         directory.

     EROFS               The file name2 would reside on a read-only file
                         system.

DIAGNOSTICS
     Upon successful completion symlink returns a value of 0; otherwise, it
     returns -1 and places an error code in errno.

SEE ALSO
     cp(1), umask(1), creat(2), link(2), readlink(2), umask(2), unlink(2),
     realpath(3C)


                                                                        Page 2