]>
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 | .\" |
ad624ff4 | 44 | .TH READLINK 2 2014-10-15 "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 MK |
49 | .B #include <unistd.h> |
50 | .sp | |
634e5fa8 MK |
51 | .BI "ssize_t readlink(const char *" pathname ", char *" buf \ |
52 | ", size_t " bufsiz ); | |
cc4615cc | 53 | .sp |
dcdd0751 MK |
54 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
55 | .B #include <unistd.h> | |
56 | .sp | |
479fd9ad RV |
57 | .BI "ssize_t readlinkat(int " dirfd ", const char *" pathname , |
58 | .BI " char *" buf ", size_t " bufsiz ); | |
dcdd0751 MK |
59 | .sp |
60 | .fi | |
cc4615cc MK |
61 | .in -4n |
62 | Feature Test Macro Requirements for glibc (see | |
63 | .BR feature_test_macros (7)): | |
64 | .in | |
65 | .sp | |
66 | .ad l | |
67 | .BR readlink (): | |
cde2506f MK |
68 | .RS 4 |
69 | _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || | |
70 | _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE\ >=\ 200112L | |
71 | .RE | |
dcdd0751 MK |
72 | .sp |
73 | .BR readlinkat (): | |
74 | .PD 0 | |
75 | .ad l | |
76 | .RS 4 | |
77 | .TP 4 | |
78 | Since glibc 2.10: | |
79 | _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L | |
80 | .TP | |
81 | Before glibc 2.10: | |
82 | _ATFILE_SOURCE | |
83 | .RE | |
cc4615cc | 84 | .ad b |
dcdd0751 | 85 | .PD |
fea681da | 86 | .SH DESCRIPTION |
e511ffb6 | 87 | .BR readlink () |
fea681da | 88 | places the contents of the symbolic link |
634e5fa8 | 89 | .I pathname |
fea681da MK |
90 | in the buffer |
91 | .IR buf , | |
92 | which has size | |
93 | .IR bufsiz . | |
e511ffb6 | 94 | .BR readlink () |
28d88c17 | 95 | does not append a null byte to |
fea681da MK |
96 | .IR buf . |
97 | It will truncate the contents (to a length of | |
98 | .I bufsiz | |
99 | characters), in case the buffer is too small to hold all of the contents. | |
dcdd0751 MK |
100 | .SS readlinkat() |
101 | The | |
102 | .BR readlinkat () | |
103 | system call operates in exactly the same way as | |
cadd38ba | 104 | .BR readlink (), |
dcdd0751 MK |
105 | except for the differences described here. |
106 | ||
107 | If the pathname given in | |
108 | .I pathname | |
109 | is relative, then it is interpreted relative to the directory | |
110 | referred to by the file descriptor | |
111 | .I dirfd | |
112 | (rather than relative to the current working directory of | |
113 | the calling process, as is done by | |
cadd38ba | 114 | .BR readlink () |
dcdd0751 MK |
115 | for a relative pathname). |
116 | ||
117 | If | |
118 | .I pathname | |
119 | is relative and | |
120 | .I dirfd | |
121 | is the special value | |
122 | .BR AT_FDCWD , | |
123 | then | |
124 | .I pathname | |
125 | is interpreted relative to the current working | |
126 | directory of the calling process (like | |
cadd38ba | 127 | .BR readlink ()). |
dcdd0751 MK |
128 | |
129 | If | |
130 | .I pathname | |
131 | is absolute, then | |
132 | .I dirfd | |
133 | is ignored. | |
134 | ||
135 | Since Linux 2.6.39, | |
136 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
137 | .I pathname | |
138 | can be an empty string, | |
bb7a4bcc | 139 | in which case the call operates on the symbolic link referred to by |
dcdd0751 | 140 | .IR dirfd |
cf781d99 | 141 | (which should have been obtained using |
dcdd0751 | 142 | .BR open (2) |
bb7a4bcc | 143 | with the |
dcdd0751 | 144 | .B O_PATH |
bb7a4bcc MK |
145 | and |
146 | .B O_NOFOLLOW | |
147 | flags). | |
dcdd0751 MK |
148 | .PP |
149 | See | |
150 | .BR openat (2) | |
151 | for an explanation of the need for | |
152 | .BR readlinkat (). | |
47297adb | 153 | .SH RETURN VALUE |
dcdd0751 | 154 | On success, these calls return the number of bytes placed in |
64aae2b1 MK |
155 | .IR buf . |
156 | On error, \-1 is returned and | |
157 | .I errno | |
158 | is set to indicate the error. | |
fea681da MK |
159 | .SH ERRORS |
160 | .TP | |
161 | .B EACCES | |
162 | Search permission is denied for a component of the path prefix. | |
163 | (See also | |
ad7cc990 | 164 | .BR path_resolution (7).) |
fea681da MK |
165 | .TP |
166 | .B EFAULT | |
167 | .I buf | |
168 | extends outside the process's allocated address space. | |
169 | .TP | |
170 | .B EINVAL | |
171 | .I bufsiz | |
172 | is not positive. | |
89cb804a MK |
173 | .\" At the glibc level, bufsiz is unsigned, so this error can only occur |
174 | .\" if bufsiz==0. However, the in the kernel syscall, bufsiz is signed, | |
175 | .\" and this error can also occur if bufsiz < 0. | |
176 | .\" See: http://thread.gmane.org/gmane.linux.man/380 | |
177 | .\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall? | |
fea681da MK |
178 | .TP |
179 | .B EINVAL | |
972748d8 MK |
180 | The named file (i.e., the final filename component of |
181 | .IR pathname ) | |
182 | is not a symbolic link. | |
fea681da MK |
183 | .TP |
184 | .B EIO | |
9ee4a2b6 | 185 | An I/O error occurred while reading from the filesystem. |
fea681da MK |
186 | .TP |
187 | .B ELOOP | |
188 | Too many symbolic links were encountered in translating the pathname. | |
189 | .TP | |
190 | .B ENAMETOOLONG | |
191 | A pathname, or a component of a pathname, was too long. | |
192 | .TP | |
193 | .B ENOENT | |
194 | The named file does not exist. | |
195 | .TP | |
196 | .B ENOMEM | |
197 | Insufficient kernel memory was available. | |
198 | .TP | |
199 | .B ENOTDIR | |
200 | A component of the path prefix is not a directory. | |
dcdd0751 MK |
201 | .PP |
202 | The following additional errors can occur for | |
203 | .BR readlinkat (): | |
204 | .TP | |
205 | .B EBADF | |
206 | .I dirfd | |
207 | is not a valid file descriptor. | |
208 | .TP | |
209 | .B ENOTDIR | |
210 | .I pathname | |
211 | is relative and | |
212 | .I dirfd | |
213 | is a file descriptor referring to a file other than a directory. | |
214 | .SH VERSIONS | |
215 | .BR readlinkat () | |
216 | was added to Linux in kernel 2.6.16; | |
217 | library support was added to glibc in version 2.4. | |
47297adb | 218 | .SH CONFORMING TO |
dcdd0751 | 219 | .BR readlink (): |
5d127cc9 MK |
220 | 4.4BSD |
221 | .RB ( readlink () | |
222 | first appeared in 4.2BSD), | |
6315ed1f | 223 | POSIX.1-2001, POSIX.1-2008. |
dcdd0751 MK |
224 | |
225 | .BR readlinkat (): | |
226 | POSIX.1-2008. | |
889829be | 227 | .SH NOTES |
4595d739 MK |
228 | In versions of glibc up to and including glibc 2.4, the return type of |
229 | .BR readlink () | |
230 | was declared as | |
231 | .IR int . | |
232 | Nowadays, the return type is declared as | |
233 | .IR ssize_t , | |
234 | as (newly) required in POSIX.1-2001. | |
b61acee9 MK |
235 | |
236 | Using a statically sized buffer might not provide enough room for the | |
237 | symbolic link contents. | |
238 | The required size for the buffer can be obtained from the | |
239 | .I stat.st_size | |
240 | value returned by a call to | |
241 | .BR lstat (2) | |
242 | on the link. | |
243 | However, the number of bytes written by | |
244 | .BR readlink () | |
787b49e7 MK |
245 | and |
246 | .BR readlinkat () | |
b61acee9 MK |
247 | should be checked to make sure that the size of the |
248 | symbolic link did not increase between the calls. | |
249 | Dynamically allocating the buffer for | |
250 | .BR readlink () | |
787b49e7 MK |
251 | and |
252 | .BR readlinkat () | |
b61acee9 MK |
253 | also addresses a common portability problem when using |
254 | .I PATH_MAX | |
255 | for the buffer size, | |
256 | as this constant is not guaranteed to be defined per POSIX | |
257 | if the system does not have such limit. | |
1e40dbf5 MK |
258 | .SS Glibc notes |
259 | On older kernels where | |
260 | .BR readlinkat () | |
261 | is unavailable, the glibc wrapper function falls back to the use of | |
262 | .BR readlink (). | |
263 | When | |
264 | .I pathname | |
265 | is a relative pathname, | |
266 | glibc constructs a pathname based on the symbolic link in | |
267 | .IR /proc/self/fd | |
268 | that corresponds to the | |
269 | .IR dirfd | |
270 | argument. | |
f91c6bd7 | 271 | .SH EXAMPLE |
b61acee9 | 272 | The following program allocates the buffer needed by |
f91c6bd7 GJ |
273 | .BR readlink () |
274 | dynamically from the information provided by | |
275 | .BR lstat (), | |
b61acee9 | 276 | making sure there's no race condition between the calls. |
f91c6bd7 GJ |
277 | .nf |
278 | ||
279 | #include <sys/types.h> | |
280 | #include <sys/stat.h> | |
281 | #include <stdio.h> | |
282 | #include <stdlib.h> | |
283 | #include <unistd.h> | |
284 | ||
285 | int | |
286 | main(int argc, char *argv[]) | |
287 | { | |
288 | struct stat sb; | |
289 | char *linkname; | |
290 | ssize_t r; | |
291 | ||
292 | if (argc != 2) { | |
293 | fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]); | |
294 | exit(EXIT_FAILURE); | |
295 | } | |
296 | ||
297 | if (lstat(argv[1], &sb) == \-1) { | |
298 | perror("lstat"); | |
299 | exit(EXIT_FAILURE); | |
300 | } | |
301 | ||
302 | linkname = malloc(sb.st_size + 1); | |
303 | if (linkname == NULL) { | |
304 | fprintf(stderr, "insufficient memory\\n"); | |
305 | exit(EXIT_FAILURE); | |
306 | } | |
307 | ||
308 | r = readlink(argv[1], linkname, sb.st_size + 1); | |
1976f57a | 309 | |
4b80b37c | 310 | if (r == \-1) { |
3468b312 | 311 | perror("readlink"); |
f91c6bd7 | 312 | exit(EXIT_FAILURE); |
1976f57a | 313 | } |
b61acee9 | 314 | |
f497e456 | 315 | if (r > sb.st_size) { |
b61acee9 MK |
316 | fprintf(stderr, "symlink increased in size " |
317 | "between lstat() and readlink()\\n"); | |
f91c6bd7 GJ |
318 | exit(EXIT_FAILURE); |
319 | } | |
b61acee9 | 320 | |
c1de8e3e | 321 | linkname[r] = \(aq\\0\(aq; |
f91c6bd7 | 322 | |
836830b4 | 323 | printf("\(aq%s\(aq points to \(aq%s\(aq\\n", argv[1], linkname); |
f91c6bd7 | 324 | |
4bf044cb MK |
325 | free(linkname); |
326 | ||
f91c6bd7 GJ |
327 | exit(EXIT_SUCCESS); |
328 | } | |
329 | .fi | |
47297adb | 330 | .SH SEE ALSO |
c370cc1b | 331 | .BR readlink (1), |
fea681da | 332 | .BR lstat (2), |
fea681da | 333 | .BR stat (2), |
ad7cc990 | 334 | .BR symlink (2), |
2333bf67 | 335 | .BR realpath (3), |
a9cfde1d | 336 | .BR path_resolution (7), |
ad22ad55 | 337 | .BR symlink (7) |