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

localised

Some fields contain strings that are described to be localised. 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 number 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.