newlib-cygwin/winsup/mingw/man/dirname.man

.\" 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