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 .