# readlink

## 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



           readlink, readlinkat — read the contents of a symbolic link
    


## SYNOPSIS



           #include <unistd.h>
    
           ssize_t readlink(const char *restrict _path_ , char *restrict _buf_ ,
               size_t _bufsize_);
    
           #include <fcntl.h>
    
           ssize_t readlinkat(int _fd_ , const char *restrict _path_ ,
               char *restrict _buf_ , size_t _bufsize_);
    


## DESCRIPTION



           The _readlink_() function shall place the contents of the symbolic
           link referred to by _path_ in the buffer _buf_ which has size _bufsize_.
           If the number of bytes in the symbolic link is less than _bufsize_ ,
           the contents of the remainder of _buf_ are unspecified. If the _buf_
           argument is not large enough to contain the link content, the
           first _bufsize_ bytes shall be placed in _buf_.
    
           If the value of _bufsize_ is greater than {SSIZE_MAX}, the result is
           implementation-defined.
    
           Upon successful completion, _readlink_() shall mark for update the
           last data access timestamp of the symbolic link.
    
           The _readlinkat_() function shall be equivalent to the _readlink_()
           function except in the case where _path_ specifies a relative path.
           In this case the symbolic link whose content is read is relative
           to the directory associated with the file descriptor _fd_ 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 _readlinkat_() is passed the special value AT_FDCWD in the _fd_
           parameter, the current working directory shall be used and the
           behavior shall be identical to a call to _readlink_().
    


## RETURN VALUE



           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 _errno_ to
           indicate the error.
    


## ERRORS



           These functions shall fail if:
    
           **EACCES** Search permission is denied for a component of the path
                  prefix of _path_.
    
           **EINVAL** The _path_ argument names a file that is not a symbolic link.
    
           **EIO** An I/O error occurred while reading from the file system.
    
           **ELOOP** A loop exists in symbolic links encountered during
                  resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a component of a pathname is longer than
                  {NAME_MAX}.
    
           **ENOENT** A component of _path_ does not name an existing file or _path_
                  is an empty string.
    
           **ENOTDIR**
                  A component of the path prefix names an existing file that
                  is neither a directory nor a symbolic link to a directory,
                  or the _path_ 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 _readlinkat_() function shall fail if:
    
           **EACCES** The access mode of the open file description associated
                  with _fd_ is not O_SEARCH and the permissions of the
                  directory underlying _fd_ do not permit directory searches.
    
           **EBADF** The _path_ argument does not specify an absolute path and the
                  _fd_ argument is neither AT_FDCWD nor a valid file descriptor
                  open for reading or searching.
    
           **ENOTDIR**
                  The _path_ argument is not an absolute path and _fd_ is a file
                  descriptor associated with a non-directory file.
    
           These functions may fail if:
    
           **ELOOP** More than {SYMLOOP_MAX} symbolic links were encountered
                  during resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  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}.
    
           _The following sections are informative._
    


## EXAMPLES



       **Reading the Name of a Symbolic Link**
           The following example shows how to read the name of a symbolic
           link named **/modules/pass1**.
    
               #include <unistd.h>
    
               char buf[1024];
               ssize_t len;
               ...
               if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1)
                   buf[len] = '\0';
    


## APPLICATION USAGE



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


## RATIONALE



           The type associated with _bufsiz_ is a **size_t** in order to be
           consistent with both the ISO C standard and the definition of
           _read_().  The behavior specified for _readlink_() when _bufsiz_ is zero
           represents historical practice. For this case, the standard
           developers considered a change whereby _readlink_() would return the
           number of non-null bytes contained in the symbolic link with the
           buffer _buf_ remaining unchanged; however, since the **stat** structure
           member _st_size_ value can be used to determine the size of buffer
           necessary to contain the contents of the symbolic link as returned
           by _readlink_(), this proposal was rejected, and the historical
           practice retained.
    
           The purpose of the _readlinkat_() 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
           _readlink_(), resulting in unspecified behavior. By opening a file
           descriptor for the target directory and using the _readlinkat_()
           function it can be guaranteed that the symbolic link read is
           located relative to the desired directory.
    


## FUTURE DIRECTIONS



           None.
    


* * *