huschi.net

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 (consult 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 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
              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  {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 Defi-
       nitions 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 .

IEEE/The Open Group                  2003                          SYMLINK(3P)