2004-03-03  Marcus Brinkmann  <marcus@gnu.org>

	* manual/getopt.texi (Reentrant Getopt): New subsection.

diff -ru libc-old/manual/getopt.texi libc/manual/getopt.texi
--- libc-old/manual/getopt.texi	2004-03-03 19:21:52.000000000 +0100
+++ libc/manual/getopt.texi	2004-03-03 22:20:03.000000000 +0100
@@ -10,6 +10,7 @@
 * Getopt Long Options::         GNU suggests utilities accept long-named
                                  options; here is one way to do.
 * Getopt Long Option Example::  An example of using @code{getopt_long}.
+* Reentrant Getopt::            Reentrant versions of @code{getopt}.
 @end menu
 
 @node Using Getopt, Example of Getopt, , Getopt
@@ -305,3 +306,91 @@
 @smallexample
 @include longopt.c.texi
 @end smallexample
+
+@node Reentrant Getopt
+@subsection Using @code{getopt} recursively
+
+The @code{getopt} interface uses global variables to keep state
+information and is not reentrant.  To use @code{getopt} recursively or
+from several threads, you can make use of the following thread-safe
+versions of @code{getopt}.  This is a GNU extension.
+
+Even the reentrant versions of @code{getopt} can reorder the elements
+of the argument vector.  To be safe you have to disable reordering of
+the arguments or avoid using the same argument vector concurrently.
+
+@comment getopt.h
+@comment GNU
+@deftp {Data Type} {struct getopt_data}
+This structure is used by the reentrant versions of Getopt.
+
+The @code{struct getopt_data} structure has these fields, which have
+exactly the same meaning and default values as the corresponding
+global variables of @code{getopt}.
+
+@table @code
+@item int optind
+
+@item int opterr
+
+@item int optopt
+
+@item char *optarg
+@end table
+@end deftp
+
+@deftypevr Macro {struct getopt_data} GETOPT_DATA_INITIALIZER
+This macro must be used to initialize a statically allocated variable
+of type @code{struct getopt_data}.
+
+@smallexample
+static struct getopt_data opt_data = GETOPT_DATA_INITIALIZER;
+@end smallexample
+
+In other contexts you have to use it in a compound statement like
+this:
+
+@smallexample
+@{
+  struct getopt_data opt_data
+    = (struct getopt_data) GETOPT_DATA_INITIALIZER;
+  opt_date.opterr = 0;
+  @dots{}
+@}
+@end smallexample
+@end deftypevr
+
+@comment getopt.h
+@comment GNU
+@deftypefun int getopt_r (int @var{argc}, char **@var{argv}, const char *@var{options}, struct getopt_data *@var{data})
+The @code{getopt_r} function is identical to the @code{getopt}
+function, except that it does use the storage pointed to by @var{data}
+to keep its state across invocations, and is reentrant.
+
+@var{data} must have been allocated by the caller and initialized with
+@code{GETOPT_DATA_INITIALIZER}.
+@end deftypefun
+
+@comment getopt.h
+@comment GNU
+@deftypefun int getopt_long_r (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr}, struct getopt_data *@var{data})
+The @code{getopt_long_r} function is identical to the
+@code{getopt_long} function, except that it does use the storage
+pointed to by @var{data} to keep its state across invocations, and is
+reentrant.
+
+@var{data} must have been allocated by the caller and initialized with
+@code{GETOPT_DATA_INITIALIZER}.
+@end deftypefun
+
+@comment getopt.h
+@comment GNU
+@deftypefun int getopt_long_only_r (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr}, struct getopt_data *@var{data})
+The @code{getopt_long_only_r} function is identical to the
+@code{getopt_long_only} function, except that it does use the storage
+pointed to by @var{data} to keep its state across invocations, and is
+reentrant.
+
+@var{data} must have been allocated by the caller and initialized with
+@code{GETOPT_DATA_INITIALIZER}.
+@end deftypefun