The Open Group Base Specifications Issue 7
IEEE Std 1003.1-2008, 2016 Edition
Copyright © 2001-2016 The IEEE and The Open Group

#### NAME

> dirname - report the parent directory name of a file pathname

#### SYNOPSIS

> ``[XSI] #include <libgen.h>
> char *dirname(char *`path`);``
> `
> `

#### DESCRIPTION

> The dirname() function 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. The dirname() function shall not perform pathname resolution; the result shall not be affected by whether or not path exists or by its file type. 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 `"."`. If path is a null pointer or points to an empty string, dirname() shall return a pointer to the string `"."` .

> 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().

> The dirname() function need not be thread-safe.

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

#### ERRORS

> No errors are defined.

The following sections are informative.

#### EXAMPLES

> The following code fragment reads a pathname, changes the current working directory to the parent directory, and opens the file.

>     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);

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

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

> Since the meaning of the leading `"//"` is implementation-defined, dirname(" //foo) may return either `"//"` or `'/'` (but nothing else).

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> basename

> XBD <libgen.h>

> XCU basename, dirname

#### CHANGE HISTORY

> First released in Issue 4, Version 2.

#### Issue 5

> Moved from X/OPEN UNIX extension to BASE.

> Normative text previously in the APPLICATION USAGE section is moved to the DESCRIPTION.

> A note indicating that this function need not be reentrant is added to the DESCRIPTION.

#### Issue 7

> Austin Group Interpretation 1003.1-2001 #156 is applied.

> The EXAMPLES section is revised.

> POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0068 [75] is applied.

> POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0077 [830], XSH/TC2-2008/0078 [612], XSH/TC2-2008/0079 [830], XSH/TC2-2008/0080 [656], and XSH/TC2-2008/0081 [612] are applied.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2016 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]