File: gnupg.info, Node: Format conventions, Next: Listing components, Prev: gpgconf.php">Invoking gpgconf, Up: gpgconf 10.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.