]>
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> |
fea681da MK |
3 | .\" All rights reserved. |
4 | .\" | |
a9cd9cb7 | 5 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
6 | .\" Redistribution and use in source and binary forms, with or without |
7 | .\" modification, are permitted provided that the following conditions | |
8 | .\" are met: | |
9 | .\" 1. Redistributions of source code must retain the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer. | |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer in the | |
13 | .\" documentation and/or other materials provided with the distribution. | |
14 | .\" 3. All advertising materials mentioning features or use of this software | |
15 | .\" must display the following acknowledgement: | |
16 | .\" This product includes software developed by the University of | |
17 | .\" California, Berkeley and its contributors. | |
18 | .\" 4. Neither the name of the University nor the names of its contributors | |
19 | .\" may be used to endorse or promote products derived from this software | |
20 | .\" without specific prior written permission. | |
21 | .\" | |
22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
32 | .\" SUCH DAMAGE. | |
8c9302dc | 33 | .\" %%%LICENSE_END |
fea681da MK |
34 | .\" |
35 | .\" @(#)readlink.2 6.8 (Berkeley) 3/10/91 | |
36 | .\" | |
37 | .\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu) | |
38 | .\" Modified Tue Jul 9 23:55:17 1996 by aeb | |
39 | .\" Modified Fri Jan 24 00:26:00 1997 by aeb | |
96f62554 MK |
40 | .\" 2011-09-20, Guillem Jover <guillem@hadrons.org>: |
41 | .\" Added text on dynamically allocating buffer + example program | |
fea681da | 42 | .\" |
3468b312 | 43 | .TH READLINK 2 2013-10-26 "Linux" "Linux Programmer's Manual" |
fea681da MK |
44 | .SH NAME |
45 | readlink \- read value of a symbolic link | |
46 | .SH SYNOPSIS | |
47 | .B #include <unistd.h> | |
48 | .sp | |
4595d739 | 49 | .BI "ssize_t readlink(const char *" path ", char *" buf ", size_t " bufsiz ); |
cc4615cc MK |
50 | .sp |
51 | .in -4n | |
52 | Feature Test Macro Requirements for glibc (see | |
53 | .BR feature_test_macros (7)): | |
54 | .in | |
55 | .sp | |
56 | .ad l | |
57 | .BR readlink (): | |
cde2506f MK |
58 | .RS 4 |
59 | _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || | |
60 | _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE\ >=\ 200112L | |
61 | .RE | |
cc4615cc | 62 | .ad b |
fea681da | 63 | .SH DESCRIPTION |
e511ffb6 | 64 | .BR readlink () |
fea681da MK |
65 | places the contents of the symbolic link |
66 | .I path | |
67 | in the buffer | |
68 | .IR buf , | |
69 | which has size | |
70 | .IR bufsiz . | |
e511ffb6 | 71 | .BR readlink () |
28d88c17 | 72 | does not append a null byte to |
fea681da MK |
73 | .IR buf . |
74 | It will truncate the contents (to a length of | |
75 | .I bufsiz | |
76 | characters), in case the buffer is too small to hold all of the contents. | |
47297adb | 77 | .SH RETURN VALUE |
64aae2b1 MK |
78 | On success, |
79 | .BR readlink () | |
80 | returns the number of bytes placed in | |
81 | .IR buf . | |
82 | On error, \-1 is returned and | |
83 | .I errno | |
84 | is set to indicate the error. | |
fea681da MK |
85 | .SH ERRORS |
86 | .TP | |
87 | .B EACCES | |
88 | Search permission is denied for a component of the path prefix. | |
89 | (See also | |
ad7cc990 | 90 | .BR path_resolution (7).) |
fea681da MK |
91 | .TP |
92 | .B EFAULT | |
93 | .I buf | |
94 | extends outside the process's allocated address space. | |
95 | .TP | |
96 | .B EINVAL | |
97 | .I bufsiz | |
98 | is not positive. | |
89cb804a MK |
99 | .\" At the glibc level, bufsiz is unsigned, so this error can only occur |
100 | .\" if bufsiz==0. However, the in the kernel syscall, bufsiz is signed, | |
101 | .\" and this error can also occur if bufsiz < 0. | |
102 | .\" See: http://thread.gmane.org/gmane.linux.man/380 | |
103 | .\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall? | |
fea681da MK |
104 | .TP |
105 | .B EINVAL | |
106 | The named file is not a symbolic link. | |
107 | .TP | |
108 | .B EIO | |
9ee4a2b6 | 109 | An I/O error occurred while reading from the filesystem. |
fea681da MK |
110 | .TP |
111 | .B ELOOP | |
112 | Too many symbolic links were encountered in translating the pathname. | |
113 | .TP | |
114 | .B ENAMETOOLONG | |
115 | A pathname, or a component of a pathname, was too long. | |
116 | .TP | |
117 | .B ENOENT | |
118 | The named file does not exist. | |
119 | .TP | |
120 | .B ENOMEM | |
121 | Insufficient kernel memory was available. | |
122 | .TP | |
123 | .B ENOTDIR | |
124 | A component of the path prefix is not a directory. | |
47297adb | 125 | .SH CONFORMING TO |
5d127cc9 MK |
126 | 4.4BSD |
127 | .RB ( readlink () | |
128 | first appeared in 4.2BSD), | |
97c1eac8 | 129 | POSIX.1-2001. |
889829be | 130 | .SH NOTES |
4595d739 MK |
131 | In versions of glibc up to and including glibc 2.4, the return type of |
132 | .BR readlink () | |
133 | was declared as | |
134 | .IR int . | |
135 | Nowadays, the return type is declared as | |
136 | .IR ssize_t , | |
137 | as (newly) required in POSIX.1-2001. | |
b61acee9 MK |
138 | |
139 | Using a statically sized buffer might not provide enough room for the | |
140 | symbolic link contents. | |
141 | The required size for the buffer can be obtained from the | |
142 | .I stat.st_size | |
143 | value returned by a call to | |
144 | .BR lstat (2) | |
145 | on the link. | |
146 | However, the number of bytes written by | |
147 | .BR readlink () | |
148 | should be checked to make sure that the size of the | |
149 | symbolic link did not increase between the calls. | |
150 | Dynamically allocating the buffer for | |
151 | .BR readlink () | |
152 | also addresses a common portability problem when using | |
153 | .I PATH_MAX | |
154 | for the buffer size, | |
155 | as this constant is not guaranteed to be defined per POSIX | |
156 | if the system does not have such limit. | |
f91c6bd7 | 157 | .SH EXAMPLE |
b61acee9 | 158 | The following program allocates the buffer needed by |
f91c6bd7 GJ |
159 | .BR readlink () |
160 | dynamically from the information provided by | |
161 | .BR lstat (), | |
b61acee9 | 162 | making sure there's no race condition between the calls. |
f91c6bd7 GJ |
163 | .nf |
164 | ||
165 | #include <sys/types.h> | |
166 | #include <sys/stat.h> | |
167 | #include <stdio.h> | |
168 | #include <stdlib.h> | |
169 | #include <unistd.h> | |
170 | ||
171 | int | |
172 | main(int argc, char *argv[]) | |
173 | { | |
174 | struct stat sb; | |
175 | char *linkname; | |
176 | ssize_t r; | |
177 | ||
178 | if (argc != 2) { | |
179 | fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]); | |
180 | exit(EXIT_FAILURE); | |
181 | } | |
182 | ||
183 | if (lstat(argv[1], &sb) == \-1) { | |
184 | perror("lstat"); | |
185 | exit(EXIT_FAILURE); | |
186 | } | |
187 | ||
188 | linkname = malloc(sb.st_size + 1); | |
189 | if (linkname == NULL) { | |
190 | fprintf(stderr, "insufficient memory\\n"); | |
191 | exit(EXIT_FAILURE); | |
192 | } | |
193 | ||
194 | r = readlink(argv[1], linkname, sb.st_size + 1); | |
1976f57a | 195 | |
4b80b37c | 196 | if (r == \-1) { |
3468b312 | 197 | perror("readlink"); |
f91c6bd7 | 198 | exit(EXIT_FAILURE); |
1976f57a | 199 | } |
b61acee9 | 200 | |
f497e456 | 201 | if (r > sb.st_size) { |
b61acee9 MK |
202 | fprintf(stderr, "symlink increased in size " |
203 | "between lstat() and readlink()\\n"); | |
f91c6bd7 GJ |
204 | exit(EXIT_FAILURE); |
205 | } | |
b61acee9 | 206 | |
c1de8e3e | 207 | linkname[r] = \(aq\\0\(aq; |
f91c6bd7 | 208 | |
836830b4 | 209 | printf("\(aq%s\(aq points to \(aq%s\(aq\\n", argv[1], linkname); |
f91c6bd7 GJ |
210 | |
211 | exit(EXIT_SUCCESS); | |
212 | } | |
213 | .fi | |
47297adb | 214 | .SH SEE ALSO |
c370cc1b | 215 | .BR readlink (1), |
fea681da | 216 | .BR lstat (2), |
591f90f7 | 217 | .BR readlinkat (2), |
fea681da | 218 | .BR stat (2), |
ad7cc990 | 219 | .BR symlink (2), |
a9cfde1d | 220 | .BR path_resolution (7), |
ad22ad55 | 221 | .BR symlink (7) |