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>
(cherry picked from commit 9b4f1ca3342bdff7e1c3d8eaf3735cf821f407bc)

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 67d5737fd1256e81d9a052f08251f04cc1116c9d..0d85b6628dd7247b871161d799990a6e95e106ba 100644 (file)
--- a/misc-utils/getopt.c
+++ b/misc-utils/getopt.c
@@ -202,6 +202,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) {