gen/FreeBSD/getcwd.3

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