getcwd

GETCWD(3)                  Linux Programmer's Manual                 GETCWD(3)



NAME
       getcwd, get_current_dir_name, getwd - Get current working directory

SYNOPSIS
       #include <unistd.h>

       char *getcwd(char *buf, size_t size);
       char *get_current_dir_name(void);
       char *getwd(char *buf);

DESCRIPTION
       The  getcwd() function copies an absolute pathname of the current work-
       ing directory to the array pointed to by buf, which is of length  size.

       If  the  current  absolute path name would require a buffer longer than
       size elements, NULL is returned, and errno is set to ERANGE; an  appli-
       cation  should  check  for  this error, and allocate a larger buffer if
       necessary.

       If buf is NULL, the behaviour of getcwd() is undefined.

       As an extension to the POSIX.1 standard, Linux  (libc4,  libc5,  glibc)
       getcwd() allocates the buffer dynamically using malloc() if buf is NULL
       on call.  In this case, the allocated buffer has the length size unless
       size  is zero, when buf is allocated as big as necessary.  It is possi-
       ble (and, indeed, advisable) to free() the buffers if  they  have  been
       obtained this way.

       get_current_dir_name,  which  is  only  prototyped  if  _GNU_SOURCE  is
       defined, will malloc(3) an array big enough to hold the current  direc-
       tory  name.   If  the environment variable PWD is set, and its value is
       correct, then that value will be returned.

       getwd,    which    is    only    prototyped    if    _BSD_SOURCE     or
       _XOPEN_SOURCE_EXTENDED  is  defined, will not malloc(3) any memory. The
       buf argument should be a pointer to an array at  least  PATH_MAX  bytes
       long.   getwd  does  only return the first PATH_MAX bytes of the actual
       pathname.  Note that PATH_MAX need not be a compile-time  constant;  it
       may depend on the filesystem and may even be unlimited. For portability
       and security reasons, use of getwd is deprecated.

RETURN VALUE
       NULL on failure with errno set accordingly, and  buf  on  success.  The
       contents of the array pointed to by buf is undefined on error.

ERRORS
       EACCES Permission  to  read  or search a component of the file name was
              denied.

       EFAULT buf points to a bad address.

       EINVAL The size argument is zero and buf is not a null pointer.

       ENOENT The current working directory has been unlinked.

       ERANGE The size argument is less than the length of the working  direc-
              tory name.  You need to allocate a bigger array and try again.

NOTES
       Under Linux, the function getcwd() is a system call (since 2.1.92).  On
       older systems it would query /proc/self/cwd.  If both system  call  and
       proc  file system are missing, a generic implementation is called. Only
       in that case can these calls fail under Linux with EACCES.

       These functions are often used to save  the  location  of  the  current
       working directory for the purpose of returning to it later. Opening the
       current directory (".") and calling fchdir(2) to return  is  usually  a
       faster  and  more  reliable  alternative  when  sufficiently  many file
       descriptors are available, especially on platforms other than Linux.

CONFORMING TO
       POSIX.1

SEE ALSO
       chdir(2), fchdir(2), open(2), unlink(2), free(3), malloc(3)



GNU                               2002-04-22                         GETCWD(3)