DIRNAME(3P)

💖 hey bestie, welcome to DIRNAME(3P) 💖

okay so this one is from the POSIX Programmer's Manual, and I need you to clock that before we go any further. 🫶

🌸 PROLOG 🌸

so like, real talk: this manual page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ (so if you're on Linux, go check the corresponding Linux manual page for the actual Linux behavior, bestie), or honestly the interface may not even be implemented on Linux at all. 💀

---

✨ NAME ✨

dirname — she reports the parent directory name of a file pathname. that's her whole job and she does it flawlessly, no cap. 👑

---

✨ SYNOPSIS ✨

#include <libgen.h>

char *dirname(char *path);

---

✨ DESCRIPTION ✨

okay so dirname() shall take a pointer to a character string that contains a pathname, and return a pointer to a string that is a pathname of the parent directory of that file. that's it, that's the gig. 💅

and listen — dirname() shall not perform pathname resolution. the result shall not be affected by whether or not path exists or by its file type. she does not care, she does not check, she just does string math. trailing '/' characters in the path that are not also leading '/' characters shall not be counted as part of the path.

if path does not contain a '/', then dirname() shall return a pointer to the string ".". and if path is a null pointer or points to an empty string, dirname() shall return a pointer to the string ".". same energy either way. 💖

🚨 IMPORTANT SIS: the dirname() function may modify the string pointed to by path, and may return a pointer to static storage that may then be overwritten by a subsequent call to dirname().

and the dirname() function need not be thread-safe. 😭 like, she's not built for that. respect it.

---

✨ RETURN VALUE ✨

the dirname() function shall return a pointer to a string as described above. 💫

the dirname() function may modify the string pointed to by path, and may return a pointer to internal storage. the returned pointer might be invalidated or the storage might be overwritten by a subsequent call to dirname(). the returned pointer might also be invalidated if the calling thread is terminated. 🙈

so basically: use it, love it, but don't hold onto that pointer like it's gonna last forever, because she will move on.

---

✨ ERRORS ✨

no errors are defined. like, none. zero. not a single one. she simply does not fail, she just vibes. ✨

the following sections are informative. 📖

---

✨ EXAMPLES ✨

okay here's a lil code fragment that reads a pathname, changes the current working directory to the parent directory, and opens the file. iconic behavior honestly:

char *path = NULL, *pathcopy;
size_t buflen = 0;
ssize_t linelen = 0;
int fd;

linelen = getline(&path, &buflen, stdin);

path[linelen-1] = 0;
pathcopy = strdup(path);
if (chdir(dirname(pathcopy)) < 0) {
    ...
}
if ((fd = open(basename(path), O_RDONLY)) >= 0) {
    ...
    close (fd);
}
...
free (pathcopy);
free (path);

and bestie, the EXAMPLES section of the basename() function (see basename()) includes a table showing examples of the results of processing several sample pathnames by the basename() and dirname() functions and by the basename and dirname utilities. go look, it's giving visual learner. 📊💖

---

✨ APPLICATION USAGE ✨

the dirname() and basename() functions together yield a complete pathname. the expression dirname(path) obtains the pathname of the directory where basename(path) is found. they're a duo. a package deal. the main characters. 👑

and since the meaning of the leading "//" is implementation-defined, dirname("//foo) may return either "//" or '/' (but nothing else). so like... don't be weird about it. 🦋

---

✨ RATIONALE ✨

none. 💀 (she said nothing, your honor.)

---

✨ FUTURE DIRECTIONS ✨

none. 🔮 (also nothing. the future is a mystery and she is not commenting on it.)

---

✨ SEE ALSO ✨

• basename()
• The Base Definitions volume of POSIX.1‐2017, <libgen.h>
• The Shell and Utilities volume of POSIX.1‐2017, basename, dirname

---

✨ 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 .

---

and that's the whole page, bestie!! this one came to you from IEEE/The Open Group, dated 2017, and its manual page name is DIRNAME(3P). go forth and dirname responsibly. mwah. 💅💖🎀