7.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 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

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 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.

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 (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.

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 (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.

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 explicitely 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).