<<< Previous | Home | Next >>>

The Open Group Base Specifications Issue 7
IEEE Std 1003.1-2008
Copyright © 2001-2008 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. 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 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 = 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);

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

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

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

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-2008 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]

<<< Previous | Home | Next >>>