RGBCube/serenity
1
Fork 0
mirror of https://github.com/RGBCube/serenity synced 2025-07-27 02:57:44 +00:00
Code Issues Activity Actions

Base: Document getopt

Browse source
This commit is contained in:
Sergey Bugaev 2020-05-30 14:37:51 +03:00 • committed by Andreas Kling
parent b4ca45b5ec
commit 52711921c6
2 changed files with 244 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

153
Base/usr/share/man/man3/getopt.md Normal file
View 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
View 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)