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 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.
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).
RATIONALE
None.
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.