1.\"	$OpenBSD: getcwd.3,v 1.22 2021/12/16 19:15:29 millert 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: December 16 2021 $
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 ,
163and
164.Fn getcwd
165in
166.Bx 4.3 Net/2 .
167.Pp
168In
169.Ox 4.0 ,
170.Fn getcwd
171was reimplemented on top of the
172.Fn __getcwd
173system call.
174Its calling convention differs from the standard
175function by requiring
176.Ar buf
177to not be
178.Dv NULL
179and by returning an integer,
180zero on success, and -1 with corresponding errno on failure.
181This is visible in the output of
182.Xr kdump 1 .
183.Sh BUGS
184The
185.Fn getwd
186function does not do sufficient error checking and is not able to return very
187long, but valid, paths.
188It is provided for compatibility only.
189