Provided by: manpages-posix-dev_2017a-2_all 
PROLOG
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.
NAME
getcwd — get the pathname of the current working directory
SYNOPSIS
#include <unistd.h>
char *getcwd(char *buf, size_t size);
DESCRIPTION
The getcwd() function shall place an absolute pathname of the current working directory in
the array pointed to by buf, and return buf. The pathname shall contain no components
that are dot or dot-dot, or are symbolic links.
If there are multiple pathnames that getcwd() could place in the array pointed to by buf,
one beginning with a single <slash> character and one or more beginning with two <slash>
characters, then getcwd() shall place the pathname beginning with a single <slash>
character in the array. The pathname shall not contain any unnecessary <slash> characters
after the leading one or two <slash> characters.
The size argument is the size in bytes of the character array pointed to by the buf
argument. If buf is a null pointer, the behavior of getcwd() is unspecified.
RETURN VALUE
Upon successful completion, getcwd() shall return the buf argument. Otherwise, getcwd()
shall return a null pointer and set errno to indicate the error. The contents of the array
pointed to by buf are then undefined.
ERRORS
The getcwd() function shall fail if:
EINVAL The size argument is 0.
ERANGE The size argument is greater than 0, but is smaller than the length of the string
+1.
The getcwd() function may fail if:
EACCES 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.
ENOMEM Insufficient storage space is available.
The following sections are informative.
EXAMPLES
The following example uses {PATH_MAX} as the initial buffer size (unless it is
indeterminate or very large), and calls getcwd() with progressively larger buffers until
it does not give an [ERANGE] error.
#include <stdlib.h>
#include <errno.h>
#include <unistd.h>
...
long path_max;
size_t size;
char *buf;
char *ptr;
path_max = pathconf(".", _PC_PATH_MAX);
if (path_max == -1)
size = 1024;
else if (path_max > 10240)
size = 10240;
else
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 ...
}
}
...
free (buf);
APPLICATION USAGE
If the pathname obtained from getcwd() is longer than {PATH_MAX} bytes, it could produce
an [ENAMETOOLONG] error if passed to chdir(). Therefore, in order to return to that
directory it may be necessary to break the pathname into sections shorter than {PATH_MAX}
bytes and call chdir() 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 {PATH_MAX} bytes in the
file hierarchy is to use a file descriptor and fchdir(), rather than getcwd() and chdir().
However, the two methods do have some differences. The fchdir() approach causes the
program to restore a working directory even if it has been renamed in the meantime,
whereas the chdir() approach restores to a directory with the same name as the original,
even if the directories were renamed in the meantime. Since the fchdir() approach does not
access parent directories, it can succeed when getcwd() would fail due to permissions
problems. In applications conforming to earlier versions of this standard, it was not
possible to use the fchdir() approach when the working directory is searchable but not
readable, as the only way to open a directory was with O_RDONLY, whereas the getcwd()
approach can succeed in this case.
RATIONALE
Having getcwd() take no arguments and instead use the malloc() function to produce space
for the returned argument was considered. The advantage is that getcwd() knows how big
the working directory pathname is and can allocate an appropriate amount of space. But the
programmer would have to use the free() function to free the resulting object, or each use
of getcwd() would further reduce the available memory. Finally, getcwd() is taken from the
SVID where it has the two arguments used in this volume of POSIX.1‐2017.
The older function getwd() was rejected for use in this context because it had only a
buffer argument and no size 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 buf is a null pointer, getcwd() may obtain size bytes of
memory using malloc(). In this case, the pointer returned by getcwd() may be used as the
argument in a subsequent call to free(). Invoking getcwd() with buf as a null pointer is
not recommended in conforming applications.
Earlier implementations of getcwd() sometimes generated pathnames like
"../../../subdirname" internally, using them to explore the path of ancestor directories
back to the root. If one of these internal pathnames exceeded {PATH_MAX} in length, the
implementation could fail with errno set to [ENAMETOOLONG]. This is no longer allowed.
If a program is operating in a directory where some (grand)parent directory does not
permit reading, getcwd() 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 [EACCES] error condition
makes the reporting of the error consistent and warns the application developer that
getcwd() can fail for reasons beyond the control of the application developer or user.
Some implementations can avoid this occurrence (for example, by implementing getcwd()
using pwd, where pwd is a set-user-root process), thus the error was made optional. Since
this volume of POSIX.1‐2017 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.
FUTURE DIRECTIONS
None.
SEE ALSO
malloc()
The Base Definitions volume of POSIX.1‐2017, <unistd.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std
1003.1-2017, Standard for Information Technology -- Portable Operating System Interface
(POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by
the Institute of Electrical and Electronics Engineers, Inc and The Open Group. 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 http://www.opengroup.org/unix/online.html .
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 https://www.kernel.org/doc/man-pages/reporting_bugs.html .