]> Savannah Git Hosting - gnulib.git/commitdiff
getopt: harmonize comments with glibc
authorZack Weinberg <zackw@panix.com>
Thu, 6 Apr 2017 18:14:13 +0000 (11:14 -0700)
committerPaul Eggert <eggert@cs.ucla.edu>
Thu, 6 Apr 2017 22:42:02 +0000 (15:42 -0700)
The comments explaining how the behavior of 'getopt' varies depending
on whether it's the standalone version and whether there are special
characters at the beginning of the options string were inconsistent
between gnulib and glibc, and also out of sync with the code.

* lib/getopt.c, lib/getopt_int.h: Harmonize comments with glibc.

ChangeLog
lib/getopt.c
lib/getopt_int.h

index 0e51f1d5ac500f8d60264da4c752f7bb5f15548f..2c8109197bd21d5c21eff12cd2191c67f345dd58 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
 2017-04-06  Zack Weinberg  <zackw@panix.com>
 
+       getopt: harmonize comments with glibc
+
+       The comments explaining how the behavior of 'getopt' varies depending
+       on whether it's the standalone version and whether there are special
+       characters at the beginning of the options string were inconsistent
+       between gnulib and glibc, and also out of sync with the code.
+
+       * lib/getopt.c, lib/getopt_int.h: Harmonize comments with glibc.
+
+
        getopt: remove USE_NONOPTION_FLAGS
 
        getopt includes code to parse an environment variable named
index 157a737f9e009e3fb718237fd0747b7df2b2e892..65ad56780ffed7654cd8f11c841ca6bfea74f1e2 100644 (file)
 # include <wchar.h>
 #endif
 
-/* This version of 'getopt' appears to the caller like standard Unix 'getopt'
-   but it behaves differently for the user, since it allows the user
-   to intersperse the options with the other arguments.
-
-   As 'getopt_long' works, it permutes the elements of ARGV so that,
-   when it is done, all the options precede everything else.  Thus
-   all application programs are extended to handle flexible argument order.
-
-   Using 'getopt' or setting the environment variable POSIXLY_CORRECT
+/* This implementation of 'getopt' has three modes for handling
+   options interspersed with non-option arguments.  It can stop
+   scanning for options at the first non-option argument encountered,
+   as POSIX specifies.  It can continue scanning for options after the
+   first non-option argument, but permute 'argv' as it goes so that,
+   after 'getopt' is done, all the options precede all the non-option
+   arguments and 'optind' points to the first non-option argument.
+   Or, it can report non-option arguments as if they were arguments to
+   the option character '\x01'.
+
+   The default behavior of 'getopt_long' is to permute the argument list.
+   When this implementation is used standalone, the default behavior of
+   'getopt' is to stop at the first non-option argument, but when it is
+   used as part of GNU libc it also permutes the argument list.  In both
+   cases, setting the environment variable POSIXLY_CORRECT to any value
    disables permutation.
-   Then the behavior is completely standard.
 
-   GNU application programs can use a third alternative mode in which
-   they can distinguish the relative order of options and other arguments.  */
+   If the first character of the OPTSTRING argument to 'getopt' or
+   'getopt_long' is '+', both functions will stop at the first
+   non-option argument.  If it is '-', both functions will report
+   non-option arguments as arguments to the option character '\x01'.  */
 
 #include "getopt_int.h"
 
index 5a5528c626a4acdaa315b812a2e8f736c6e397b6..762679a30598b9c8a128abf6f7abaa626886f5a4 100644 (file)
@@ -32,28 +32,20 @@ extern int _getopt_internal (int ___argc, char **___argv,
 
 /* Describe how to deal with options that follow non-option ARGV-elements.
 
-   If the caller did not specify anything,
-   the default is REQUIRE_ORDER if the environment variable
-   POSIXLY_CORRECT is defined, PERMUTE otherwise.
-
-   REQUIRE_ORDER means don't recognize them as options;
-   stop option processing when the first non-option is seen.
-   This is what Unix does.
-   This mode of operation is selected by either setting the environment
-   variable POSIXLY_CORRECT, or using '+' as the first character
-   of the list of option characters, or by calling getopt.
-
-   PERMUTE is the default.  We permute the contents of ARGV as we
-   scan, so that eventually all the non-options are at the end.
-   This allows options to be given in any order, even with programs
-   that were not written to expect this.
+   REQUIRE_ORDER means don't recognize them as options; stop option
+   processing when the first non-option is seen.  This is what POSIX
+   specifies should happen.
+
+   PERMUTE means permute the contents of ARGV as we scan, so that
+   eventually all the non-options are at the end.  This allows options
+   to be given in any order, even with programs that were not written
+   to expect this.
 
    RETURN_IN_ORDER is an option available to programs that were
    written to expect options and other ARGV-elements in any order
    and that care about the ordering of the two.  We describe each
    non-option ARGV-element as if it were the argument of an option
-   with character code 1.  Using '-' as the first character of the
-   list of option characters selects this mode of operation.
+   with character code 1.
 
    The special argument '--' forces an end of option-scanning regardless
    of the value of 'ordering'.  In the case of RETURN_IN_ORDER, only
@@ -91,8 +83,7 @@ struct _getopt_data
   /* See __ord above.  */
   enum __ord __ordering;
 
-  /* If the POSIXLY_CORRECT environment variable is set
-     or getopt was called.  */
+  /* True if behaving strictly as specified by POSIX.  */
   int __posixly_correct;