lib/libc/gen/getcwd.3

   1 .\"     $NetBSD: getcwd.3,v 1.18 2010/04/29 06:54:26 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)getcwd.3    8.2 (Berkeley) 12/11/93
  31 .\"
  32 .Dd April 29, 2010
  33 .Dt GETCWD 3
  34 .Os
  35 .Sh NAME
  36 .Nm getcwd ,
  37 .Nm getwd
  38 .Nd get working directory pathname
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In unistd.h
  43 .Ft char *
  44 .Fn getcwd "char *buf" "size_t size"
  45 .Ft char *
  46 .Fn getwd "char *buf"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn getcwd
  50 function copies the absolute pathname of the current working directory
  51 into the memory referenced by
  52 .Fa buf
  53 and returns a pointer to
  54 .Fa buf .
  55 The
  56 .Fa size
  57 argument is the size, in bytes, of the array referenced by
  58 .Fa buf .
  59 .Pp
  60 If
  61 .Fa buf
  62 is
  63 .Dv NULL ,
  64 space is allocated as necessary to store the pathname.
  65 This space may later be
  66 .Xr free 3 Ns 'd .
  67 .Pp
  68 The function
  69 .Fn getwd
  70 is a compatibility routine which calls
  71 .Fn getcwd
  72 with its
  73 .Fa buf
  74 argument and a size of
  75 .Dv MAXPATHLEN
  76 (as defined in the include
  77 file
  78 .In sys/param.h ) .
  79 Obviously,
  80 .Fa buf
  81 should be at least
  82 .Dv MAXPATHLEN
  83 bytes in length.
  84 .Pp
  85 These routines have traditionally been used by programs to save the
  86 name of a working directory for the purpose of returning to it.
  87 A much faster and less error-prone method of accomplishing this is to
  88 open the current directory
  89 .Pq Ql \&.
  90 and use the
  91 .Xr fchdir 2
  92 function to return.
  93 .Sh RETURN VALUES
  94 Upon successful completion, a pointer to the pathname is returned.
  95 Otherwise a
  96 .Dv NULL
  97 pointer is returned and the global variable
  98 .Va errno
  99 is set to indicate the error.
 100 In addition,
 101 .Fn getwd
 102 copies the error message associated with
 103 .Va errno
 104 into the memory referenced by
 105 .Fa buf .
 106 .Sh ERRORS
 107 The
 108 .Fn getcwd
 109 function
 110 will fail if:
 111 .Bl -tag -width Er
 112 .It Bq Er EACCES
 113 Read or search permission was denied for a component of the pathname.
 114 .It Bq Er EINVAL
 115 The
 116 .Fa size
 117 argument is zero.
 118 .It Bq Er ENOENT
 119 A component of the pathname no longer exists.
 120 .It Bq Er ENOMEM
 121 Insufficient memory is available.
 122 .It Bq Er ERANGE
 123 The
 124 .Fa size
 125 argument is greater than zero but smaller than the length of the pathname
 126 plus 1.
 127 .El
 128 .Sh SEE ALSO
 129 .Xr chdir 2 ,
 130 .Xr fchdir 2 ,
 131 .Xr malloc 3 ,
 132 .Xr strerror 3
 133 .Sh STANDARDS
 134 The
 135 .Fn getwd
 136 and
 137 .Fn getcwd
 138 functions conform to
 139 .St -p1003.1-90 .
 140 The
 141 .St -p1003.1-2004
 142 revision marked
 143 .Fn getwd
 144 as legacy and recommended the use of
 145 .Fn getcwd
 146 instead.
 147 The
 148 .St -p1003.1-2008
 149 revision removed
 150 .Fn getwd
 151 from the specification.
 152 .Pp
 153 The ability to specify a
 154 .Dv NULL
 155 pointer and have
 156 .Fn getcwd
 157 allocate memory as necessary is an extension.
 158 .Sh HISTORY
 159 The
 160 .Fn getwd
 161 function appeared in
 162 .Bx 4.0 .
 163 .Sh SECURITY CONSIDERATIONS
 164 As
 165 .Fn getwd
 166 does not know the length of the supplied buffer, it is possible
 167 for a long (but valid) path to overflow the buffer and provide
 168 a means for an attacker to exploit the caller.
 169 .Fn getcwd
 170 should be used in place of
 171 .Fn getwd
 172 (the latter is only provided for compatibility purposes).