[patch] document basename() and dirname()

[Ben Collins <bcollins at debian dot org>]

Let me know if this isn't the best section for these definitions, or if
the wording isn't exactly as it should be (WRT to GNU or XPG basename being
prefered).

2001-01-05  Ben Collins  <bcollins@debian.org>

	* manual/string.texi: Finding Tokens in a String: document XPG
	  basename() and dirname(), aswell as GNU basename()

-- 
 -----------=======-=-======-=========-----------=====------------=-=------
/  Ben Collins  --  ...on that fantastic voyage...  --  Debian GNU/Linux   \
`  bcollins@debian.org  --  bcollins@openldap.org  --  bcollins@linux.com  '
 `---=========------=======-------------=-=-----=-===-======-------=--=---'
Index: string.texi
===================================================================
RCS file: /cvs/glibc/libc/manual/string.texi,v
retrieving revision 1.57
diff -u -u -r1.57 string.texi
--- string.texi	2000/04/30 17:54:40	1.57
+++ string.texi	2001/01/05 22:17:30
@@ -1421,6 +1421,79 @@
 token = strsep (&running, delimiters);    /* token => NULL */
 @end smallexample
 
+@comment string.h
+@comment GNU
+@deftypefun {char *} basename (const char *@var{filename})
+The GNU version of the @code{basename} function returns the last component of
+the path in @var{filename}.  This function is the prefered usage, since it
+does not modify the argument, @var{filename}, and respects trailing
+slashes. Note, this function is overriden by the XPG version, if libgen.h
+is included.
+
+Example of using GNU @code{basename}:
+
+@smallexample
+#include <string.h>
+
+int main (int argc, char *argv[])
+@{
+  char *prog = basename(argv[0]);
+
+  if (argc < 2)
+    @{
+      fprintf(stderr, "Usage %s <arg>\n", prog);
+      exit(1);
+    @}
+
+  @dots{}
+@}
+@end smallexample
+
+@strong{Portability Note:}  This function may produce different results on different systems.
+
+@end deftypefun
+
+@comment libgen.h
+@comment XPG
+@deftypefun {char *} basename (char *@var{path})
+This is the standard XPG defined @code{basename}. It is similar in spirit
+to the GNU version, but may modify the @var{path} by removing trailing '/'
+characters.  If the @var{path} is made up entirely of '/' characters, then
+"/" will be returned.  Also, if @var{path} is @code{NULL} or an empty
+string, then "." is returned.
+
+Example of using XPG @code{basename}:
+
+@smallexample
+#include <libgen.h>
+
+int main (int argc, char *argv[])
+@{
+  char *prog, *path = strdup(argv[0]);
+
+  prog = basename(path);
+
+  if (argc < 2)
+    @{
+      fprintf(stderr, "Usage %s <arg>\n", prog);
+      exit(1);
+    @}
+
+  @dots{}
+
+  free(path);
+@}
+@end smallexample
+@end deftypefun
+
+@comment libgen.h
+@comment XPG
+@deftypefun {char *} dirname (char *@var{path})
+The @code{dirname} function is the compliment to @code{basename}.  It
+returns the parent directory of the file specified by @var{path}.  If
+@var{path} is @code{NULL}, an empty string, or contains no '/' characters,
+then "." is returned.
+@end deftypefun
 
 @node strfry
 @section strfry