diff --git a/Base/usr/share/man/man3/getopt.md b/Base/usr/share/man/man3/getopt.md new file mode 100644 index 0000000000..b9953d5a28 --- /dev/null +++ b/Base/usr/share/man/man3/getopt.md @@ -0,0 +1,153 @@ +## Name + +getopt - parse command-line options + +## Synopsis + +```**c++ +#include + +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 + +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) diff --git a/Base/usr/share/man/man5/getopt.md b/Base/usr/share/man/man5/getopt.md new file mode 100644 index 0000000000..38062a2d51 --- /dev/null +++ b/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)