basename(3)basename(3)NAME
basename, dirname, dirname_r - Return the base filename or directory
portion of a pathname
SYNOPSIS
#include <libgen.h>
char *basename(
char *path ); char *dirname(
char *path );
The following function is supported only for backward compatibility:
#include <string.h>
int dirname_r
char *path,
char *buf,
int size );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
basename(), dirname(): XSH4.2
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
The string from which the base pathname or the directory portion is to
be extracted. [Tru64 UNIX] Specifies a working buffer to hold the
directory name component. [Tru64 UNIX] Specifies the length of buf.
DESCRIPTION
The basename() and dirname() functions complement each other. The base‐
name() function reads path and returns a pointer to the final component
of the pathname, deleting any trailing / (slash) characters. If the
string consists entirely of the / (slash) character, basename() returns
a pointer to the string / (slash). If path is a null pointer or points
to an empty string, basename() returns a pointer to the string
(period).
[Tru64 UNIX] In applications that are compiled in an environment that
excludes the _XOPEN_SOURCE_EXTENDED standard definitions, the base‐
name() function returns an empty string if the string consists entirely
of the / (slash) character. If path is a null pointer, basename()
returns a core dump. If path points to an empty string, basename()
returns an empty string.
The dirname() function reads path and returns a pointer to a new string
that is a pathname of the parent directory of that file. Trailing /
(slash) characters in the path are not counted as part of the path. If
there is no / (slash), if path is a null pointer, or if path points to
an empty string, the dirname() function returns a pointer to the string
(period).
[Tru64 UNIX] In applications that are compiled in an environment that
excludes the _XOPEN_SOURCE_EXTENDED standard definitions, the dirname()
function returns a NULL if there is no / (slash), and a core dump if
path is a null pointer, or if path points to an empty string.
The dirname_r() function is the reentrant version of the dirname()
function. It is supported only to maintain backward compatibility with
versions of the operating system prior to Digital UNIX Version 4.0.
NOTES
The value returned by the basename() and dirname() functions is a
pointer to a thread-specific buffer whose contents will be overwritten
on subsequent calls from the same thread.
[Tru64 UNIX] The basename(), dirname(), and dirname_r() functions
belong to a small set of libc functions that are handled differently
when compiled in the X/Open UNIX environment. In the X/Open UNIX envi‐
ronment, calls to these functions are internally renamed by prepending
_E to the function name. The renaming is done only when there is an
incompatible conflict between an existing version of the function and
the version that conforms to the X/Open UNIX standard. The renaming
strategy supports binary compatibility by allowing applications to com‐
pile in the X/Open UNIX environment and also link with site-specific
and third-party libraries that use the old versions of the same libc
interfaces. However, internal renaming of the calls affects how these
calls are identified during debugging sessions. Therefore, when you are
debugging a module that includes the basename() and/or dirname() or
dirname_r() functions and for which _XOPEN_SOURCE_EXTENDED has been
defined, use _Ebasename to refer to the basename() call and _Edirname
to refer to the dirname call and _Edirname_r to refer to the dirname_r
call. See standards(5) for information on when the
_XOPEN_SOURCE_EXTENDED macro is defined.
RETURN VALUES
Upon success, the basename() and dirname() functions return the compo‐
nent string. Upon failure, these functions return NULL. If there is no
/ (slash), the dirname() function returns a (period).
[Tru64 UNIX] In applications that are compiled in an environment that
excludes the _XOPEN_SOURCE_EXTENDED standard definitions, the dirname()
function returns NULL if there is no / (slash).
[Tru64 UNIX] Upon successful completion, the dirname_r() function
returns a value of 0 (zero) and places the directory name component in
the buffer pointed at by buf. Upon failure (for example, if there is no
/ (slash)), the dirname_r() function returns -1 and sets errno.
ERRORS
If the dirname_r() function fails, errno may be set to the following:
The value of the buf parameter is invalid or too small.
SEE ALSO
Commands: basename(1)
Standards: standards(5)basename(3)