man3/getcwd.3

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