lib/libc/gen/getcwd.3

   1 .\"     $NetBSD: getcwd.3,v 1.15 2003/04/16 13:34:36 wiz 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 December 11, 1993
  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 .Aq Pa 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 getcwd
 136 function
 137 conforms to
 138 .St -p1003.1-90 .
 139 The ability to specify a
 140 .Dv NULL
 141 pointer and have
 142 .Fn getcwd
 143 allocate memory as necessary is an extension.
 144 .Sh HISTORY
 145 The
 146 .Fn getwd
 147 function appeared in
 148 .Bx 4.0 .
 149 .Sh SECURITY CONSIDERATIONS
 150 As
 151 .Fn getwd
 152 does not know the length of the supplied buffer, it is possible
 153 for a long (but valid) path to overflow the buffer and provide
 154 a means for an attacker to exploit the caller.
 155 .Fn getcwd
 156 should be used in place of
 157 .Fn getwd
 158 (the latter is only provided for compatibility purposes).