DIRNAME(3) Linux Programmer's Manual DIRNAME(3)
NAME
dirname, basename(1,3,3 File::Basename) - Parse pathname components
SYNOPSIS
#include <libgen.h>
char *dirname(char *path);
char *basename(1,3,3 File::Basename)(char *path);
DESCRIPTION
Warning: there are two different functions basename(1,3,3 File::Basename) - see below.
The functions dirname and basename(1,3,3 File::Basename) break a null-terminated pathname
string(3,n) into directory and filename components. In the usual case,
dirname returns the string(3,n) up to, but not including, the final '/', and
basename(1,3,3 File::Basename) returns the component following the final '/'. Trailing '/'
characters are not counted as part of the pathname.
If path does not contain a slash, dirname returns the string(3,n) "." while
basename(1,3,3 File::Basename) returns a copy of path. If path is the string(3,n) "/", then both
dirname and basename(1,3,3 File::Basename) return the string(3,n) "/". If path is a NULL pointer
or points to an empty string(3,n), then both dirname and basename(1,3,3 File::Basename) return the
string(3,n) ".".
Concatenating the string(3,n) returned by dirname, a "/", and the string(3,n)
returned by basename(1,3,3 File::Basename) yields a complete pathname.
Both dirname and basename(1,3,3 File::Basename) may modify the contents of path, so copies
should be passed to these functions. Furthermore, dirname and basename(1,3,3 File::Basename)
may return pointers to statically allocated memory which may be over-
written by subsequent calls.
The following list of examples (taken from SUSv2) shows the strings
returned by dirname and basename(1,3,3 File::Basename) for different paths:
path dirname basename(1,3,3 File::Basename)
"/usr/lib" "/usr" "lib"
"/usr/" "/" "usr"
"usr" "." "usr"
"/" "/" "/"
"." "." "."
".." "." ".."
EXAMPLE
char *dirc, *basec, *bname, *dname;
char *path = "/etc/passwd(1,5)";
dirc = strdup(path);
basec = strdup(path);
dname = dirname(dirc);
bname = basename(1,3,3 File::Basename)(basec);
printf(1,3,1 builtins)("dirname=%s, basename(1,3,3 File::Basename)=%s\n", dname, bname);
RETURN VALUE
Both dirname and basename(1,3,3 File::Basename) return pointers to null-terminated strings.
NOTES
There are two different versions of basename(1,3,3 File::Basename) - the POSIX version(1,3,5)
described above, and the GNU version(1,3,5) one gets(3,n) after
#define _GNU_SOURCE
#include <string.h>
The GNU version(1,3,5) never modifies its argument, and returns the empty
string(3,n) when path has a trailing slash, and in(1,8) particular also when it
is "/". There is no GNU version(1,3,5) of dirname.
With glibc, one gets(3,n) the POSIX version(1,3,5) of basename(1,3,3 File::Basename) when <libgen.h> is
included, and the GNU version(1,3,5) otherwise.
BUGS
In the glibc implementation of the POSIX versions of these functions
they modify their argument, and segfault when called with a static
string(3,n) like "/usr/". Before glibc 2.2.1, the glibc version(1,3,5) of dirname
did not correctly handle pathnames with trailing '/' characters, and
generated a segfault if(3,n) given a NULL argument.
CONFORMING TO
POSIX 1003.1-2001
SEE ALSO
basename(1,3,3 File::Basename)(1), dirname(1)
GNU 2000-12-14 DIRNAME(3)