NAME
readlink
,
readlinkat
—
read value of a symbolic
link
LIBRARY
library “libc”
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.
SEE ALSO
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.