Next: Changing options, Previous: Checking programs, Up: gpgconf [Contents][Index]
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 argument --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
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.
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.
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.
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.
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.
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.
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 localised 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.
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 (See 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.
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 (See 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.
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).
Next: Changing options, Previous: Checking programs, Up: gpgconf [Contents][Index]