Debian Codegraph @

upstream/debian-unstable/man3/getcwd.3

raw
1 '\" t
2 .\" Copyright 1993, Thomas Koenig <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH getcwd 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 getcwd, getwd, get_current_dir_name \- get current working directory
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .BR "char *getcwd(" "size_t size;"
18 .BI " char " buf [ size "], size_t " size );
19 .B "char *get_current_dir_name(void);"
20 .P
21 .BI "[[deprecated]] char *getwd(char " buf [PATH_MAX]);
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 get_current_dir_name ():
30 .nf
31 _GNU_SOURCE
32 .fi
33 .P
34 .BR getwd ():
35 .nf
36 Since glibc 2.12:
37 (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
38 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
39 || /* glibc <= 2.19: */ _BSD_SOURCE
40 Before glibc 2.12:
41 _BSD_SOURCE || _XOPEN_SOURCE >= 500
42 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
43 .fi
44 .SH DESCRIPTION
45 These functions return a null-terminated string containing an
46 absolute pathname that is the current working directory of
47 the calling process.
48 The pathname is returned as the function result and via the argument
49 .IR buf ,
50 if present.
51 .P
52 The
53 .BR getcwd ()
54 function copies an absolute pathname of the current working directory
55 to the array pointed to by
56 .IR buf ,
57 which is of length
58 .IR size .
59 .P
60 If the length of the absolute pathname of the current working directory,
61 including the terminating null byte, exceeds
62 .I size
63 bytes, NULL is returned, and
64 .I errno
65 is set to
66 .BR ERANGE ;
67 an application should check for this error, and allocate a larger
68 buffer if necessary.
69 .P
70 As an extension to the POSIX.1-2001 standard, glibc's
71 .BR getcwd ()
72 allocates the buffer dynamically using
73 .BR malloc (3)
74 if
75 .I buf
76 is NULL.
77 In this case, the allocated buffer has the length
78 .I size
79 unless
80 .I size
81 is zero, when
82 .I buf
83 is allocated as big as necessary.
84 The caller should
85 .BR free (3)
86 the returned buffer.
87 .P
88 .BR get_current_dir_name ()
89 will
90 .BR malloc (3)
91 an array big enough to hold the absolute pathname of
92 the current working directory.
93 If the environment
94 variable
95 .B PWD
96 is set, and its value is correct, then that value will be returned.
97 The caller should
98 .BR free (3)
99 the returned buffer.
100 .P
101 .BR getwd ()
102 does not
103 .BR malloc (3)
104 any memory.
105 The
106 .I buf
107 argument should be a pointer to an array at least
108 .B PATH_MAX
109 bytes long.
110 If the length of the absolute pathname of the current working directory,
111 including the terminating null byte, exceeds
112 .B PATH_MAX
113 bytes, NULL is returned, and
114 .I errno
115 is set to
116 .BR ENAMETOOLONG .
117 (Note that on some systems,
118 .B PATH_MAX
119 may not be a compile-time constant;
120 furthermore, its value may depend on the filesystem, see
121 .BR pathconf (3).)
122 For portability and security reasons, use of
123 .BR getwd ()
124 is deprecated.
125 .SH RETURN VALUE
126 On success, these functions return a pointer to a string containing
127 the pathname of the current working directory.
128 In the case of
129 .BR getcwd ()
130 and
131 .BR getwd ()
132 this is the same value as
133 .IR buf .
134 .P
135 On failure, these functions return NULL, and
136 .I errno
137 is set to indicate the error.
138 The contents of the array pointed to by
139 .I buf
140 are undefined on error.
141 .SH ERRORS
142 .TP
143 .B EACCES
144 Permission to read or search a component of the filename was denied.
145 .TP
146 .B EFAULT
147 .I buf
148 points to a bad address.
149 .TP
150 .B EINVAL
151 The
152 .I size
153 argument is zero and
154 .I buf
155 is not a null pointer.
156 .TP
157 .B EINVAL
158 .BR getwd ():
159 .I buf
160 is NULL.
161 .TP
162 .B ENAMETOOLONG
163 .BR getwd ():
164 The size of the null-terminated absolute pathname string exceeds
165 .B PATH_MAX
166 bytes.
167 .TP
168 .B ENOENT
169 The current working directory has been unlinked.
170 .TP
171 .B ENOMEM
172 Out of memory.
173 .TP
174 .B ERANGE
175 The
176 .I size
177 argument is less than the length of the absolute pathname of the
178 working directory, including the terminating null byte.
179 You need to allocate a bigger array and try again.
180 .SH ATTRIBUTES
181 For an explanation of the terms used in this section, see
182 .BR attributes (7).
183 .TS
184 allbox;
185 lbx lb lb
186 l l l.
187 Interface Attribute Value
188 T{
189 .na
190 .nh
191 .BR getcwd (),
192 .BR getwd ()
193 T} Thread safety MT-Safe
194 T{
195 .na
196 .nh
197 .BR get_current_dir_name ()
198 T} Thread safety MT-Safe env
199 .TE
200 .SH VERSIONS
201 POSIX.1-2001 leaves the behavior of
202 .BR getcwd ()
203 unspecified if
204 .I buf
205 is NULL.
206 .P
207 POSIX.1-2001
208 does not define any errors for
209 .BR getwd ().
210 .SH VERSIONS
211 .SS C library/kernel differences
212 On Linux, the kernel provides a
213 .BR getcwd ()
214 system call, which the functions described in this page will use if possible.
215 The system call takes the same arguments as the library function
216 of the same name, but is limited to returning at most
217 .B PATH_MAX
218 bytes.
219 (Before Linux 3.12,
220 .\" commit 3272c544da48f8915a0e34189182aed029bd0f2b
221 the limit on the size of the returned pathname was the system page size.
222 On many architectures,
223 .B PATH_MAX
224 and the system page size are both 4096 bytes,
225 but a few architectures have a larger page size.)
226 If the length of the pathname of the current working directory
227 exceeds this limit, then the system call fails with the error
228 .BR ENAMETOOLONG .
229 In this case, the library functions fall back to
230 a (slower) alternative implementation that returns the full pathname.
231 .P
232 Following a change in Linux 2.6.36,
233 .\" commit 8df9d1a4142311c084ffeeacb67cd34d190eff74
234 the pathname returned by the
235 .BR getcwd ()
236 system call will be prefixed with the string "(unreachable)"
237 if the current directory is not below the root directory of the current
238 process (e.g., because the process set a new filesystem root using
239 .BR chroot (2)
240 without changing its current directory into the new root).
241 Such behavior can also be caused by an unprivileged user by changing
242 the current directory into another mount namespace.
243 When dealing with pathnames from untrusted sources, callers of the
244 functions described in this page (before glibc 2.27)
245 or the raw
246 .BR getcwd ()
247 system call
248 should consider checking whether the returned pathname starts
249 with '/' or '(' to avoid misinterpreting an unreachable path
250 as a relative pathname.
251 .SH STANDARDS
252 .TP
253 .BR getcwd ()
254 POSIX.1-2008.
255 .TP
256 .BR get_current_dir_name ()
257 GNU.
258 .TP
259 .BR getwd ()
260 None.
261 .SH HISTORY
262 .TP
263 .BR getcwd ()
264 POSIX.1-2001.
265 .TP
266 .BR getwd ()
267 POSIX.1-2001, but marked LEGACY.
268 Removed in POSIX.1-2008.
269 Use
270 .BR getcwd ()
271 instead.
272 .P
273 Under Linux, these functions make use of the
274 .BR getcwd ()
275 system call (available since Linux 2.1.92).
276 On older systems they would query
277 .IR /proc/self/cwd .
278 If both system call and proc filesystem are missing, a
279 generic implementation is called.
280 Only in that case can
281 these calls fail under Linux with
282 .BR EACCES .
283 .SH NOTES
284 These functions are often used to save the location of the current working
285 directory for the purpose of returning to it later.
286 Opening the current
287 directory (".") and calling
288 .BR fchdir (2)
289 to return is usually a faster and more reliable alternative when sufficiently
290 many file descriptors are available, especially on platforms other than Linux.
291 .SH BUGS
292 Since the Linux 2.6.36 change that added "(unreachable)" in the
293 circumstances described above, the glibc implementation of
294 .BR getcwd ()
295 has failed to conform to POSIX and returned a relative pathname when the API
296 contract requires an absolute pathname.
297 With glibc 2.27 onwards this is corrected;
298 calling
299 .BR getcwd ()
300 from such a pathname will now result in failure with
301 .BR ENOENT .
302 .SH SEE ALSO
303 .BR pwd (1),
304 .BR chdir (2),
305 .BR fchdir (2),
306 .BR open (2),
307 .BR unlink (2),
308 .BR free (3),
309 .BR malloc (3)