GETCWD(3)

GETCWD(3) | Library Functions Manual | GETCWD(3)

# NAME

getcwd, getwd — get working directory pathname

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

#include <unistd.h>
char *
getcwd(char *buf, size_t size);
char *
getwd(char *buf);

# DESCRIPTION

The getcwd() function copies the absolute pathname of the current working directory into the memory referenced by buf and returns a pointer to buf. The size argument is the size, in bytes, of the array referenced by buf.
If buf is `NULL`, space is allocated as necessary to store the pathname. This space may later be free(3)'d.
The function getwd() is a compatibility routine which calls getcwd() with its buf argument and a size of `MAXPATHLEN` (as defined in the include file <sys/param.h>). Obviously, buf should be at least `MAXPATHLEN` bytes in length.
These routines have traditionally been used by programs to save the name of a working directory for the purpose of returning to it. A much faster and less error-prone method of accomplishing this is to open the current directory (‘`.`’) and use the fchdir(2) function to return.

# RETURN VALUES

Upon successful completion, a pointer to the pathname is returned. Otherwise a `NULL` pointer is returned and the global variable errno is set to indicate the error. In addition, getwd() copies the error message associated with errno into the memory referenced by buf.

# ERRORS

The getcwd() function will fail if:

[`EACCES`]
  Read or search permission was denied for a component of the pathname.
[`EINVAL`]
  The size argument is zero.
[`ENOENT`]
  A component of the pathname no longer exists.
[`ENOMEM`]
  Insufficient memory is available.
[`ERANGE`]
  The size argument is greater than zero but smaller than the length of the pathname plus 1.

# SEE ALSO

chdir(2), fchdir(2), malloc(3), strerror(3)

# STANDARDS

The getwd() and getcwd() functions conform to IEEE Std 1003.1-1990 (“POSIX.1”). The IEEE Std 1003.1-2004 (“POSIX.1”) revision marked getwd() as legacy and recommended the use of getcwd() instead. The IEEE Std 1003.1-2008 (“POSIX.1”) revision removed getwd() from the specification.
The ability to specify a `NULL` pointer and have getcwd() allocate memory as necessary is an extension.

# HISTORY

The getwd() function appeared in 4.0BSD.

# SECURITY CONSIDERATIONS

As getwd() does not know the length of the supplied buffer, it is possible for a long (but valid) path to overflow the buffer and provide a means for an attacker to exploit the caller. getcwd() should be used in place of getwd() (the latter is only provided for compatibility purposes).

April 29, 2010 | NetBSD 8.0