Base: Document getopt

Base/usr/share/man/man3/getopt.md

@@ -0,0 +1,153 @@
+## Name
+
+getopt - parse command-line options
+
+## Synopsis
+
+```**c++
+#include <getopt.h>
+
+extren int opterr;
+extern int optopt;
+extern int optind;
+extern int optreset;
+extern char* optarg;
+
+struct option {
+    const char* name;
+    int has_arg;
+    int* flag;
+    int val;
+};
+
+int getopt(int argc, char** argv, const char* short_options);
+int getopt_long(int argc, char** argv, const char* short_options, const struct option* long_options, int* out_long_option_index);
+```
+
+## Description
+
+`getopt()` and `getopt_long()` parse options according to the syntax specified
+in [`getopt`(5)](../getopt.md). `getopt()` only supports short options;
+`getopt_long()` supports both short and long options.
+
+One invocation of either function extracts at most one option from command line
+arguments, which are passed to it as the `argc`/`argv` pair, starting from
+argument at index `optind`, which is initially set to 1 at program startup.
+
+The `short_options` string should specify the short options to be recognized, as
+single characters. If a short option requires a value, it is to be followed by a
+colon character (`:`); if a short option optionally accepts a value, it is to be
+followed by a double colon (`::`). If the first character in the `short_options`
+is `+`, `getopt()` and `getopt_long()` won't look for further options once first
+non-option argument is encountered.
+
+`getopt_long()` additionally accepts an array of values describing long options
+to be recognized. To specify whether a long option has a value, the `has_arg`
+member of `struct option` must be set to one of the following predefined macro
+values:
+
+* `no_argument`, if no value is accepted;
+* `required_argument`, if a value is optionally accepted;
+* `optional_argument`, if a value is optionally accepted.
+
+If an option is parsed successfully, `getopt()` and `getopt_long()`
+automatically increase the `optind` variable to point to the next command-line
+argument to be parsed. This makes it possible to invoke `getopt()` or
+`getopt_long()` in a loop unless they indicate either an error or the end of
+options, and then treat the remaining command-line arguments, starting from the
+one pointed to be `optind`, as non-option argument.
+
+Unless `+` is specified as the first character of `short_options`, `getopt()`
+and `getopt_long()` automatically reorder elements of `argv` to put options and
+their values before any non-option arguments.
+
+If, after having used `getopt()` or `getopt_long()` to parse a set of
+command-line arguments, the program intends to use the `getopt()` or
+`getopt_long()` to parse a different set of command-line arguments, it must ask
+`getopt()` and `getopt_long()` to reset the internal state that they keep across
+calls to handle some tricky cases. To do so, the program must either set the
+`optreset` variable to a non-zero value, or set `optind` variable to 0. Doing
+either of these things will reset the internal state, and option parsing will
+start from command-line argument at index 1 in either case.
+
+## Return value
+
+If no option has been found, `getopt()` and `getopt_long()` return -1.
+
+In case some invalid configuration of options and their values are passed in
+`argv`, `getopt()` and `getopt_long()` return the `'?'` character. If the error
+is related to a short option, the variable `optopt` is set to the option
+character. If the variable `opterr` has a non-zero value (as it does by
+default), an appropriate error message is printed to the standard error stream.
+
+If a short option has been successfully parsed, `getopt()` and `getopt_long()`
+return its character. Its value, if any, is assigned to the `optarg` variable.
+If the option has been given no value, `optarg` is set to `nullptr`.
+
+If a long option has been successfully parsed, `getopt_long()` return value
+depends on the value of the `flag` pointer for that option. If `flag` is
+`nullptr`, `getopt_long()` returns the value of `val` for that option.
+Otherwise, the pointee of `flag` is set to `val`, and `getopt_long()` returns 0.
+In either case, the index of the long option in the `long_options` array is
+stored to the pointee of `out_long_option_index`, if it's not a `nullptr`. Same
+as for short options, the `optarg` variable is set to point to the value of the
+option, or to `nullptr` is none has been given.
+
+## Examples
+
+```c++
+#include <getopt.h>
+
+int verbose = 0;
+const char* pad = nullptr;
+const char* source = nullptr;
+
+while (true) {
+    // Accept short options: -h, -l, -s value, -p [value], -N.
+    const char* short_options = "hls:p::N";
+    // Accept long options: --pad [value], --verbose.
+    const option long_options[] {
+        { "pad", optional_argument, nullptr, 'p' },
+        { "verbose", no_argument, &verbose, 1 },
+    };
+    int opt = getopt(argc, argv, short_options, long_options, nullptr);
+    switch (opt) {
+    case -1:
+        // No more options.
+        return true;
+    case '?':
+        // Some error; getopt() has already printed an error message.
+        exit(1);
+    case 'h':
+        // Handle the -h option...
+        break;
+    case 'l':
+        // Handle the -l option...
+        break;
+    case 's':
+        // Handle the -s option.
+        source = optarg;
+        break;
+    case 'p':
+        // Handle the -p short option or the --pad long option.
+        if (optarg)
+            pad = optarg;
+        else
+            pad = ' ';
+        break;
+    case 'N':
+        // Handle the -N option.
+        break;
+    case 0:
+        // A long option (--verbose) has been parsed, but its
+        // effect was setting the verbose variable to 1.
+        break;
+    }
+}
+
+const char* file_name = argv[optind];
+```
+
+## See also
+
+* [`getopt`(5)](../man5/getopt.md)

Base/usr/share/man/man5/getopt.md

@@ -0,0 +1,91 @@
+## Name
+
+getopt - command-line options
+
+## Synopsis
+
+```**sh
+$ command -o --long-option
+```
+
+## Description
+
+Most programs accept various *options* that configure their behavior to be
+passed alongside other command-line arguments. Each program accepts its own set
+of options, though many programs share options in common.
+
+Options come in two kinds, **short** and **long**. Short options have a single
+letter as their name, are preceded by a single dash, and can be grouped together
+in one argument. Long options have whole strings as their names, are preceded by
+a double dash, and cannot be grouped.
+
+Each option can require (or optionally accept) a **value** (also often
+confusingly called an *argument*). Generally, a value for an option, if any,
+should be written after the option itself, although the exact syntax for values
+of short and long options differs. In both cases, the value can be specified as
+the next command-line argument after the option. For short options, the value
+can also immediately follow the option as a part of the same command-line
+argument. For long options, the value can follow the option as a part of the
+same command-line argument, separated form it by the `=` character.
+
+If several short options are combined into one command line argument, only the
+one specified last can be provided with a value. All the characters following
+the first short option to accept (optionally or not) a value are treated as a
+value for that option, and not as further options.
+
+Options can be freely mixed with non-option command-line arguments (with the
+exception of the very first argument to be specified, which must be the command
+itself). A special command-line argument value `--` can be specified to indicate
+that all further command-line arguments are to be treated like non-option
+arguments, even if they otherwise look like options. The `--` argument itself is
+not considered to be either an option or a non-option argument, and is otherwise
+ignored.
+
+A special argument `-` (a single dash) is always treated as a non-option
+argument.
+
+## Examples
+
+Short and long options, without values or non-option arguments:
+
+```sh
+$ command -o
+$ command -vf -l
+$ command --long-option
+$ command --verbose --force --long
+```
+
+Short and long options with values:
+
+```sh
+$ command -o rw
+$ command --type text/plain
+```
+
+Alternative syntaxes for values:
+
+```sh
+$ command -fttext/plain
+$ command --force --type=text/plain
+```
+
+These two invocation are equivalent, provided the `-f` option has same effect as
+`--force`, and the `-t` option has the same effect as `--type`.
+
+Mixing options and non-option arguments:
+
+```sh
+$ command --force argument
+$ command argument -o value another-argument
+```
+
+Using `--` to prevent arguments from being accidentally misinterpreted as
+options:
+
+```sh
+$ command --force -- -argument --another-argument
+```
+
+## See also
+
+* [`getopt`(3)](../man3/getopt.md)