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

# NAME

`getcwd`, `getwd` — get working directory pathname

# 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 not `NULL` and the length of the pathname plus the terminating NUL character is greater than size, a null pointer is returned and errno is set to `ERANGE`.

As an extension to IEEE Std 1003.1-2001 (“POSIX.1”), if buf is `NULL`, space is allocated as necessary to store the pathname. In this case, it is the responsibility of the caller to free(3) the pointer that `getcwd`() returns.

The deprecated `getwd`() function is similar to `getcwd`(), but assumes that buf is non-NULL and has a size of `PATH_MAX` (as defined by the include file `<limits.h>`). It does not allocate memory and is provided for source compatibility only. If the length of the pathname plus the terminating NUL character is greater than `PATH_MAX`, a null pointer is returned. On error, `getwd`() writes an error message into the memory referenced by buf.

These functions 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 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.
[`EFAULT`]
  buf points to an invalid address.
[`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

pwd(1), chdir(2), malloc(3), strerror(3)

# STANDARDS

The `getcwd`() function conforms to IEEE Std 1003.1-2001 (“POSIX.1”). The ability to specify a null pointer and have `getcwd`() allocate memory as necessary is an extension.

# HISTORY

The `getwd`() function first appeared in 4.0BSD. The `getcwd`() function first appeared in AT&T System V Release 1 UNIX and was reimplemented for 4.3BSD-Net/2.

In OpenBSD 4.0, `getcwd`() was reimplemented on top of the `__getcwd`() system call. Its calling convention differs from the standard function by requiring buf to not be `NULL` and by returning an integer, zero on success, and -1 with corresponding errno on failure. This is visible in the output of kdump(1).

# BUGS

The `getwd`() function does not do sufficient error checking and is not able to return very long, but valid, paths. It is provided for compatibility only.

July 25, 2022 | Debian