1.\" $OpenBSD: getcwd.3,v 1.23 2022/07/25 02:25:55 jsg 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.Dd $Mdocdate: July 25 2022 $ 31.Dt GETCWD 3 32.Os 33.Sh NAME 34.Nm getcwd , 35.Nm getwd 36.Nd get working directory pathname 37.Sh SYNOPSIS 38.In unistd.h 39.Ft char * 40.Fn getcwd "char *buf" "size_t size" 41.Ft char * 42.Fn getwd "char *buf" 43.Sh DESCRIPTION 44The 45.Fn getcwd 46function copies the absolute pathname of the current working directory 47into the memory referenced by 48.Fa buf 49and returns a pointer to 50.Fa buf . 51The 52.Fa size 53argument is the size, in bytes, of the array referenced by 54.Fa buf . 55.Pp 56If 57.Fa buf 58is not 59.Dv NULL 60and the length of the pathname plus the terminating NUL 61character is greater than 62.Fa size , 63a null pointer is returned and 64.Va errno 65is set to 66.Dv ERANGE . 67.Pp 68As an extension to 69.St -p1003.1-2001 , 70if 71.Fa buf 72is 73.Dv NULL , 74space is allocated as necessary to store the pathname. 75In this case, it is the responsibility of the caller to 76.Xr free 3 77the pointer that 78.Fn getcwd 79returns. 80.Pp 81The deprecated 82.Fn getwd 83function is similar to 84.Fn getcwd , 85but assumes that 86.Fa buf 87is non-NULL and has a size of 88.Dv PATH_MAX 89(as defined by the include 90file 91.In limits.h ) . 92It does not allocate memory and is provided for source compatibility only. 93If the length of the pathname plus the terminating NUL 94character is greater than 95.Dv PATH_MAX , 96a null pointer is returned. 97On error, 98.Fn getwd 99writes an error message into the memory referenced by 100.Fa buf . 101.Pp 102These functions have traditionally been used by programs to save the 103name of a working directory for the purpose of returning to it. 104A much faster and less error-prone method of accomplishing this is to 105open the current directory 106.Pq Pa \&. 107and use the 108.Xr fchdir 2 109function to return. 110.Sh RETURN VALUES 111Upon successful completion, a pointer to the pathname is returned. 112Otherwise a null pointer is returned and 113.Va errno 114is set to indicate the error. 115In addition, 116.Fn getwd 117copies the error message associated with 118.Va errno 119into the memory referenced by 120.Fa buf . 121.Sh ERRORS 122The 123.Fn getcwd 124function will fail if: 125.Bl -tag -width Er 126.It Bq Er EACCES 127Read or search permission was denied for a component of the pathname. 128.It Bq Er EFAULT 129.Fa buf 130points to an invalid address. 131.It Bq Er EINVAL 132The 133.Fa size 134argument is zero. 135.It Bq Er ENOENT 136A component of the pathname no longer exists. 137.It Bq Er ENOMEM 138Insufficient memory is available. 139.It Bq Er ERANGE 140The 141.Fa size 142argument is greater than zero but smaller than the length of the pathname 143plus 1. 144.El 145.Sh SEE ALSO 146.Xr pwd 1 , 147.Xr chdir 2 , 148.Xr malloc 3 , 149.Xr strerror 3 150.Sh STANDARDS 151The 152.Fn getcwd 153function conforms to 154.St -p1003.1-2001 . 155The ability to specify a null pointer and have 156.Fn getcwd 157allocate memory as necessary is an extension. 158.Sh HISTORY 159The 160.Fn getwd 161function first appeared in 162.Bx 4.0 . 163The 164.Fn getcwd 165function first appeared in 166.At V.1 167and was reimplemented for 168.Bx 4.3 Net/2 . 169.Pp 170In 171.Ox 4.0 , 172.Fn getcwd 173was reimplemented on top of the 174.Fn __getcwd 175system call. 176Its calling convention differs from the standard 177function by requiring 178.Ar buf 179to not be 180.Dv NULL 181and by returning an integer, 182zero on success, and -1 with corresponding errno on failure. 183This is visible in the output of 184.Xr kdump 1 . 185.Sh BUGS 186The 187.Fn getwd 188function does not do sufficient error checking and is not able to return very 189long, but valid, paths. 190It is provided for compatibility only. 191