gnupg: Listing options
9.4.5 Listing options
---------------------
Every component contains one or more options. Options may be gathered
into option groups to allow the GUI to give visual hints to the user
about which options are related.
The command '--list-options COMPONENT' lists all options (and the
groups they belong to) in the component COMPONENT, one per line.
COMPONENT must be the string in the field NAME in the output of the
'--list-components' command.
There is one line for each option and each group. First come all
options that are not in any group. Then comes a line describing a
group. Then come all options that belong into each group. Then comes
the next group and so on. There does not need to be any group (and in
this case the output will stop after the last non-grouped option).
The format of each line is:
'NAME:FLAGS:LEVEL:DESCRIPTION:TYPE:ALT-TYPE:ARGNAME:DEFAULT:ARGDEF:VALUE'
NAME
This field contains a name tag for the group or option. The name
tag is used to specify the group or option in all communication
with 'gpgconf'. The name tag is to be used _verbatim_. It is thus
not in any escaped format.
FLAGS
The flags field contains an _unsigned number_. Its value is the
OR-wise combination of the following flag values:
'group (1)'
If this flag is set, this is a line describing a group and not
an option.
The following flag values are only defined for options (that is, if
the 'group' flag is not used).
'optional arg (2)'
If this flag is set, the argument is optional. This is never
set for TYPE '0' (none) options.
'list (4)'
If this flag is set, the option can be given multiple times.
'runtime (8)'
If this flag is set, the option can be changed at runtime.
'default (16)'
If this flag is set, a default value is available.
'default desc (32)'
If this flag is set, a (runtime) default is available. This
and the 'default' flag are mutually exclusive.
'no arg desc (64)'
If this flag is set, and the 'optional arg' flag is set, then
the option has a special meaning if no argument is given.
'no change (128)'
If this flag is set, 'gpgconf' ignores requests to change the
value. GUI frontends should grey out this option. Note, that
manual changes of the configuration files are still possible.
LEVEL
This field is defined for options and for groups. It contains an
_unsigned number_ that specifies the expert level under which this
group or option should be displayed. The following expert levels
are defined for options (they have analogous meaning for groups):
'basic (0)'
This option should always be offered to the user.
'advanced (1)'
This option may be offered to advanced users.
'expert (2)'
This option should only be offered to expert users.
'invisible (3)'
This option should normally never be displayed, not even to
expert users.
'internal (4)'
This option is for internal use only. Ignore it.
The level of a group will always be the lowest level of all options
it contains.
DESCRIPTION
This field is defined for options and groups. The _string_ in this
field contains a human-readable description of the option or group.
It can be displayed to the user of the GUI for informational
purposes. It is _percent-escaped_ and _localized_.
TYPE
This field is only defined for options. It contains an _unsigned
number_ that specifies the type of the option's argument, if any.
The following types are defined:
Basic types:
'none (0)'
No argument allowed.
'string (1)'
An _unformatted string_.
'int32 (2)'
A _signed number_.
'uint32 (3)'
An _unsigned number_.
Complex types:
'pathname (32)'
A _string_ that describes the pathname of a file. The file
does not necessarily need to exist.
'ldap server (33)'
A _string_ that describes an LDAP server in the format:
'HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN'
'key fingerprint (34)'
A _string_ with a 40 digit fingerprint specifying a
certificate.
'pub key (35)'
A _string_ that describes a certificate by user ID, key ID or
fingerprint.
'sec key (36)'
A _string_ that describes a certificate with a key by user ID,
key ID or fingerprint.
'alias list (37)'
A _string_ that describes an alias list, like the one used
with gpg's group option. The list consists of a key, an equal
sign and space separated values.
More types will be added in the future. Please see the ALT-TYPE
field for information on how to cope with unknown types.
ALT-TYPE
This field is identical to TYPE, except that only the types '0' to
'31' are allowed. The GUI is expected to present the user the
option in the format specified by TYPE. But if the argument type
TYPE is not supported by the GUI, it can still display the option
in the more generic basic type ALT-TYPE. The GUI must support all
the defined basic types to be able to display all options. More
basic types may be added in future versions. If the GUI encounters
a basic type it doesn't support, it should report an error and
abort the operation.
ARGNAME
This field is only defined for options with an argument type TYPE
that is not '0'. In this case it may contain a _percent-escaped_
and _localized string_ that gives a short name for the argument.
The field may also be empty, though, in which case a short name is
not known.
DEFAULT
This field is defined only for options for which the 'default' or
'default desc' flag is set. If the 'default' flag is set, its
format is that of an _option argument_ (⇒Format conventions,
for details). If the default value is empty, then no default is
known. Otherwise, the value specifies the default value for this
option. If the 'default desc' flag is set, the field is either
empty or contains a description of the effect if the option is not
given.
ARGDEF
This field is defined only for options for which the 'optional arg'
flag is set. If the 'no arg desc' flag is not set, its format is
that of an _option argument_ (⇒Format conventions, for
details). If the default value is empty, then no default is known.
Otherwise, the value specifies the default argument for this
option. If the 'no arg desc' flag is set, the field is either
empty or contains a description of the effect of this option if no
argument is given.
VALUE
This field is defined only for options. Its format is that of an
_option argument_. If it is empty, then the option is not
explicitly set in the current configuration, and the default
applies (if any). Otherwise, it contains the current value of the
option. Note that this field is also meaningful if the option
itself does not take a real argument (in this case, it contains the
number of times the option appears).
Info Catalog
gnupg: Checking programs
gnupg: gpgconf
gnupg: Changing options