Add manpages for dirname and basename functions.

3 files changed, 501 insertions, 0 deletions

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  <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
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 <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