xref: /illumos-gate/usr/src/man/man3c/getcwd.3c (revision bbf215553c7233fbab8a0afdf1fac74c44781867)
1.\"
2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3.\" permission to reproduce portions of its copyrighted documentation.
4.\" Original documentation from The Open Group can be obtained online at
5.\" http://www.opengroup.org/bookstore/.
6.\"
7.\" The Institute of Electrical and Electronics Engineers and The Open
8.\" Group, have given us permission to reprint portions of their
9.\" documentation.
10.\"
11.\" In the following statement, the phrase ``this text'' refers to portions
12.\" of the system documentation.
13.\"
14.\" Portions of this text are reprinted and reproduced in electronic form
15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16.\" Standard for Information Technology -- Portable Operating System
17.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
20.\" between these versions and the original IEEE and The Open Group
21.\" Standard, the original IEEE and The Open Group Standard is the referee
22.\" document.  The original Standard can be obtained online at
23.\" http://www.opengroup.org/unix/online.html.
24.\"
25.\" This notice shall appear on any product containing this material.
26.\"
27.\" The contents of this file are subject to the terms of the
28.\" Common Development and Distribution License (the "License").
29.\" You may not use this file except in compliance with the License.
30.\"
31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32.\" or http://www.opensolaris.org/os/licensing.
33.\" See the License for the specific language governing permissions
34.\" and limitations under the License.
35.\"
36.\" When distributing Covered Code, include this CDDL HEADER in each
37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38.\" If applicable, add the following below this CDDL HEADER, with the
39.\" fields enclosed by brackets "[]" replaced with your own identifying
40.\" information: Portions Copyright [yyyy] [name of copyright owner]
41.\"
42.\"
43.\" Copyright 1989 AT&T
44.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
45.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
46.\" Copyright 2021 OmniOS Community Edition (OmniOSce) Association.
47.\"
48.Dd February 27, 2021
49.Dt GETCWD 3C
50.Os
51.Sh NAME
52.Nm getcwd
53.Nd get pathname of current working directory
54.Sh SYNOPSIS
55.In unistd.h
56.Ft "char *"
57.Fo getcwd
58.Fa "char *buf"
59.Fa "size_t size"
60.Fc
61.Sh DESCRIPTION
62The
63.Fn getcwd
64function returns a pointer to a buffer containing the absolute pathname of the
65current working directory.
66The returned pathname contains no components that are symbolic links.
67.Pp
68When
69.Fa buf
70is not
71.Dv NULL ,
72the absolute pathname will be written into
73.Fa buf
74and
75.Fa size
76represents the length in bytes of
77.Fa buf .
78If the length of the pathname and nul terminator exceeds
79.Fa size ,
80nothing will be written and
81.Fn getcwd
82will return
83.Dv NULL .
84Otherwise,
85.Fn getcwd
86returns
87.Fa buf .
88.Pp
89When
90.Fa buf
91is
92.Dv NULL
93then
94.Fn getcwd
95will allocate memory in which to store the pathname of the current working
96directory.
97If
98.Fa size
99is non-zero, then
100.Fa size
101bytes will be allocated.
102If the length of the pathname and nul terminator exceeds
103.Fa size ,
104the memory will be freed and
105.Fn getcwd
106will return
107.Dv NULL .
108If
109.Fa size
110is zero, then
111.Fn getcwd
112will attempt to allocate enough space to hold the pathname.
113In both cases, it is the caller's responsibility to free the returned buffer
114with the
115.Xr free 3C
116function.
117.Sh RETURN VALUES
118Upon successful completion, the
119.Fn getcwd
120function returns a pointer to a buffer containing the pathname.
121Otherwise,
122.Dv NULL
123is returned and
124.Va errno
125is set to indicate the error.
126.Sh EXAMPLES
127.Sy Example 1
128Determine the absolute pathname of the current working directory.
129.Pp
130The following example returns a pointer to an array that holds the absolute
131pathname of the current working directory.
132The pointer is returned in the
133.Va ptr
134variable, which points to the
135.Va buf
136array where the pathname is stored.
137.Bd -literal -offset Ds
138#include <stdlib.h>
139#include <unistd.h>
140\&...
141long size;
142char *buf;
143char *ptr;
144size = pathconf(".", _PC_PATH_MAX);
145if ((buf = (char *)malloc((size_t)size)) != NULL)
146	ptr = getcwd(buf, (size_t)size);
147\&...
148.Ed
149.Pp
150.Sy Example 2
151Print the current working directory.
152.Pp
153The following example prints the current working directory.
154.Bd -literal -offset Ds
155#include <stdio.h>
156#include <unistd.h>
157
158int
159main(void)
160{
161	char *cwd;
162
163	if ((cwd = getcwd(NULL, 0)) == NULL) {
164		perror("pwd");
165		exit(2);
166	}
167	(void)printf("%s\en", cwd);
168	free(cwd); /* free memory allocated by getcwd() */
169	return(0);
170}
171.Ed
172.Sh ERRORS
173The
174.Fn getcwd
175function will fail if:
176.Bl -tag -width Er
177.It Er EFAULT
178The
179.Fa buf
180argument points to an invalid address.
181.It Er EINVAL
182The
183.Fa buf
184argument is not
185.Dv NULL
186and the
187.Fa size
188argument is 0.
189.It Er ERANGE
190The pathname
191.Pq including its terminating nul character
192is too long to fit into the provided
193.Pq or allocated
194buffer.
195.It Er EACCESS
196A parent directory cannot be read to get its name.
197.It Er ENOMEM
198Insufficient storage space is available.
199.El
200.Sh USAGE
201Applications should exercise care when using
202.Xr chdir 2
203in conjunction with
204.Fn getcwd .
205The current working directory is global to all threads within a process.
206If more than one thread calls
207.Xr chdir 2
208to change the working directory, a subsequent call to
209.Fn getcwd
210could produce unexpected results.
211.Sh INTERFACE STABILITY
212.Sy Committed
213.Sh SEE ALSO
214.Xr chdir 2 ,
215.Xr free 3C ,
216.Xr attributes 7 ,
217.Xr standards 7
218