Unix/Linux Go Back    


Linux 2.6 - man page for getcwd (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


GETCWD(P)			    POSIX Programmer's Manual				GETCWD(P)

NAME
       getcwd - get the pathname of the current working directory

SYNOPSIS
       #include <unistd.h>

       char *getcwd(char *buf, size_t size);

DESCRIPTION
       The getcwd() function shall place an absolute pathname of the current working directory in
       the array pointed to by buf, and return buf. The pathname copied to the array  shall  con-
       tain  no components that are symbolic links. The size argument is the size in bytes of the
       character array pointed to by the buf argument. If buf is a null pointer, the behavior  of
       getcwd() is unspecified.

RETURN VALUE
       Upon  successful  completion,  getcwd() shall return the buf argument. Otherwise, getcwd()
       shall return a null pointer and set errno to indicate the error. The contents of the array
       pointed to by buf are then undefined.

ERRORS
       The getcwd() function shall fail if:

       EINVAL The size argument is 0.

       ERANGE The size argument is greater than 0, but is smaller than the length of the pathname
	      +1.

       The getcwd() function may fail if:

       EACCES Read or search permission was denied for a component of the pathname.

       ENOMEM Insufficient storage space is available.

       The following sections are informative.

EXAMPLES
   Determining the Absolute Pathname of the Current Working Directory
       The following example returns a pointer to an array that holds the  absolute  pathname  of
       the  current  working directory. The pointer is returned in the ptr variable, which points
       to the buf array where the pathname is stored.

	      #include <stdlib.h>
	      #include <unistd.h>
	      ...
	      long size;
	      char *buf;
	      char *ptr;

	      size = pathconf(".", _PC_PATH_MAX);

	      if ((buf = (char *)malloc((size_t)size)) != NULL)
		  ptr = getcwd(buf, (size_t)size);
	      ...

APPLICATION USAGE
       None.

RATIONALE
       Since the maximum pathname length is arbitrary unless {PATH_MAX} is defined,  an  applica-
       tion generally cannot supply a buf with size {{PATH_MAX}+1}.

       Having  getcwd()  take no arguments and instead use the malloc() function to produce space
       for the returned argument was considered. The advantage is that getcwd() knows how big the
       working	directory  pathname  is  and can allocate an appropriate amount of space. But the
       programmer would have to use the free() function to free the resulting object, or each use
       of  getcwd() would further reduce the available memory. Also, malloc() and free() are used
       nowhere else in this volume of IEEE Std 1003.1-2001. Finally, getcwd() is taken	from  the
       SVID where it has the two arguments used in this volume of IEEE Std 1003.1-2001.

       The older function getwd() was rejected for use in this context because it had only a buf-
       fer argument and no size argument, and thus had no way to prevent overwriting the  buffer,
       except to depend on the programmer to provide a large enough buffer.

       On  some implementations, if buf is a null pointer, getcwd() may obtain size bytes of mem-
       ory using malloc(). In this case, the pointer returned by getcwd()  may	be  used  as  the
       argument  in  a subsequent call to free(). Invoking getcwd() with buf as a null pointer is
       not recommended in conforming applications.

       If a program is operating in a directory where some (grand)parent directory does not  per-
       mit  reading,  getcwd() may fail, as in most implementations it must read the directory to
       determine the name of the file. This can occur if search,  but  not  read,  permission  is
       granted	in  an	intermediate  directory, or if the program is placed in that directory by
       some more privileged process (for example, login). Including the [EACCES] error	condition
       makes the reporting of the error consistent and warns the application writer that getcwd()
       can fail for reasons beyond the control of the application writer or user. Some	implemen-
       tations	can avoid this occurrence (for example, by implementing getcwd() using pwd, where
       pwd is a set-user-root process), thus the error was made optional. Since  this  volume  of
       IEEE Std 1003.1-2001 permits the addition of other errors, this would be a common addition
       and yet one that applications could not be expected to deal with without this addition.

FUTURE DIRECTIONS
       None.

SEE ALSO
       malloc() , the Base Definitions volume of IEEE Std 1003.1-2001, <unistd.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					GETCWD(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:10 AM.