]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright (C) 1999 Andries Brouwer (aeb@cwi.nl) |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
5 | .\" |
6 | .\" Rewritten old page, 990824, aeb@cwi.nl | |
7841ad47 | 7 | .\" 2004-12-14, mtk, added discussion of resolved_path == NULL |
fea681da | 8 | .\" |
4c1c5274 | 9 | .TH realpath 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
10 | .SH NAME |
11 | realpath \- return the canonicalized absolute pathname | |
f1d2fd3f AC |
12 | .SH LIBRARY |
13 | Standard C library | |
8fc3b2cf | 14 | .RI ( libc ", " \-lc ) |
fea681da MK |
15 | .SH SYNOPSIS |
16 | .nf | |
17 | .B #include <limits.h> | |
18 | .B #include <stdlib.h> | |
68e4db0a | 19 | .PP |
0f8d366c AC |
20 | .BI "char *realpath(const char *restrict " path , |
21 | .BI " char *restrict " resolved_path ); | |
cc4615cc | 22 | .fi |
68e4db0a | 23 | .PP |
d39ad78f | 24 | .RS -4 |
cc4615cc MK |
25 | Feature Test Macro Requirements for glibc (see |
26 | .BR feature_test_macros (7)): | |
d39ad78f | 27 | .RE |
68e4db0a | 28 | .PP |
cc4615cc | 29 | .BR realpath (): |
9d2adbae | 30 | .nf |
5c10d2c5 MK |
31 | _XOPEN_SOURCE >= 500 |
32 | .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED | |
75c018a1 AC |
33 | || /* glibc >= 2.19: */ _DEFAULT_SOURCE |
34 | || /* glibc <= 2.19: */ _BSD_SOURCE | |
9d2adbae | 35 | .fi |
fea681da | 36 | .SH DESCRIPTION |
7841ad47 | 37 | .BR realpath () |
fea681da MK |
38 | expands all symbolic links and resolves references |
39 | to | |
f8a07a21 | 40 | .IR "/./" ", " "/../" |
b957f81f | 41 | and extra \[aq]/\[aq] |
d0cb7cc6 | 42 | characters in the null-terminated string named by |
fea681da | 43 | .I path |
bf0e2b8a MK |
44 | to produce a canonicalized absolute pathname. |
45 | The resulting pathname is stored as a null-terminated string, | |
46 | up to a maximum of | |
fea681da | 47 | .B PATH_MAX |
5a3b4036 | 48 | bytes, |
bf0e2b8a | 49 | in the buffer pointed to by |
fea681da MK |
50 | .IR resolved_path . |
51 | The resulting path will have no symbolic link, | |
f8a07a21 | 52 | .I "/./" |
fea681da | 53 | or |
f8a07a21 | 54 | .I "/../" |
fea681da | 55 | components. |
847e0d88 | 56 | .PP |
55e80e25 MK |
57 | If |
58 | .I resolved_path | |
59 | is specified as NULL, then | |
60 | .BR realpath () | |
61 | uses | |
62 | .BR malloc (3) | |
63 | to allocate a buffer of up to | |
64 | .B PATH_MAX | |
65 | bytes to hold the resolved pathname, | |
66 | and returns a pointer to this buffer. | |
67 | The caller should deallocate this buffer using | |
68 | .BR free (3). | |
69 | .\" Even if we use resolved_path == NULL, then realpath() will still | |
70 | .\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX | |
71 | .\" bytes -- MTK, Dec 04 | |
47297adb | 72 | .SH RETURN VALUE |
7841ad47 MK |
73 | If there is no error, |
74 | .BR realpath () | |
75 | returns a pointer to the | |
fea681da | 76 | .IR resolved_path . |
847e0d88 | 77 | .PP |
b437fdd9 | 78 | Otherwise, it returns NULL, the contents |
fea681da | 79 | of the array |
c13182ef | 80 | .I resolved_path |
28d03ce9 | 81 | are undefined, and |
c13182ef MK |
82 | .I errno |
83 | is set to indicate the error. | |
fea681da MK |
84 | .SH ERRORS |
85 | .TP | |
86 | .B EACCES | |
87 | Read or search permission was denied for a component of the path prefix. | |
88 | .TP | |
89 | .B EINVAL | |
fea681da | 90 | .I path |
6387216b | 91 | is NULL. |
536bc966 | 92 | .\" (In libc5 this would just cause a segfault.) |
b324e17d | 93 | (Before glibc 2.3, |
536bc966 | 94 | this error is also returned if |
1ae6b2c7 | 95 | .I resolved_path |
536bc966 | 96 | is NULL.) |
fea681da MK |
97 | .TP |
98 | .B EIO | |
9ee4a2b6 | 99 | An I/O error occurred while reading from the filesystem. |
fea681da MK |
100 | .TP |
101 | .B ELOOP | |
102 | Too many symbolic links were encountered in translating the pathname. | |
103 | .TP | |
104 | .B ENAMETOOLONG | |
c13182ef | 105 | A component of a pathname exceeded |
fea681da | 106 | .B NAME_MAX |
c13182ef | 107 | characters, or an entire pathname exceeded |
fea681da MK |
108 | .B PATH_MAX |
109 | characters. | |
110 | .TP | |
111 | .B ENOENT | |
112 | The named file does not exist. | |
113 | .TP | |
66ced968 MK |
114 | .B ENOMEM |
115 | Out of memory. | |
116 | .TP | |
fea681da MK |
117 | .B ENOTDIR |
118 | A component of the path prefix is not a directory. | |
3b8c8d78 MS |
119 | .SH ATTRIBUTES |
120 | For an explanation of the terms used in this section, see | |
121 | .BR attributes (7). | |
122 | .TS | |
123 | allbox; | |
c466875e | 124 | lbx lb lb |
3b8c8d78 MS |
125 | l l l. |
126 | Interface Attribute Value | |
127 | T{ | |
9e54434e BR |
128 | .na |
129 | .nh | |
3b8c8d78 MS |
130 | .BR realpath () |
131 | T} Thread safety MT-Safe | |
132 | .TE | |
c466875e | 133 | .sp 1 |
4131356c AC |
134 | .SH VERSIONS |
135 | .SS GNU extensions | |
136 | If the call fails with either | |
137 | .B EACCES | |
138 | or | |
139 | .B ENOENT | |
140 | and | |
141 | .I resolved_path | |
142 | is not NULL, then the prefix of | |
143 | .I path | |
144 | that is not readable or does not exist is returned in | |
145 | .IR resolved_path . | |
3113c7f3 | 146 | .SH STANDARDS |
4131356c AC |
147 | POSIX.1-2008. |
148 | .SH HISTORY | |
149 | 4.4BSD, POSIX.1-2001, Solaris. | |
847e0d88 | 150 | .PP |
c49e8fc9 | 151 | POSIX.1-2001 says that the behavior if |
55e80e25 MK |
152 | .I resolved_path |
153 | is NULL is implementation-defined. | |
154 | POSIX.1-2008 specifies the behavior described in this page. | |
4131356c | 155 | .PP |
2221c1b9 | 156 | In 4.4BSD and Solaris, the limit on the pathname length is |
2f0af33b | 157 | .B MAXPATHLEN |
c84371c6 | 158 | (found in \fI<sys/param.h>\fP). |
2f0af33b | 159 | SUSv2 prescribes |
0daa9e92 | 160 | .B PATH_MAX |
2f0af33b MK |
161 | and |
162 | .BR NAME_MAX , | |
163 | as found in \fI<limits.h>\fP or provided by the | |
2b2581ee MK |
164 | .BR pathconf (3) |
165 | function. | |
166 | A typical source fragment would be | |
dd3568a1 | 167 | .PP |
a6e2f128 | 168 | .in +4n |
b8302363 | 169 | .EX |
2b2581ee MK |
170 | #ifdef PATH_MAX |
171 | path_max = PATH_MAX; | |
172 | #else | |
173 | path_max = pathconf(path, _PC_PATH_MAX); | |
174 | if (path_max <= 0) | |
175 | path_max = 4096; | |
176 | #endif | |
b8302363 | 177 | .EE |
a6e2f128 | 178 | .in |
dd3568a1 | 179 | .PP |
2b2581ee | 180 | (But see the BUGS section.) |
7f740303 | 181 | .\".PP |
8f826cd8 MK |
182 | .\" 2012-05-05, According to Casper Dik, the statement about |
183 | .\" Solaris was not true at least as far back as 1997, and | |
184 | .\" may never have been true. | |
185 | .\" | |
186 | .\" The 4.4BSD, Linux and SUSv2 versions always return an absolute | |
187 | .\" pathname. | |
188 | .\" Solaris may return a relative pathname when the | |
189 | .\" .I path | |
190 | .\" argument is relative. | |
788b19a2 MK |
191 | .\" The prototype of |
192 | .\" .BR realpath () | |
193 | .\" is given in \fI<unistd.h>\fP in libc4 and libc5, | |
194 | .\" but in \fI<stdlib.h>\fP everywhere else. | |
fea681da | 195 | .SH BUGS |
c49e8fc9 MK |
196 | The POSIX.1-2001 standard version of this function is broken by design, |
197 | since it is impossible to determine a suitable size for the output buffer, | |
7841ad47 | 198 | .IR resolved_path . |
c49e8fc9 | 199 | According to POSIX.1-2001 a buffer of size |
2f0af33b MK |
200 | .B PATH_MAX |
201 | suffices, but | |
202 | .B PATH_MAX | |
203 | need not be a defined constant, and may have to be obtained using | |
fb186734 | 204 | .BR pathconf (3). |
fea681da | 205 | And asking |
fb186734 | 206 | .BR pathconf (3) |
c49e8fc9 | 207 | does not really help, since, on the one hand POSIX warns that |
fea681da | 208 | the result of |
fb186734 | 209 | .BR pathconf (3) |
c49e8fc9 MK |
210 | may be huge and unsuitable for mallocing memory, |
211 | and on the other hand | |
fb186734 | 212 | .BR pathconf (3) |
2f0af33b MK |
213 | may return \-1 to signify that |
214 | .B PATH_MAX | |
215 | is not bounded. | |
c49e8fc9 MK |
216 | The |
217 | .I "resolved_path\ ==\ NULL" | |
218 | feature, not standardized in POSIX.1-2001, | |
219 | but standardized in POSIX.1-2008, allows this design problem to be avoided. | |
788b19a2 MK |
220 | .\" .LP |
221 | .\" The libc4 and libc5 implementation contained a buffer overflow | |
222 | .\" (fixed in libc-5.4.13). | |
223 | .\" Thus, set-user-ID programs like | |
224 | .\" .BR mount (8) | |
225 | .\" needed a private version. | |
47297adb | 226 | .SH SEE ALSO |
9e4f79d4 | 227 | .BR realpath (1), |
fea681da | 228 | .BR readlink (2), |
a8431b7b | 229 | .BR canonicalize_file_name (3), |
fea681da MK |
230 | .BR getcwd (3), |
231 | .BR pathconf (3), | |
232 | .BR sysconf (3) |