man3/getcwd.3

   1 '\" t
   2 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified Wed Jul 21 22:35:42 1993 by Rik Faith (faith@cs.unc.edu)
   7 .\" Modified 18 Mar 1996 by Martin Schulze (joey@infodrom.north.de):
   8 .\"   Corrected description of getwd().
   9 .\" Modified Sat Aug 21 12:32:12 MET 1999 by aeb - applied fix by aj
  10 .\" Modified Mon Dec 11 13:32:51 MET 2000 by aeb
  11 .\" Modified Thu Apr 22 03:49:15 CEST 2002 by Roger Luethi <rl@hellgate.ch>
  12 .\"
  13 .TH getcwd 3 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 getcwd, getwd, get_current_dir_name \- get current working directory
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <unistd.h>
  22 .P
  23 .BI "char *getcwd(char " buf [. size "], size_t " size );
  24 .B "char *get_current_dir_name(void);"
  25 .P
  26 .BI "[[deprecated]] char *getwd(char " buf [PATH_MAX]);
  27 .fi
  28 .P
  29 .RS -4
  30 Feature Test Macro Requirements for glibc (see
  31 .BR feature_test_macros (7)):
  32 .RE
  33 .P
  34 .BR get_current_dir_name ():
  35 .nf
  36     _GNU_SOURCE
  37 .fi
  38 .P
  39 .BR getwd ():
  40 .nf
  41     Since glibc 2.12:
  42         (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
  43             || /* glibc >= 2.19: */ _DEFAULT_SOURCE
  44             || /* glibc <= 2.19: */ _BSD_SOURCE
  45     Before glibc 2.12:
  46         _BSD_SOURCE || _XOPEN_SOURCE >= 500
  47 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  48 .fi
  49 .SH DESCRIPTION
  50 These functions return a null-terminated string containing an
  51 absolute pathname that is the current working directory of
  52 the calling process.
  53 The pathname is returned as the function result and via the argument
  54 .IR buf ,
  55 if present.
  56 .P
  57 The
  58 .BR getcwd ()
  59 function copies an absolute pathname of the current working directory
  60 to the array pointed to by
  61 .IR buf ,
  62 which is of length
  63 .IR size .
  64 .P
  65 If the length of the absolute pathname of the current working directory,
  66 including the terminating null byte, exceeds
  67 .I size
  68 bytes, NULL is returned, and
  69 .I errno
  70 is set to
  71 .BR ERANGE ;
  72 an application should check for this error, and allocate a larger
  73 buffer if necessary.
  74 .P
  75 As an extension to the POSIX.1-2001 standard, glibc's
  76 .BR getcwd ()
  77 allocates the buffer dynamically using
  78 .BR malloc (3)
  79 if
  80 .I buf
  81 is NULL.
  82 In this case, the allocated buffer has the length
  83 .I size
  84 unless
  85 .I size
  86 is zero, when
  87 .I buf
  88 is allocated as big as necessary.
  89 The caller should
  90 .BR free (3)
  91 the returned buffer.
  92 .P
  93 .BR get_current_dir_name ()
  94 will
  95 .BR malloc (3)
  96 an array big enough to hold the absolute pathname of
  97 the current working directory.
  98 If the environment
  99 variable
 100 .B PWD
 101 is set, and its value is correct, then that value will be returned.
 102 The caller should
 103 .BR free (3)
 104 the returned buffer.
 105 .P
 106 .BR getwd ()
 107 does not
 108 .BR malloc (3)
 109 any memory.
 110 The
 111 .I buf
 112 argument should be a pointer to an array at least
 113 .B PATH_MAX
 114 bytes long.
 115 If the length of the absolute pathname of the current working directory,
 116 including the terminating null byte, exceeds
 117 .B PATH_MAX
 118 bytes, NULL is returned, and
 119 .I errno
 120 is set to
 121 .BR ENAMETOOLONG .
 122 (Note that on some systems,
 123 .B PATH_MAX
 124 may not be a compile-time constant;
 125 furthermore, its value may depend on the filesystem, see
 126 .BR pathconf (3).)
 127 For portability and security reasons, use of
 128 .BR getwd ()
 129 is deprecated.
 130 .SH RETURN VALUE
 131 On success, these functions return a pointer to a string containing
 132 the pathname of the current working directory.
 133 In the case of
 134 .BR getcwd ()
 135 and
 136 .BR getwd ()
 137 this is the same value as
 138 .IR buf .
 139 .P
 140 On failure, these functions return NULL, and
 141 .I errno
 142 is set to indicate the error.
 143 The contents of the array pointed to by
 144 .I buf
 145 are undefined on error.
 146 .SH ERRORS
 147 .TP
 148 .B EACCES
 149 Permission to read or search a component of the filename was denied.
 150 .TP
 151 .B EFAULT
 152 .I buf
 153 points to a bad address.
 154 .TP
 155 .B EINVAL
 156 The
 157 .I size
 158 argument is zero and
 159 .I buf
 160 is not a null pointer.
 161 .TP
 162 .B EINVAL
 163 .BR getwd ():
 164 .I buf
 165 is NULL.
 166 .TP
 167 .B ENAMETOOLONG
 168 .BR getwd ():
 169 The size of the null-terminated absolute pathname string exceeds
 170 .B PATH_MAX
 171 bytes.
 172 .TP
 173 .B ENOENT
 174 The current working directory has been unlinked.
 175 .TP
 176 .B ENOMEM
 177 Out of memory.
 178 .TP
 179 .B ERANGE
 180 The
 181 .I size
 182 argument is less than the length of the absolute pathname of the
 183 working directory, including the terminating null byte.
 184 You need to allocate a bigger array and try again.
 185 .SH ATTRIBUTES
 186 For an explanation of the terms used in this section, see
 187 .BR attributes (7).
 188 .TS
 189 allbox;
 190 lbx lb lb
 191 l l l.
 192 Interface       Attribute       Value
 193 T{
 194 .na
 195 .nh
 196 .BR getcwd (),
 197 .BR getwd ()
 198 T}      Thread safety   MT-Safe
 199 T{
 200 .na
 201 .nh
 202 .BR get_current_dir_name ()
 203 T}      Thread safety   MT-Safe env
 204 .TE
 205 .SH VERSIONS
 206 POSIX.1-2001 leaves the behavior of
 207 .BR getcwd ()
 208 unspecified if
 209 .I buf
 210 is NULL.
 211 .P
 212 POSIX.1-2001
 213 does not define any errors for
 214 .BR getwd ().
 215 .SH VERSIONS
 216 .SS C library/kernel differences
 217 On Linux, the kernel provides a
 218 .BR getcwd ()
 219 system call, which the functions described in this page will use if possible.
 220 The system call takes the same arguments as the library function
 221 of the same name, but is limited to returning at most
 222 .B PATH_MAX
 223 bytes.
 224 (Before Linux 3.12,
 225 .\" commit 3272c544da48f8915a0e34189182aed029bd0f2b
 226 the limit on the size of the returned pathname was the system page size.
 227 On many architectures,
 228 .B PATH_MAX
 229 and the system page size are both 4096 bytes,
 230 but a few architectures have a larger page size.)
 231 If the length of the pathname of the current working directory
 232 exceeds this limit, then the system call fails with the error
 233 .BR ENAMETOOLONG .
 234 In this case, the library functions fall back to
 235 a (slower) alternative implementation that returns the full pathname.
 236 .P
 237 Following a change in Linux 2.6.36,
 238 .\" commit 8df9d1a4142311c084ffeeacb67cd34d190eff74
 239 the pathname returned by the
 240 .BR getcwd ()
 241 system call will be prefixed with the string "(unreachable)"
 242 if the current directory is not below the root directory of the current
 243 process (e.g., because the process set a new filesystem root using
 244 .BR chroot (2)
 245 without changing its current directory into the new root).
 246 Such behavior can also be caused by an unprivileged user by changing
 247 the current directory into another mount namespace.
 248 When dealing with pathname from untrusted sources, callers of the
 249 functions described in this page
 250 should consider checking whether the returned pathname starts
 251 with '/' or '(' to avoid misinterpreting an unreachable path
 252 as a relative pathname.
 253 .SH STANDARDS
 254 .TP
 255 .BR getcwd ()
 256 POSIX.1-2008.
 257 .TP
 258 .BR get_current_dir_name ()
 259 GNU.
 260 .TP
 261 .BR getwd ()
 262 None.
 263 .SH HISTORY
 264 .TP
 265 .BR getcwd ()
 266 POSIX.1-2001.
 267 .TP
 268 .BR getwd ()
 269 POSIX.1-2001, but marked LEGACY.
 270 Removed in POSIX.1-2008.
 271 Use
 272 .BR getcwd ()
 273 instead.
 274 .P
 275 Under Linux, these functions make use of the
 276 .BR getcwd ()
 277 system call (available since Linux 2.1.92).
 278 On older systems they would query
 279 .IR /proc/self/cwd .
 280 If both system call and proc filesystem are missing, a
 281 generic implementation is called.
 282 Only in that case can
 283 these calls fail under Linux with
 284 .BR EACCES .
 285 .SH NOTES
 286 These functions are often used to save the location of the current working
 287 directory for the purpose of returning to it later.
 288 Opening the current
 289 directory (".") and calling
 290 .BR fchdir (2)
 291 to return is usually a faster and more reliable alternative when sufficiently
 292 many file descriptors are available, especially on platforms other than Linux.
 293 .SH BUGS
 294 Since the Linux 2.6.36 change that added "(unreachable)" in the
 295 circumstances described above, the glibc implementation of
 296 .BR getcwd ()
 297 has failed to conform to POSIX and returned a relative pathname when the API
 298 contract requires an absolute pathname.
 299 With glibc 2.27 onwards this is corrected;
 300 calling
 301 .BR getcwd ()
 302 from such a pathname will now result in failure with
 303 .BR ENOENT .
 304 .SH SEE ALSO
 305 .BR pwd (1),
 306 .BR chdir (2),
 307 .BR fchdir (2),
 308 .BR open (2),
 309 .BR unlink (2),
 310 .BR free (3),
 311 .BR malloc (3)