GETCWD(3POSIX)

💅 GETCWD(3POSIX) — the POSIX Programmer's Manual era 💅

okay bestie so this page is straight outta the POSIX Programmer's Manual (yes, that's the POSIX Programmer's Manual, GETCWD(3POSIX), we love a certified classic 🎀). heads up though: the Linux implementation of this interface may differ — so if you're on Linux, pls consult the corresponding Linux manual page for the deets on Linux behavior — or honestly the interface may not even be implemented on Linux at all. vibe check first, always 🦋

---

✨ PROLOG ✨

This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux. no cap, that's the whole disclaimer 💀

---

🌸 NAME 🌸

getcwd — get the pathname of the current working directory. it does exactly what it says on the tin, iconic behavior, no notes 👑

---

⭐ SYNOPSIS ⭐

#include <unistd.h>

char *getcwd(char *buf, size_t size);

---

🦋 DESCRIPTION 🦋

okay so the getcwd() function shall place an absolute pathname of the current working directory in the array pointed to by buf, and it returns buf. periodt. and the pathname shall contain no components that are dot or dot-dot, or are symbolic links. so like… no ., no .., no symlink shenanigans. clean. fresh. immaculate ✨

now if there are multiple pathnames that getcwd() could place in the array pointed to by buf — one beginning with a single <slash> character and one or more beginning with two <slash> characters — then getcwd() shall place the pathname beginning with a single <slash> character in the array. yes bestie, one slash wins, it's giving minimalist 💅 and the pathname shall not contain any unnecessary <slash> characters after the leading one or two <slash> characters. no double-slashes lurking in the middle, we're not animals 🙈

the size argument is the size in bytes of the character array pointed to by the buf argument. and here's the big one, the plot twist: if buf is a null pointer, the behavior of getcwd() is unspecified. 😭 that's UB territory, don't do it, that's not a vibe, that's a crash

---

💖 RETURN VALUE 💖

Upon successful completion, getcwd() shall return the buf argument. slay.

Otherwise, getcwd() shall return a null pointer and set errno to indicate the error. and then? the contents of the array pointed to by buf are undefined. so like, whatever's in that buffer now? not yours. not real. don't look at it 💀

---

🔥 ERRORS 🔥

The getcwd() function shall fail if:

• EINVAL — The size argument is 0. (you asked for zero bytes. zero. bestie what did you expect 😭)
• ERANGE — The size argument is greater than 0, but is smaller than the length of the string +1. (close but not close enough, so rude)

The getcwd() function may fail if:

• EACCES — Search permission was denied for the current directory, or read or search permission was denied for a directory above the current directory in the file hierarchy. (permissions said no 🚫)
• ENOMEM — Insufficient storage space is available. (the memory said no too 🫠)

The following sections are informative. (so like, the lore, the backstory, the director's commentary 🎬)

---

🎀 EXAMPLES 🎀

The following example uses {PATH_MAX} as the initial buffer size (unless it is indeterminate or very large), and calls getcwd() with progressively larger buffers until it does not give an [ERANGE] error. it's giving persistence, it's giving growth mindset 🌈

#include <stdlib.h>
#include <errno.h>
#include <unistd.h>

...

long path_max;
size_t size;
char *buf;
char *ptr;

path_max = pathconf(".", _PC_PATH_MAX);
if (path_max == -1)
    size = 1024;
else if (path_max > 10240)
    size = 10240;
else
    size = path_max;

for (buf = ptr = NULL; ptr == NULL; size *= 2)
{
    if ((buf = realloc(buf, size)) == NULL)
    {
        ... handle error ...
    }

    ptr = getcwd(buf, size);
    if (ptr == NULL && errno != ERANGE)
    {
        ... handle error ...
    }
}
...
free (buf);

see how size *= 2 just keeps doubling?? that's the glow-up arc fr fr 🔥

---

🧚 APPLICATION USAGE 🧚

If the pathname obtained from getcwd() is longer than {PATH_MAX} bytes, it could produce an [ENAMETOOLONG] error if passed to chdir(). so yeah, you can get the path but not necessarily go to it, which is deeply unfair and I'm mad about it 😤

Therefore, in order to return to that directory it may be necessary to break the pathname into sections shorter than {PATH_MAX} bytes and call chdir() on each section in turn (the first section being an absolute pathname and subsequent sections being relative pathnames). chunk it up, bestie, little bites 🍓

A simpler way to handle saving and restoring the working directory when it may be deeper than {PATH_MAX} bytes in the file hierarchy is to use a file descriptor and fchdir(), rather than getcwd() and chdir(). However, the two methods do have some differences:

• The fchdir() approach causes the program to restore a working directory even if it has been renamed in the meantime.
• The chdir() approach restores to a directory with the same name as the original, even if the directories were renamed in the meantime.

Since the fchdir() approach does not access parent directories, it can succeed when getcwd() would fail due to permissions problems. 👑

In applications conforming to earlier versions of this standard, it was not possible to use the fchdir() approach when the working directory is searchable but not readable, as the only way to open a directory was with O_RDONLY, whereas the getcwd() approach can succeed in this case. so like, historical plot twist, the old way had the W here 📜

---

💜 RATIONALE 💜

okay gather round, storytime 📖

Having getcwd() take no arguments and instead use the malloc() function to produce space for the returned argument was considered. The advantage is that getcwd() knows how big the working directory pathname is and can allocate an appropriate amount of space. But — and this is the catch — the programmer would have to use the free() function to free the resulting object, or each use of getcwd() would further reduce the available memory. memory leak speedrun, not the move 💀

Finally, getcwd() is taken from the SVID where it has the two arguments used in this volume of POSIX.1‐2017. yes it's old. it's vintage. it's archival. respect the elders 🫶

The older function getwd() was rejected for use in this context because it had only a buffer argument and no size argument, and thus had no way to prevent overwriting the buffer, except to depend on the programmer to provide a large enough buffer. so basically it was a "trust me bro" API. rejected. cancelled. not invited to the function party 🙅

On some implementations, if buf is a null pointer, getcwd() may obtain size bytes of memory using malloc(). In this case, the pointer returned by getcwd() may be used as the argument in a subsequent call to free(). Invoking getcwd() with buf as a null pointer is not recommended in conforming applications. ⚠️ like I said. do not. it's not specified behavior, it's just "some implementations happen to do this." don't build on vibes.

Earlier implementations of getcwd() sometimes generated pathnames like "../../../subdirname" internally, using them to explore the path of ancestor directories back to the root. If one of these internal pathnames exceeded {PATH_MAX} in length, the implementation could fail with errno set to [ENAMETOOLONG]. This is no longer allowed. retro behavior, we do not miss it, rip bozo ✌️

If a program is operating in a directory where some (grand)parent directory does not permit reading, getcwd() may fail, as in most implementations it must read the directory to determine the name of the file. This can occur if search, but not read, permission is granted in an intermediate directory, or if the program is placed in that directory by some more privileged process (for example, login). Including the [EACCES] error condition makes the reporting of the error consistent and warns the application developer that getcwd() can fail for reasons beyond the control of the application developer or user. 😭 the audacity, honestly

Some implementations can avoid this occurrence (for example, by implementing getcwd() using pwd, where pwd is a set-user-root process), thus the error was made optional. Since this volume of POSIX.1‐2017 permits the addition of other errors, this would be a common addition and yet one that applications could not be expected to deal with without this addition. so it's optional but everyone does it, which is the most relatable thing about this entire manpage ngl 🫠

---

🌈 FUTURE DIRECTIONS 🌈

None. (the future is empty. no notes. moving on. periodt 💅)

---

👑 SEE ALSO 👑

• malloc()
• The Base Definitions volume of POSIX.1‐2017, <unistd.h>

---

📜 COPYRIGHT 📜

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

ok that's the whole thing bestie, every flag, every error code, every historical grievance, preserved with love 🫶

and that's a wrap!! this page came to you courtesy of IEEE/The Open Group, 2017, filed under GETCWD(3POSIX) — drink some water, free your buffers, and remember: if buf is null the behavior is unspecified and I will be checking 💖✨🎀