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  de-
       fined, will malloc(3) an	array big enough to hold the current directory
       name.  If the environment variable PWD is set, and its  value  is  cor-
       rect, then that value will be returned.

       getwd,  which  is  only	prototyped if _BSD_SOURCE or _XOPEN_SOURCE_EX-
       TENDED 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 rea-
       sons, 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  de-
       scriptors 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