1GETCWD(3P) POSIX Programmer's Manual GETCWD(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 getcwd — get the pathname of the current working directory
13
15 #include <unistd.h>
16 char *getcwd(char *buf, size_t size);
18
20 The getcwd() function shall place an absolute pathname of the current
21 working directory in the array pointed to by buf, and return buf. The
22 pathname shall contain no components that are dot or dot-dot, or are
23 symbolic links.
24 If there are multiple pathnames that getcwd() could place in the array
26 pointed to by buf, one beginning with a single <slash> character and
27 one or more beginning with two <slash> characters, then getcwd() shall
28 place the pathname beginning with a single <slash> character in the
29 array. The pathname shall not contain any unnecessary <slash> charac‐
30 ters after the leading one or two <slash> characters.
31 The size argument is the size in bytes of the character array pointed
33 to by the buf argument. If buf is a null pointer, the behavior of
34 getcwd() is unspecified.
35
37 Upon successful completion, getcwd() shall return the buf argument.
38 Otherwise, getcwd() shall return a null pointer and set errno to indi‐
39 cate the error. The contents of the array pointed to by buf are then
40 undefined.
41
43 The getcwd() function shall fail if:
44 EINVAL The size argument is 0.
46 ERANGE The size argument is greater than 0, but is smaller than the
48 length of the string +1.
49 The getcwd() function may fail if:
51 EACCES Search permission was denied for the current directory, or read
53 or search permission was denied for a directory above the cur‐
54 rent directory in the file hierarchy.
55 ENOMEM Insufficient storage space is available.
57 The following sections are informative.
59
61 The following example uses {PATH_MAX} as the initial buffer size
62 (unless it is indeterminate or very large), and calls getcwd() with
63 progressively larger buffers until it does not give an [ERANGE] error.
64 #include <stdlib.h>
67 #include <errno.h>
68 #include <unistd.h>
69 ...
71 long path_max;
73 size_t size;
74 char *buf;
75 char *ptr;
76 path_max = pathconf(".", _PC_PATH_MAX);
78 if (path_max == -1)
79 size = 1024;
80 else if (path_max > 10240)
81 size = 10240;
82 else
83 size = path_max;
84 for (buf = ptr = NULL; ptr == NULL; size *= 2)
86 {
87 if ((buf = realloc(buf, size)) == NULL)
88 {
89 ... handle error ...
90 }
91 ptr = getcwd(buf, size);
93 if (ptr == NULL && errno != ERANGE)
94 {
95 ... handle error ...
96 }
97 }
98 ...
99 free (buf);
100
102 If the pathname obtained from getcwd() is longer than {PATH_MAX} bytes,
103 it could produce an [ENAMETOOLONG] error if passed to chdir(). There‐
104 fore, in order to return to that directory it may be necessary to break
105 the pathname into sections shorter than {PATH_MAX} bytes and call
106 chdir() on each section in turn (the first section being an absolute
107 pathname and subsequent sections being relative pathnames). A simpler
108 way to handle saving and restoring the working directory when it may be
109 deeper than {PATH_MAX} bytes in the file hierarchy is to use a file
110 descriptor and fchdir(), rather than getcwd() and chdir(). However,
111 the two methods do have some differences. The fchdir() approach causes
112 the program to restore a working directory even if it has been renamed
113 in the meantime, whereas the chdir() approach restores to a directory
114 with the same name as the original, even if the directories were
115 renamed in the meantime. Since the fchdir() approach does not access
116 parent directories, it can succeed when getcwd() would fail due to per‐
117 missions problems. In applications conforming to earlier versions of
118 this standard, it was not possible to use the fchdir() approach when
119 the working directory is searchable but not readable, as the only way
120 to open a directory was with O_RDONLY, whereas the getcwd() approach
121 can succeed in this case.
122
124 Having getcwd() take no arguments and instead use the malloc() function
125 to produce space for the returned argument was considered. The advan‐
126 tage is that getcwd() knows how big the working directory pathname is
127 and can allocate an appropriate amount of space. But the programmer
128 would have to use the free() function to free the resulting object, or
129 each use of getcwd() would further reduce the available memory.
130 Finally, getcwd() is taken from the SVID where it has the two arguments
131 used in this volume of POSIX.1‐2017.
132 The older function getwd() was rejected for use in this context because
134 it had only a buffer argument and no size argument, and thus had no way
135 to prevent overwriting the buffer, except to depend on the programmer
136 to provide a large enough buffer.
137 On some implementations, if buf is a null pointer, getcwd() may obtain
139 size bytes of memory using malloc(). In this case, the pointer
140 returned by getcwd() may be used as the argument in a subsequent call
141 to free(). Invoking getcwd() with buf as a null pointer is not recom‐
142 mended in conforming applications.
143 Earlier implementations of getcwd() sometimes generated pathnames like
145 "../../../subdirname" internally, using them to explore the path of
146 ancestor directories back to the root. If one of these internal path‐
147 names exceeded {PATH_MAX} in length, the implementation could fail with
148 errno set to [ENAMETOOLONG]. This is no longer allowed.
149 If a program is operating in a directory where some (grand)parent
151 directory does not permit reading, getcwd() may fail, as in most imple‐
152 mentations it must read the directory to determine the name of the
153 file. This can occur if search, but not read, permission is granted in
154 an intermediate directory, or if the program is placed in that direc‐
155 tory by some more privileged process (for example, login). Including
156 the [EACCES] error condition makes the reporting of the error consis‐
157 tent and warns the application developer that getcwd() can fail for
158 reasons beyond the control of the application developer or user. Some
159 implementations can avoid this occurrence (for example, by implementing
160 getcwd() using pwd, where pwd is a set-user-root process), thus the
161 error was made optional. Since this volume of POSIX.1‐2017 permits the
162 addition of other errors, this would be a common addition and yet one
163 that applications could not be expected to deal with without this addi‐
164 tion.
165
167 None.
168
170 malloc()
171 The Base Definitions volume of POSIX.1‐2017, <unistd.h>
173
175 Portions of this text are reprinted and reproduced in electronic form
176 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
177 table Operating System Interface (POSIX), The Open Group Base Specifi‐
178 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
179 Electrical and Electronics Engineers, Inc and The Open Group. In the
180 event of any discrepancy between this version and the original IEEE and
181 The Open Group Standard, the original IEEE and The Open Group Standard
182 is the referee document. The original Standard can be obtained online
183 at http://www.opengroup.org/unix/online.html .
184 Any typographical or formatting errors that appear in this page are
186 most likely to have been introduced during the conversion of the source
187 files to man page format. To report such errors, see https://www.ker‐
188 nel.org/doc/man-pages/reporting_bugs.html .
189IEEE/The Open Group 2017 GETCWD(3P)