1GETCWD(3P) POSIX Programmer's Manual GETCWD(3P)
2
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
12 getcwd - get the pathname of the current working directory
13
15 #include <unistd.h>
16 char *getcwd(char *buf, size_t size);
18
21 The getcwd() function shall place an absolute pathname of the current
22 working directory in the array pointed to by buf, and return buf. The
23 pathname copied to the array shall contain no components that are sym‐
24 bolic links. The size argument is the size in bytes of the character
25 array pointed to by the buf argument. If buf is a null pointer, the
26 behavior of getcwd() is unspecified.
27
29 Upon successful completion, getcwd() shall return the buf argument.
30 Otherwise, getcwd() shall return a null pointer and set errno to indi‐
31 cate the error. The contents of the array pointed to by buf are then
32 undefined.
33
35 The getcwd() function shall fail if:
36 EINVAL The size argument is 0.
38 ERANGE The size argument is greater than 0, but is smaller than the
40 length of the pathname +1.
41 The getcwd() function may fail if:
44 EACCES Read or search permission was denied for a component of the
46 pathname.
47 ENOMEM Insufficient storage space is available.
49 The following sections are informative.
52
54 Determining the Absolute Pathname of the Current Working Directory
55 The following example returns a pointer to an array that holds the
56 absolute pathname of the current working directory. The pointer is
57 returned in the ptr variable, which points to the buf array where the
58 pathname is stored.
59 #include <stdlib.h>
62 #include <unistd.h>
63 ...
64 long size;
65 char *buf;
66 char *ptr;
67 size = pathconf(".", _PC_PATH_MAX);
70 if ((buf = (char *)malloc((size_t)size)) != NULL)
73 ptr = getcwd(buf, (size_t)size);
74 ...
75
77 None.
78
80 Since the maximum pathname length is arbitrary unless {PATH_MAX} is
81 defined, an application generally cannot supply a buf with size
82 {{PATH_MAX}+1}.
83 Having getcwd() take no arguments and instead use the malloc() function
85 to produce space for the returned argument was considered. The advan‐
86 tage is that getcwd() knows how big the working directory pathname is
87 and can allocate an appropriate amount of space. But the programmer
88 would have to use the free() function to free the resulting object, or
89 each use of getcwd() would further reduce the available memory. Also,
90 malloc() and free() are used nowhere else in this volume of
91 IEEE Std 1003.1-2001. Finally, getcwd() is taken from the SVID where it
92 has the two arguments used in this volume of IEEE Std 1003.1-2001.
93 The older function getwd() was rejected for use in this context because
95 it had only a buffer argument and no size argument, and thus had no way
96 to prevent overwriting the buffer, except to depend on the programmer
97 to provide a large enough buffer.
98 On some implementations, if buf is a null pointer, getcwd() may obtain
100 size bytes of memory using malloc(). In this case, the pointer returned
101 by getcwd() may be used as the argument in a subsequent call to free().
102 Invoking getcwd() with buf as a null pointer is not recommended in con‐
103 forming applications.
104 If a program is operating in a directory where some (grand)parent
106 directory does not permit reading, getcwd() may fail, as in most imple‐
107 mentations it must read the directory to determine the name of the
108 file. This can occur if search, but not read, permission is granted in
109 an intermediate directory, or if the program is placed in that direc‐
110 tory by some more privileged process (for example, login). Including
111 the [EACCES] error condition makes the reporting of the error consis‐
112 tent and warns the application writer that getcwd() can fail for rea‐
113 sons beyond the control of the application writer or user. Some imple‐
114 mentations can avoid this occurrence (for example, by implementing
115 getcwd() using pwd, where pwd is a set-user-root process), thus the
116 error was made optional. Since this volume of IEEE Std 1003.1-2001 per‐
117 mits the addition of other errors, this would be a common addition and
118 yet one that applications could not be expected to deal with without
119 this addition.
120
122 None.
123
125 malloc(), the Base Definitions volume of IEEE Std 1003.1-2001,
126 <unistd.h>
127
129 Portions of this text are reprinted and reproduced in electronic form
130 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
131 -- Portable Operating System Interface (POSIX), The Open Group Base
132 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
133 Electrical and Electronics Engineers, Inc and The Open Group. In the
134 event of any discrepancy between this version and the original IEEE and
135 The Open Group Standard, the original IEEE and The Open Group Standard
136 is the referee document. The original Standard can be obtained online
137 at http://www.opengroup.org/unix/online.html .
138IEEE/The Open Group 2003 GETCWD(3P)