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
13       char *getwd(char *buf);
14
15       char *get_current_dir_name(void);
16
17   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18
19       get_current_dir_name():
20              _GNU_SOURCE
21
22       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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

ATTRIBUTES

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

CONFORMING TO

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

NOTES

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

BUGS

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

SEE ALSO

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

COLOPHON

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