NAME
dirname — report
the parent directory name of a file pathname
SYNOPSIS
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 directory containing the entry of the
final pathname component. 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 pathname that
are not also leading ‘/’ characters
shall not be counted as part of the pathname.
If the pathname 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
".".
It is unspecified whether redundant
‘/’ characters and
‘’. pathname components in
path are removed after determining the pathname to output.
However, ".." pathname components
occurring prior to the final component shall not be removed.
The dirname () function may modify the
string pointed to by path, and may return a pointer into
the input string. The returned pointer might be invalidated if the input
string is subsequently modified or freed. If path does not
contain a ‘/’, is a null pointer, or
points to an empty string the returned pointer may point to constant data
that cannot be modified.
RETURN VALUE
The dirname () function shall return a
pointer to a string as described above.
The dirname () function shall always be
successful and no return value is reserved to indicate an error.
ERRORS
No errors are defined.
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(3) function
(see basename(3)) includes a table showing examples of the
results of processing several sample pathnames by the
basename(3) and dirname ()
functions and by the basename(1) and
dirname(1) utilities.
APPLICATION USAGE
The dirname () and
basename(3) 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).
Note that in some circumstances, the returned pointer might point into constant data. Therefore, if the application needs to modify the returned data, it should be copied first.
RATIONALE
An implementation should prefer the shortest output possible;
however, this is not required, in part because earlier versions of the
standard did not mention whether elision of redundant <slash>
characters or dot ( ".") components was
permitted. Removal of the dot-dot ( "..")
pathname component is not permitted, because eliding it correctly would
require performing pathname resolution to ensure the resulting string would
still point to the correct pathname if the original string resolved as a
pathname. On implementations where pathname
"//" has an implementation-defined meaning
distinct from the pathname "/", the
dirname of "//" will be
"//".
Earlier versions of this standard seemed to allow
thread-safe and non-thread-safe implementations of
basename(3) and dirname (), but
did not allow implementations to return a null pointer and require that
errno be set when
that happened. The standard now requires thread-safe behavior for both of
these functions and clearly states that they are always successful.
FUTURE DIRECTIONS
None.
SEE ALSO
XBD <libgen.h>
XCU basename(1), dirname(1)
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.
Issue 8
Austin Group Defect 1064 is applied, requiring
dirname () to be thread-safe and allowing it to
return a pointer to constant data under certain conditions.
Austin Group Defect 1073 is applied, changing "parent
directory of that file" to "directory containing the entry of the
final pathname component" and clarifying that redundant
‘/’ characters and
‘’. pathname components may be removed
after determining the pathname to output.