Format conventions - Using the GNU Privacy Guard
Description: Using the GNU Privacy Guard

Next: Listing components, Previous: Invoking gpgconf, Up: gpgconf

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