get_current_dir_name

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
       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 portabil-
       ity 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)