JSON output
Supported types:
any: a valid printf format, parameters to fmt_print() must match the number (and are not validated)
number:
%llustring:
%sstring:
str- backslash escaped special characters (0x08, 0x08, 0x0a, 0x0c, 0x0d, 0x0b), the rest of range from 0x00 to 0x1f as \uXXXX encodingbool:
bool- unquoted native json values true or falseqgroupid:
qgroupid- split to 48/16 for level/subvolidsize:
size- size with SI/IEC size suffixsize:
size-or-none- same as size but for 0 it’s noneUUID:
uuid- if all zeros then null (native json), or properly formatted UUID stringdate + time:
date-time- timestamp formatted as YYYY-MM-DD HH:MM:SS TIMEZONEduration:
duration- difference of two timestamps, like D days HH:MM:SS (days not show of 0)
Commands that support json output
btrfs device stats
btrfs filesystem df
btrfs qgroup show
btrfs subvolume get-default
btrfs subvolume list
btrfs subvolume show
Recommendations
Keys and formatting are defined as an array of struct rowspec.
- key names
should be unified with the printed value if they mean the same thing
not abbreviated (e.g. generation instead of gen)
referring to existing and well known names (qgroupid, devid, …)
using
-as word separator, or_if it’s better to keep the same name of the value
- values
numbers without suffix or other transformation, i.e. no KiB
formatted by the types if possible
any printf format is possible but should be avoided or a new type should be defined
printing more data about an item is better than printing less, assuming the filtering is done on the user side
structure of json output may not reflect the way it’s printed in plain text, in that case do two separate printer functions
if plain and json output roughly follow the same style, e.g. line oriented that is easy to transform to a map, then both outputs should use the same rowspec
one value can be printed by multiple rowspecs that may do different formatting depending on the context