475 lines
8.7 KiB
Groff
Executable File
475 lines
8.7 KiB
Groff
Executable File
.\" t
|
|
.TH DIRNAME 3 04-Jan-2007 MinGW "Programmer's Reference Manual"
|
|
.
|
|
.SH NAME
|
|
.
|
|
.BR dirname ,\0 basename
|
|
\- parse path name components
|
|
.
|
|
.
|
|
.SH SYNOPSIS
|
|
.
|
|
.B #include
|
|
.RB < libgen.h >
|
|
.PP
|
|
.B char *dirname( char
|
|
.BI * path
|
|
.B );
|
|
.br
|
|
.B char *basename( char
|
|
.BI * path
|
|
.B );
|
|
.
|
|
.
|
|
.SH DESCRIPTION
|
|
.
|
|
The
|
|
.B dirname
|
|
and
|
|
.B basename
|
|
functions parse a null\-terminated path name string,
|
|
and split it into its
|
|
.B directory name
|
|
and
|
|
.B file name
|
|
components.
|
|
Splitting is performed on the basis of the location of the
|
|
.B directory separator
|
|
characters,
|
|
which,
|
|
for this MS\-Windows(\(tm) implementation,
|
|
are the characters
|
|
.RB \(dq / \(dq
|
|
and
|
|
.RB \(dq \e \(dq,
|
|
each of which is interpreted as being equivalent.
|
|
Additionally,
|
|
if the
|
|
.I second
|
|
character of
|
|
.I path
|
|
is a colon
|
|
.RB (\(dq : \(dq),
|
|
the first two characters of
|
|
.I path
|
|
are interpreted as an MS\-Windows(\(tm) drive designator,
|
|
which will be included in the
|
|
.B directory name
|
|
component of
|
|
.IR path ,
|
|
but is never considered to form part of the
|
|
.B file name
|
|
component.
|
|
.
|
|
.PP
|
|
In normal usage,
|
|
.B dirname
|
|
returns a pointer to a string representing the path name component of
|
|
.IR path ,
|
|
up to but not including the rightmost directory separator,
|
|
while
|
|
.B basename
|
|
returns a pointer to the component following this separator.
|
|
Any trailing directory separators present in
|
|
.I path
|
|
are disregarded,
|
|
when determining the rightmost separator,
|
|
and, in the case of the return value from
|
|
.BR dirname ,
|
|
any internal sequences of recurring separator characters
|
|
are each reduced to a single such character.
|
|
.
|
|
.PP
|
|
If
|
|
.I path
|
|
contains no MS\-Windows(\(tm) drive designator,
|
|
and no directory separator character,
|
|
then
|
|
.B dirname
|
|
returns the string
|
|
.RB \(dq . \(dq,
|
|
and
|
|
.B basename
|
|
returns a copy of
|
|
.IR path.
|
|
If
|
|
.I path
|
|
does commence with an MS\-Windows(\(tm) drive designator,
|
|
but contains no directory separators,
|
|
then
|
|
.B dirname
|
|
returns the string
|
|
.RB \(dq d:. \(dq,
|
|
where
|
|
.RB \(dq d: \(dq
|
|
represents the drive designator,
|
|
while
|
|
.B basename
|
|
returns a copy of
|
|
.IR path ,
|
|
with its initial two characters,
|
|
(i.e.\ the drive designator),
|
|
deleted.
|
|
.
|
|
.PP
|
|
If
|
|
.I path
|
|
is a NULL pointer,
|
|
or is a pointer to an empty string,
|
|
then both
|
|
.B dirname
|
|
and
|
|
.B basename
|
|
return the string
|
|
.RB \(dq . \(dq.
|
|
.
|
|
.PP
|
|
If
|
|
.I path
|
|
is the string
|
|
.RB \(dq / \(dq,
|
|
or the string
|
|
.RB \(dq \e \(dq,
|
|
both
|
|
.B dirname
|
|
and
|
|
.B basename
|
|
return the string
|
|
.RB \(dq / \(dq,
|
|
or the string
|
|
.RB \(dq \e \(dq,
|
|
respectively.
|
|
.
|
|
.PP
|
|
If
|
|
.I path
|
|
commences with
|
|
.I exactly
|
|
two directory separator characters,
|
|
which must be similar,
|
|
then
|
|
.B dirname
|
|
will preserve these two characters in the returned path name.
|
|
This construct does not affect the string returned by
|
|
.BR basename ,
|
|
neither is this behaviour replicated by
|
|
.BR dirname ,
|
|
if
|
|
.I path
|
|
includes an MS\-Windows(\(tm) drive designator.
|
|
.
|
|
.PP
|
|
In the special case,
|
|
where
|
|
.I path
|
|
is specified as
|
|
.I exactly
|
|
two identical directory separator characters,
|
|
with no MS\-Windows(\(tm) drive designator,
|
|
and no following path name,
|
|
.B dirname
|
|
returns
|
|
.I path
|
|
unchanged;
|
|
.B basename
|
|
normalises the return string to only a single character,
|
|
either
|
|
.RB \(dq / \(dq
|
|
or
|
|
.RB \(dq \e \(dq,
|
|
matching the characters used to specify
|
|
.IR path .
|
|
.
|
|
.PP
|
|
Concatenating the string returned by
|
|
.BR dirname ,
|
|
a
|
|
.RB \(dq / \(dq
|
|
or a
|
|
.RB \(dq \e \(dq,
|
|
and the string returned by
|
|
.B basename
|
|
yields a complete path name.
|
|
.
|
|
.PP
|
|
The
|
|
.B dirname
|
|
and
|
|
.B basename
|
|
functions conform generally to SUSv3,
|
|
extended to accommodate the handling of
|
|
.RB \(dq / \(dq
|
|
and
|
|
.RB \(dq \e \(dq
|
|
as alternative directory separator characters,
|
|
and also to accommodate the likelihood of MS\-Windows(\(tm)
|
|
drive designators appearing in any path name specification.
|
|
The example,
|
|
which follows,
|
|
illustrates the conformance to SUSv3,
|
|
and also the effects of the extended behaviour.
|
|
.
|
|
.
|
|
.SH EXAMPLE
|
|
.
|
|
To verify the behaviour of the
|
|
.B dirname
|
|
and
|
|
.B basename
|
|
functions,
|
|
the test program defines the following function:\(em
|
|
.
|
|
.PP
|
|
.RS
|
|
.nf
|
|
#include <stdio.h>
|
|
#include <string.h>
|
|
#include <libgen.h>
|
|
|
|
void result( char *path )
|
|
{
|
|
char *dir = strdup( path );
|
|
char *file = strdup( path );
|
|
|
|
printf( " %-15s%-15s%-12s", path, dirname( dir ),
|
|
basename( file ) );
|
|
|
|
free( dir );
|
|
free( file );
|
|
}
|
|
.fi
|
|
.RE
|
|
.PP
|
|
This illustrates the correct use of the
|
|
.B dirname
|
|
and the
|
|
.B basename
|
|
functions,
|
|
with copies of the original
|
|
.I path
|
|
string being passed in the function calls.
|
|
Note that the return values from each function are used immediately,
|
|
in the
|
|
.B printf
|
|
call,
|
|
and the temporary copies of
|
|
.I path
|
|
are discarded,
|
|
and the associated memory is freed,
|
|
before these go out of scope.
|
|
.
|
|
.PP
|
|
Calling this example function illustrates the effect of each of the
|
|
.B dirname
|
|
and
|
|
.B basename
|
|
functions,
|
|
for various values of
|
|
.IR path .
|
|
The following,
|
|
taken from SUSv3,
|
|
illustrate general conformance with the standard:\(em
|
|
.RS
|
|
.TS
|
|
tab(!);
|
|
lB lB lB
|
|
lw(15n) lw(10n) lw(10n).
|
|
\0path!\0dirname!\0basename
|
|
\_!\_!\_
|
|
\0/usr/lib!\0/usr!\0lib
|
|
\0//usr//lib//!\0//usr!\0lib
|
|
\0///usr//lib//!\0/usr!\0lib
|
|
\0/usr/!\0/!\0usr
|
|
\0usr!\0.!\0usr
|
|
\0//!\0//!\0/
|
|
\0/!\0/!\0/
|
|
\0.!\0.!\0.
|
|
\0..!\0.!\0..
|
|
.TE
|
|
.RE
|
|
.
|
|
.PP
|
|
Similarly,
|
|
for the case where path names are expressed using the MS\-Windows(\(tm)
|
|
.RB \(dq \e \(dq
|
|
directory separator notation,
|
|
calling the example function displays:\(em
|
|
.RS
|
|
.TS
|
|
tab(!);
|
|
lB lB lB
|
|
lw(15n) lw(10n) lw(10n).
|
|
\0path!\0dirname!\0basename
|
|
\_!\_!\_
|
|
\0\eusr\elib!\0\eusr!\0lib
|
|
\0\e\eusr\e\elib\e\e!\0\e\eusr!\0lib
|
|
\0\e\e\eusr\e\elib\e\e!\0\eusr!\0lib
|
|
\0\eusr\e!\0\e!\0usr
|
|
\0usr!\0.!\0usr
|
|
\0\e\e!\0\e\e!\0\e
|
|
\0\e!\0\e!\0\e
|
|
\0.!\0.!\0.
|
|
\0..!\0.!\0..
|
|
.TE
|
|
.RE
|
|
.
|
|
.PP
|
|
and,
|
|
when an MS\-Windows(\(tm) drive designator is also specified,
|
|
this becomes:\(em
|
|
.RS
|
|
.TS
|
|
tab(!);
|
|
lB lB lB
|
|
lw(15n) lw(10n) lw(10n).
|
|
\0path!\0dirname!\0basename
|
|
\_!\_!\_
|
|
\0d:\eusr\elib!\0d:\eusr!\0lib
|
|
\0d:\e\eusr\e\elib\e\e!\0d:\eusr!\0lib
|
|
\0d:\e\e\eusr\e\elib\e\e!\0d:\eusr!\0lib
|
|
\0d:\eusr\e!\0d:\e!\0usr
|
|
\0d:usr!\0d:.!\0usr
|
|
\0d:\e\e!\0d:\e!\0\e
|
|
\0d:\e!\0d:\e!\0\e
|
|
\0d:.!\0d:.!\0.
|
|
\0d:..!\0d:.!\0..
|
|
.TE
|
|
.RE
|
|
.
|
|
.PP
|
|
Please note,
|
|
in particular,
|
|
the special handling of path names which begin with
|
|
.I exactly
|
|
two directory separator characters,
|
|
and also that this special handling is suppressed
|
|
when these two characters are dissimilar,
|
|
or when an MS\-Windows(\(tm) drive designator is specified:\(em
|
|
.RS
|
|
.TS
|
|
tab(!);
|
|
lB lB lB
|
|
lw(15n) lw(10n) lw(10n).
|
|
\0path!\0dirname!\0basename
|
|
\_!\_!\_
|
|
\0//usr//lib//!\0//usr!\0lib
|
|
\0\e\eusr\e\elib\e\e!\0\e\eusr!\0lib
|
|
\0/\eusr\e\elib\e\e!\0/usr!\0lib
|
|
\0\e/usr\e\elib\e\e!\0\eusr!\0lib
|
|
\0d:\e\eusr\e\elib\e\e!\0d:\eusr!\0lib
|
|
\0//!\0//!\0/
|
|
\0\e\e!\0\e\e!\0\e
|
|
\0/\e!\0/!\0/
|
|
\0\e/!\0\e!\0\e
|
|
\0d:\e\e!\0d:\e!\0\e
|
|
.TE
|
|
.RE
|
|
.
|
|
.
|
|
.SH RETURN VALUE
|
|
.
|
|
The
|
|
.B dirname
|
|
function returns a pointer to a null terminated string,
|
|
which represents the directory path component of the passed
|
|
.I path
|
|
string,
|
|
without any trailing directory separator character,
|
|
and with all internal sequences of directory separator characters
|
|
normalised to a single separator at each level of directory nesting.
|
|
.
|
|
.PP
|
|
The
|
|
.B basename
|
|
function
|
|
returns a pointer to a null terminated string,
|
|
which represents the rightmost element of the passed
|
|
.I path
|
|
string,
|
|
with all trailing directory separator characters removed.
|
|
.
|
|
.PP
|
|
If any MS\-Windows(\(tm) drive designator is specified in the input
|
|
.I path
|
|
string,
|
|
it is included in the return value of the
|
|
.B dirname
|
|
function,
|
|
but not in that of the
|
|
.B basename
|
|
function.
|
|
.
|
|
.
|
|
.SH ERROR RETURNS
|
|
.
|
|
None.
|
|
.
|
|
.
|
|
.SH CAVEATS AND BUGS
|
|
.
|
|
The
|
|
.B dirname
|
|
and
|
|
.B basename
|
|
functions may modify the
|
|
.I path
|
|
string passed to them.
|
|
Therefore, it is an error to pass a character constant as the
|
|
.I path
|
|
parameter;
|
|
to do so may result in memory violation errors,
|
|
(segmentation faults),
|
|
and consequent abnormal program termination.
|
|
.PP
|
|
Also note that,
|
|
since the
|
|
.I path
|
|
argument may be modified by the
|
|
.B dirname
|
|
or the
|
|
.B basename
|
|
function call,
|
|
if you wish to preserve the original content of
|
|
.IR path ,
|
|
you should pass a copy to the function.
|
|
Furthermore,
|
|
either function may return its result in a statically allocated buffer,
|
|
which may be overwritten on a subsequent function call.
|
|
.PP
|
|
Although the
|
|
.B dirname
|
|
and
|
|
.B basename
|
|
functions parse path name strings,
|
|
they are basically just
|
|
.I string
|
|
functions.
|
|
The presence of an MS\-Windows(\(tm) drive designator is determined
|
|
by the appearance of a colon
|
|
.RB (\(dq : \(dq)
|
|
as the second character of the
|
|
.I path
|
|
string,
|
|
but neither function performs any check
|
|
to ensure that the first character represents a valid file system device;
|
|
neither is any form of validation performed,
|
|
to ensure that the remainder of the string
|
|
represents a valid path name.
|
|
.
|
|
.
|
|
.SH AUTHOR
|
|
.
|
|
This manpage was written for the MinGW implementation of the
|
|
.B dirname
|
|
and
|
|
.B basename
|
|
functions by Keith\ Marshall,
|
|
<keithmarshall@users.sourceforge.net>.
|
|
It may copied, modified and redistributed,
|
|
without restriction of copyright,
|
|
provided this acknowledgement of contribution by
|
|
the original author remains unchanged.
|
|
.
|
|
.
|
|
.\" EOF
|