]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. | |
2 | .\" And Copyright (C) 2011 Guillem Jover <guillem@hadrons.org> | |
3 | .\" And Copyright (C) 2006, 2014 Michael Kerrisk | |
4 | .\" All rights reserved. | |
5 | .\" | |
6 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) | |
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. | |
34 | .\" %%%LICENSE_END | |
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 | |
41 | .\" 2011-09-20, Guillem Jover <guillem@hadrons.org>: | |
42 | .\" Added text on dynamically allocating buffer + example program | |
43 | .\" | |
44 | .TH READLINK 2 2017-09-15 "Linux" "Linux Programmer's Manual" | |
45 | .SH NAME | |
46 | readlink, readlinkat \- read value of a symbolic link | |
47 | .SH SYNOPSIS | |
48 | .nf | |
49 | .B #include <unistd.h> | |
50 | .PP | |
51 | .BI "ssize_t readlink(const char *" pathname ", char *" buf \ | |
52 | ", size_t " bufsiz ); | |
53 | ||
54 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" | |
55 | .B #include <unistd.h> | |
56 | .PP | |
57 | .BI "ssize_t readlinkat(int " dirfd ", const char *" pathname , | |
58 | .BI " char *" buf ", size_t " bufsiz ); | |
59 | .PP | |
60 | .fi | |
61 | .in -4n | |
62 | Feature Test Macro Requirements for glibc (see | |
63 | .BR feature_test_macros (7)): | |
64 | .in | |
65 | .PP | |
66 | .ad l | |
67 | .BR readlink (): | |
68 | .RS 4 | |
69 | _XOPEN_SOURCE\ >=\ 500 || _POSIX_C_SOURCE\ >=\ 200112L | |
70 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
71 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE | |
72 | .RE | |
73 | .PP | |
74 | .BR readlinkat (): | |
75 | .PD 0 | |
76 | .ad l | |
77 | .RS 4 | |
78 | .TP 4 | |
79 | Since glibc 2.10: | |
80 | _POSIX_C_SOURCE\ >=\ 200809L | |
81 | .TP | |
82 | Before glibc 2.10: | |
83 | _ATFILE_SOURCE | |
84 | .RE | |
85 | .ad b | |
86 | .PD | |
87 | .SH DESCRIPTION | |
88 | .BR readlink () | |
89 | places the contents of the symbolic link | |
90 | .I pathname | |
91 | in the buffer | |
92 | .IR buf , | |
93 | which has size | |
94 | .IR bufsiz . | |
95 | .BR readlink () | |
96 | does not append a null byte to | |
97 | .IR buf . | |
98 | It will (silently) truncate the contents (to a length of | |
99 | .I bufsiz | |
100 | characters), in case the buffer is too small to hold all of the contents. | |
101 | .SS readlinkat() | |
102 | The | |
103 | .BR readlinkat () | |
104 | system call operates in exactly the same way as | |
105 | .BR readlink (), | |
106 | except for the differences described here. | |
107 | .PP | |
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 | |
115 | .BR readlink () | |
116 | for a relative pathname). | |
117 | .PP | |
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 | |
128 | .BR readlink ()). | |
129 | .PP | |
130 | If | |
131 | .I pathname | |
132 | is absolute, then | |
133 | .I dirfd | |
134 | is ignored. | |
135 | .PP | |
136 | Since Linux 2.6.39, | |
137 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
138 | .I pathname | |
139 | can be an empty string, | |
140 | in which case the call operates on the symbolic link referred to by | |
141 | .IR dirfd | |
142 | (which should have been obtained using | |
143 | .BR open (2) | |
144 | with the | |
145 | .B O_PATH | |
146 | and | |
147 | .B O_NOFOLLOW | |
148 | flags). | |
149 | .PP | |
150 | See | |
151 | .BR openat (2) | |
152 | for an explanation of the need for | |
153 | .BR readlinkat (). | |
154 | .SH RETURN VALUE | |
155 | On success, these calls return the number of bytes placed in | |
156 | .IR buf . | |
157 | (If the returned value equals | |
158 | .IR bufsiz , | |
159 | then truncation may have occurred.) | |
160 | On error, \-1 is returned and | |
161 | .I errno | |
162 | is set to indicate the error. | |
163 | .SH ERRORS | |
164 | .TP | |
165 | .B EACCES | |
166 | Search permission is denied for a component of the path prefix. | |
167 | (See also | |
168 | .BR path_resolution (7).) | |
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. | |
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? | |
182 | .TP | |
183 | .B EINVAL | |
184 | The named file (i.e., the final filename component of | |
185 | .IR pathname ) | |
186 | is not a symbolic link. | |
187 | .TP | |
188 | .B EIO | |
189 | An I/O error occurred while reading from the filesystem. | |
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. | |
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. | |
222 | .SH CONFORMING TO | |
223 | .BR readlink (): | |
224 | 4.4BSD | |
225 | .RB ( readlink () | |
226 | first appeared in 4.2BSD), | |
227 | POSIX.1-2001, POSIX.1-2008. | |
228 | .PP | |
229 | .BR readlinkat (): | |
230 | POSIX.1-2008. | |
231 | .SH NOTES | |
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. | |
239 | .PP | |
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 () | |
249 | and | |
250 | .BR readlinkat () | |
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 () | |
255 | and | |
256 | .BR readlinkat () | |
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. | |
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. | |
275 | .SH EXAMPLE | |
276 | The following program allocates the buffer needed by | |
277 | .BR readlink () | |
278 | dynamically from the information provided by | |
279 | .BR lstat (2), | |
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. | |
285 | .PP | |
286 | .EX | |
287 | #include <sys/types.h> | |
288 | #include <sys/stat.h> | |
289 | #include <limits.h> | |
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; | |
298 | char *buf; | |
299 | ssize_t nbytes, bufsiz; | |
300 | ||
301 | if (argc != 2) { | |
302 | fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]); | |
303 | exit(EXIT_FAILURE); | |
304 | } | |
305 | ||
306 | if (lstat(argv[1], &sb) == \-1) { | |
307 | perror("lstat"); | |
308 | exit(EXIT_FAILURE); | |
309 | } | |
310 | ||
311 | /* Add one to the link size, so that we can determine whether | |
312 | the buffer returned by readlink() was truncated. */ | |
313 | ||
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 | |
318 | a "good enough" estimate. */ | |
319 | ||
320 | if (sb.st_size == 0) | |
321 | bufsiz = PATH_MAX; | |
322 | ||
323 | buf = malloc(bufsiz); | |
324 | if (buf == NULL) { | |
325 | perror("malloc"); | |
326 | exit(EXIT_FAILURE); | |
327 | } | |
328 | ||
329 | nbytes = readlink(argv[1], buf, bufsiz); | |
330 | if (nbytes == \-1) { | |
331 | perror("readlink"); | |
332 | exit(EXIT_FAILURE); | |
333 | } | |
334 | ||
335 | printf("\(aq%s\(aq points to \(aq%.*s\(aq\\n", argv[1], (int) nbytes, buf); | |
336 | ||
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. */ | |
342 | ||
343 | if (nbytes == bufsiz) | |
344 | printf("(Returned buffer may have been truncated)\\n"); | |
345 | ||
346 | free(buf); | |
347 | exit(EXIT_SUCCESS); | |
348 | } | |
349 | .EE | |
350 | .SH SEE ALSO | |
351 | .BR readlink (1), | |
352 | .BR lstat (2), | |
353 | .BR stat (2), | |
354 | .BR symlink (2), | |
355 | .BR realpath (3), | |
356 | .BR path_resolution (7), | |
357 | .BR symlink (7) |