Debian Codegraph @

docs/modules/yaml/pages/struct-ft-obj.adoc

raw
1 = YAML structure field type objects
2
3 A _**structure field type object**_ is the type of structure data
4 fields, found in xref:how-barectf-works:ctf-primer.adoc#ds[data
5 streams].
6
7 A structure data field is a sequence of named data fields, or
8 _members_. In CTF, the names of those members are found in the
9 xref:how-barectf-works:ctf-primer.adoc#trace[metadata stream].
10
11 [[props]]
12 == Properties
13
14 [%autowidth.stretch, cols="d,a,a,d,a"]
15 |===
16 |Name |Type |Description |{req-abbr} |Default
17
18 |[[class-prop]]`class`
19 |String
20 |This property's value must be one of:
21
22 * `structure`
23 * `struct`
24 |Yes if the <<inherit-prop,`$inherit`>> property is not set.
25 |
26
27 include::partial$ft-obj-inherit-prop.adoc[]
28 |
29
30 |[[min-align-prop]]`minimum-alignment`
31 |Power-of-two integer
32 |_Minimum_ alignment of the first bit of this field type's instances
33 within a xref:how-barectf-works:ctf-primer.adoc#pkt[CTF{nbsp}packet]
34 (bits).
35 |No
36 |1
37
38 |[[members-prop]]`members`
39 |Sequence of mappings, where each mapping has a single entry:
40
41 Key::
42 Member's name.
43
44 Value::
45 <<struct-ft-member-obj,Structure field type member object>>
46 or string.
47
48 This sequence is considered to be an _ordered mapping_, similar to
49 YAML's https://yaml.org/type/omap.html[`+!!omap+`] type. Therefore,
50 each mapping key must be unique.
51 |Members of this structure field type.
52
53 If a mapping's value is a string, it must be the name of an existing
54 xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. This
55 field type must _not_ be a structure field type.
56 |No
57 |No members
58 |===
59
60 [[struct-ft-member-obj]]
61 == Structure field type member object
62
63 A member within a structure field type object.
64
65 === Properties
66
67 [%autowidth.stretch, cols="d,d,a,d"]
68 |===
69 |Name |Type |Description |{req-abbr}
70
71 |[[member-ft-prop]]`field-type`
72 |xref:ft-obj.adoc[Field type object] (except a structure field type
73 object) or string
74 |Member's field type.
75
76 If this property's value is a string, it must be the name of an existing
77 xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. This
78 field type must _not_ be a structure field type.
79 |Yes
80 |===
81
82 == Examples
83
84 .Basic structure field type object with no <<members-prop,members>>.
85 ====
86 [source,yaml]
87 ----
88 class: structure
89 ----
90 ====
91
92 .Structure field type object with three <<members-prop,members>> using xref:trace-type-obj.adoc#ft-aliases-prop[field type aliases].
93 ====
94 [source,yaml]
95 ----
96 class: structure
97 members:
98 - msg: string
99 - msg_id: uint32
100 - src_ip_addr: ipv4
101 ----
102 ====
103
104 .Structure field type object with one <<struct-ft-member-obj,member object>>.
105 ====
106 [source,yaml]
107 ----
108 class: structure
109 members:
110 - msg: string
111 - msg_id:
112 field-type:
113 class: unsigned-integer
114 size: 32
115 - src_ip_addr: ipv4
116 ----
117 ====
118
119 .Structure field type object with an explicit <<min-align-prop,minimum alignment>>.
120 ====
121 [source,yaml]
122 ----
123 class: structure
124 minimum-alignment: 64
125 members:
126 - msg: string
127 - msg_id: uint32
128 - src_ip_addr: ipv4
129 ----
130 ====