NAME

       symlink - make a symbolic link to a file

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 symbolic 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 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  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 pathname 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
              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:

       ELOOP  More  than  {SYMLOOP_MAX}  symbolic links were encountered during resolution of the
              path2 argument.

       ENAMETOOLONG
              As a result of encountering a symbolic link in resolution of  the  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 {SYMLINK_MAX}.

       The following sections are informative.

EXAMPLES

       None.

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.

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 .