From 25aea26a871b2c117682809b3c11f857f80fd8a5 Mon Sep 17 00:00:00 2001
From: millert <millert@openbsd.org>
Date: Thu, 16 Dec 2021 19:15:29 +0000
Subject: [PATCH] Document the failure mode if size is too small and mention
 that allocating space when buf is NULL is an extension more prominently.
 Clarify that getwd() is deprecated and should not be used. Mention EFAULT
 errno value for invalid (non-NULL) buf. OK deraadt@ jmc@

---
 lib/libc/gen/getcwd.3 | 62 ++++++++++++++++++++++++++++++-------------
 1 file changed, 43 insertions(+), 19 deletions(-)

diff --git a/lib/libc/gen/getcwd.3 b/lib/libc/gen/getcwd.3
index 1de983a7b55..de4bb66f67e 100644
--- a/lib/libc/gen/getcwd.3
+++ b/lib/libc/gen/getcwd.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: getcwd.3,v 1.21 2019/07/05 12:55:36 deraadt Exp $
+.\"	$OpenBSD: getcwd.3,v 1.22 2021/12/16 19:15:29 millert Exp $
 .\"
 .\" Copyright (c) 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 5 2019 $
+.Dd $Mdocdate: December 16 2021 $
 .Dt GETCWD 3
 .Os
 .Sh NAME
@@ -55,30 +55,51 @@ argument is the size, in bytes, of the array referenced by
 .Pp
 If
 .Fa buf
+is not
+.Dv NULL
+and the length of the pathname plus the terminating NUL
+character is greater than
+.Fa size ,
+a null pointer is returned and
+.Va errno
+is set to
+.Dv ERANGE .
+.Pp
+As an extension to
+.St -p1003.1-2001 ,
+if
+.Fa buf
 is
 .Dv NULL ,
 space is allocated as necessary to store the pathname.
-This space may later be
-.Xr free 3 Ns 'd.
+In this case, it is the responsibility of the caller to
+.Xr free 3
+the pointer that
+.Fn getcwd
+returns.
 .Pp
-The function
+The deprecated
 .Fn getwd
-is a compatibility routine which calls
-.Fn getcwd
-with its
+function is similar to
+.Fn getcwd ,
+but assumes that
 .Fa buf
-argument and a size of
+is non-NULL and has a size of
 .Dv PATH_MAX
-(as defined in the include
+(as defined by the include
 file
 .In limits.h ) .
-Obviously,
-.Fa buf
-should be at least
-.Dv PATH_MAX
-bytes in length.
+It does not allocate memory and is provided for source compatibility only.
+If the length of the pathname plus the terminating NUL
+character is greater than
+.Dv PATH_MAX ,
+a null pointer is returned.
+On error,
+.Fn getwd
+writes an error message into the memory referenced by
+.Fa buf .
 .Pp
-These routines have traditionally been used by programs to save the
+These functions have traditionally been used by programs to save the
 name of a working directory for the purpose of returning to it.
 A much faster and less error-prone method of accomplishing this is to
 open the current directory
@@ -88,7 +109,7 @@ and use the
 function to return.
 .Sh RETURN VALUES
 Upon successful completion, a pointer to the pathname is returned.
-Otherwise a null pointer is returned and the global variable
+Otherwise a null pointer is returned and
 .Va errno
 is set to indicate the error.
 In addition,
@@ -99,11 +120,14 @@ into the memory referenced by
 .Fa buf .
 .Sh ERRORS
 The
-.Fn getwd
+.Fn getcwd
 function will fail if:
 .Bl -tag -width Er
 .It Bq Er EACCES
 Read or search permission was denied for a component of the pathname.
+.It Bq Er EFAULT
+.Fa buf
+points to an invalid address.
 .It Bq Er EINVAL
 The
 .Fa size
@@ -161,4 +185,4 @@ The
 .Fn getwd
 function does not do sufficient error checking and is not able to return very
 long, but valid, paths.
-It is provided for compatibility.
+It is provided for compatibility only.
-- 
2.20.1