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