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 9.0