1GETCWD(3P)                 POSIX Programmer's Manual                GETCWD(3P)
2
3
4

PROLOG

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

NAME

12       getcwd — get the pathname of the current working directory
13

SYNOPSIS

15       #include <unistd.h>
16
17       char *getcwd(char *buf, size_t size);
18

DESCRIPTION

20       The getcwd() function shall place an absolute pathname of  the  current
21       working  directory in the array pointed to by buf, and return buf.  The
22       pathname shall contain no components that are dot or  dot-dot,  or  are
23       symbolic links.
24
25       If  there are multiple pathnames that getcwd() could place in the array
26       pointed to by buf, one beginning with a single  <slash>  character  and
27       one  or more beginning with two <slash> characters, then getcwd() shall
28       place the pathname beginning with a single  <slash>  character  in  the
29       array.  The  pathname shall not contain any unnecessary <slash> charac‐
30       ters after the leading one or two <slash> characters.
31
32       The size argument is the size in bytes of the character  array  pointed
33       to  by  the  buf  argument.  If  buf is a null pointer, the behavior of
34       getcwd() is unspecified.
35

RETURN VALUE

37       Upon successful completion, getcwd() shall  return  the  buf  argument.
38       Otherwise,  getcwd() shall return a null pointer and set errno to indi‐
39       cate the error. The contents of the array pointed to by  buf  are  then
40       undefined.
41

ERRORS

43       The getcwd() function shall fail if:
44
45       EINVAL The size argument is 0.
46
47       ERANGE The  size  argument  is  greater than 0, but is smaller than the
48              length of the string +1.
49
50       The getcwd() function may fail if:
51
52       EACCES Search permission was denied for the current directory, or  read
53              or  search  permission was denied for a directory above the cur‐
54              rent directory in the file hierarchy.
55
56       ENOMEM Insufficient storage space is available.
57
58       The following sections are informative.
59

EXAMPLES

61       The following example  uses  {PATH_MAX}  as  the  initial  buffer  size
62       (unless  it  is  indeterminate  or very large), and calls getcwd() with
63       progressively larger buffers until it does not give an [ERANGE] error.
64
65
66           #include <stdlib.h>
67           #include <errno.h>
68           #include <unistd.h>
69
70           ...
71
72           long path_max;
73           size_t size;
74           char *buf;
75           char *ptr;
76
77           path_max = pathconf(".", _PC_PATH_MAX);
78           if (path_max == -1)
79               size = 1024;
80           else if (path_max > 10240)
81               size = 10240;
82           else
83               size = path_max;
84
85           for (buf = ptr = NULL; ptr == NULL; size *= 2)
86           {
87               if ((buf = realloc(buf, size)) == NULL)
88               {
89                   ... handle error ...
90               }
91
92               ptr = getcwd(buf, size);
93               if (ptr == NULL && errno != ERANGE)
94               {
95                   ... handle error ...
96               }
97           }
98           ...
99           free (buf);
100

APPLICATION USAGE

102       If the pathname obtained from getcwd() is longer than {PATH_MAX} bytes,
103       it  could produce an [ENAMETOOLONG] error if passed to chdir().  There‐
104       fore, in order to return to that directory it may be necessary to break
105       the  pathname  into  sections  shorter  than  {PATH_MAX} bytes and call
106       chdir() on each section in turn (the first section  being  an  absolute
107       pathname  and  subsequent sections being relative pathnames). A simpler
108       way to handle saving and restoring the working directory when it may be
109       deeper  than  {PATH_MAX}  bytes  in the file hierarchy is to use a file
110       descriptor and fchdir(), rather than getcwd()  and  chdir().   However,
111       the  two methods do have some differences. The fchdir() approach causes
112       the program to restore a working directory even if it has been  renamed
113       in  the  meantime, whereas the chdir() approach restores to a directory
114       with the same name as  the  original,  even  if  the  directories  were
115       renamed  in  the  meantime. Since the fchdir() approach does not access
116       parent directories, it can succeed when getcwd() would fail due to per‐
117       missions  problems.  In  applications conforming to earlier versions of
118       this standard, it was not possible to use the  fchdir()  approach  when
119       the  working  directory is searchable but not readable, as the only way
120       to open a directory was with O_RDONLY, whereas  the  getcwd()  approach
121       can succeed in this case.
122

RATIONALE

124       Having getcwd() take no arguments and instead use the malloc() function
125       to produce space for the returned argument was considered.  The  advan‐
126       tage  is  that getcwd() knows how big the working directory pathname is
127       and can allocate an appropriate amount of  space.  But  the  programmer
128       would  have to use the free() function to free the resulting object, or
129       each use  of  getcwd()  would  further  reduce  the  available  memory.
130       Finally, getcwd() is taken from the SVID where it has the two arguments
131       used in this volume of POSIX.1‐2017.
132
133       The older function getwd() was rejected for use in this context because
134       it had only a buffer argument and no size argument, and thus had no way
135       to prevent overwriting the buffer, except to depend on  the  programmer
136       to provide a large enough buffer.
137
138       On  some implementations, if buf is a null pointer, getcwd() may obtain
139       size bytes of  memory  using  malloc().   In  this  case,  the  pointer
140       returned  by  getcwd() may be used as the argument in a subsequent call
141       to free().  Invoking getcwd() with buf as a null pointer is not  recom‐
142       mended in conforming applications.
143
144       Earlier  implementations of getcwd() sometimes generated pathnames like
145       "../../../subdirname" internally, using them to  explore  the  path  of
146       ancestor  directories  back to the root. If one of these internal path‐
147       names exceeded {PATH_MAX} in length, the implementation could fail with
148       errno set to [ENAMETOOLONG].  This is no longer allowed.
149
150       If  a  program  is  operating  in  a directory where some (grand)parent
151       directory does not permit reading, getcwd() may fail, as in most imple‐
152       mentations  it  must  read  the  directory to determine the name of the
153       file. This can occur if search, but not read, permission is granted  in
154       an  intermediate  directory, or if the program is placed in that direc‐
155       tory by some more privileged process (for  example,  login).  Including
156       the  [EACCES]  error condition makes the reporting of the error consis‐
157       tent and warns the application developer that  getcwd()  can  fail  for
158       reasons  beyond  the control of the application developer or user. Some
159       implementations can avoid this occurrence (for example, by implementing
160       getcwd()  using  pwd,  where  pwd is a set-user-root process), thus the
161       error was made optional. Since this volume of POSIX.1‐2017 permits  the
162       addition  of  other errors, this would be a common addition and yet one
163       that applications could not be expected to deal with without this addi‐
164       tion.
165

FUTURE DIRECTIONS

167       None.
168

SEE ALSO

170       malloc()
171
172       The Base Definitions volume of POSIX.1‐2017, <unistd.h>
173
175       Portions  of  this text are reprinted and reproduced in electronic form
176       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
177       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
178       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
179       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
180       event of any discrepancy between this version and the original IEEE and
181       The  Open Group Standard, the original IEEE and The Open Group Standard
182       is the referee document. The original Standard can be  obtained  online
183       at http://www.opengroup.org/unix/online.html .
184
185       Any  typographical  or  formatting  errors that appear in this page are
186       most likely to have been introduced during the conversion of the source
187       files  to  man page format. To report such errors, see https://www.ker
188       nel.org/doc/man-pages/reporting_bugs.html .
189
190
191
192IEEE/The Open Group                  2017                           GETCWD(3P)
Impressum