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



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

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  appropri-
       ate  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  argu-
       ment, 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 consis-
       tent 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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                    GETCWD(3P)