READLINK(2) |
System Calls Manual |
READLINK(2) |
NAME
readlink, readlinkat — read value of a symbolic link
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <unistd.h>
ssize_t
readlink(const char * restrict path, char * restrict buf, size_t bufsiz);
ssize_t
readlinkat(int fd, const char * restrict path, char * restrict buf, size_t bufsiz);
DESCRIPTION
readlink() places the contents of the symbolic link
path in the buffer
buf, which has size
bufsiz.
readlink() does not append a
NUL character to
buf.
readlinkat() works the same way as readlink() except if path is relative. In that case, it is looked up from a directory whose file descriptor was passed as fd. Search permission is required on this directory. fd can be set to AT_FDCWD in order to specify the current directory.
RETURN VALUES
The call returns the count of characters placed in the buffer if it succeeds, or a -1 if an error occurs, placing the error code in the global variable errno.
EXAMPLES
A typical use is illustrated in the following piece of code which reads the contents of a symbolic link named
/symbolic/link and stores them as null-terminated string:
#include <limits.h>
#include <unistd.h>
char buf[PATH_MAX];
ssize_t len;
if ((len = readlink("/symbolic/link", buf, sizeof(buf)-1)) == -1)
error handling;
buf[len] = '\0';
ERRORS
readlink() and
readlinkat() will fail if:
-
[EACCES]
-
Search permission is denied for a component of the path prefix.
-
[EFAULT]
-
buf extends outside the process's allocated address space.
-
[EINVAL]
-
The named file is not a symbolic link.
-
[EIO]
-
An I/O error occurred while reading from the file system.
-
[ELOOP]
-
Too many symbolic links were encountered in translating the pathname.
-
[ENAMETOOLONG]
-
A component of a pathname exceeded {NAME_MAX} characters, or an entire path name exceeded {PATH_MAX} characters.
-
[ENOENT]
-
The named file does not exist.
-
[ENOTDIR]
-
A component of the path prefix is not a directory.
In addition, readlinkat() will fail if:
-
[EBADF]
-
path does not specify an absolute path and fd is neither AT_FDCWD nor a valid file descriptor open for reading or searching.
-
[ENOTDIR]
-
path is not an absolute path and fd is a file descriptor associated with a non-directory file.
STANDARDS
The readlink() function conforms to IEEE Std 1003.1-2001 (“POSIX.1”). readlinkat() conforms to IEEE Std 1003.1-2008 (“POSIX.1”).
HISTORY
The readlink() function appeared in 4.2BSD. The type returned was changed from int to ssize_t in NetBSD 2.1.