READLINK(3)                POSIX Programmer's Manual               READLINK(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
       readlink, readlinkat -- read the contents of a symbolic link

SSYYNNOOPPSSIISS
       #include <unistd.h>

       ssize_t readlink(const char *restrict _p_a_t_h, char *restrict _b_u_f,
           size_t _b_u_f_s_i_z_e);

       #include <fcntl.h>

       ssize_t readlinkat(int _f_d, const char *restrict _p_a_t_h,
           char *restrict _b_u_f, size_t _b_u_f_s_i_z_e);

DDEESSCCRRIIPPTTIIOONN
       The _r_e_a_d_l_i_n_k() function shall place the contents of the symbolic link
       referred to by _p_a_t_h in the buffer _b_u_f which has size _b_u_f_s_i_z_e.  If the
       number of bytes in the symbolic link is less than _b_u_f_s_i_z_e, the contents
       of the remainder of _b_u_f are unspecified. If the _b_u_f argument is not
       large enough to contain the link content, the first _b_u_f_s_i_z_e bytes shall
       be placed in _b_u_f.

       If the value of _b_u_f_s_i_z_e is greater than {SSIZE_MAX}, the result is
       implementation-defined.

       Upon successful completion, _r_e_a_d_l_i_n_k() shall mark for update the last
       data access timestamp of the symbolic link.

       The _r_e_a_d_l_i_n_k_a_t() function shall be equivalent to the _r_e_a_d_l_i_n_k()
       function except in the case where _p_a_t_h specifies a relative path. In
       this case the symbolic link whose content is read is relative to the
       directory associated with the file descriptor _f_d instead of the current
       working directory. If the access mode of the open file description
       associated with the file descriptor is not O_SEARCH, the function shall
       check whether directory searches are permitted using the current
       permissions of the directory underlying the file descriptor. If the
       access mode is O_SEARCH, the function shall not perform the check.

       If _r_e_a_d_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 _r_e_a_d_l_i_n_k().

RREETTUURRNN VVAALLUUEE
       Upon successful completion, these functions shall return the count of
       bytes placed in the buffer. Otherwise, these functions shall return a
       value of -1, leave the buffer unchanged, and set _e_r_r_n_o to indicate the
       error.

EERRRROORRSS
       These functions shall fail if:

       EEAACCCCEESS Search permission is denied for a component of the path prefix
              of _p_a_t_h.

       EEIINNVVAALL The _p_a_t_h argument names a file that is not a symbolic link.

       EEIIOO    An I/O error occurred while reading from the file system.

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

       EENNAAMMEETTOOOOLLOONNGG
              The length of a component of a pathname is longer than
              {NAME_MAX}.

       EENNOOEENNTT A component of _p_a_t_h does not name an existing file or _p_a_t_h is an
              empty string.

       EENNOOTTDDIIRR
              A component of the path prefix names an existing file that is
              neither a directory nor a symbolic link to a directory, or the
              _p_a_t_h argument contains at least one non-<slash> character and
              ends with one or more trailing <slash> characters and the last
              pathname component names an existing file that is neither a
              directory nor a symbolic link to a directory.

       The _r_e_a_d_l_i_n_k_a_t() function shall fail if:

       EEAACCCCEESS The access mode of the open file description associated with _f_d
              is not O_SEARCH and the permissions of the directory underlying
              _f_d do not permit directory searches.

       EEBBAADDFF  The _p_a_t_h 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 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 argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a pathname exceeds {PATH_MAX}, or pathname
              resolution of a symbolic link 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
   RReeaaddiinngg tthhee NNaammee ooff aa SSyymmbboolliicc LLiinnkk
       The following example shows how to read the name of a symbolic link
       named //mmoodduulleess//ppaassss11.


           #include <unistd.h>

           char buf[1024];
           ssize_t len;
           ...
           if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1)
               buf[len] = '\0';

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Conforming applications should not assume that the returned contents of
       the symbolic link are null-terminated.

RRAATTIIOONNAALLEE
       The type associated with _b_u_f_s_i_z is a ssiizzee__tt in order to be consistent
       with both the ISO C standard and the definition of _r_e_a_d().  The
       behavior specified for _r_e_a_d_l_i_n_k() when _b_u_f_s_i_z is zero represents
       historical practice. For this case, the standard developers considered
       a change whereby _r_e_a_d_l_i_n_k() would return the number of non-null bytes
       contained in the symbolic link with the buffer _b_u_f remaining unchanged;
       however, since the ssttaatt structure member _s_t___s_i_z_e value can be used to
       determine the size of buffer necessary to contain the contents of the
       symbolic link as returned by _r_e_a_d_l_i_n_k(), this proposal was rejected,
       and the historical practice retained.

       The purpose of the _r_e_a_d_l_i_n_k_a_t() function is to read the content of
       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 _r_e_a_d_l_i_n_k(), resulting in
       unspecified behavior. By opening a file descriptor for the target
       directory and using the _r_e_a_d_l_i_n_k_a_t() function it can be guaranteed that
       the symbolic link read is located relative to the desired directory.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _f_s_t_a_t_a_t(), _s_y_m_l_i_n_k()

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

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

       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                  2017                          READLINK(3)
