configure.in (MAKEINFO, PERL): Detect these.

* configure.in (MAKEINFO, PERL): Detect these.
(--enable-maintainer-mode): Add.
* configure: Regenerate.
* Makefile.in (MAKEINFO, PERL): Define.
(libiberty.info, libiberty.dvi, libiberty.html): New.
(CFILES): Add bsearch.c.
(CONFIGURED_OFILES): New, list of objects configure might add.
(maint-missing, maint-buildall): New, for maintainers only.
(clean, mostlyclean): Add info/dvi/html files.
* libiberty.texi, copying-lib.texi, obstacks.texi, functions.texi: New.
* gather-docs: New, for maintainers.
* maint-tool: New, for maintainers.
* alloca.c, atexit.c, basename.c, bcmp.c, bcopy.c, bsearch.c,
bzero.c, calloc.c, clock.c, configure.in, configure, getcwd.c,
getpagesize.c, getpwd.c, index.c, memchr.c, memcmp.c, memcpy.c,
memmove.c, memset.c, putenv.c, rename.c, rindex.c, setenv.c,
sigsetmask.c, strcasecmp.c, strchr.c, strdup.c, strerror.c,
strncasecmp.c, strncmp.c, strrchr.c, strstr.c, strtod.c, strtol.c,
tmpnam.c, vfork.c, vprintf.c, waitpid.c, xatexit.c, xexit.c,
xmalloc.c, xmemdup.c, xstrdup.c, xstrerror.c: Add or update
documentation.

Co-Authored-By: Phil Edwards <pedwards@disaster.jaj.com>

From-SVN: r45828

libiberty/ChangeLog

+2001-09-20  DJ Delorie  <dj@redhat.com>
+	    Phil Edwards  <pedwards@disaster.jaj.com>
+	
+	* configure.in (MAKEINFO, PERL): Detect these.
+	(--enable-maintainer-mode): Add.
+	* configure: Regenerate.
+	* Makefile.in (MAKEINFO, PERL): Define.
+	(libiberty.info, libiberty.dvi, libiberty.html): New.
+	(CFILES): Add bsearch.c.
+	(CONFIGURED_OFILES): New, list of objects configure might add.
+	(maint-missing, maint-buildall): New, for maintainers only.
+	(clean, mostlyclean): Add info/dvi/html files.
+	* libiberty.texi, copying-lib.texi, obstacks.texi, functions.texi: New.
+	* gather-docs: New, for maintainers.
+	* maint-tool: New, for maintainers.
+	* alloca.c, atexit.c, basename.c, bcmp.c, bcopy.c, bsearch.c,
+	bzero.c, calloc.c, clock.c, configure.in, configure, getcwd.c,
+	getpagesize.c, getpwd.c, index.c, memchr.c, memcmp.c, memcpy.c,
+	memmove.c, memset.c, putenv.c, rename.c, rindex.c, setenv.c,
+	sigsetmask.c, strcasecmp.c, strchr.c, strdup.c, strerror.c,
+	strncasecmp.c, strncmp.c, strrchr.c, strstr.c, strtod.c, strtol.c,
+	tmpnam.c, vfork.c, vprintf.c, waitpid.c, xatexit.c, xexit.c,
+	xmalloc.c, xmemdup.c, xstrdup.c, xstrerror.c: Add or update
+	documentation.
+	
 2001-09-25  Kaveh R. Ghazi  <ghazi@caip.rutgers.edu>
 
 	* concat.c (reconcat): Fix for traditional C.

libiberty/Makefile.in

 #
 # Makefile
-#   Copyright (C) 1990, 91-99, 2000
+#   Copyright (C) 1990, 91-99, 2000, 2001
 #   Free Software Foundation
 #
 # This file is part of the libiberty library.
@@ -56,6 +56,8 @@ CC = @CC@
 CFLAGS = @CFLAGS@
 LIBCFLAGS = $(CFLAGS)
 RANLIB = @RANLIB@
+MAKEINFO = @MAKEINFO@
+PERL = @PERL@
 
 PICFLAG =
 
@@ -94,6 +96,7 @@ FLAGS_TO_PASS = \
 # Subdirectories to recurse into. We need to override this during cleaning
 SUBDIRS = testsuite
 
+# FIXME: add @BUILD_INFO@ once we're sure it works for everyone.
 all: stamp-picdir $(TARGETLIB) needed-list required-list all-subdir
 	@$(MULTIDO) $(FLAGS_TO_PASS) multi-do DO=all
 
@@ -112,16 +115,11 @@ COMPILE.c = $(CC) -c @DEFS@ $(LIBCFLAGS) -I. -I$(INCDIR) $(HDEFINES) @ac_libiber
 	else true; fi
 	$(COMPILE.c) $<
 
-info: info-subdir
-install-info: install-info-subdir
-clean-info: clean-info-subdir
-dvi: dvi-subdir
-
 # NOTE: If you add new files to the library, add them to this list
 # (alphabetical), and add them to REQUIRED_OFILES or funcs in
 # configure.in.
 CFILES = asprintf.c alloca.c argv.c atexit.c basename.c bcmp.c bcopy.c	      \
-	bzero.c calloc.c choose-temp.c clock.c concat.c cplus-dem.c	      \
+	bsearch.c bzero.c calloc.c choose-temp.c clock.c concat.c cplus-dem.c \
         cp-demangle.c dyn-string.c fdmatch.c fnmatch.c ffs.c getcwd.c	      \
 	getpwd.c getopt.c getopt1.c getpagesize.c getruntime.c		      \
 	floatformat.c hashtab.c hex.c index.c insque.c lbasename.c            \
@@ -144,12 +142,55 @@ REQUIRED_OFILES = argv.o alloca.o choose-temp.o concat.o cplus-dem.o          \
 	splay-tree.o strerror.o strsignal.o xatexit.o xexit.o xmalloc.o       \
 	xmemdup.o xstrdup.o xstrerror.o ternary.o fibheap.o
 
+# These are all the objects that configure may add to the library via
+# $funcs.  This list exists here only for "make maint-missing".
+CONFIGURED_OFILES = asprintf.o atexit.o basename.o bcmp.o bcopy.o	\
+	bsearch.o bzero.o calloc.o clock.o ffs.o getcwd.o		\
+	getpagesize.o index.o insque.o memchr.o memcmp.o memcpy.o	\
+	memmove.o memset.o mkstemps.o putenv.o random.o rename.o	\
+	rindex.o setenv.o sigsetmask.o strcasecmp.o strchr.o strdup.o	\
+	strncasecmp.o strncmp.o strrchr.o strstr.o strtod.o strtol.o	\
+	strtoul.o tmpnam.o vasprintf.o vfork.o vfprintf.o vprintf.o	\
+	vsprintf.o waitpid.o
+
 $(TARGETLIB): $(REQUIRED_OFILES) $(EXTRA_OFILES) $(LIBOBJS)
 	-rm -f $(TARGETLIB)
 	$(AR) $(AR_FLAGS) $(TARGETLIB) \
 	  $(REQUIRED_OFILES) $(EXTRA_OFILES) $(LIBOBJS)
 	$(RANLIB) $(TARGETLIB)
 
+info: libiberty.info info-subdir
+install-info: install-info-subdir
+clean-info: clean-info-subdir
+dvi: libiberty.dvi dvi-subdir
+html: libiberty.html
+
+TEXISRC = \
+	$(srcdir)/libiberty.texi \
+	$(srcdir)/copying-lib.texi \
+	$(srcdir)/obstacks.texi \
+	$(srcdir)/functions.texi
+
+# Additional files that have texi snippets that need to be collected
+# and sorted.
+TEXIFILES = 
+
+libiberty.info : $(srcdir)/libiberty.texi $(TEXISRC)
+	$(MAKEINFO) -I$(srcdir) $(srcdir)/libiberty.texi
+
+libiberty.dvi : $(srcdir)/libiberty.texi $(TEXISRC)
+	texi2dvi $(srcdir)/libiberty.texi
+
+libiberty.html : $(srcdir)/libiberty.texi $(TEXISRC)
+	$(MAKEINFO) --html -I$(srcdir) $(srcdir)/libiberty.texi
+
+@MAINT@$(srcdir)/functions.texi : stamp-functions
+@MAINT@	@true
+
+@MAINT@stamp-functions : $(CFILES) $(TEXIFILES) $(srcdir)/gather-docs Makefile
+@MAINT@@HAVE_PERL@	$(PERL) $(srcdir)/gather-docs $(srcdir) $(srcdir)/functions.texi $(CFILES) $(TEXIFILES)
+@MAINT@	echo stamp > stamp-functions
+
 INSTALL_DEST = @INSTALL_DEST@
 install: install_to_$(INSTALL_DEST) install-subdir
 
@@ -208,6 +249,14 @@ demangle:
 ls:
 	@echo Makefile $(CFILES)
 
+# Various targets for maintainers.
+
+maint-missing :
+	@$(PERL) $(srcdir)/maint-tool -s $(srcdir) missing $(CFILES) $(REQUIRED_OFILES) $(CONFIGURED_OFILES)
+
+maint-buildall : $(REQUIRED_OFILES) $(CONFIGURED_OFILES)
+	@true
+
 # Need to deal with profiled libraries, too.
 
 # Cleaning has to be done carefully to ensure that we don't clean our SUBDIRS
@@ -216,10 +265,15 @@ mostlyclean: mostlyclean-subdir
 	-rm -rf *.o pic core errs \#* *.E a.out
 	-rm -f needed.awk needed2.awk errors dummy needed-list config.h stamp-*
 	-rm -f $(CONFIG_H) $(NEEDED_LIST) stamp-picdir
+	-rm -f libiberty.aux libiberty.cp libiberty.cps libiberty.fn libiberty.ky
+	-rm -f libiberty.log libiberty.tmp libiberty.tps libiberty.pg
+	-rm -f libiberty.pgs libiberty.toc libiberty.tp libiberty.tpl libiberty.vr
+	-rm -f libtexi.stamp
 	@$(MULTICLEAN) multi-clean DO=mostlyclean
 clean: clean-subdir
 	$(MAKE) SUBDIRS="" mostlyclean
 	-rm -f *.a required-list tmpmulti.out
+	-rm -f libiberty.dvi libiberty.info* libiberty.html
 	@$(MULTICLEAN) multi-clean DO=clean
 distclean: distclean-subdir
 	$(MAKE) SUBDIRS="" clean

libiberty/alloca.c

@@ -21,6 +21,27 @@
    allocating any.  It is a good idea to use alloca(0) in
    your main control loop, etc. to force garbage collection.  */
 
+/*
+
+@deftypefn Replacement void* alloca (size_t)
+
+This function allocates memory which will be automatically reclaimed
+after the procedure exits.  The @libib{} implementation does not free
+the memory immediately but will do so eventually during subsequent
+calls to this function.  Memory is allocated using @code{xmalloc} under
+normal circumstances.
+
+The header file @file{alloca-conf.h} can be used in conjunction with the
+GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
+available this function.  The @code{AC_FUNC_ALLOCA} test requires that
+client code use a block of preprocessor code to be safe (see the Autoconf
+manual for more); this header incorporates that logic and more, including
+the possibility of a GCC builtin function.
+
+@end deftypefn
+
+*/
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif

libiberty/atexit.c

 /* Wrapper to implement ANSI C's atexit using SunOS's on_exit. */
 /* This function is in the public domain.  --Mike Stump. */
 
+/*
+
+@deftypefn Supplemental int atexit (void (*@var{f})())
+
+Causes function @var{f} to be called at exit.  Returns 0.
+
+@end deftypefn
+
+*/
+
 #include "config.h"
 
 #ifdef HAVE_ON_EXIT

libiberty/basename.c

@@ -2,20 +2,14 @@
    This file is in the public domain. */
 
 /*
-NAME
-	basename -- return pointer to last component of a pathname
 
-SYNOPSIS
-	char *basename (const char *name)
+@deftypefn Supplemental char* basename (const char *@var{name})
 
-DESCRIPTION
-	Given a pointer to a string containing a typical pathname
-	(/usr/src/cmd/ls/ls.c for example), returns a pointer to the
-	last component of the pathname ("ls.c" in this case).
+Returns a pointer to the last component of pathname @var{name}.
+Behavior is undefined if the pathname ends in a directory separator.
+
+@end deftypefn
 
-BUGS
-	Presumes a UNIX or DOS/Windows style path with UNIX or DOS/Windows 
-	style separators.
 */
 
 #include "ansidecl.h"

libiberty/bcmp.c

@@ -3,28 +3,15 @@
 
 /*
 
-NAME
+@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
 
-	bcmp -- compare two memory regions
+Compares the first @var{count} bytes of two areas of memory.  Returns
+zero if they are the same, non-zero otherwise.  Returns zero if
+@var{count} is zero.  A non-zero result only indicates a difference,
+it does not indicate any sorting order (say, by having a positive
+result mean @var{x} sorts before @var{y}).
 
-SYNOPSIS
-
-	int bcmp (char *from, char *to, int count)
-
-DESCRIPTION
-
-	Compare two memory regions and return zero if they are identical,
-	non-zero otherwise.  If count is zero, return zero.
-
-NOTES
-
-	No guarantee is made about the non-zero returned value.  In
-	particular, the results may be signficantly different than
-	strcmp(), where the return value is guaranteed to be less than,
-	equal to, or greater than zero, according to lexicographical
-	sorting of the compared regions.
-
-BUGS
+@end deftypefn
 
 */
 

libiberty/bcopy.c

 /* bcopy -- copy memory regions of arbitary length
 
-NAME
-	bcopy -- copy memory regions of arbitrary length
+@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
 
-SYNOPSIS
-	void bcopy (char *in, char *out, int length)
+Copies @var{length} bytes from memory region @var{in} to region
+@var{out}.  The use of @code{bcopy} is deprecated in new programs.
 
-DESCRIPTION
-	Copy LENGTH bytes from memory region pointed to by IN to memory
-	region pointed to by OUT.
-
-BUGS
-	Significant speed improvements can be made in some cases by
-	implementing copies of multiple bytes simultaneously, or unrolling
-	the copy loop.
+@end deftypefn
 
 */
 

libiberty/bsearch.c

@@ -28,6 +28,23 @@
  * SUCH DAMAGE.
  */
 
+/*
+
+@deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *))
+
+Performs a search over an array of @var{nmemb} elements pointed to by
+@var{base} for a member that matches the object pointed to by @var{key}.
+The size of each member is specified by @var{size}.  The array contents
+should be sorted in ascending order according to the @var{compar}
+comparison function.  This routine should take two arguments pointing to
+the @var{key} and to an array member, in that order, and should return an
+integer less than, equal to, or greater than zero if the @var{key} object
+is respectively less than, matching, or greater than the array member.
+
+@end deftypefn
+
+*/
+
 #include "config.h"
 #include "ansidecl.h"
 #include <sys/types.h>		/* size_t */

libiberty/bzero.c

@@ -2,19 +2,13 @@
    This function is in the public domain.  */
 
 /*
-NAME
-	bzero -- zero the contents of a specified memory region
 
-SYNOPSIS
-	void bzero (char *to, int count)
+@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
 
-DESCRIPTION
-	Zero COUNT bytes of memory pointed to by TO.
+Zeros @var{count} bytes starting at @var{mem}.  Use of this function
+is deprecated in favor of @code{memset}.
 
-BUGS
-	Significant speed enhancements may be made in some environments
-	by zeroing more than a single byte at a time, or by unrolling the
-	loop.
+@end deftypefn
 
 */
 

libiberty/calloc.c

 /* calloc -- allocate memory which has been initialized to zero.
    This function is in the public domain. */
+
+/*
+
+@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
+
+Uses @code{malloc} to allocate storage for @var{nelem} objects of
+@var{elsize} bytes each, then zeros the memory.
+
+@end deftypefn
+
+*/
  
 #include "ansidecl.h"
 #include "libiberty.h"

libiberty/clock.c

@@ -22,6 +22,18 @@ the resulting executable to be covered by the GNU General Public License.
 This exception does not however invalidate any other reasons why
 the executable file might be covered by the GNU General Public License. */
 
+/*
+
+@deftypefn Supplemental long clock ()
+
+Returns an approximation of the CPU time used by the process as a
+@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
+number of seconds used.
+
+@end deftypefn
+
+*/
+
 #include "config.h"
 
 #ifdef HAVE_GETRUSAGE

libiberty/configure.in

@@ -26,6 +26,51 @@ else
 fi
 AC_CONFIG_AUX_DIR($libiberty_topdir)
 
+dnl Very limited version of automake's enable-maintainer-mode
+
+AC_MSG_CHECKING([whether to enable maintainer-specific portions of Makefiles])
+  dnl maintainer-mode is disabled by default
+  AC_ARG_ENABLE(maintainer-mode,
+[  --enable-maintainer-mode
+                          enable make rules and dependencies not useful
+                          (and sometimes confusing) to the casual installer],
+      maintainer_mode=$enableval,
+      maintainer_mode=no)
+
+AC_MSG_RESULT($maintainer_mode)
+
+if test "$maintainer_mode" = "yes"; then
+  MAINT=''
+  NOTMAINT='#'
+else
+  MAINT='#'
+  NOTMAINT=''
+fi
+AC_SUBST(MAINT)dnl
+AC_SUBST(NOTMAINT)dnl
+
+# Do we have a single-tree copy of texinfo?
+if test -f $srcdir/../texinfo/Makefile.in; then
+  MAKEINFO='$(objdir)/../texinfo/makeinfo/makeinfo'
+  AC_MSG_RESULT([Using makeinfo from the unified source tree.])
+else
+  AC_CHECK_PROG(MAKEINFO, makeinfo, makeinfo, )
+fi
+if test x"$MAKEINFO" = x""; then
+  BUILD_INFO=
+else
+  BUILD_INFO=info
+fi
+AC_SUBST(BUILD_INFO)
+
+AC_CHECK_PROG(PERL, perl, perl, )
+if test x"$PERL" = x""; then
+  HAVE_PERL='#'
+else
+  HAVE_PERL=''
+fi
+AC_SUBST(HAVE_PERL)
+
 AC_CANONICAL_HOST
 
 dnl When we start using automake:

libiberty/gather-docs

+#!/usr/bin/perl
+# -*- perl -*-
+
+#   Copyright (C) 2001
+#   Free Software Foundation
+#
+# This file is part of the libiberty library.
+# Libiberty is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Library General Public
+# License as published by the Free Software Foundation; either
+# version 2 of the License, or (at your option) any later version.
+#
+# Libiberty is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Library General Public License for more details.
+#
+# You should have received a copy of the GNU Library General Public
+# License along with libiberty; see the file COPYING.LIB.  If not,
+# write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+#
+# Originally written by DJ Delorie <dj@redhat.com>
+
+
+
+# This program looks for texinfo snippets in source files and other
+# files, and builds per-category files with entries sorted in
+# alphabetical order.
+
+# The syntax it looks for is lines starting with '@def' in *.c and
+# other files (see TEXIFILES in Makefile.in).  Entries are terminated
+# at the next @def* (which begins a new entry) or, for C files, a line
+# that begins with '*/' without leading spaces (this assumes that the
+# texinfo snippet is within a C-style /* */ comment).
+
+# 
+
+
+
+if ($ARGV[0] eq "-v") {
+    $verbose = 1;
+    shift;
+}
+
+$srcdir = shift;
+$outfile = shift;
+
+if ($outfile !~ /\S/ || ! -f "$srcdir/Makefile.in" ) {
+    print STDERR "Usage: gather-docs [-v] srcdir outfile.txi [files with snippets in them ...]\n";
+    exit 1;
+}
+
+$errors = 0;
+
+for $in (@ARGV) {
+
+    if (!open(IN, "$srcdir/$in")) {
+	print STDERR "Cannot open $srcdir/$in for reading: $!\n";
+	$errors ++;
+
+    } else {
+	$first = 1;
+	$pertinent = 0;
+	$man_mode = 0;
+	$line = 0;
+
+	while (<IN>) {
+	    $line ++;
+	    $pertinent = 1 if /^\@def[a-z]*[a-wyz] /;
+	    $pertinent = 0 if /^\*\//;
+	    next unless $pertinent;
+
+	    if (/^\@def[a-z]*[a-wyz] /) {
+		
+		($name) = m/[^\(]* ([^\( \t\r\n]+) *\(/;
+		$name =~ s/[ 	]*$//;
+		$key = $name;
+		$key =~ tr/A-Z/a-z/;
+		$key =~ s/[^a-z0-9]+/ /g;
+		$name{$key} = $node;
+		$lines{$key} = '';
+		$src_file{$key} = $in;
+		$src_line{$key} = $line;
+		print "\nReading $in :" if $verbose && $first;
+		$first = 0;
+		print " $name" if $verbose;
+		$node_lines{$key} .= $_;
+
+	    } else {
+		$node_lines{$key} .= $_;
+	    }
+
+	    $pertinent = 0 if /^\@end def/;
+	}
+	close (IN);
+    }
+}
+
+print "\n" if $verbose;
+exit $errors if $errors;
+
+if (!open (OUT, "> $outfile")) {
+    print STDERR "Cannot open $outfile for writing: $!\n";
+    $errors ++;
+    next;
+}
+print "Writing $outfile\n" if $verbose;
+
+print OUT "\@c Automatically generated from *.c and others (the comments before\n";
+print OUT "\@c each entry tell you which file and where in that file).  DO NOT EDIT!\n";
+print OUT "\@c Edit the *.c files, configure with --enable-maintainer-mode,\n";
+print OUT "\@c and let gather-docs build you a new copy.\n\n";
+
+for $key (sort keys %name) {
+    print OUT "\@c $src_file{$key}:$src_line{$key}\n";
+    print OUT $node_lines{$key};
+    print OUT "\n";
+}
+
+if (! print OUT "\n") {
+    print STDERR "Disk full writing $srcdir/$cat.texi\n";
+    $errors ++;
+}
+
+close (OUT);
+
+exit $errors;

libiberty/getcwd.c

@@ -2,24 +2,18 @@
    This function is in the public domain. */
 
 /*
-NAME
-	getcwd -- get absolute pathname for current working directory
 
-SYNOPSIS
-	char *getcwd (char pathname[len], len)
+@deftypefn Supplemental char* getcwd (char *@var{pathname}, @var{len})
 
-DESCRIPTION
-	Copy the absolute pathname for the current working directory into
-	the supplied buffer and return a pointer to the buffer.  If the 
-	current directory's path doesn't fit in LEN characters, the result
-	is NULL and errno is set.
+Copy the absolute pathname for the current working directory into
+@var{pathname}, which is assumed to point to a buffer of at least
+@var{len} bytes, and return a pointer to the buffer.  If the current
+directory's path doesn't fit in @var{len} characters, the result is
+NULL and @var{errno} is set.  If @var{pathname} is a null pointer,
+@code{getcwd} will obtain @var{len} bytes of space using
+@code{malloc}.
 
-	If pathname is a null pointer, getcwd() will obtain size bytes of
-	space using malloc.
-
-BUGS
-	Emulated via the getwd() call, which is reasonable for most
-	systems that do not have getcwd().
+@end deftypefn
 
 */
 

libiberty/getpagesize.c

@@ -2,20 +2,14 @@
 
 /*
 
-NAME
+@deftypefn Supplemental int getpagesize ()
 
-	getpagesize -- return the number of bytes in page of memory
+Returns the number of bytes in a page of memory.  This is the
+granularity of many of the system memory management routines.  No
+guarantee is made as to whether or not it is the same as the basic
+memory management hardware page size.
 
-SYNOPSIS
-
-	int getpagesize (void)
-
-DESCRIPTION
-
-	Returns the number of bytes in a page of memory.  This is the
-	granularity of many of the system memory management routines.
-	No guarantee is made as to whether or not it is the same as the
-	basic memory management hardware page size.
+@end deftypefn
 
 BUGS
 

libiberty/getpwd.c

 /* getpwd.c - get the working directory */
 
+/*
+
+@deftypefn Supplemental char* getpwd ()
+
+Returns the current working directory.  This implementation caches the
+result on the assumption that the process will not call @code{chdir}
+between calls to @code{getpwd}.
+
+@end deftypefn
+
+*/
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

libiberty/index.c

 /* Stub implementation of (obsolete) index(). */
 
+/*
+
+@deftypefn Supplemental char* index (char *@var{s}, int @var{c})
+
+Returns a pointer to the first occurance of the character @var{c} in
+the string @var{s}, or NULL if not found.  The use of @code{index} is
+deprecated in new programs in favor of @code{strchr}.
+
+@end deftypefn
+
+*/
+
 extern char * strchr();
 
 char *

libiberty/maint-tool

+#!/usr/bin/perl
+# -*- perl -*-
+
+#   Copyright (C) 2001
+#   Free Software Foundation
+#
+# This file is part of the libiberty library.
+# Libiberty is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Library General Public
+# License as published by the Free Software Foundation; either
+# version 2 of the License, or (at your option) any later version.
+#
+# Libiberty is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Library General Public License for more details.
+#
+# You should have received a copy of the GNU Library General Public
+# License along with libiberty; see the file COPYING.LIB.  If not,
+# write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+#
+# Originally written by DJ Delorie <dj@redhat.com>
+
+
+# This is a trivial script which checks the lists of C and O files in
+# the Makefile for consistency.
+
+$mode = shift;
+$srcdir = ".";
+
+if ($mode eq "-s") {
+    $srcdir = shift;
+    $mode = shift;
+}
+
+&missing() if $mode eq "missing";
+
+exit 0;
+
+######################################################################
+
+sub missing {
+
+    opendir(S, $srcdir);
+    while ($f = readdir S) {
+	$have{$f} = 1;
+    }
+    closedir(S);
+    opendir(S, ".");
+    while ($f = readdir S) {
+	$have{$f} = 1;
+    }
+    closedir(S);
+
+    for $a (@ARGV) {
+	$listed{$a} = 1;
+	$have{$a} = 0;
+    }
+
+    for $f (sort keys %have) {
+	next unless $have{$f};
+	if ($f =~ /\.c$/) {
+	    print "S $f\n";
+	}
+    }
+    for $f (sort keys %listed) {
+	if ($f =~ /(.*)\.c$/) {
+	    $base = $1;
+	    if (! $listed{"$base.o"}) {
+		print "O $f\n";
+	    }
+	}
+    }
+}

libiberty/memchr.c

 /*
-FUNCTION
-	<<memchr>>---find character in memory
 
-INDEX
-	memchr
+@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
 
-ANSI_SYNOPSIS
-	#include <string.h>
-	void *memchr(const void *<[src]>, int <[c]>, size_t <[length]>);
+This function searches memory starting at @code{*}@var{src} for the
+character @var{c}.  The search only ends with the first occurrence of
+@var{c}, or after @var{length} characters; in particular, a null
+character does not terminate the search.  If the character @var{c} is
+found within @var{length} characters of @code{*}@var{src}, a pointer
+to the character is returned. If @var{c} is not found, then NULL is
+returned.
 
-TRAD_SYNOPSIS
-	#include <string.h>
-	void *memchr(<[src]>, <[c]>, <[length]>)
-	void *<[src]>;
-	void *<[c]>;
-	size_t <[length]>;
-
-DESCRIPTION
-	This function searches memory starting at <<*<[src]>>> for the
-	character <[c]>.  The search only ends with the first
-	occurrence of <[c]>, or after <[length]> characters; in
-	particular, <<NULL>> does not terminate the search.
-
-RETURNS
-	If the character <[c]> is found within <[length]> characters
-	of <<*<[src]>>>, a pointer to the character is returned. If
-	<[c]> is not found, then <<NULL>> is returned. 	
-
-PORTABILITY
-<<memchr>>  requires no supporting OS subroutines.
-
-QUICKREF
-	memchr ansi pure
+@end deftypefn
 
 */
 

libiberty/memcmp.c

@@ -2,16 +2,17 @@
    This function is in the public domain.  */
 
 /*
-NAME
-	memcmp -- compare two memory regions
 
-SYNOPSIS
-	int memcmp (const void *from, const void *to, size_t count)
+@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
+
+Compares the first @var{count} bytes of two areas of memory.  Returns
+zero if they are the same, a value less than zero if @var{x} is
+lexically less than @var{y}, or a value greater than zero if @var{x}
+is lexically greater than @var{y}.  Note that lexical order is determined
+as if comparing unsigned char arrays.
+
+@end deftypefn
 
-DESCRIPTION
-	Compare two memory regions and return less than,
-	equal to, or greater than zero, according to lexicographical
-	ordering of the compared regions.
 */
 
 #include <ansidecl.h>

libiberty/memcpy.c

@@ -2,15 +2,14 @@
    This function is in the public domain.  */
 
 /*
-NAME
-	memcpy -- copy memory regions of arbitary length
 
-SYNOPSIS
-	void* memcpy (void *out, const void *in, size_t n);
+@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
+
+Copies @var{length} bytes from memory region @var{in} to region
+@var{out}.  Returns a pointer to @var{out}.
+
+@end deftypefn
 
-DESCRIPTION
-	Copy LENGTH bytes from memory region pointed to by IN to memory
-	region pointed to by OUT.
 */
 
 #include <ansidecl.h>

libiberty/memmove.c

 /* Wrapper to implement ANSI C's memmove using BSD's bcopy. */
 /* This function is in the public domain.  --Per Bothner. */
+
+/*
+
+@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
+
+Copies @var{count} bytes from memory area @var{from} to memory area
+@var{to}, returning a pointer to @var{to}.
+
+@end deftypefn
+
+*/
+
 #include <ansidecl.h>
 #ifdef __STDC__
 #include <stddef.h>

libiberty/memset.c

 /* memset
    This implementation is in the public domain.  */
 
+/*
+
+@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
+
+Sets the first @var{count} bytes of @var{s} to the constant byte
+@var{c}, returning a pointer to @var{s}.
+
+@end deftypefn
+
+*/
+
 #include <ansidecl.h>
 #ifdef __STDC__
 #include <stddef.h>

libiberty/putenv.c

@@ -16,6 +16,19 @@
    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.  */
 
+/*
+
+@deftypefn Supplemental int putenv (const char *@var{string})
+
+Uses @code{setenv} or @code{unsetenv} to put @var{string} into
+the environment or remove it.  If @var{string} is of the form
+@samp{name=value} the string is added; if no `=' is present the
+name is unset/removed.
+
+@end deftypefn
+
+*/
+
 #if defined (_AIX) && !defined (__GNUC__)
  #pragma alloca
 #endif

libiberty/rename.c

 /* rename -- rename a file
    This function is in the public domain. */
 
-/* Rename a file.  */
+/*
+
+@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
+
+Renames a file from @var{old} to @var{new}.  If @var{new} already
+exists, it is removed.
+
+@end deftypefn
+
+*/
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"

libiberty/rindex.c

 /* Stub implementation of (obsolete) rindex(). */
 
+/*
+
+@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
+
+Returns a pointer to the last occurance of the character @var{c} in
+the string @var{s}, or NULL if not found.  The use of @code{rindex} is
+deprecated in new programs in favor of @code{strrchr}.
+
+@end deftypefn
+
+*/
+
 extern char *strrchr ();
 
 char *

libiberty/setenv.c

@@ -16,6 +16,22 @@
    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.  */
 
+
+/*
+
+@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
+@deftypefnx Supplemental void unsetenv (const char *@var{name})
+
+@code{setenv} adds @var{name} to the environment with value
+@var{value}.  If the name was already present in the environment,
+the new value will be stored only if @var{overwrite} is non-zero.
+The companion @code{unsetenv} function removes @var{name} from the
+environment.  This implementation is not safe for multithreaded code.
+
+@end deftypefn
+
+*/
+
 #if HAVE_CONFIG_H
 # include <config.h>
 #endif

libiberty/sigsetmask.c

@@ -3,8 +3,17 @@
    Contributed by Cygnus Support.
    This file is in the public doamin. */
 
-/* Set the current signal mask to the set provided, and return the 
-   previous value */
+/*
+
+@deftypefn Supplemental int sigsetmask (int @var{set})
+
+Sets the signal mask to the one provided in @var{set} and returns
+the old mask (which, for libiberty's implementation, will always
+be the value @code{1}).
+
+@end deftypefn
+
+*/
 
 #define _POSIX_SOURCE
 #include <ansidecl.h>

libiberty/strcasecmp.c

@@ -10,6 +10,16 @@
  * is provided ``as is'' without express or implied warranty.
  */
 
+/*
+  
+@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
+
+A case-insensitive @code{strcmp}.
+
+@end deftypefn
+
+*/
+
 #if defined(LIBC_SCCS) && !defined(lint)
 static char sccsid[] = "@(#)strcasecmp.c	5.5 (Berkeley) 11/24/87";
 #endif /* LIBC_SCCS and not lint */

libiberty/strchr.c

@@ -2,19 +2,15 @@
    This function is in the public domain.  */
 
 /*
-NAME
-	strchr -- return pointer to first occurance of a character
 
-SYNOPSIS
-	char *strchr (const char *s, int c)
+@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
+
+Returns a pointer to the first occurance of the character @var{c} in
+the string @var{s}, or NULL if not found.  If @var{c} is itself the
+null character, the results are undefined.
+
+@end deftypefn
 
-DESCRIPTION
-	Returns a pointer to the first occurance of character C in
-	string S, or a NULL pointer if no occurance is found.
-	
-BUGS
-	Behavior when character is the null character is implementation
-	dependent.
 */
 
 #include <ansidecl.h>

libiberty/strdup.c

+/*
+
+@deftypefn Supplemental char* strdup (const char *@var{s})
+
+Returns a pointer to a copy of @var{s} in memory obtained from
+@code{malloc}, or NULL if insufficient memory was available.
+
+@end deftypefn
+
+*/
+
 char *
 strdup(s)
      char *s;

libiberty/strerror.c

@@ -562,28 +562,23 @@ init_error_tables ()
 
 /*
 
-NAME
-
-	errno_max -- return the max errno value
 
-SYNOPSIS
+@deftypefn Replacement int errno_max (void)
 
-	int errno_max ();
+Returns the maximum @code{errno} value for which a corresponding
+symbolic name or message is available.  Note that in the case where we
+use the @code{sys_errlist} supplied by the system, it is possible for
+there to be more symbolic names than messages, or vice versa.  In
+fact, the manual page for @code{perror(3C)} explicitly warns that one
+should check the size of the table (@code{sys_nerr}) before indexing
+it, since new error codes may be added to the system before they are
+added to the table.  Thus @code{sys_nerr} might be smaller than value
+implied by the largest @code{errno} value defined in @file{errno.h}.
 
-DESCRIPTION
+We return the maximum value that can be used to obtain a meaningful
+symbolic name or message.
 
-	Returns the maximum errno value for which a corresponding symbolic
-	name or message is available.  Note that in the case where
-	we use the sys_errlist supplied by the system, it is possible for
-	there to be more symbolic names than messages, or vice versa.
-	In fact, the manual page for perror(3C) explicitly warns that one
-	should check the size of the table (sys_nerr) before indexing it,
-	since new error codes may be added to the system before they are
-	added to the table.  Thus sys_nerr might be smaller than value
-	implied by the largest errno value defined in <errno.h>.
-
-	We return the maximum value that can be used to obtain a meaningful
-	symbolic name or message.
+@end deftypefn
 
 */
 
@@ -604,31 +599,25 @@ errno_max ()
 
 /*
 
-NAME
+@deftypefn Replacement char* strerror (int @var{errnoval})
 
-	strerror -- map an error number to an error message string
+Maps an @code{errno} number to an error message string, the contents
+of which are implementation defined.  On systems which have the
+external variables @code{sys_nerr} and @code{sys_errlist}, these
+strings will be the same as the ones used by @code{perror}.
 
-SYNOPSIS
+If the supplied error number is within the valid range of indices for
+the @code{sys_errlist}, but no message is available for the particular
+error number, then returns the string @samp{"Error NUM"}, where NUM is
+the error number.
 
-	char *strerror (int errnoval)
+If the supplied error number is not a valid index into
+@code{sys_errlist}, returns NULL.
 
-DESCRIPTION
-
-	Maps an errno number to an error message string, the contents of
-	which are implementation defined.  On systems which have the external
-	variables sys_nerr and sys_errlist, these strings will be the same
-	as the ones used by perror().
-
-	If the supplied error number is within the valid range of indices
-	for the sys_errlist, but no message is available for the particular
-	error number, then returns the string "Error NUM", where NUM is the
-	error number.
+The returned string is only guaranteed to be valid only until the
+next call to @code{strerror}.
 
-	If the supplied error number is not a valid index into sys_errlist,
-	returns NULL.
-
-	The returned string is only guaranteed to be valid only until the
-	next call to strerror.
+@end deftypefn
 
 */
 
@@ -678,32 +667,24 @@ strerror (errnoval)
 
 /*
 
-NAME
+@deftypefn Replacement const char* strerrno (int @var{errnum})
 
-	strerrno -- map an error number to a symbolic name string
+Given an error number returned from a system call (typically returned
+in @code{errno}), returns a pointer to a string containing the
+symbolic name of that error number, as found in @file{errno.h}.
 
-SYNOPSIS
+If the supplied error number is within the valid range of indices for
+symbolic names, but no name is available for the particular error
+number, then returns the string @samp{"Error NUM"}, where NUM is the
+error number.
 
-	const char *strerrno (int errnoval)
+If the supplied error number is not within the range of valid
+indices, then returns NULL.
 
-DESCRIPTION
-
-	Given an error number returned from a system call (typically
-	returned in errno), returns a pointer to a string containing the
-	symbolic name of that error number, as found in <errno.h>.
-
-	If the supplied error number is within the valid range of indices
-	for symbolic names, but no name is available for the particular
-	error number, then returns the string "Error NUM", where NUM is
-	the error number.
-
-	If the supplied error number is not within the range of valid
-	indices, then returns NULL.
-
-BUGS
+The contents of the location pointed to are only guaranteed to be
+valid until the next call to strerrno.
 
-	The contents of the location pointed to are only guaranteed to be
-	valid until the next call to strerrno.
+@end deftypefn
 
 */
 
@@ -746,18 +727,12 @@ strerrno (errnoval)
 
 /*
 
-NAME
-
-	strtoerrno -- map a symbolic errno name to a numeric value
-
-SYNOPSIS
-
-	int strtoerrno (char *name)
+@deftypefn Replacement int strtoerrno (const char *@var{name})
 
-DESCRIPTION
+Given the symbolic name of a error number (e.g., @code{EACCESS}), map it
+to an errno value.  If no translation is found, returns 0.
 
-	Given the symbolic name of a error number, map it to an errno value.
-	If no translation is found, returns 0.
+@end deftypefn
 
 */
 

libiberty/strncasecmp.c

@@ -10,6 +10,16 @@
  * is provided ``as is'' without express or implied warranty.
  */
 
+/*
+  
+@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
+
+A case-insensitive @code{strncmp}.
+
+@end deftypefn
+
+*/
+
 #if defined(LIBC_SCCS) && !defined(lint)
 static char sccsid[] = "@(#)strcasecmp.c	5.5 (Berkeley) 11/24/87";
 #endif /* LIBC_SCCS and not lint */

libiberty/strncmp.c

 /* strncmp -- compare two strings, stop after n bytes.
    This function is in the public domain.  */
 
+/*
+
+@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
+
+Compares the first @var{n} bytes of two strings, returning a value as
+@code{strcmp}.
+
+@end deftypefn
+
+*/
+
 #include <ansidecl.h>
 #ifdef __STDC__
 #include <stddef.h>

libiberty/strrchr.c

@@ -2,19 +2,15 @@
    This function is in the public domain. */
 
 /*
-NAME
-	strrchr -- return pointer to last occurance of a character
-
-SYNOPSIS
-	char *strrchr (const char *s, int c)
-
-DESCRIPTION
-	Returns a pointer to the last occurance of character C in
-	string S, or a NULL pointer if no occurance is found.
-	
-BUGS
-	Behavior when character is the null character is implementation
-	dependent.
+
+@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
+
+Returns a pointer to the last occurance of the character @var{c} in
+the string @var{s}, or NULL if not found.  If @var{c} is itself the
+null character, the results are undefined.
+
+@end deftypefn
+
 */
 
 #include <ansidecl.h>

libiberty/strstr.c

@@ -3,24 +3,16 @@
 
 /*
 
-NAME
+@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
 
-	strstr -- locate first occurance of a substring
+This function searches for the substring @var{sub} in the string
+@var{string}, not including the terminating NUL characters.  A pointer
+to the first occurance of @var{sub} is returned, or NULL if the
+substring is absent.  If @var{sub} points to a string with zero
+length, the function returns @var{string}.
 
-SYNOPSIS
+@end deftypefn
 
-	#include <string.h>
-
-	char *strstr (char *s1, char *s2)
-
-DESCRIPTION
-
-	Locates the first occurance in the string pointed to by S1 of
-	the string pointed to by S2.  Returns a pointer to the substring
-	found, or a NULL pointer if not found.  If S2 points to a string
-	with zero length, the function returns S1.
-	
-BUGS
 
 */
 

libiberty/strtod.c

@@ -22,6 +22,21 @@ the resulting executable to be covered by the GNU General Public License.
 This exception does not however invalidate any other reasons why
 the executable file might be covered by the GNU General Public License. */
 
+/*
+
+@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
+
+This ANSI C function converts the initial portion of @var{string} to a
+@code{double}.  If @var{endptr} is not NULL, a pointer to the
+character after the last character used in the conversion is stored in
+the location referenced by @var{endptr}.  If no conversion is
+performed, zero is returned and the value of @var{string} is stored in
+the location referenced by @var{endptr}.
+
+@end deftypefn
+
+*/
+
 #include "ansidecl.h"
 #include "safe-ctype.h"
 

libiberty/strtol.c

@@ -28,6 +28,23 @@
  * SUCH DAMAGE.
  */
 
+/*
+
+@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
+
+The @code{strtol} function converts the string in @var{string} to a
+long integer value according to the given @var{base}, which must be
+between 2 and 36 inclusive, or be the special value 0.  If @var{base}
+is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
+to indicate bases 8 and 16, respectively, else default to base 10.
+When the base is 16 (either explicitly or implicitly), a prefix of
+@code{0x} is allowed.  The handling of endptr is as that of
+@code{strtod} above.
+
+@end deftypefn
+
+*/
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

libiberty/tmpnam.c

+/*
+
+@deftypefn Supplemental char* tmpnam (char *@var{s})
+
+This function attempts to create a name for a temporary file, which
+will be a valid file name yet not exist when @code{tmpnam} checks for
+it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
+or be NULL.  Use of this function creates a security risk, and it must
+not be used in new projects.  Use @code{mkstemp} instead.
+
+@end deftypefn
+
+*/
+
 #include <stdio.h>
 
 #ifndef L_tmpnam

libiberty/vfork.c

 /* Emulate vfork using just plain fork, for systems without a real vfork.
    This function is in the public domain. */
 
+/*
+
+@deftypefn Supplemental int vfork ()
+
+Emulates @code{vfork} by calling @code{fork} and returning its value.
+
+@end deftypefn
+
+*/
+
 #include "ansidecl.h"
 
 extern int fork PARAMS ((void));

libiberty/vprintf.c

+/*
+
+@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
+@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
+@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
+
+These functions are the same as @code{printf}, @code{fprintf}, and
+@code{sprintf}, respectively, except that they are called with a
+@code{va_list} instead of a variable number of arguments.  Note that
+they do not call @code{va_end}; this is the application's
+responsibility.  In @libib{} they are implemented in terms of the
+nonstandard but common function @code{_doprnt}.
+
+@end deftypefn
+
+*/
+
 #ifdef __STDC__
 #include <stdarg.h>
 #else

libiberty/waitpid.c

+/*
+
+@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
+
+This is a wrapper around the @code{wait} function.  Any ``special''
+values of @var{pid} depend on your implementation of @code{wait}, as
+does the return value.  The third argument is unused in @libib{}.
+
+@end deftypefn
+
+*/
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

libiberty/xatexit.c

@@ -5,6 +5,20 @@
  * %sccs.include.redist.c%
  */
 
+
+/*
+
+@deftypefun int xatexit (void (*@var{fn}) (void))
+
+Behaves as the standard @code{atexit} function, but with no limit on
+the number of registered funtions.  Returns 0 on success, or -1 on
+failure.  If you use @code{xatexit} to register functions, you must use
+@code{xexit} to terminate your program.
+
+@end deftypefun
+
+*/
+
 /* Adapted from newlib/libc/stdlib/{,at}exit.[ch].
    If you use xatexit, you must call xexit instead of exit.  */
 

libiberty/xexit.c

@@ -17,6 +17,18 @@ License along with libiberty; see the file COPYING.LIB.  If not, write
 to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 Boston, MA 02111-1307, USA.  */
 
+/*
+
+@deftypefn Replacement void xexit (int @var{code})
+
+Terminates the program.  If any functions have been registered with
+the @code{xatexit} rpelacement function, they will be called first.
+Termination is handled via the system's normal @code{exit} call.
+
+@end deftypefn
+
+*/
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

libiberty/xmalloc.c

@@ -17,6 +17,48 @@ License along with libiberty; see the file COPYING.LIB.  If
 not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 Boston, MA 02111-1307, USA.  */
 
+/*
+
+@deftypefn Replacement void* xmalloc (size_t)
+
+Allocate memory without fail.  If @code{malloc} fails, this will print
+a message to stderr (using the name set by @code{xmalloc_set_program_name},
+if any) and then call @code{xexit}.  Note that it is therefore safe for
+a program to contain @code{#define malloc xmalloc} in its source.
+
+@end deftypefn
+
+@deftypefn Replacement void* xrealloc (void*, size_t)
+Reallocate memory without fail.  This routine functions like @code{realloc},
+but will behave the same as @code{xmalloc} if memory cannot be found.
+
+@end deftypefn
+
+@deftypefn Replacement void* xcalloc (size_t, size_t)
+
+Allocate memory without fail, and set it to zero.  This routine functions
+like @code{calloc}, but will behave the same as @code{xmalloc} if memory
+cannot be found.
+
+@end deftypefn
+
+@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
+
+You can use this to set the name of the program used by
+@code{xmalloc_failed} when printing a failure message.
+
+@end deftypefn
+
+@deftypefn Replacement void xmalloc_failed (size_t)
+
+This function is not meant to be called by client code, and is listed
+here for completeness only.  If any of the allocation routines fail, this
+function will be called to print an error message and terminate execution.
+
+@end deftypefn
+
+*/
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

libiberty/xmemdup.c

@@ -2,6 +2,19 @@
    This trivial function is in the public domain.
    Jeff Garzik, September 1999.  */
 
+/*
+
+@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
+
+Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
+are allocated, then @var{copy_size} bytes from @var{input} are copied into
+it, and the new memory is returned.  If fewer bytes are copied than were
+allocated, the remaining memory is zeroed.
+
+@end deftypefn
+
+*/
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

libiberty/xstrdup.c

@@ -2,6 +2,17 @@
    This trivial function is in the public domain.
    Ian Lance Taylor, Cygnus Support, December 1995.  */
 
+/*
+
+@deftypefn Replacement char* xstrdup (const char *@var{s})
+
+Duplicates a character string without fail, using @code{xmalloc} to
+obtain memory.
+
+@end deftypefn
+
+*/
+
 #include <sys/types.h>
 #ifdef HAVE_CONFIG_H
 #include "config.h"

libiberty/xstrerror.c

@@ -2,6 +2,17 @@
    Fri Jun 16 18:30:00 1995  Pat Rankin  <rankin@eql.caltech.edu>
    This code is in the public domain.  */
 
+/*
+
+@deftypefn Replacement char* xstrerror (int @var{errnum})
+
+Behaves exactly like the standard @code{strerror} function, but
+will never return a NULL pointer.
+
+@end deftypefn
+
+*/
+
 #include <stdio.h>
 
 #include "libiberty.h"