The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

#### 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. Trailing `'/'` characters in the path are not 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 need not be reentrant. A function that is not required to be reentrant is not required to be thread-safe.

#### RETURN VALUE

> The dirname() function shall return a pointer to a string that is the parent directory of path. If path is a null pointer or points to an empty string, a pointer to a string `"."` is returned.

> 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 subsequent calls to dirname().

#### 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[PATH_MAX], *pathcopy;
>     int fd;
>     fgets(path, PATH_MAX, stdin);
>     pathcopy = strdup(path);
>     chdir(dirname(pathcopy));
>     fd = open(basename(path), O_RDONLY);

> ##### Sample Input and Output Strings for dirname()

> In the following table, the input string is the value pointed to by path, and the output string is the return value of the dirname() function.

> Input String | Output String
> --- | ---
> "/usr/lib" | "/usr"
> "/usr/" | "/"
> "usr" | "."
> "/" | "/"
> "." | "."
> ".." | "."

> ##### Changing the Current Directory to the Parent Directory

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

>     #include <unistd.h>
>     #include <limits.h>
>     #include <stdio.h>
>     #include <fcntl.h>
>     #include <string.h>
>     #include <libgen.h>
>     ...
>     char path[PATH_MAX], *pathcopy;
>     int fd;
>     ...
>     fgets(path, PATH_MAX, stdin);
>     pathcopy = strdup(path);
>     chdir(dirname(pathcopy));
>     fd = open(basename(path), O_RDONLY);

#### 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(), the Base Definitions volume of IEEE Std 1003.1-2001, <libgen.h>

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

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]