SYMLINK(3P)                                         POSIX Programmer's Manual                                        SYMLINK(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                   SYMLINK(3P)