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



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       symlink, symlinkat -- make a symbolic link relative to directory file
       descriptor

SSYYNNOOPPSSIISS
       #include <unistd.h>

       int symlink(const char *_p_a_t_h_1, const char *_p_a_t_h_2);
       int symlinkat(const char *_p_a_t_h_1, int _f_d, const char *_p_a_t_h_2);

DDEESSCCRRIIPPTTIIOONN
       The _s_y_m_l_i_n_k() function shall create a symbolic link called _p_a_t_h_2 that
       contains the string pointed to by _p_a_t_h_1 (_p_a_t_h_2 is the name of the
       symbolic link created, _p_a_t_h_1 is the string contained in the symbolic
       link).

       The string pointed to by _p_a_t_h_1 shall be treated only as a character
       string and shall not be validated as a pathname.

       If the _s_y_m_l_i_n_k() function fails for any reason other than [[EEIIOO]], any
       file named by _p_a_t_h_2 shall be unaffected.

       If _p_a_t_h_2 names a symbolic link, _s_y_m_l_i_n_k() shall fail and set _e_r_r_n_o to
       [[EEEEXXIISSTT]].

       The symbolic link's user ID shall be set to the process' effective user
       ID. The symbolic link's group ID shall be set to the group ID of the
       parent directory or to the effective group ID of the process.
       Implementations shall provide a way to initialize the symbolic link's
       group ID to the group ID of the parent directory. Implementations may,
       but need not, provide an implementation-defined way to initialize the
       symbolic link's group ID to the effective group ID of the calling
       process.

       The values of the file mode bits for the created symbolic link are
       unspecified. All interfaces specified by POSIX.1-2008 shall behave as
       if the contents of symbolic links can always be read, except that the
       value of the file mode bits returned in the _s_t___m_o_d_e field of the ssttaatt
       structure is unspecified.

       Upon successful completion, _s_y_m_l_i_n_k() shall mark for update the last
       data access, last data modification, and last file status change
       timestamps of the symbolic link. Also, the last data modification and
       last file status change timestamps of the directory that contains the
       new entry shall be marked for update.

       The _s_y_m_l_i_n_k_a_t() function shall be equivalent to the _s_y_m_l_i_n_k() function
       except in the case where _p_a_t_h_2 specifies a relative path. In this case
       the symbolic link is created relative to the directory associated with
       the file descriptor _f_d instead of the current working directory. If the
       file descriptor was opened without O_SEARCH, the function shall check
       whether directory searches are permitted using the current permissions
       of the directory underlying the file descriptor. If the file descriptor
       was opened with O_SEARCH, the function shall not perform the check.

       If _s_y_m_l_i_n_k_a_t() is passed the special value AT_FDCWD in the _f_d
       parameter, the current working directory shall be used and the behavior
       shall be identical to a call to _s_y_m_l_i_n_k().

RREETTUURRNN VVAALLUUEE
       Upon successful completion, these functions shall return 0.  Otherwise,
       these functions shall return -1 and set _e_r_r_n_o to indicate the error.

EERRRROORRSS
       These functions shall fail if:

       EEAACCCCEESS 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 _p_a_t_h_2.

       EEEEXXIISSTT The _p_a_t_h_2 argument names an existing file.

       EEIIOO    An I/O error occurs while reading from or writing to the file
              system.

       EELLOOOOPP  A loop exists in symbolic links encountered during resolution of
              the _p_a_t_h_2 argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a component of the pathname specified by the _p_a_t_h_2
              argument is longer than {NAME_MAX} or the length of the _p_a_t_h_1
              argument is longer than {SYMLINK_MAX}.

       EENNOOEENNTT A component of the path prefix of _p_a_t_h_2 does not name an
              existing file or _p_a_t_h_2 is an empty string.

       EENNOOSSPPCC 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.

       EENNOOTTDDIIRR
              A component of the path prefix of _p_a_t_h_2 names an existing file
              that is neither a directory nor a symbolic link to a directory.

       EERROOFFSS  The new symbolic link would reside on a read-only file system.

       The _s_y_m_l_i_n_k_a_t() function shall fail if:

       EEAACCCCEESS _f_d was not opened with O_SEARCH and the permissions of the
              directory underlying _f_d do not permit directory searches.

       EEBBAADDFF  The _p_a_t_h_2 argument does not specify an absolute path and the _f_d
              argument is neither AT_FDCWD nor a valid file descriptor open
              for reading or searching.

       EENNOOTTDDIIRR
              The _p_a_t_h_2 argument is not an absolute path and _f_d is a file
              descriptor associated with a non-directory file.

       These functions may fail if:

       EELLOOOOPP  More than {SYMLOOP_MAX} symbolic links were encountered during
              resolution of the _p_a_t_h_2 argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of the _p_a_t_h_2 argument exceeds {PATH_MAX} or pathname
              resolution of a symbolic link in the _p_a_t_h_2 argument produced an
              intermediate result with a length that exceeds {PATH_MAX}.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       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 _p_a_t_h_1
       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.

RRAATTIIOONNAALLEE
       The purpose of the _s_y_m_l_i_n_k_a_t() function is to create symbolic links in
       directories other than the current working directory without exposure
       to race conditions. Any part of the path of a file could be changed in
       parallel to a call to _s_y_m_l_i_n_k(), resulting in unspecified behavior. By
       opening a file descriptor for the target directory and using the
       _s_y_m_l_i_n_k_a_t() function it can be guaranteed that the created symbolic
       link is located relative to the desired directory.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _f_d_o_p_e_n_d_i_r(), _f_s_t_a_t_a_t(), _l_c_h_o_w_n(), _l_i_n_k(), _o_p_e_n(), _r_e_a_d_l_i_n_k(), _r_e_n_a_m_e(),
       _u_n_l_i_n_k()

       The Base Definitions volume of POSIX.1-2008, <<uunniissttdd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                           SYMLINK(3)
