Debian Codegraph @

upstream/debian-trixie/man3/realpath.3

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