Debian Codegraph @

upstream/debian-unstable/man2/readlink.2

raw
1 .\" Copyright 1983-1991, The Regents of the University of California.
2 .\" Copyright 2011, Guillem Jover <[email protected]>
3 .\" Copyright 2006-2014, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: BSD-4-Clause-UC
7 .\"
8 .TH readlink 2 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 readlink, readlinkat \- read value of a symbolic link
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <unistd.h>
17 .P
18 .BR "ssize_t readlink(" "size_t bufsiz;"
19 .BI " const char *restrict " path ,
20 .BI " char " buf "[restrict " bufsiz "], size_t " bufsiz );
21 .P
22 .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
23 .B #include <unistd.h>
24 .P
25 .BR "ssize_t readlinkat(" "size_t bufsiz;"
26 .BI " int " dirfd ", const char *restrict " path ,
27 .BI " char " buf "[restrict " bufsiz "], size_t " bufsiz );
28 .P
29 .fi
30 .RS -4
31 Feature Test Macro Requirements for glibc (see
32 .BR feature_test_macros (7)):
33 .RE
34 .P
35 .BR readlink ():
36 .nf
37 _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
38 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
39 || /* glibc <= 2.19: */ _BSD_SOURCE
40 .fi
41 .P
42 .BR readlinkat ():
43 .nf
44 Since glibc 2.10:
45 _POSIX_C_SOURCE >= 200809L
46 Before glibc 2.10:
47 _ATFILE_SOURCE
48 .fi
49 .SH DESCRIPTION
50 .BR readlink ()
51 places the contents of the symbolic link
52 .I path
53 in the buffer
54 .IR buf ,
55 which has size
56 .IR bufsiz .
57 .BR readlink ()
58 does not append a terminating null byte to
59 .IR buf .
60 It will (silently) truncate the contents (to a length of
61 .I bufsiz
62 characters), in case the buffer is too small to hold all of the contents.
63 .SS readlinkat()
64 The
65 .BR readlinkat ()
66 system call operates in exactly the same way as
67 .BR readlink (),
68 except for the differences described here.
69 .P
70 If
71 .I path
72 is relative, then it is interpreted relative to the directory
73 referred to by the file descriptor
74 .I dirfd
75 (rather than relative to the current working directory of
76 the calling process, as is done by
77 .BR readlink ()
78 for a relative pathname).
79 .P
80 If
81 .I path
82 is relative and
83 .I dirfd
84 is the special value
85 .BR AT_FDCWD ,
86 then
87 .I path
88 is interpreted relative to the current working
89 directory of the calling process (like
90 .BR readlink ()).
91 .P
92 If
93 .I path
94 is absolute, then
95 .I dirfd
96 is ignored.
97 .P
98 Since Linux 2.6.39,
99 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
100 .I path
101 can be an empty string,
102 in which case the call operates on the symbolic link referred to by
103 .I dirfd
104 (which should have been obtained using
105 .BR open (2)
106 with the
107 .B O_PATH
108 and
109 .B O_NOFOLLOW
110 flags).
111 .P
112 See
113 .BR openat (2)
114 for an explanation of the need for
115 .BR readlinkat ().
116 .SH RETURN VALUE
117 On success, these calls return the number of bytes placed in
118 .IR buf .
119 (If the returned value equals
120 .IR bufsiz ,
121 then truncation may have occurred.)
122 On error, \-1 is returned and
123 .I errno
124 is set to indicate the error.
125 .SH ERRORS
126 .TP
127 .B EACCES
128 Search permission is denied for a component of the path prefix.
129 (See also
130 .BR path_resolution (7).)
131 .TP
132 .B EBADF
133 .RB ( readlinkat ())
134 .I path
135 is relative but
136 .I dirfd
137 is neither
138 .B AT_FDCWD
139 nor a valid file descriptor.
140 .TP
141 .B EFAULT
142 .I buf
143 extends outside the process's allocated address space.
144 .TP
145 .B EINVAL
146 .I bufsiz
147 is not positive.
148 .\" At the glibc level, bufsiz is unsigned, so this error can only occur
149 .\" if bufsiz==0. However, the in the kernel syscall, bufsiz is signed,
150 .\" and this error can also occur if bufsiz < 0.
151 .\" See: http://thread.gmane.org/gmane.linux.man/380
152 .\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall?
153 .TP
154 .B EINVAL
155 The named file (i.e., the final filename component of
156 .IR path )
157 is not a symbolic link.
158 .TP
159 .B EIO
160 An I/O error occurred while reading from the filesystem.
161 .TP
162 .B ELOOP
163 Too many symbolic links were encountered in translating the pathname.
164 .TP
165 .B ENAMETOOLONG
166 A pathname, or a component of a pathname, was too long.
167 .TP
168 .B ENOENT
169 The named file does not exist.
170 .TP
171 .B ENOMEM
172 Insufficient kernel memory was available.
173 .TP
174 .B ENOTDIR
175 A component of the path prefix is not a directory.
176 .TP
177 .B ENOTDIR
178 .RB ( readlinkat ())
179 .I path
180 is relative and
181 .I dirfd
182 is a file descriptor referring to a file other than a directory.
183 .SH STANDARDS
184 POSIX.1-2024.
185 .SH HISTORY
186 .TP
187 .BR readlink ()
188 4.4BSD
189 (first appeared in 4.2BSD),
190 POSIX.1-2001, POSIX.1-2008.
191 .TP
192 .BR readlinkat ()
193 POSIX.1-2008.
194 Linux 2.6.16,
195 glibc 2.4.
196 .P
197 Up to and including glibc 2.4, the return type of
198 .BR readlink ()
199 was declared as
200 .IR int .
201 Nowadays, the return type is declared as
202 .IR ssize_t ,
203 as (newly) required in POSIX.1-2001.
204 .SS glibc
205 On older kernels where
206 .BR readlinkat ()
207 is unavailable, the glibc wrapper function falls back to the use of
208 .BR readlink ().
209 When
210 .I path
211 is relative,
212 glibc constructs a pathname based on the symbolic link in
213 .I /proc/self/fd
214 that corresponds to the
215 .I dirfd
216 argument.
217 .SH NOTES
218 Using a statically sized buffer might not provide enough room for the
219 symbolic link contents.
220 The required size for the buffer can be obtained from the
221 .I stat.st_size
222 value returned by a call to
223 .BR lstat (2)
224 on the link.
225 However, the number of bytes written by
226 .BR readlink ()
227 and
228 .BR readlinkat ()
229 should be checked to make sure that the size of the
230 symbolic link did not increase between the calls.
231 Dynamically allocating the buffer for
232 .BR readlink ()
233 and
234 .BR readlinkat ()
235 also addresses a common portability problem when using
236 .B PATH_MAX
237 for the buffer size,
238 as this constant is not guaranteed to be defined per POSIX
239 if the system does not have such limit.
240 .SH EXAMPLES
241 The following program allocates the buffer needed by
242 .BR readlink ()
243 dynamically from the information provided by
244 .BR lstat (2),
245 falling back to a buffer of size
246 .B PATH_MAX
247 in cases where
248 .BR lstat (2)
249 reports a size of zero.
250 .P
251 .\" SRC BEGIN (readlink.c)
252 .EX
253 #include <limits.h>
254 #include <stdio.h>
255 #include <stdlib.h>
256 #include <sys/stat.h>
257 #include <sys/types.h>
258 #include <unistd.h>
259 \&
260 int
261 main(int argc, char *argv[])
262 {
263 char *buf;
264 ssize_t nbytes, bufsiz;
265 struct stat sb;
266 \&
267 if (argc != 2) {
268 fprintf(stderr, "Usage: %s <path>\[rs]n", argv[0]);
269 exit(EXIT_FAILURE);
270 }
271 \&
272 if (lstat(argv[1], &sb) == \-1) {
273 perror("lstat");
274 exit(EXIT_FAILURE);
275 }
276 \&
277 /* Add one to the link size, so that we can determine whether
278 the buffer returned by readlink() was truncated. */
279 \&
280 bufsiz = sb.st_size + 1;
281 \&
282 /* Some magic symlinks under (for example) /proc and /sys
283 report \[aq]st_size\[aq] as zero. In that case, take PATH_MAX as
284 a "good enough" estimate. */
285 \&
286 if (sb.st_size == 0)
287 bufsiz = PATH_MAX;
288 \&
289 buf = malloc(bufsiz);
290 if (buf == NULL) {
291 perror("malloc");
292 exit(EXIT_FAILURE);
293 }
294 \&
295 nbytes = readlink(argv[1], buf, bufsiz);
296 if (nbytes == \-1) {
297 perror("readlink");
298 exit(EXIT_FAILURE);
299 }
300 \&
301 /* Print only \[aq]nbytes\[aq] of \[aq]buf\[aq], as it doesn't contain a terminating
302 null byte (\[aq]\[rs]0\[aq]). */
303 printf("\[aq]%s\[aq] points to \[aq]%.*s\[aq]\[rs]n", argv[1], (int) nbytes, buf);
304 \&
305 /* If the return value was equal to the buffer size, then
306 the link target was larger than expected (perhaps because the
307 target was changed between the call to lstat() and the call to
308 readlink()). Warn the user that the returned target may have
309 been truncated. */
310 \&
311 if (nbytes == bufsiz)
312 printf("(Returned buffer may have been truncated)\[rs]n");
313 \&
314 free(buf);
315 exit(EXIT_SUCCESS);
316 }
317 .EE
318 .\" SRC END
319 .SH SEE ALSO
320 .BR readlink (1),
321 .BR lstat (2),
322 .BR stat (2),
323 .BR symlink (2),
324 .BR realpath (3),
325 .BR path_resolution (7),
326 .BR symlink (7)