File: gnupg.info,  Node: Listing options,  Next: Changing options,  Prev: Checking programs,  Up: gpgconf

10.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_ (*note 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_ (*note 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).