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
              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 ALSO
       lchown() , 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 .