From 31e07d86d284f1b12afc55daaabf2272ed0044cd Mon Sep 17 00:00:00 2001 From: Keith Marshall Date: Sun, 11 Mar 2007 00:15:00 +0000 Subject: [PATCH] Add manpages for dirname and basename functions. --- winsup/mingw/ChangeLog | 8 + winsup/mingw/Makefile.in | 19 ++ winsup/mingw/man/dirname.man | 474 +++++++++++++++++++++++++++++++++++ 3 files changed, 501 insertions(+) create mode 100755 winsup/mingw/man/dirname.man diff --git a/winsup/mingw/ChangeLog b/winsup/mingw/ChangeLog index b0c559ae0..769291244 100644 --- a/winsup/mingw/ChangeLog +++ b/winsup/mingw/ChangeLog @@ -1,3 +1,11 @@ +2007-03-10 Keith Marshall + + 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 * mingwex/basename.c: Make it work with path names containing diff --git a/winsup/mingw/Makefile.in b/winsup/mingw/Makefile.in index ccbc33917..3a5c63aed 100644 --- a/winsup/mingw/Makefile.in +++ b/winsup/mingw/Makefile.in @@ -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) diff --git a/winsup/mingw/man/dirname.man b/winsup/mingw/man/dirname.man new file mode 100755 index 000000000..82e1a9acc --- /dev/null +++ b/winsup/mingw/man/dirname.man @@ -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 +#include +#include + +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, +. +It may copied, modified and redistributed, +without restriction of copyright, +provided this acknowledgement of contribution by +the original author remains unchanged. +. +. +.\" EOF