1READLINK(2) Linux Programmer's Manual READLINK(2)
2
6 readlink, readlinkat - read value of a symbolic link
7
9 #include <unistd.h>
10 ssize_t readlink(const char *restrict pathname, char *restrict buf,
12 size_t bufsiz);
13 #include <fcntl.h> /* Definition of AT_* constants */
15 #include <unistd.h>
16 ssize_t readlinkat(int dirfd, const char *restrict pathname,
18 char *restrict buf, size_t bufsiz);
19 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
21 readlink():
23 _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
24 || /* Glibc <= 2.19: */ _BSD_SOURCE
25 readlinkat():
27 Since glibc 2.10:
28 _POSIX_C_SOURCE >= 200809L
29 Before glibc 2.10:
30 _ATFILE_SOURCE
31
33 readlink() places the contents of the symbolic link pathname in the
34 buffer buf, which has size bufsiz. readlink() does not append a termi‐
35 nating null byte to buf. It will (silently) truncate the contents (to
36 a length of bufsiz characters), in case the buffer is too small to hold
37 all of the contents.
38 readlinkat()
40 The readlinkat() system call operates in exactly the same way as read‐
41 link(), except for the differences described here.
42 If the pathname given in pathname is relative, then it is interpreted
44 relative to the directory referred to by the file descriptor dirfd
45 (rather than relative to the current working directory of the calling
46 process, as is done by readlink() for a relative pathname).
47 If pathname is relative and dirfd is the special value AT_FDCWD, then
49 pathname is interpreted relative to the current working directory of
50 the calling process (like readlink()).
51 If pathname is absolute, then dirfd is ignored.
53 Since Linux 2.6.39, pathname can be an empty string, in which case the
55 call operates on the symbolic link referred to by dirfd (which should
56 have been obtained using open(2) with the O_PATH and O_NOFOLLOW flags).
57 See openat(2) for an explanation of the need for readlinkat().
59
61 On success, these calls return the number of bytes placed in buf. (If
62 the returned value equals bufsiz, then truncation may have occurred.)
63 On error, -1 is returned and errno is set to indicate the error.
64
66 EACCES Search permission is denied for a component of the path prefix.
67 (See also path_resolution(7).)
68 EBADF (readlinkat()) pathname is relative but dirfd is neither AT_FD‐
70 CWD nor a valid file descriptor.
71 EFAULT buf extends outside the process's allocated address space.
73 EINVAL bufsiz is not positive.
75 EINVAL The named file (i.e., the final filename component of pathname)
77 is not a symbolic link.
78 EIO An I/O error occurred while reading from the filesystem.
80 ELOOP Too many symbolic links were encountered in translating the
82 pathname.
83 ENAMETOOLONG
85 A pathname, or a component of a pathname, was too long.
86 ENOENT The named file does not exist.
88 ENOMEM Insufficient kernel memory was available.
90 ENOTDIR
92 A component of the path prefix is not a directory.
93 ENOTDIR
95 (readlinkat()) pathname is relative and dirfd is a file descrip‐
96 tor referring to a file other than a directory.
97
99 readlinkat() was added to Linux in kernel 2.6.16; library support was
100 added to glibc in version 2.4.
101
103 readlink(): 4.4BSD (readlink() first appeared in 4.2BSD), POSIX.1-2001,
104 POSIX.1-2008.
105 readlinkat(): POSIX.1-2008.
107
109 In versions of glibc up to and including glibc 2.4, the return type of
110 readlink() was declared as int. Nowadays, the return type is declared
111 as ssize_t, as (newly) required in POSIX.1-2001.
112 Using a statically sized buffer might not provide enough room for the
114 symbolic link contents. The required size for the buffer can be ob‐
115 tained from the stat.st_size value returned by a call to lstat(2) on
116 the link. However, the number of bytes written by readlink() and read‐
117 linkat() should be checked to make sure that the size of the symbolic
118 link did not increase between the calls. Dynamically allocating the
119 buffer for readlink() and readlinkat() also addresses a common porta‐
120 bility problem when using PATH_MAX for the buffer size, as this con‐
121 stant is not guaranteed to be defined per POSIX if the system does not
122 have such limit.
123 Glibc notes
125 On older kernels where readlinkat() is unavailable, the glibc wrapper
126 function falls back to the use of readlink(). When pathname is a rela‐
127 tive pathname, glibc constructs a pathname based on the symbolic link
128 in /proc/self/fd that corresponds to the dirfd argument.
129
131 The following program allocates the buffer needed by readlink() dynami‐
132 cally from the information provided by lstat(2), falling back to a buf‐
133 fer of size PATH_MAX in cases where lstat(2) reports a size of zero.
134 #include <sys/types.h>
136 #include <sys/stat.h>
137 #include <limits.h>
138 #include <stdio.h>
139 #include <stdlib.h>
140 #include <unistd.h>
141 int
143 main(int argc, char *argv[])
144 {
145 struct stat sb;
146 char *buf;
147 ssize_t nbytes, bufsiz;
148 if (argc != 2) {
150 fprintf(stderr, "Usage: %s <pathname>\n", argv[0]);
151 exit(EXIT_FAILURE);
152 }
153 if (lstat(argv[1], &sb) == -1) {
155 perror("lstat");
156 exit(EXIT_FAILURE);
157 }
158 /* Add one to the link size, so that we can determine whether
160 the buffer returned by readlink() was truncated. */
161 bufsiz = sb.st_size + 1;
163 /* Some magic symlinks under (for example) /proc and /sys
165 report 'st_size' as zero. In that case, take PATH_MAX as
166 a "good enough" estimate. */
167 if (sb.st_size == 0)
169 bufsiz = PATH_MAX;
170 buf = malloc(bufsiz);
172 if (buf == NULL) {
173 perror("malloc");
174 exit(EXIT_FAILURE);
175 }
176 nbytes = readlink(argv[1], buf, bufsiz);
178 if (nbytes == -1) {
179 perror("readlink");
180 exit(EXIT_FAILURE);
181 }
182 /* Print only 'nbytes' of 'buf', as it doesn't contain a terminating
184 null byte ('\0'). */
185 printf("'%s' points to '%.*s'\n", argv[1], (int) nbytes, buf);
186 /* If the return value was equal to the buffer size, then the
188 the link target was larger than expected (perhaps because the
189 target was changed between the call to lstat() and the call to
190 readlink()). Warn the user that the returned target may have
191 been truncated. */
192 if (nbytes == bufsiz)
194 printf("(Returned buffer may have been truncated)\n");
195 free(buf);
197 exit(EXIT_SUCCESS);
198 }
199
201 readlink(1), lstat(2), stat(2), symlink(2), realpath(3), path_resolu‐
202 tion(7), symlink(7)
203
205 This page is part of release 5.13 of the Linux man-pages project. A
206 description of the project, information about reporting bugs, and the
207 latest version of this page, can be found at
208 https://www.kernel.org/doc/man-pages/.
209Linux 2021-08-27 READLINK(2)