1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getcwd.3 8.2 (Berkeley) 12/11/93 7.\" 8.Dd 9.Dt GETCWD 3 10.Os BSD 4.2 11.Sh NAME 12.Nm getcwd 13.Nd get working directory pathname 14.Sh SYNOPSIS 15.Fd #include <stdio.h> 16.Ft char * 17.Fn getcwd "char *buf" "size_t size" 18.Ft char * 19.Fn getwd "char *buf" 20.Sh DESCRIPTION 21The 22.Fn getcwd 23function copies the absolute pathname of the current working directory 24into the memory referenced by 25.Fa buf 26and returns a pointer to 27.Fa buf . 28The 29.Fa size 30argument is the size, in bytes, of the array referenced by 31.Fa buf . 32.Pp 33If 34.Fa buf 35is 36.Dv NULL , 37space is allocated as necessary to store the pathname. 38This space may later be 39.Xr free 3 Ns 'd. 40.Pp 41The function 42.Fn getwd 43is a compatibility routine which calls 44.Fn getcwd 45with its 46.Fa buf 47argument and a size of 48.Dv MAXPATHLEN 49(as defined in the include 50file 51.Aq Pa sys/param.h ) . 52Obviously, 53.Fa buf 54should be at least 55.Dv MAXPATHLEN 56bytes in length. 57.Pp 58These routines have traditionally been used by programs to save the 59name of a working directory for the purpose of returning to it. 60A much faster and less error-prone method of accomplishing this is to 61open the current directory 62.Pq Ql \&. 63and use the 64.Xr fchdir 2 65function to return. 66.Sh RETURN VALUES 67Upon successful completion, a pointer to the pathname is returned. 68Otherwise a 69.Dv NULL 70pointer is returned and the global variable 71.Va errno 72is set to indicate the error. 73In addition, 74.Fn getwd 75copies the error message associated with 76.Va errno 77into the memory referenced by 78.Fa buf . 79.Sh ERRORS 80The 81.Fn getcwd 82function 83will fail if: 84.Bl -tag -width [EACCESS] 85.It Bq Er EACCESS 86Read or search permission was denied for a component of the pathname. 87.It Bq Er EINVAL 88The 89.Fa size 90argument is zero. 91.It Bq Er ENOENT 92A component of the pathname no longer exists. 93.It Bq Er ENOMEM 94Insufficient memory is available. 95.It Bq Er ERANGE 96The 97.Fa size 98argument is greater than zero but smaller than the length of the pathname 99plus 1. 100.El 101.Sh SEE ALSO 102.Xr chdir 2 , 103.Xr fchdir 2 , 104.Xr malloc 3 , 105.Xr strerror 3 106.Sh STANDARDS 107The 108.Fn getcwd 109function 110conforms to 111.St -ansiC . 112The ability to specify a 113.Dv NULL 114pointer and have 115.Fn getcwd 116allocate memory as necessary is an extension. 117.Sh HISTORY 118The 119.Fn getwd 120function appeared in 121.Bx 4.0 . 122.Sh BUGS 123The 124.Fn getwd 125function 126does not do sufficient error checking and is not able to return very 127long, but valid, paths. 128It is provided for compatibility. 129