symlink(2)

NAME

     symlink - make a symbolic link to a file

SYNOPSIS

     #include <unistd.h>

     int symlink(const char *name1, const char *name2);

DESCRIPTION

     The symlink() function 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() opera-
     tion performed on a  symbolic  link  returns  the  linked-to
     file,  while  an lstat() operation returns information about
     the link itself.  See stat(2). Unexpected results may  occur
     when a symbolic link is made to a directory. To avoid confu-
     sion in applications, the readlink(2) call can  be  used  to
     read the contents of a symbolic link.

RETURN VALUES

     Upon successful completion, 0 is returned.  Otherwise, -1 is
     returned,  errno  is set to indicate the error, and the sym-
     bolic link is not made.

ERRORS

     The symlink() function will fail if:

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

     EDQUOT
           The directory where the entry  for  the  new  symbolic
           link  is  being  placed cannot be extended because the
           user's quota of disk blocks on that  file  system  has
           been  exhausted;  the  new  symbolic  link  cannot  be
           created because the user's quota  of  disk  blocks  on
           that  file  system  has  been exhausted; or the user's
           quota of inodes on the file system where the  file  is
           being created has been exhausted.

     EEXIST
           The file referred to by name2 already exists.

     EFAULT
           The name1 or  name2  argument  points  to  an  illegal
           address.

     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 name2 argument exceeds PATH_MAX,  or
           the length of a 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 direc-
           tory;  the new symbolic link cannot be created because
           no space is left on the file system which will contain
           the link; or there are no free inodes on the file sys-
           tem 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  sys-
           tem.

USAGE

     When a UFS file system is mounted with logging enabled, file
     system  transactions  that  free blocks from files might not
     actually add those freed blocks to the  file  system's  free
     list  until  some  unspecified  time  in  the  future.  This
     behavior improves file system performance but does not  con-
     form  to the POSIX, Single UNIX Specification, SPARC Confor-
     mance Definition, System  V  Application  Binary  Interface,
     System  V Interface Definition, and X/Open Portability Guide
     Standards, which  require  that  freed  space  be  available
     immediately.  To enable standards conformance regarding file
     deletions or to address the problem of  not  being  able  to
     grow  files  on a relatively full UFS file system even after
     files  have  been  deleted,   disable   UFS   logging   (see
     mount_ufs(1M).

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|

SEE ALSO

     cp(1),   mount_ufs(1M),   link(2),   open(2),   readlink(2),
     stat(2), unlink(2), attributes(5)