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



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       getcwd -- get the pathname of the current working directory

SSYYNNOOPPSSIISS
       #include <unistd.h>

       char *getcwd(char *_b_u_f, size_t _s_i_z_e);

DDEESSCCRRIIPPTTIIOONN
       The _g_e_t_c_w_d() function shall place an absolute pathname of the current
       working directory in the array pointed to by _b_u_f, and return _b_u_f.  The
       pathname shall contain no components that are dot or dot-dot, or are
       symbolic links.

       If there are multiple pathnames that _g_e_t_c_w_d() could place in the array
       pointed to by _b_u_f, one beginning with a single <slash> character and
       one or more beginning with two <slash> characters, then _g_e_t_c_w_d() 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 _s_i_z_e argument is the size in bytes of the character array pointed
       to by the _b_u_f argument. If _b_u_f is a null pointer, the behavior of
       _g_e_t_c_w_d() is unspecified.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _g_e_t_c_w_d() shall return the _b_u_f argument.
       Otherwise, _g_e_t_c_w_d() shall return a null pointer and set _e_r_r_n_o to
       indicate the error. The contents of the array pointed to by _b_u_f are
       then undefined.

EERRRROORRSS
       The _g_e_t_c_w_d() function shall fail if:

       EEIINNVVAALL The _s_i_z_e argument is 0.

       EERRAANNGGEE The _s_i_z_e argument is greater than 0, but is smaller than the
              length of the string +1.

       The _g_e_t_c_w_d() function may fail if:

       EEAACCCCEESS 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.

       EENNOOMMEEMM Insufficient storage space is available.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       The following example uses {PATH_MAX} as the initial buffer size
       (unless it is indeterminate or very large), and calls _g_e_t_c_w_d() with
       progressively larger buffers until it does not give an [[EERRAANNGGEE]] error.

           ##iinncclluuddee <<ssttddlliibb..hh>>
           ##iinncclluuddee <<eerrrrnnoo..hh>>
           ##iinncclluuddee <<uunniissttdd..hh>>

           ...

           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);

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       If the pathname obtained from _g_e_t_c_w_d() is longer than {PATH_MAX} bytes,
       it could produce an [[EENNAAMMEETTOOOOLLOONNGG]] error if passed to _c_h_d_i_r().
       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
       _c_h_d_i_r() 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 _f_c_h_d_i_r(), rather than _g_e_t_c_w_d() and _c_h_d_i_r().  However,
       the two methods do have some differences. The _f_c_h_d_i_r() approach causes
       the program to restore a working directory even if it has been renamed
       in the meantime, whereas the _c_h_d_i_r() approach restores to a directory
       with the same name as the original, even if the directories were
       renamed in the meantime. Since the _f_c_h_d_i_r() approach does not access
       parent directories, it can succeed when _g_e_t_c_w_d() would fail due to
       permissions problems. In applications conforming to earlier versions of
       this standard, it was not possible to use the _f_c_h_d_i_r() approach when
       the working directory is searchable but not readable, as the only way
       to open a directory was with O_RDONLY, whereas the _g_e_t_c_w_d() approach
       can succeed in this case.

RRAATTIIOONNAALLEE
       Having _g_e_t_c_w_d() take no arguments and instead use the _m_a_l_l_o_c() function
       to produce space for the returned argument was considered.  The
       advantage is that _g_e_t_c_w_d() knows how big the working directory pathname
       is and can allocate an appropriate amount of space. But the programmer
       would have to use the _f_r_e_e() function to free the resulting object, or
       each use of _g_e_t_c_w_d() would further reduce the available memory.
       Finally, _g_e_t_c_w_d() is taken from the SVID where it has the two arguments
       used in this volume of POSIX.1-2008.

       The older function _g_e_t_w_d() was rejected for use in this context because
       it had only a buffer argument and no _s_i_z_e 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 _b_u_f is a null pointer, _g_e_t_c_w_d() may obtain
       _s_i_z_e bytes of memory using _m_a_l_l_o_c().  In this case, the pointer
       returned by _g_e_t_c_w_d() may be used as the argument in a subsequent call
       to _f_r_e_e().  Invoking _g_e_t_c_w_d() with _b_u_f as a null pointer is not
       recommended in conforming applications.

       Earlier implementations of _g_e_t_c_w_d() sometimes generated pathnames like
       ""....//....//....//ssuubbddiirrnnaammee"" 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 _e_r_r_n_o set to [[EENNAAMMEETTOOOOLLOONNGG]].  This is no longer allowed.

       If a program is operating in a directory where some (grand)parent
       directory does not permit reading, _g_e_t_c_w_d() 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 [[EEAACCCCEESS]] error condition makes the reporting of the error
       consistent and warns the application developer that _g_e_t_c_w_d() can fail
       for reasons beyond the control of the application developer or user.
       Some implementations can avoid this occurrence (for example, by
       implementing _g_e_t_c_w_d() using _p_w_d, where _p_w_d is a set-user-root process),
       thus the error was made optional. Since this volume of POSIX.1-2008
       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.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _m_a_l_l_o_c()

       The Base Definitions volume of POSIX.1-2008, <<uunniissttdd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                            GETCWD(3)
