|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
GETCWD(3P) POSIX Programmer's Manual GETCWD(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.
getcwd — get the pathname of the current working directory
#include <unistd.h>
char *getcwd(char *buf, size_t size);
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.
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.
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.
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);
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.
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‐2008.
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‐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.
None.
malloc(3p)
The Base Definitions volume of POSIX.1‐2008, unistd.h(0p)
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 http://www.unix.org/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 .
IEEE/The Open Group 2013 GETCWD(3P)
Pages that refer to this page: unistd.h(0p), pwd(1p), chdir(3p), realpath(3p)