original/man3/getcwd.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\" License.
  23 .\" Modified Wed Jul 21 22:35:42 1993 by Rik Faith (faith@cs.unc.edu)
  24 .\" Modified 18 Mar 1996 by Martin Schulze (joey@infodrom.north.de):
  25 .\"   Corrected description of getwd().
  26 .\" Modified Sat Aug 21 12:32:12 MET 1999 by aeb - applied fix by aj
  27 .\" Modified Mon Dec 11 13:32:51 MET 2000 by aeb
  28 .\" Modified Thu Apr 22 03:49:15 CEST 2002 by Roger Luethi <rl@hellgate.ch>
  29 .\"
  30 .TH GETCWD 3 2010-09-20 "GNU" "Linux Programmer's Manual"
  31 .SH NAME
  32 getcwd, getwd, get_current_dir_name \- Get current working directory
  33 .SH SYNOPSIS
  34 .nf
  35 .B #include <unistd.h>
  36 .sp
  37 .BI "char *getcwd(char *" buf ", size_t " size );
  38 .sp
  39 .BI "char *getwd(char *" buf );
  40 .sp
  41 .B "char *get_current_dir_name(void);"
  42 .fi
  43 .sp
  44 .in -4n
  45 Feature Test Macro Requirements for glibc (see
  46 .BR feature_test_macros (7)):
  47 .sp
  48 .in
  49 .BR get_current_dir_name ():
  50 .RS
  51 _GNU_SOURCE
  52 .RE
  53 .sp
  54 .BR getwd ():
  55 .ad l
  56 .RS 4
  57 .PD 0
  58 .TP 4
  59 Since glibc 2.12:
  60 .nf
  61 _BSD_SOURCE ||
  62     (_XOPEN_SOURCE\ >=\ 500 ||
  63         _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
  64     !(_POSIX_C_SOURCE\ >=\ 200809L || _XOPEN_SOURCE\ >=\ 700)
  65 .TP 4
  66 .fi
  67 Before glibc 2.12:
  68 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  69 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  70 .PD
  71 .RE
  72 .ad b
  73 .SH DESCRIPTION
  74 These functions return a null-terminated string containing an
  75 absolute pathname that is the current working directory of
  76 the calling process.
  77 The pathname is returned as the function result and via the argument
  78 .IR buf ,
  79 if present.
  80
  81 The
  82 .BR getcwd ()
  83 function copies an absolute pathname of the current working directory
  84 to the array pointed to by
  85 .IR buf ,
  86 which is of length
  87 .IR size .
  88 .PP
  89 If the length of the absolute pathname of the current working directory,
  90 including the terminating null byte, exceeds
  91 .I size
  92 bytes, NULL is returned, and
  93 .I errno
  94 is set to
  95 .BR ERANGE ;
  96 an application should check for this error, and allocate a larger
  97 buffer if necessary.
  98 .PP
  99 As an extension to the POSIX.1-2001 standard, Linux (libc4, libc5, glibc)
 100 .BR getcwd ()
 101 allocates the buffer dynamically using
 102 .BR malloc (3)
 103 if
 104 .I buf
 105 is NULL.
 106 In this case, the allocated buffer has the length
 107 .I size
 108 unless
 109 .I size
 110 is zero, when
 111 .I buf
 112 is allocated as big as necessary.
 113 The caller should
 114 .BR free (3)
 115 the returned buffer.
 116
 117 .BR get_current_dir_name ()
 118 will
 119 .BR malloc (3)
 120 an array big enough to hold the absolute pathname of
 121 the current working directory.
 122 If the environment
 123 variable
 124 .B PWD
 125 is set, and its value is correct, then that value will be returned.
 126 The caller should
 127 .BR free (3)
 128 the returned buffer.
 129
 130 .BR getwd ()
 131 does not
 132 .BR malloc (3)
 133 any memory.
 134 The
 135 .I buf
 136 argument should be a pointer to an array at least
 137 .B PATH_MAX
 138 bytes long.
 139 If the length of the absolute pathname of the current working directory,
 140 including the terminating null byte, exceeds
 141 .B PATH_MAX
 142 bytes, NULL is returned, and
 143 .I errno
 144 is set to
 145 .BR ENAMETOOLONG .
 146 (Note that on some systems,
 147 .B PATH_MAX
 148 may not be a compile-time constant;
 149 furthermore, its value may depend on the file system, see
 150 .BR pathconf (3).)
 151 For portability and security reasons, use of
 152 .BR getwd ()
 153 is deprecated.
 154 .SH "RETURN VALUE"
 155 On success, these functions return a pointer to a string containing
 156 the pathname of the current working directory.
 157 In the case
 158 .BR getcwd ()
 159 and
 160 .BR getwd ()
 161 this is the same value as
 162 .IR buf .
 163
 164 On failure, these functions return NULL, and
 165 .I errno
 166 is set to indicate the error.
 167 The contents of the array pointed to by
 168 .I buf
 169 are undefined on error.
 170 .SH ERRORS
 171 .TP
 172 .B EACCES
 173 Permission to read or search a component of the filename was denied.
 174 .TP
 175 .B EFAULT
 176 .I buf
 177 points to a bad address.
 178 .TP
 179 .B EINVAL
 180 The
 181 .I size
 182 argument is zero and
 183 .I buf
 184 is not a null pointer.
 185 .TP
 186 EINVAL
 187 .BR getwd ():
 188 .I buf
 189 is NULL.
 190 .TP
 191 ENAMETOOLONG
 192 .BR getwd ():
 193 The size of the null-terminated absolute pathname string exceeds
 194 .B PATH_MAX
 195 bytes.
 196 .TP
 197 .B ENOENT
 198 The current working directory has been unlinked.
 199 .TP
 200 .B ERANGE
 201 The
 202 .I size
 203 argument is less than the length of the absolute pathname of the
 204 working directory, including the terminating null byte.
 205 You need to allocate a bigger array and try again.
 206 .SH "CONFORMING TO"
 207 .BR getcwd ()
 208 conforms to POSIX.1-2001.
 209 Note however that POSIX.1-2001 leaves the behavior of
 210 .BR getcwd ()
 211 unspecified if
 212 .I buf
 213 is NULL.
 214
 215 .BR getwd ()
 216 is present in POSIX.1-2001, but marked LEGACY.
 217 POSIX.1-2008 removes the specification of
 218 .BR getwd ().
 219 Use
 220 .BR getcwd ()
 221 instead.
 222 POSIX.1-2001
 223 does not define any errors for
 224 .BR getwd ().
 225
 226 .BR get_current_dir_name ()
 227 is a GNU extension.
 228 .SH NOTES
 229 Under Linux, the function
 230 .BR getcwd ()
 231 is a system call (since 2.1.92).
 232 On older systems it would query
 233 .IR /proc/self/cwd .
 234 If both system call and proc file system are missing, a
 235 generic implementation is called.
 236 Only in that case can
 237 these calls fail under Linux with
 238 .BR EACCES .
 239 .LP
 240 These functions are often used to save the location of the current working
 241 directory for the purpose of returning to it later.
 242 Opening the current
 243 directory (".") and calling
 244 .BR fchdir (2)
 245 to return is usually a faster and more reliable alternative when sufficiently
 246 many file descriptors are available, especially on platforms other than Linux.
 247 .SH "SEE ALSO"
 248 .BR chdir (2),
 249 .BR fchdir (2),
 250 .BR open (2),
 251 .BR unlink (2),
 252 .BR free (3),
 253 .BR malloc (3)