# getcwd

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult 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 shall contain no components that are dot
           or dot-dot, or are symbolic links.
    
           If there are multiple pathnames that _getcwd_() could place in the
           array pointed to by _buf_ , one beginning with a single <slash>
           character and one or more beginning with two <slash> characters,
           then _getcwd_() shall place the pathname beginning with a single
           <slash> character in the array. The pathname shall not contain any
           unnecessary <slash> characters after the leading one or two
           <slash> characters.
    
           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 string +1.
    
           The _getcwd_() function may fail if:
    
           **EACCES** Search permission was denied for the current directory, or
                  read or search permission was denied for a directory above
                  the current directory in the file hierarchy.
    
           **ENOMEM** Insufficient storage space is available.
    
           _The following sections are informative._
    


## EXAMPLES



           The following example uses {PATH_MAX} as the initial buffer size
           (unless it is indeterminate or very large), and calls _getcwd_()
           with progressively larger buffers until it does not give an
           **[ERANGE]** error.
    
               #include <stdlib.h>
               #include <errno.h>
               #include <unistd.h>
    
               ...
    
               long path_max;
               size_t size;
               char *buf;
               char *ptr;
    
               path_max = pathconf(".", _PC_PATH_MAX);
               if (path_max == -1)
                   size = 1024;
               else if (path_max > 10240)
                   size = 10240;
               else
                   size = path_max;
    
               for (buf = ptr = NULL; ptr == NULL; size *= 2)
               {
                   if ((buf = realloc(buf, size)) == NULL)
                   {
                       ... handle error ...
                   }
    
                   ptr = getcwd(buf, size);
                   if (ptr == NULL && errno != ERANGE)
                   {
                       ... handle error ...
                   }
               }
               ...
               free (buf);
    


## APPLICATION USAGE



           If the pathname obtained from _getcwd_() is longer than {PATH_MAX}
           bytes, it could produce an **[ENAMETOOLONG]** error if passed to
           _chdir_().  Therefore, in order to return to that directory it may
           be necessary to break the pathname into sections shorter than
           {PATH_MAX} bytes and call _chdir_() on each section in turn (the
           first section being an absolute pathname and subsequent sections
           being relative pathnames). A simpler way to handle saving and
           restoring the working directory when it may be deeper than
           {PATH_MAX} bytes in the file hierarchy is to use a file descriptor
           and _fchdir_(), rather than _getcwd_() and _chdir_().  However, the two
           methods do have some differences. The _fchdir_() approach causes the
           program to restore a working directory even if it has been renamed
           in the meantime, whereas the _chdir_() approach restores to a
           directory with the same name as the original, even if the
           directories were renamed in the meantime. Since the _fchdir_()
           approach does not access parent directories, it can succeed when
           _getcwd_() would fail due to permissions problems. In applications
           conforming to earlier versions of this standard, it was not
           possible to use the _fchdir_() approach when the working directory
           is searchable but not readable, as the only way to open a
           directory was with O_RDONLY, whereas the _getcwd_() approach can
           succeed in this case.
    


## RATIONALE



           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. Finally, _getcwd_() is
           taken from the SVID where it has the two arguments used in this
           volume of POSIX.1‐2017.
    
           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.
    
           Earlier implementations of _getcwd_() sometimes generated pathnames
           like **"../../../subdirname"** internally, using them to explore the
           path of ancestor directories back to the root. If one of these
           internal pathnames exceeded {PATH_MAX} in length, the
           implementation could fail with _errno_ set to **[ENAMETOOLONG]**.  This
           is no longer allowed.
    
           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 developer that
           _getcwd_() can fail for reasons beyond the control of the
           application developer 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 POSIX.1‐2017 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.
    


* * *