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.
SEE ALSO
lstat(2),
stat(2),
symlink(2),
symlink(7)
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.