gnupg: Format conventions
9.4.2 Format conventions
------------------------
Some lines in the output of 'gpgconf' contain a list of colon-separated
fields. The following conventions apply:
* The GUI program is required to strip off trailing newline and/or
carriage return characters from the output.
* 'gpgconf' will never leave out fields. If a certain version
provides a certain field, this field will always be present in all
'gpgconf' versions from that time on.
* Future versions of 'gpgconf' might append fields to the list. New
fields will always be separated from the previously last field by a
colon separator. The GUI should be prepared to parse the last
field it knows about up until a colon or end of line.
* Not all fields are defined under all conditions. You are required
to ignore the content of undefined fields.
There are several standard types for the content of a field:
verbatim
Some fields contain strings that are not escaped in any way. Such
fields are described to be used _verbatim_. These fields will
never contain a colon character (for obvious reasons). No
de-escaping or other formatting is required to use the field
content. This is for easy parsing of the output, when it is known
that the content can never contain any special characters.
percent-escaped
Some fields contain strings that are described to be
_percent-escaped_. Such strings need to be de-escaped before their
content can be presented to the user. A percent-escaped string is
de-escaped by replacing all occurrences of '%XY' by the byte that
has the hexadecimal value 'XY'. 'X' and 'Y' are from the set
'0-9a-f'.
localized
Some fields contain strings that are described to be _localized_.
Such strings are translated to the active language and formatted in
the active character set.
unsigned number
Some fields contain an _unsigned number_. This number will always
fit into a 32-bit unsigned integer variable. The number may be
followed by a space, followed by a human readable description of
that value (if the verbose option is used). You should ignore
everything in the field that follows the number.
signed number
Some fields contain a _signed number_. This number will always fit
into a 32-bit signed integer variable. The number may be followed
by a space, followed by a human readable description of that value
(if the verbose option is used). You should ignore everything in
the field that follows the number.
boolean value
Some fields contain a _boolean value_. This is a number with
either the value 0 or 1. The number may be followed by a space,
followed by a human readable description of that value (if the
verbose option is used). You should ignore everything in the field
that follows the number; checking just the first character is
sufficient in this case.
option
Some fields contain an _option_ argument. The format of an option
argument depends on the type of the option and on some flags:
no argument
The simplest case is that the option does not take an argument
at all (TYPE '0'). Then the option argument is an unsigned
number that specifies how often the option occurs. If the
'list' flag is not set, then the only valid number is '1'.
Options that do not take an argument never have the 'default'
or 'optional arg' flag set.
number
If the option takes a number argument (ALT-TYPE is '2' or
'3'), and it can only occur once ('list' flag is not set),
then the option argument is either empty (only allowed if the
argument is optional), or it is a number. A number is a
string that begins with an optional minus character, followed
by one or more digits. The number must fit into an integer
variable (unsigned or signed, depending on ALT-TYPE).
number list
If the option takes a number argument and it can occur more
than once, then the option argument is either empty, or it is
a comma-separated list of numbers as described above.
string
If the option takes a string argument (ALT-TYPE is 1), and it
can only occur once ('list' flag is not set) then the option
argument is either empty (only allowed if the argument is
optional), or it starts with a double quote character ('"')
followed by a percent-escaped string that is the argument
value. Note that there is only a leading double quote
character, no trailing one. The double quote character is
only needed to be able to differentiate between no value and
the empty string as value.
string list
If the option takes a string argument and it can occur more
than once, then the option argument is either empty, or it is
a comma-separated list of string arguments as described above.
The active language and character set are currently determined from
the locale environment of the 'gpgconf' program.
Info Catalog
gnupg: Invoking gpgconf
gnupg: gpgconf
gnupg: Listing components