1GETCWD(3) Linux Programmer's Manual GETCWD(3)
2
6 getcwd, getwd, get_current_dir_name - get current working directory
7
9 #include <unistd.h>
10 char *getcwd(char *buf, size_t size);
12 char *getwd(char *buf);
14 char *get_current_dir_name(void);
16 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18 get_current_dir_name():
20 _GNU_SOURCE
21 getwd():
23 Since glibc 2.12:
24 (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
25 || /* Glibc since 2.19: */ _DEFAULT_SOURCE
26 || /* Glibc versions <= 2.19: */ _BSD_SOURCE
27 Before glibc 2.12:
28 _BSD_SOURCE || _XOPEN_SOURCE >= 500
29
31 These functions return a null-terminated string containing an absolute
32 pathname that is the current working directory of the calling process.
33 The pathname is returned as the function result and via the argument
34 buf, if present.
35 If the current directory is not below the root directory of the current
37 process (e.g., because the process set a new filesystem root using
38 chroot(2) without changing its current directory into the new root),
39 then, since Linux 2.6.36, the returned path will be prefixed with the
40 string "(unreachable)". Such behavior can also be caused by an unpriv‐
41 ileged user by changing the current directory into another mount names‐
42 pace. When dealing with paths from untrusted sources, callers of these
43 functions should consider checking whether the returned path starts
44 with '/' or '(' to avoid misinterpreting an unreachable path as a rela‐
45 tive path. This is no longer true under some C libraries; see NOTES.
46 The getcwd() function copies an absolute pathname of the current work‐
48 ing directory to the array pointed to by buf, which is of length size.
49 If the length of the absolute pathname of the current working direc‐
51 tory, including the terminating null byte, exceeds size bytes, NULL is
52 returned, and errno is set to ERANGE; an application should check for
53 this error, and allocate a larger buffer if necessary.
54 As an extension to the POSIX.1-2001 standard, glibc's getcwd() allo‐
56 cates the buffer dynamically using malloc(3) if buf is NULL. In this
57 case, the allocated buffer has the length size unless size is zero,
58 when buf is allocated as big as necessary. The caller should free(3)
59 the returned buffer.
60 get_current_dir_name() will malloc(3) an array big enough to hold the
62 absolute pathname of the current working directory. If the environment
63 variable PWD is set, and its value is correct, then that value will be
64 returned. The caller should free(3) the returned buffer.
65 getwd() does not malloc(3) any memory. The buf argument should be a
67 pointer to an array at least PATH_MAX bytes long. If the length of the
68 absolute pathname of the current working directory, including the ter‐
69 minating null byte, exceeds PATH_MAX bytes, NULL is returned, and errno
70 is set to ENAMETOOLONG. (Note that on some systems, PATH_MAX may not
71 be a compile-time constant; furthermore, its value may depend on the
72 filesystem, see pathconf(3).) For portability and security reasons,
73 use of getwd() is deprecated.
74
76 On success, these functions return a pointer to a string containing the
77 pathname of the current working directory. In the case getcwd() and
78 getwd() this is the same value as buf.
79 On failure, these functions return NULL, and errno is set to indicate
81 the error. The contents of the array pointed to by buf are undefined
82 on error.
83
85 EACCES Permission to read or search a component of the filename was
86 denied.
87 EFAULT buf points to a bad address.
89 EINVAL The size argument is zero and buf is not a null pointer.
91 EINVAL getwd(): buf is NULL.
93 ENAMETOOLONG
95 getwd(): The size of the null-terminated absolute pathname
96 string exceeds PATH_MAX bytes.
97 ENOENT The current working directory has been unlinked.
99 ENOMEM Out of memory.
101 ERANGE The size argument is less than the length of the absolute path‐
103 name of the working directory, including the terminating null
104 byte. You need to allocate a bigger array and try again.
105
107 For an explanation of the terms used in this section, see
108 attributes(7).
109 ┌───────────────────────┬───────────────┬─────────────┐
111 │Interface │ Attribute │ Value │
112 ├───────────────────────┼───────────────┼─────────────┤
113 │getcwd(), getwd() │ Thread safety │ MT-Safe │
114 ├───────────────────────┼───────────────┼─────────────┤
115 │get_current_dir_name() │ Thread safety │ MT-Safe env │
116 └───────────────────────┴───────────────┴─────────────┘
118 getcwd() conforms to POSIX.1-2001. Note however that POSIX.1-2001
119 leaves the behavior of getcwd() unspecified if buf is NULL.
120 getwd() is present in POSIX.1-2001, but marked LEGACY. POSIX.1-2008
122 removes the specification of getwd(). Use getcwd() instead.
123 POSIX.1-2001 does not define any errors for getwd().
124 get_current_dir_name() is a GNU extension.
126
128 Under Linux, the function getcwd() is a system call (since 2.1.92). On
129 older systems it would query /proc/self/cwd. If both system call and
130 proc filesystem are missing, a generic implementation is called. Only
131 in that case can these calls fail under Linux with EACCES.
132 Since a Linux 2.6.36 change that added "(unreachable)", the glibc
134 getcwd() has failed to conform to POSIX and returned a relative path
135 when the API contract requires an absolute path. With glibc 2.27
136 onwards this is corrected; calling getcwd() from such a path will now
137 result in failure with ENOENT.
138 These functions are often used to save the location of the current
140 working directory for the purpose of returning to it later. Opening
141 the current directory (".") and calling fchdir(2) to return is usually
142 a faster and more reliable alternative when sufficiently many file
143 descriptors are available, especially on platforms other than Linux.
144
146 pwd(1), chdir(2), fchdir(2), open(2), unlink(2), free(3), malloc(3)
147
149 This page is part of release 4.16 of the Linux man-pages project. A
150 description of the project, information about reporting bugs, and the
151 latest version of this page, can be found at
152 https://www.kernel.org/doc/man-pages/.
153GNU 2018-04-30 GETCWD(3)