getopt: document special symbols that should not be used as option characters

getopt(3) routines return `?` or `:` when an unknown option character is encountered
or an option is missing its required argument, respectively. It also disallows
`;` as an option character. Documenting this makes users aware that they may not use
these reserved symbols as option characters, e.g. `-?` which is used in some older programs.

Addresses: #2995
Signed-off-by: Christian Goeschel Ndjomouo <cgoesc2@wgu.edu>

diff --git a/misc-utils/getopt.1.adoc b/misc-utils/getopt.1.adoc
index 2630205e35a7d9a8fe90e72ed8f98a5eb25913cb..0108c300aae12d959a16ab349f9bed1050101526 100644 (file)
--- a/misc-utils/getopt.1.adoc
+++ b/misc-utils/getopt.1.adoc
@@ -67,7 +67,7 @@ This section specifies the format of the second part of the parameters of *getop
 
 The parameters are parsed from left to right. Each parameter is classified as a short option, a long option, an argument to an option, or a non-option parameter.
 
-A simple short option is a '*-*' followed by a short option character. If the option has a required argument, it may be written directly after the option character or as the next parameter (i.e., separated by whitespace on the command line). If the option has an optional argument, it must be written directly after the option character if present.
+A simple short option is a '*-*' followed by a short option character, except for the ':', ';' and '?' characters, as these are reserved by *getopt*(3). If the option has a required argument, it may be written directly after the option character or as the next parameter (i.e., separated by whitespace on the command line). If the option has an optional argument, it must be written directly after the option character if present.
 
 It is possible to specify several short options after one '*-*', as long as all (except possibly the last) do not have required or optional arguments.
 

diff --git a/misc-utils/getopt.c b/misc-utils/getopt.c
index ca68d964835f1950ef46702bff8399557852f2ed..35737d504727f34ed4175fc174f776d11c30182f 100644 (file)
--- a/misc-utils/getopt.c
+++ b/misc-utils/getopt.c
@@ -201,6 +201,10 @@ static int generate_output(struct getopt_control *ctl, char *argv[], int argc)
                 (argc, argv, ctl->optstr,
                  (const struct option *)ctl->long_options, &longindex)))
               != EOF) {
+               /* Given that these two characters are returned by the getopt(3) routines 
+                * to distinguish between two distinct internal error states, they should
+                * not be used as option characters.
+               */
                if (opt == '?' || opt == ':')
                        exit_code = GETOPT_EXIT_CODE;
                else if (!ctl->quiet_output) {