Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GETCWD(3)		   Linux Programmer's Manual		     GETCWD(3)

       getcwd, get_current_dir_name, getwd - Get current working directory

       #include	<unistd.h>

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

       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

       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.

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

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

       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.

       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.


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

GNU				  2002-04-22			     GETCWD(3)


Want to link to this manual page? Use this URL:

home | help