GETCWD(3)



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  pathname 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-2001  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 possible (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 filename 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-2001.

SEE ALSO
       chdir(2),  fchdir(2),  open(2),  unlink(2),  free(3),  malloc(3),  fea-
       ture_test_macros(7)

GNU                               2002-04-22                         GETCWD(3)

Man(1) output converted with man2html
list of all man pages