Base: Document getopt
This commit is contained in:
Sergey Bugaev
Andreas Kling
parent
b4ca45b5ec
commit
52711921c6
Notes:
sideshowbarker
2024-07-19 05:57:03 +09:00
Author: https://github.com/bugaevc Commit: https://github.com/SerenityOS/serenity/commit/52711921c63 Pull-request: https://github.com/SerenityOS/serenity/pull/2445 Issue: https://github.com/SerenityOS/serenity/issues/91 Reviewed-by: https://github.com/alimpfard
2 changed files with 244 additions and 0 deletions
153
Base/usr/share/man/man3/getopt.md
Normal file
153
Base/usr/share/man/man3/getopt.md
Normal file
|
|
@ -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)
|
||||
91
Base/usr/share/man/man5/getopt.md
Normal file
91
Base/usr/share/man/man5/getopt.md
Normal file
|
|
@ -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)
|
||||
Loading…
Add table
Reference in a new issue