DIRNAME(3) Library Functions Manual DIRNAME(3)

dirname — report the parent directory name of a file pathname


#include <libgen.h>

char *dirname(char *path);

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.

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

No errors are defined.

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

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

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

The dirname () and basename(3) functions together yield a complete pathname. The expression dirname ( path) obtains the pathname of the directory where ( path) is found.

Since the meaning of the leading "//" is implementation-defined, dirname (" ) may return either "//" or ‘/’ (but nothing else).

None.

None.

basename(3) , the Base Definitions volume of IEEE Std 1003.1-2001 (“POSIX.1”), <libgen.h>

First released in Issue 4, Version 2.

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.

footer end

December 6, 2001 posix.fail