Debian Codegraph @

upstream/debian-trixie/man2/readlink.2

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