1GETCWD(3)                  Linux Programmer's Manual                 GETCWD(3)
2
3
4

NAME

6       getcwd, getwd, get_current_dir_name - get current working directory
7

SYNOPSIS

9       #include <unistd.h>
10
11       char *getcwd(char *buf, size_t size);
12       char *getwd(char *buf);
13       char *get_current_dir_name(void);
14
15   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
16
17       get_current_dir_name():
18           _GNU_SOURCE
19
20       getwd():
21           Since glibc 2.12:
22               (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
23                   || /* Glibc since 2.19: */ _DEFAULT_SOURCE
24                   || /* Glibc <= 2.19: */ _BSD_SOURCE
25           Before glibc 2.12:
26               _BSD_SOURCE || _XOPEN_SOURCE >= 500
27

DESCRIPTION

29       These  functions return a null-terminated string containing an absolute
30       pathname that is the current working directory of the calling  process.
31       The  pathname  is  returned as the function result and via the argument
32       buf, if present.
33
34       The getcwd() function copies an absolute pathname of the current  work‐
35       ing directory to the array pointed to by buf, which is of length size.
36
37       If  the  length  of the absolute pathname of the current working direc‐
38       tory, including the terminating null byte, exceeds size bytes, NULL  is
39       returned,  and  errno is set to ERANGE; an application should check for
40       this error, and allocate a larger buffer if necessary.
41
42       As an extension to the POSIX.1-2001 standard,  glibc's  getcwd()  allo‐
43       cates  the  buffer dynamically using malloc(3) if buf is NULL.  In this
44       case, the allocated buffer has the length size  unless  size  is  zero,
45       when  buf  is allocated as big as necessary.  The caller should free(3)
46       the returned buffer.
47
48       get_current_dir_name() will malloc(3) an array big enough to  hold  the
49       absolute pathname of the current working directory.  If the environment
50       variable PWD is set, and its value is correct, then that value will  be
51       returned.  The caller should free(3) the returned buffer.
52
53       getwd()  does  not  malloc(3) any memory.  The buf argument should be a
54       pointer to an array at least PATH_MAX bytes long.  If the length of the
55       absolute  pathname of the current working directory, including the ter‐
56       minating null byte, exceeds PATH_MAX bytes, NULL is returned, and errno
57       is  set  to ENAMETOOLONG.  (Note that on some systems, PATH_MAX may not
58       be a compile-time constant; furthermore, its value may  depend  on  the
59       filesystem,  see  pathconf(3).)   For portability and security reasons,
60       use of getwd() is deprecated.
61

RETURN VALUE

63       On success, these functions return a pointer to a string containing the
64       pathname of the current working directory.  In the case of getcwd() and
65       getwd() this is the same value as buf.
66
67       On failure, these functions return NULL, and errno is set  to  indicate
68       the  error.   The contents of the array pointed to by buf are undefined
69       on error.
70

ERRORS

72       EACCES Permission to read or search a component of the filename was de‐
73              nied.
74
75       EFAULT buf points to a bad address.
76
77       EINVAL The size argument is zero and buf is not a null pointer.
78
79       EINVAL getwd(): buf is NULL.
80
81       ENAMETOOLONG
82              getwd():  The  size  of  the  null-terminated  absolute pathname
83              string exceeds PATH_MAX bytes.
84
85       ENOENT The current working directory has been unlinked.
86
87       ENOMEM Out of memory.
88
89       ERANGE The size argument is less than the length of the absolute  path‐
90              name  of  the  working directory, including the terminating null
91              byte.  You need to allocate a bigger array and try again.
92

ATTRIBUTES

94       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
95       tributes(7).
96
97       ┌────────────────────────────────────────┬───────────────┬─────────────┐
98Interface                               Attribute     Value       
99       ├────────────────────────────────────────┼───────────────┼─────────────┤
100getcwd(), getwd()                       │ Thread safety │ MT-Safe     │
101       ├────────────────────────────────────────┼───────────────┼─────────────┤
102get_current_dir_name()                  │ Thread safety │ MT-Safe env │
103       └────────────────────────────────────────┴───────────────┴─────────────┘
104

CONFORMING TO

106       getcwd()  conforms  to  POSIX.1-2001.   Note  however that POSIX.1-2001
107       leaves the behavior of getcwd() unspecified if buf is NULL.
108
109       getwd() is present in POSIX.1-2001, but  marked  LEGACY.   POSIX.1-2008
110       removes   the   specification   of   getwd().   Use  getcwd()  instead.
111       POSIX.1-2001 does not define any errors for getwd().
112
113       get_current_dir_name() is a GNU extension.
114

NOTES

116       Under Linux, these functions make  use  of  the  getcwd()  system  call
117       (available  since  Linux  2.1.92).   On  older systems they would query
118       /proc/self/cwd.  If both system call and proc filesystem are missing, a
119       generic  implementation  is  called.  Only in that case can these calls
120       fail under Linux with EACCES.
121
122       These functions are often used to save  the  location  of  the  current
123       working  directory  for  the purpose of returning to it later.  Opening
124       the current directory (".") and calling fchdir(2) to return is  usually
125       a  faster and more reliable alternative when sufficiently many file de‐
126       scriptors are available, especially on platforms other than Linux.
127
128   C library/kernel differences
129       On Linux, the kernel provides a getcwd() system call, which  the  func‐
130       tions  described  in  this  page will use if possible.  The system call
131       takes the same arguments as the library function of the same name,  but
132       is  limited  to  returning at most PATH_MAX bytes.  (Before Linux 3.12,
133       the limit on the size of the returned  pathname  was  the  system  page
134       size.   On  many  architectures,  PATH_MAX and the system page size are
135       both 4096 bytes, but a few architectures have a larger page size.)   If
136       the  length  of  the  pathname of the current working directory exceeds
137       this limit, then the system call fails with the error ENAMETOOLONG.  In
138       this  case,  the  library functions fall back to a (slower) alternative
139       implementation that returns the full pathname.
140
141       Following a change in  Linux  2.6.36,  the  pathname  returned  by  the
142       getcwd()  system  call will be prefixed with the string "(unreachable)"
143       if the current directory is not below the root directory of the current
144       process  (e.g., because the process set a new filesystem root using ch‐
145       root(2) without changing its current  directory  into  the  new  root).
146       Such  behavior  can  also be caused by an unprivileged user by changing
147       the current directory into another mount namespace.  When dealing  with
148       pathname  from untrusted sources, callers of the functions described in
149       this page should consider checking whether the returned pathname starts
150       with '/' or '(' to avoid misinterpreting an unreachable path as a rela‐
151       tive pathname.
152

BUGS

154       Since the Linux 2.6.36 change that added "(unreachable)" in the circum‐
155       stances  described  above,  the  glibc  implementation  of getcwd() has
156       failed to conform to POSIX and returned a relative  pathname  when  the
157       API  contract  requires  an absolute pathname.  With glibc 2.27 onwards
158       this is corrected; calling getcwd() from such a pathname will  now  re‐
159       sult in failure with ENOENT.
160

SEE ALSO

162       pwd(1), chdir(2), fchdir(2), open(2), unlink(2), free(3), malloc(3)
163

COLOPHON

165       This  page  is  part of release 5.13 of the Linux man-pages project.  A
166       description of the project, information about reporting bugs,  and  the
167       latest     version     of     this    page,    can    be    found    at
168       https://www.kernel.org/doc/man-pages/.
169
170
171
172GNU                               2021-03-22                         GETCWD(3)
Impressum