Add manpages for dirname and basename functions.
This commit is contained in:
Keith Marshall
parent
af8e63023a
commit
31e07d86d2
|
|
@ -1,3 +1,11 @@
|
|||
2007-03-10 Keith Marshall <keithmarshall@users.sourceforge.net>
|
||||
|
||||
Add manpages for dirname and basename functions.
|
||||
|
||||
* man: New directory.
|
||||
* man/dirname.man: New file; it sources both manpages.
|
||||
* Makefile.in: Add provisional rules to distribute them.
|
||||
|
||||
2007-03-08 Keith Marshall <keithmarshall@users.sourceforge.net>
|
||||
|
||||
* mingwex/basename.c: Make it work with path names containing
|
||||
|
|
|
|||
|
|
@ -36,6 +36,7 @@ program_transform_name = @program_transform_name@
|
|||
exec_prefix = @exec_prefix@
|
||||
bindir = @bindir@
|
||||
libdir = @libdir@
|
||||
mandir = @mandir@
|
||||
ifeq ($(target_alias),$(host_alias))
|
||||
ifeq ($(build_alias),$(host_alias))
|
||||
tooldir:=$(exec_prefix)
|
||||
|
|
@ -379,10 +380,18 @@ srcdist:
|
|||
(cd $$i; $(MAKE) distdir=../$(distdir) dist); \
|
||||
done
|
||||
#FIXME this needs to be done with SUBDIRS and Makefiles.
|
||||
#
|
||||
# Maybe, but this is simpler, and adequate for now!
|
||||
# However, as more manpages are added, spanning multiple sections,
|
||||
# we'll probably need a separate Makefile to organise them.
|
||||
#
|
||||
mkdir $(distdir)/include
|
||||
mkdir $(distdir)/include/sys
|
||||
cp $(srcdir)/include/*.h $(distdir)/include/
|
||||
cp $(srcdir)/include/sys/*.h $(distdir)/include/sys/
|
||||
mkdir $(distdir)/man
|
||||
cp $(srcdir)/man/* $(distdir)/man/
|
||||
#
|
||||
#end FIXME
|
||||
rm -f $(distdir)-src.tar.gz
|
||||
$(TAR) $(TARFLAGS)cf $(distdir)-src$(TARFILEEXT) $(distdir)
|
||||
|
|
@ -411,6 +420,7 @@ install-dirs:
|
|||
$(mkinstalldirs) $(inst_includedir)
|
||||
$(mkinstalldirs) $(inst_libdir)
|
||||
$(mkinstalldirs) $(inst_docdir)
|
||||
$(mkinstalldirs) $(mandir)/man3
|
||||
|
||||
install: all install-dirs $(install_dlls_host)
|
||||
for i in $(LIBS); do \
|
||||
|
|
@ -429,6 +439,15 @@ install: all install-dirs $(install_dlls_host)
|
|||
$(INSTALL_DATA) $$i $$dstdir/`basename $$i` ; \
|
||||
done ; \
|
||||
done
|
||||
#
|
||||
# This provisional hack installs the only manpage we have at present...
|
||||
# It simply CANNOT suffice, when we have more manpages to ship.
|
||||
#
|
||||
$(INSTALL_DATA) $(srcdir)/man/dirname.man $(mandir)/man3
|
||||
cd $(mandir)/man3; mv dirname.man dirname.3; ln dirname.3 basename.3
|
||||
#
|
||||
# End provisional hack.
|
||||
#
|
||||
@$(MAKE) subdirs DO=$@ $(FLAGS_TO_PASS)
|
||||
|
||||
subdirs: $(SUBDIRS)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,474 @@
|
|||
.\" 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
|
||||
Loading…
Reference in New Issue