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 contain 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  application  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 buffer 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 memory 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  permit  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
       implementations  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
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                                   2003                                             GETCWD(P)