Section: POSIX Programmer's Manual (3P)
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
--- get the pathname of the current working directory
char *getcwd(char *buf, size_t size);
function shall place an absolute pathname of the current working directory
in the array pointed to by
The pathname shall contain no components that are dot or dot-dot, or
are symbolic links.
If there are multiple pathnames that
could place in the array pointed to by
one beginning with a single
character and one or more beginning with two
shall place the pathname beginning with a single
character in the array. The pathname shall not contain any unnecessary
characters after the leading one or two
argument is the size in bytes of the character array pointed to by the
is a null pointer, the behavior of
Upon successful completion,
shall return the
shall return a null pointer and set
to indicate the error. The contents of the array pointed to by
are then undefined.
function shall fail if:
argument is 0.
argument is greater than 0, but is smaller than the length of
the string +1.
function may fail if:
Search permission was denied for the current directory, or read or search
permission was denied for a directory above the current directory in
the file hierarchy.
Insufficient storage space is available.
The following sections are informative.
The following example uses
as the initial buffer size (unless it is indeterminate or very large),
with progressively larger buffers until it does not give an
path_max = pathconf(".", _PC_PATH_MAX);
if (path_max == -1)
size = 1024;
else if (path_max > 10240)
size = 10240;
size = path_max;
for (buf = ptr = NULL; ptr == NULL; size *= 2)
if ((buf = realloc(buf, size)) == NULL)
... handle error ...
ptr = getcwd(buf, size);
if (ptr == NULL && errno != ERANGE)
... handle error ...
If the pathname obtained from
is longer than
bytes, it could produce an
error if passed to
Therefore, in order to return to that directory it may be necessary to
break the pathname into sections shorter than
bytes and call
on each section in turn (the first section being an absolute pathname and
subsequent sections being relative pathnames). A simpler way to handle
saving and restoring the working directory when it may be deeper than
bytes in the file hierarchy is to use a file descriptor and
However, the two methods do have some differences. The
approach causes the program to restore a working directory even
if it has been renamed in the meantime, whereas the
approach restores to a directory with the same name as the original,
even if the directories were renamed in the meantime. Since the
approach does not access parent directories, it can succeed when
would fail due to permissions problems. In applications conforming to
earlier versions of this standard, it was not possible to use the
approach when the working directory is searchable but not readable,
as the only way to open a directory was with O_RDONLY, whereas the
approach can succeed in this case.
take no arguments and instead use the
function to produce space for the returned argument was considered.
The advantage is that
knows how big the working directory pathname is and can allocate an
appropriate amount of space. But the programmer would have to use the
function to free the resulting object, or each use of
would further reduce the available memory. Finally,
is taken from the SVID where it has the two arguments used in this volume of POSIX.1-2008.
The older function
was rejected for use in this context because it had only a buffer
argument and no
argument, and thus had no way to prevent overwriting the buffer, except
to depend on the programmer to provide a large enough buffer.
On some implementations, if
is a null pointer,
bytes of memory using
In this case, the pointer returned by
may be used as the argument in a subsequent call to
as a null pointer is not recommended in conforming applications.
Earlier implementations of
sometimes generated pathnames like
internally, using them to explore the path of ancestor directories back
to the root. If one of these internal pathnames exceeded
in length, the implementation could fail with
This is no longer allowed.
If a program is operating in a directory where some (grand)parent
directory does not permit reading,
may fail, as in most implementations it must read the directory to
determine the name of the file. This can occur if search, but not read,
permission is granted in an intermediate directory, or if the program
is placed in that directory by some more privileged process (for
example, login). Including the
error condition makes the reporting of the error consistent and warns
the application developer that
can fail for reasons beyond the control of the application developer or
user. Some implementations can avoid this occurrence (for example, by
is a set-user-root process),
thus the error was made optional. Since this volume of POSIX.1-2008 permits the addition of
other errors, this would be a common addition and yet one that
applications could not be expected to deal with without this addition.
The Base Definitions volume of POSIX.1-2008,
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see