GETCWD(3P) POSIX Programmer's Manual GETCWD(3P)
PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the correspond-
ing 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 copied to the array shall contain no components that are symbolic links. 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 indi-
cate 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 pathname +1.
The getcwd() function may fail if:
EACCES Read or search permission was denied for a component of the pathname.
ENOMEM Insufficient storage space is available.
The following sections are informative.
EXAMPLES
Determining the Absolute Pathname of the Current Working Directory
The following example returns a pointer to an array that holds the absolute pathname of the current working directory. The pointer is
returned in the ptr variable, which points to the buf array where the pathname is stored.
#include <stdlib.h>
#include <unistd.h>
...
long size;
char *buf;
char *ptr;
size = pathconf(".", _PC_PATH_MAX);
if ((buf = (char *)malloc((size_t)size)) != NULL)
ptr = getcwd(buf, (size_t)size);
...
APPLICATION USAGE
None.
RATIONALE
Since the maximum pathname length is arbitrary unless {PATH_MAX} is defined, an application generally cannot supply a buf with size
{{PATH_MAX}+1}.
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 pro-
grammer would have to use the free() function to free the resulting object, or each use of getcwd() would further reduce the available mem-
ory. Also, malloc() and free() are used nowhere else in this volume of IEEE Std 1003.1-2001. Finally, getcwd() is taken from the SVID where
it has the two arguments used in this volume of IEEE Std 1003.1-2001.
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 recom-
mended in conforming applications.
If a program is operating in a directory where some (grand)parent directory does not permit reading, getcwd() may fail, as in most imple-
mentations 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 writer that getcwd() can fail for rea-
sons beyond the control of the application writer 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 IEEE Std 1003.1-2001 per-
mits 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 IEEE Std 1003.1-2001, <unistd.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technol-
ogy -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 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 .
IEEE
/The Open Group 2003 GETCWD(3P)