]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
f497e456 | 2 | .\" And Copyright (C) 2011 Guillem Jover <guillem@hadrons.org> |
dcdd0751 | 3 | .\" And Copyright (C) 2006, 2014 Michael Kerrisk |
fea681da MK |
4 | .\" All rights reserved. |
5 | .\" | |
a9cd9cb7 | 6 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
7 | .\" Redistribution and use in source and binary forms, with or without |
8 | .\" modification, are permitted provided that the following conditions | |
9 | .\" are met: | |
10 | .\" 1. Redistributions of source code must retain the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in the | |
14 | .\" documentation and/or other materials provided with the distribution. | |
15 | .\" 3. All advertising materials mentioning features or use of this software | |
16 | .\" must display the following acknowledgement: | |
17 | .\" This product includes software developed by the University of | |
18 | .\" California, Berkeley and its contributors. | |
19 | .\" 4. Neither the name of the University nor the names of its contributors | |
20 | .\" may be used to endorse or promote products derived from this software | |
21 | .\" without specific prior written permission. | |
22 | .\" | |
23 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
24 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
25 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
26 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
27 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
28 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
29 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
30 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
31 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
32 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
33 | .\" SUCH DAMAGE. | |
8c9302dc | 34 | .\" %%%LICENSE_END |
fea681da MK |
35 | .\" |
36 | .\" @(#)readlink.2 6.8 (Berkeley) 3/10/91 | |
37 | .\" | |
38 | .\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu) | |
39 | .\" Modified Tue Jul 9 23:55:17 1996 by aeb | |
40 | .\" Modified Fri Jan 24 00:26:00 1997 by aeb | |
96f62554 MK |
41 | .\" 2011-09-20, Guillem Jover <guillem@hadrons.org>: |
42 | .\" Added text on dynamically allocating buffer + example program | |
fea681da | 43 | .\" |
9ba01802 | 44 | .TH READLINK 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da | 45 | .SH NAME |
dcdd0751 | 46 | readlink, readlinkat \- read value of a symbolic link |
fea681da | 47 | .SH SYNOPSIS |
dcdd0751 | 48 | .nf |
fea681da | 49 | .B #include <unistd.h> |
a539c872 | 50 | .PP |
634e5fa8 MK |
51 | .BI "ssize_t readlink(const char *" pathname ", char *" buf \ |
52 | ", size_t " bufsiz ); | |
a539c872 | 53 | |
dcdd0751 MK |
54 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
55 | .B #include <unistd.h> | |
a539c872 | 56 | .PP |
479fd9ad RV |
57 | .BI "ssize_t readlinkat(int " dirfd ", const char *" pathname , |
58 | .BI " char *" buf ", size_t " bufsiz ); | |
a539c872 | 59 | .PP |
dcdd0751 | 60 | .fi |
cc4615cc MK |
61 | .in -4n |
62 | Feature Test Macro Requirements for glibc (see | |
63 | .BR feature_test_macros (7)): | |
64 | .in | |
a539c872 | 65 | .PP |
cc4615cc MK |
66 | .ad l |
67 | .BR readlink (): | |
cde2506f | 68 | .RS 4 |
f8619b6a | 69 | _XOPEN_SOURCE\ >=\ 500 || _POSIX_C_SOURCE\ >=\ 200112L |
2c767761 | 70 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED |
f8619b6a | 71 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE |
cde2506f | 72 | .RE |
a539c872 | 73 | .PP |
dcdd0751 MK |
74 | .BR readlinkat (): |
75 | .PD 0 | |
76 | .ad l | |
77 | .RS 4 | |
78 | .TP 4 | |
79 | Since glibc 2.10: | |
b0da7b8b | 80 | _POSIX_C_SOURCE\ >=\ 200809L |
dcdd0751 MK |
81 | .TP |
82 | Before glibc 2.10: | |
83 | _ATFILE_SOURCE | |
84 | .RE | |
cc4615cc | 85 | .ad b |
dcdd0751 | 86 | .PD |
fea681da | 87 | .SH DESCRIPTION |
e511ffb6 | 88 | .BR readlink () |
fea681da | 89 | places the contents of the symbolic link |
634e5fa8 | 90 | .I pathname |
fea681da MK |
91 | in the buffer |
92 | .IR buf , | |
93 | which has size | |
94 | .IR bufsiz . | |
e511ffb6 | 95 | .BR readlink () |
28d88c17 | 96 | does not append a null byte to |
fea681da | 97 | .IR buf . |
e9979dff | 98 | It will (silently) truncate the contents (to a length of |
fea681da MK |
99 | .I bufsiz |
100 | characters), in case the buffer is too small to hold all of the contents. | |
dcdd0751 MK |
101 | .SS readlinkat() |
102 | The | |
103 | .BR readlinkat () | |
104 | system call operates in exactly the same way as | |
cadd38ba | 105 | .BR readlink (), |
dcdd0751 | 106 | except for the differences described here. |
a539c872 | 107 | .PP |
dcdd0751 MK |
108 | If the pathname given in |
109 | .I pathname | |
110 | is relative, then it is interpreted relative to the directory | |
111 | referred to by the file descriptor | |
112 | .I dirfd | |
113 | (rather than relative to the current working directory of | |
114 | the calling process, as is done by | |
cadd38ba | 115 | .BR readlink () |
dcdd0751 | 116 | for a relative pathname). |
a539c872 | 117 | .PP |
dcdd0751 MK |
118 | If |
119 | .I pathname | |
120 | is relative and | |
121 | .I dirfd | |
122 | is the special value | |
123 | .BR AT_FDCWD , | |
124 | then | |
125 | .I pathname | |
126 | is interpreted relative to the current working | |
127 | directory of the calling process (like | |
cadd38ba | 128 | .BR readlink ()). |
a539c872 | 129 | .PP |
dcdd0751 MK |
130 | If |
131 | .I pathname | |
132 | is absolute, then | |
133 | .I dirfd | |
134 | is ignored. | |
a539c872 | 135 | .PP |
dcdd0751 MK |
136 | Since Linux 2.6.39, |
137 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
138 | .I pathname | |
139 | can be an empty string, | |
bb7a4bcc | 140 | in which case the call operates on the symbolic link referred to by |
dcdd0751 | 141 | .IR dirfd |
cf781d99 | 142 | (which should have been obtained using |
dcdd0751 | 143 | .BR open (2) |
bb7a4bcc | 144 | with the |
dcdd0751 | 145 | .B O_PATH |
bb7a4bcc MK |
146 | and |
147 | .B O_NOFOLLOW | |
148 | flags). | |
dcdd0751 MK |
149 | .PP |
150 | See | |
151 | .BR openat (2) | |
152 | for an explanation of the need for | |
153 | .BR readlinkat (). | |
47297adb | 154 | .SH RETURN VALUE |
dcdd0751 | 155 | On success, these calls return the number of bytes placed in |
64aae2b1 | 156 | .IR buf . |
e9979dff | 157 | (If the returned value equals |
ddd5c503 | 158 | .IR bufsiz , |
e9979dff | 159 | then truncation may have occurred.) |
64aae2b1 MK |
160 | On error, \-1 is returned and |
161 | .I errno | |
162 | is set to indicate the error. | |
fea681da MK |
163 | .SH ERRORS |
164 | .TP | |
165 | .B EACCES | |
166 | Search permission is denied for a component of the path prefix. | |
167 | (See also | |
ad7cc990 | 168 | .BR path_resolution (7).) |
fea681da MK |
169 | .TP |
170 | .B EFAULT | |
171 | .I buf | |
172 | extends outside the process's allocated address space. | |
173 | .TP | |
174 | .B EINVAL | |
175 | .I bufsiz | |
176 | is not positive. | |
89cb804a MK |
177 | .\" At the glibc level, bufsiz is unsigned, so this error can only occur |
178 | .\" if bufsiz==0. However, the in the kernel syscall, bufsiz is signed, | |
179 | .\" and this error can also occur if bufsiz < 0. | |
180 | .\" See: http://thread.gmane.org/gmane.linux.man/380 | |
181 | .\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall? | |
fea681da MK |
182 | .TP |
183 | .B EINVAL | |
972748d8 MK |
184 | The named file (i.e., the final filename component of |
185 | .IR pathname ) | |
186 | is not a symbolic link. | |
fea681da MK |
187 | .TP |
188 | .B EIO | |
9ee4a2b6 | 189 | An I/O error occurred while reading from the filesystem. |
fea681da MK |
190 | .TP |
191 | .B ELOOP | |
192 | Too many symbolic links were encountered in translating the pathname. | |
193 | .TP | |
194 | .B ENAMETOOLONG | |
195 | A pathname, or a component of a pathname, was too long. | |
196 | .TP | |
197 | .B ENOENT | |
198 | The named file does not exist. | |
199 | .TP | |
200 | .B ENOMEM | |
201 | Insufficient kernel memory was available. | |
202 | .TP | |
203 | .B ENOTDIR | |
204 | A component of the path prefix is not a directory. | |
dcdd0751 MK |
205 | .PP |
206 | The following additional errors can occur for | |
207 | .BR readlinkat (): | |
208 | .TP | |
209 | .B EBADF | |
210 | .I dirfd | |
211 | is not a valid file descriptor. | |
212 | .TP | |
213 | .B ENOTDIR | |
214 | .I pathname | |
215 | is relative and | |
216 | .I dirfd | |
217 | is a file descriptor referring to a file other than a directory. | |
218 | .SH VERSIONS | |
219 | .BR readlinkat () | |
220 | was added to Linux in kernel 2.6.16; | |
221 | library support was added to glibc in version 2.4. | |
47297adb | 222 | .SH CONFORMING TO |
dcdd0751 | 223 | .BR readlink (): |
5d127cc9 MK |
224 | 4.4BSD |
225 | .RB ( readlink () | |
226 | first appeared in 4.2BSD), | |
6315ed1f | 227 | POSIX.1-2001, POSIX.1-2008. |
a539c872 | 228 | .PP |
dcdd0751 MK |
229 | .BR readlinkat (): |
230 | POSIX.1-2008. | |
889829be | 231 | .SH NOTES |
4595d739 MK |
232 | In versions of glibc up to and including glibc 2.4, the return type of |
233 | .BR readlink () | |
234 | was declared as | |
235 | .IR int . | |
236 | Nowadays, the return type is declared as | |
237 | .IR ssize_t , | |
238 | as (newly) required in POSIX.1-2001. | |
a539c872 | 239 | .PP |
b61acee9 MK |
240 | Using a statically sized buffer might not provide enough room for the |
241 | symbolic link contents. | |
242 | The required size for the buffer can be obtained from the | |
243 | .I stat.st_size | |
244 | value returned by a call to | |
245 | .BR lstat (2) | |
246 | on the link. | |
247 | However, the number of bytes written by | |
248 | .BR readlink () | |
787b49e7 MK |
249 | and |
250 | .BR readlinkat () | |
b61acee9 MK |
251 | should be checked to make sure that the size of the |
252 | symbolic link did not increase between the calls. | |
253 | Dynamically allocating the buffer for | |
254 | .BR readlink () | |
787b49e7 MK |
255 | and |
256 | .BR readlinkat () | |
b61acee9 MK |
257 | also addresses a common portability problem when using |
258 | .I PATH_MAX | |
259 | for the buffer size, | |
260 | as this constant is not guaranteed to be defined per POSIX | |
261 | if the system does not have such limit. | |
1e40dbf5 MK |
262 | .SS Glibc notes |
263 | On older kernels where | |
264 | .BR readlinkat () | |
265 | is unavailable, the glibc wrapper function falls back to the use of | |
266 | .BR readlink (). | |
267 | When | |
268 | .I pathname | |
269 | is a relative pathname, | |
270 | glibc constructs a pathname based on the symbolic link in | |
271 | .IR /proc/self/fd | |
272 | that corresponds to the | |
273 | .IR dirfd | |
274 | argument. | |
f91c6bd7 | 275 | .SH EXAMPLE |
b61acee9 | 276 | The following program allocates the buffer needed by |
f91c6bd7 GJ |
277 | .BR readlink () |
278 | dynamically from the information provided by | |
d1e268db | 279 | .BR lstat (2), |
cc6e4bf0 MK |
280 | falling back to a buffer of size |
281 | .BR PATH_MAX | |
282 | in cases where | |
283 | .BR lstat (2) | |
284 | reports a size of zero. | |
f06a3f30 | 285 | .PP |
a539c872 | 286 | .EX |
f91c6bd7 GJ |
287 | #include <sys/types.h> |
288 | #include <sys/stat.h> | |
cc6e4bf0 | 289 | #include <limits.h> |
f91c6bd7 GJ |
290 | #include <stdio.h> |
291 | #include <stdlib.h> | |
292 | #include <unistd.h> | |
293 | ||
294 | int | |
295 | main(int argc, char *argv[]) | |
296 | { | |
297 | struct stat sb; | |
f06a3f30 MK |
298 | char *buf; |
299 | ssize_t nbytes, bufsiz; | |
f91c6bd7 GJ |
300 | |
301 | if (argc != 2) { | |
d1a71985 | 302 | fprintf(stderr, "Usage: %s <pathname>\en", argv[0]); |
f91c6bd7 GJ |
303 | exit(EXIT_FAILURE); |
304 | } | |
305 | ||
306 | if (lstat(argv[1], &sb) == \-1) { | |
307 | perror("lstat"); | |
308 | exit(EXIT_FAILURE); | |
309 | } | |
310 | ||
f06a3f30 MK |
311 | /* Add one to the link size, so that we can determine whether |
312 | the buffer returned by readlink() was truncated. */ | |
313 | ||
cc6e4bf0 MK |
314 | bufsiz = sb.st_size + 1; |
315 | ||
316 | /* Some magic symlinks under (for example) /proc and /sys | |
317 | report \(aqst_size\(aq as zero. In that case, take PATH_MAX as | |
f06a3f30 | 318 | a "good enough" estimate. */ |
cc6e4bf0 MK |
319 | |
320 | if (sb.st_size == 0) | |
321 | bufsiz = PATH_MAX; | |
322 | ||
f06a3f30 MK |
323 | buf = malloc(bufsiz); |
324 | if (buf == NULL) { | |
cc6e4bf0 | 325 | perror("malloc"); |
f91c6bd7 GJ |
326 | exit(EXIT_FAILURE); |
327 | } | |
328 | ||
f06a3f30 MK |
329 | nbytes = readlink(argv[1], buf, bufsiz); |
330 | if (nbytes == \-1) { | |
3468b312 | 331 | perror("readlink"); |
f91c6bd7 | 332 | exit(EXIT_FAILURE); |
1976f57a | 333 | } |
b61acee9 | 334 | |
d1a71985 | 335 | printf("\(aq%s\(aq points to \(aq%.*s\(aq\en", argv[1], (int) nbytes, buf); |
f91c6bd7 | 336 | |
f06a3f30 MK |
337 | /* If the return value was equal to the buffer size, then the |
338 | the link target was larger than expected (perhaps because the | |
339 | target was changed between the call to lstat() and the call to | |
340 | readlink()). Warn the user that the returned target may have | |
341 | been truncated. */ | |
f91c6bd7 | 342 | |
f06a3f30 | 343 | if (nbytes == bufsiz) |
d1a71985 | 344 | printf("(Returned buffer may have been truncated)\en"); |
4bf044cb | 345 | |
f06a3f30 | 346 | free(buf); |
f91c6bd7 GJ |
347 | exit(EXIT_SUCCESS); |
348 | } | |
a539c872 | 349 | .EE |
47297adb | 350 | .SH SEE ALSO |
c370cc1b | 351 | .BR readlink (1), |
fea681da | 352 | .BR lstat (2), |
fea681da | 353 | .BR stat (2), |
ad7cc990 | 354 | .BR symlink (2), |
2333bf67 | 355 | .BR realpath (3), |
a9cfde1d | 356 | .BR path_resolution (7), |
ad22ad55 | 357 | .BR symlink (7) |