Debian Codegraph @

upstream/debian-unstable/man3/realpath.3

raw
1 '\" t
2 .\" Copyright 1999, Andries E. Brouwer <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH realpath 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 realpath \- return the canonicalized absolute pathname
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <limits.h>
16 .B #include <stdlib.h>
17 .P
18 .BI "char *realpath(const char *restrict " path ,
19 .BI " char *restrict " resolved_path );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR realpath ():
28 .nf
29 _XOPEN_SOURCE >= 500
30 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
31 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
32 || /* glibc <= 2.19: */ _BSD_SOURCE
33 .fi
34 .SH DESCRIPTION
35 .BR realpath ()
36 expands all symbolic links and resolves references
37 to
38 .IR "/./" ", " "/../"
39 and extra \[aq]/\[aq]
40 characters in the null-terminated string named by
41 .I path
42 to produce a canonicalized absolute pathname.
43 The resulting pathname is stored as a null-terminated string,
44 up to a maximum of
45 .B PATH_MAX
46 bytes,
47 in the buffer pointed to by
48 .IR resolved_path .
49 The resulting path will have no symbolic link,
50 .I "/./"
51 or
52 .I "/../"
53 components.
54 .P
55 If
56 .I resolved_path
57 is specified as NULL, then
58 .BR realpath ()
59 uses
60 .BR malloc (3)
61 to allocate a buffer of up to
62 .B PATH_MAX
63 bytes to hold the resolved pathname,
64 and returns a pointer to this buffer.
65 The caller should deallocate this buffer using
66 .BR free (3).
67 .\" Even if we use resolved_path == NULL, then realpath() will still
68 .\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX
69 .\" bytes -- MTK, Dec 04
70 .SH RETURN VALUE
71 If there is no error,
72 .BR realpath ()
73 returns a pointer to the
74 .IR resolved_path .
75 .P
76 Otherwise, it returns NULL, the contents
77 of the array
78 .I resolved_path
79 are undefined, and
80 .I errno
81 is set to indicate the error.
82 .SH ERRORS
83 .TP
84 .B EACCES
85 Read or search permission was denied for a component of the path prefix.
86 .TP
87 .B EINVAL
88 .I path
89 is NULL.
90 .\" (In libc5 this would just cause a segfault.)
91 (Before glibc 2.3,
92 this error is also returned if
93 .I resolved_path
94 is NULL.)
95 .TP
96 .B EIO
97 An I/O error occurred while reading from the filesystem.
98 .TP
99 .B ELOOP
100 Too many symbolic links were encountered in translating the pathname.
101 .TP
102 .B ENAMETOOLONG
103 A component of a pathname exceeded
104 .B NAME_MAX
105 characters, or an entire pathname exceeded
106 .B PATH_MAX
107 characters.
108 .TP
109 .B ENOENT
110 The named file does not exist.
111 .TP
112 .B ENOMEM
113 Out of memory.
114 .TP
115 .B ENOTDIR
116 A component of the path prefix is not a directory.
117 .SH ATTRIBUTES
118 For an explanation of the terms used in this section, see
119 .BR attributes (7).
120 .TS
121 allbox;
122 lbx lb lb
123 l l l.
124 Interface Attribute Value
125 T{
126 .na
127 .nh
128 .BR realpath ()
129 T} Thread safety MT-Safe
130 .TE
131 .SH VERSIONS
132 .SS GNU extensions
133 If the call fails with either
134 .B EACCES
135 or
136 .B ENOENT
137 and
138 .I resolved_path
139 is not NULL, then the prefix of
140 .I path
141 that is not readable or does not exist is returned in
142 .IR resolved_path .
143 .SH STANDARDS
144 POSIX.1-2008.
145 .SH HISTORY
146 4.4BSD, POSIX.1-2001, Solaris.
147 .P
148 POSIX.1-2001 says that the behavior if
149 .I resolved_path
150 is NULL is implementation-defined.
151 POSIX.1-2008 specifies the behavior described in this page.
152 .P
153 In 4.4BSD and Solaris, the limit on the pathname length is
154 .B MAXPATHLEN
155 (found in
156 .IR <sys/param.h> ).
157 SUSv2 prescribes
158 .B PATH_MAX
159 and
160 .BR NAME_MAX ,
161 as found in
162 .I <limits.h>
163 or provided by the
164 .BR pathconf (3)
165 function.
166 A typical source fragment would be
167 .P
168 .in +4n
169 .EX
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
177 .EE
178 .in
179 .P
180 (But see the BUGS section.)
181 .\".P
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.
191 .\" The prototype of
192 .\" .BR realpath ()
193 .\" is given in \f[I]<unistd.h>\f[] in libc4 and libc5,
194 .\" but in \f[I]<stdlib.h>\f[] everywhere else.
195 .SH BUGS
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,
198 .IR resolved_path .
199 According to POSIX.1-2001 a buffer of size
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
204 .BR pathconf (3).
205 And asking
206 .BR pathconf (3)
207 does not really help, since, on the one hand POSIX warns that
208 the result of
209 .BR pathconf (3)
210 may be huge and unsuitable for mallocing memory,
211 and on the other hand
212 .BR pathconf (3)
213 may return \-1 to signify that
214 .B PATH_MAX
215 is not bounded.
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.
220 .\" .P
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.
226 .SH SEE ALSO
227 .BR realpath (1),
228 .BR readlink (2),
229 .BR canonicalize_file_name (3),
230 .BR getcwd (3),
231 .BR pathconf (3),
232 .BR sysconf (3)