-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathfile.marshal.html
281 lines (193 loc) · 16.7 KB
/
file.marshal.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
<!DOCTYPE html>
<html>
<head>
<meta charset='UTF-8'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, user-scalable=no'>
<meta name='apple-touch-fullscreen' content='yes'>
<meta name='apple-mobile-web-app-capable' content='yes'>
<meta name='apple-mobile-web-app-status-bar-style' content='rgba(228,228,228,1.0)'>
<title>File: Marshal — Ruby-2.6.10</title>
<link rel='stylesheet' type='text/css' href='../css/y_fonts.css' />
<link rel='stylesheet' type='text/css' href='../css/highlight.github.css' />
<link rel='stylesheet' type='text/css' href='../css/y_style.css' />
<link rel='stylesheet' type='text/css' href='../css/y_list.css' />
<link rel='stylesheet' type='text/css' href='../css/y_color.css' />
<script type='text/javascript'>
var pathId = "marshal",
relpath = '';
var t2Info = {
CSEP: '.',
ISEP: '#',
NSEP: '::'
};
</script>
<script type='text/javascript' charset='utf-8' src='../js/highlight.pack.js'></script>
<script type='text/javascript' charset='utf-8' src='../js/y_app.js'></script>
</head>
<body>
<svg id='y_wait' class viewBox='0 0 90 90'></svg>
<div id='settings' class='hidden'></div>
<div id='y_list' class='d h'>
<header id='list_header'></header>
<nav id= 'list_nav' class='y_nav l_nav'>
<ul id='list_items'></ul>
</nav>
</div>
<div id='y_toc' class='f h'>
<header id='toc_header'></header>
<nav id= 'toc_nav' class='y_nav t_nav'>
<ol id='toc_items'></ol>
</nav>
</div>
<div id='y_main' tabindex='-1'>
<header id='y_header'>
<div id='y_menu'>
<a id='home_no_xhr' href='/'>Home</a> »
<a href='.'>Ruby-2.6.10</a> »
<a href='_index.html'>Index</a> »
<span class='title'><a id='t2_doc_top' href='#'>File: Marshal ▲</a></span>
</div>
<a id='list_href' href="file_list.html"></a>
<div id='y_measure_em' class='y_measure'></div>
<div id='y_measure_vh' class='y_measure'></div>
<span id='y_measure_50pre' class='y_measure'><code>123456789_123456789_123456789_123456789_123456789_</code></span>
</header>
<div id='content' class='file'>
<h1 id="label-Marshal+Format">Marshal Format</h1>
<p>The Marshal format is used to serialize ruby objects. The format can store arbitrary objects through three user-defined extension mechanisms.</p>
<p>For documentation on using Marshal to serialize and deserialize objects, see the Marshal module.</p>
<p>This document calls a serialized set of objects a stream. The Ruby implementation can load a set of objects from a String, an IO or an object that implements a <code>getc</code> method.</p>
<h2 id="label-Stream+Format">Stream Format</h2>
<p>The first two bytes of the stream contain the major and minor version, each as a single byte encoding a digit. The version implemented in Ruby is 4.8 (stored as “x04x08”) and is supported by ruby 1.8.0 and newer.</p>
<p>Different major versions of the Marshal format are not compatible and cannot be understood by other major versions. Lesser minor versions of the format can be understood by newer minor versions. Format 4.7 can be loaded by a 4.8 implementation but format 4.8 cannot be loaded by a 4.7 implementation.</p>
<p>Following the version bytes is a stream describing the serialized object. The stream contains nested objects (the same as a Ruby object) but objects in the stream do not necessarily have a direct mapping to the Ruby object model.</p>
<p>Each object in the stream is described by a byte indicating its type followed by one or more bytes describing the object. When “object” is mentioned below it means any of the types below that defines a Ruby object.</p>
<h3 id="label-true-2C+false-2C+nil">true, false, nil</h3>
<p>These objects are each one byte long. “T” is represents <code>true</code>, “F” represents <code>false</code> and “0” represents <code>nil</code>.</p>
<h3 id="label-Fixnum+and+long">Fixnum and long</h3>
<p>“i” represents a signed 32 bit value using a packed format. One through five bytes follows the type. The value loaded will always be a Fixnum. On 32 bit platforms (where the precision of a Fixnum is less than 32 bits) loading large values will cause overflow on CRuby.</p>
<p>The fixnum type is used to represent both ruby Fixnum objects and the sizes of marshaled arrays, hashes, instance variables and other types. In the following sections “long” will mean the format described below, which supports full 32 bit precision.</p>
<p>The first byte has the following special values:</p>
<dl class="rdoc-list note-list"><dt>“x00”
<dd>
<p>The value of the integer is 0. No bytes follow.</p>
</dd><dt>“x01”
<dd>
<p>The total size of the integer is two bytes. The following byte is a positive integer in the range of 0 through 255. Only values between 123 and 255 should be represented this way to save bytes.</p>
</dd><dt>“xff”
<dd>
<p>The total size of the integer is two bytes. The following byte is a negative integer in the range of -1 through -256.</p>
</dd><dt>“x02”
<dd>
<p>The total size of the integer is three bytes. The following two bytes are a positive little-endian integer.</p>
</dd><dt>“xfe”
<dd>
<p>The total size of the integer is three bytes. The following two bytes are a negative little-endian integer.</p>
</dd><dt>“x03”
<dd>
<p>The total size of the integer is four bytes. The following three bytes are a positive little-endian integer.</p>
</dd><dt>“xfd”
<dd>
<p>The total size of the integer is two bytes. The following three bytes are a negative little-endian integer.</p>
</dd><dt>“x04”
<dd>
<p>The total size of the integer is five bytes. The following four bytes are a positive little-endian integer. For compatibility with 32 bit ruby, only Fixnums less than 1073741824 should be represented this way. For sizes of stream objects full precision may be used.</p>
</dd><dt>“xfc”
<dd>
<p>The total size of the integer is two bytes. The following four bytes are a negative little-endian integer. For compatibility with 32 bit ruby, only Fixnums greater than -10737341824 should be represented this way. For sizes of stream objects full precision may be used.</p>
</dd></dl>
<p>Otherwise the first byte is a sign-extended eight-bit value with an offset. If the value is positive the value is determined by subtracting 5 from the value. If the value is negative the value is determined by adding 5 to the value.</p>
<p>There are multiple representations for many values. CRuby always outputs the shortest representation possible.</p>
<h3 id="label-Symbols+and+Byte+Sequence">Symbols and Byte Sequence</h3>
<p>“:” represents a real symbol. A real symbol contains the data needed to define the symbol for the rest of the stream as future occurrences in the stream will instead be references (a symbol link) to this one. The reference is a zero-indexed 32 bit value (so the first occurrence of <code>:hello</code> is 0).</p>
<p>Following the type byte is byte sequence which consists of a long indicating the number of bytes in the sequence followed by that many bytes of data. Byte sequences have no encoding.</p>
<p>For example, the following stream contains the Symbol <code>:hello</code>:</p>
<pre class="code ruby"><code class="ruby"><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>\x04\x08:\x0ahello</span><span class='tstring_end'>"</span></span></code></pre>
<p>“;” represents a Symbol link which references a previously defined Symbol. Following the type byte is a long containing the index in the lookup table for the linked (referenced) Symbol.</p>
<p>For example, the following stream contains <code>[:hello, :hello]</code>:</p>
<pre class="code ruby"><code class="ruby"><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>\x04\b[\a:\nhello;\x00</span><span class='tstring_end'>"</span></span></code></pre>
<p>When a “symbol” is referenced below it may be either a real symbol or a symbol link.</p>
<h3 id="label-Object+References">Object References</h3>
<p>Separate from but similar to symbol references, the stream contains only one copy of each object (as determined by #object_id) for all objects except true, false, nil, Fixnums and Symbols (which are stored separately as described above) a one-indexed 32 bit value will be stored and reused when the object is encountered again. (The first object has an index of 1).</p>
<p>“@” represents an object link. Following the type byte is a long giving the index of the object.</p>
<p>For example, the following stream contains an Array of the same <code>"hello"</code> object twice:</p>
<pre class="code ruby"><code class="ruby"><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>\004\b[\a\"\nhello@\006</span><span class='tstring_end'>"</span></span></code></pre>
<h3 id="label-Instance+Variables">Instance Variables</h3>
<p>“I” indicates that instance variables follow the next object. An object follows the type byte. Following the object is a length indicating the number of instance variables for the object. Following the length is a set of name-value pairs. The names are symbols while the values are objects. The symbols must be instance variable names (<code>:@name</code>).</p>
<p>An Object (“o” type, described below) uses the same format for its instance variables as described here.</p>
<p>For a String and Regexp (described below) a special instance variable <code>:E</code> is used to indicate the Encoding.</p>
<h3 id="label-Extended">Extended</h3>
<p>“e” indicates that the next object is extended by a module. An object follows the type byte. Following the object is a symbol that contains the name of the module the object is extended by.</p>
<h3 id="label-Array">Array</h3>
<p>“[” represents an Array. Following the type byte is a long indicating the number of objects in the array. The given number of objects follow the length.</p>
<h3 id="label-Bignum">Bignum</h3>
<p>“l” represents a Bignum which is composed of three parts:</p>
<dl class="rdoc-list note-list"><dt>sign
<dd>
<p>A single byte containing “+” for a positive value or “-” for a negative value.</p>
</dd><dt>length
<dd>
<p>A long indicating the number of bytes of Bignum data follows, divided by two. Multiply the length by two to determine the number of bytes of data that follow.</p>
</dd><dt>data
<dd>
<p>Bytes of Bignum data representing the number.</p>
</dd></dl>
<p>The following ruby code will reconstruct the Bignum value from an array of bytes:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='int'>0</span>
<span class='id identifier rubyid_bytes'>bytes</span>.<span class='id identifier rubyid_each_with_index'>each_with_index</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_byte'>byte</span><span class='comma'>,</span> <span class='id identifier rubyid_exp'>exp</span><span class='op'>|</span>
<span class='id identifier rubyid_result'>result</span> <span class='op'>+=</span> (<span class='id identifier rubyid_byte'>byte</span> <span class='op'>*</span> <span class='int'>2</span> <span class='op'>**</span> (<span class='id identifier rubyid_exp'>exp</span> <span class='op'>*</span> <span class='int'>8</span>))
<span class='kw'>end</span></code></pre>
<h3 id="label-Class+and+Module">Class and Module</h3>
<p>“c” represents a Class object, “m” represents a Module and “M” represents either a class or module (this is an old-style for compatibility). No class or module content is included, this type is only a reference. Following the type byte is a byte sequence which is used to look up an existing class or module, respectively.</p>
<p>Instance variables are not allowed on a class or module.</p>
<p>If no class or module exists an exception should be raised.</p>
<p>For “c” and “m” types, the loaded object must be a class or module, respectively.</p>
<h3 id="label-Data">Data</h3>
<p>“d” represents a Data object. (Data objects are wrapped pointers from ruby extensions.) Following the type byte is a symbol indicating the class for the Data object and an object that contains the state of the Data object.</p>
<p>To dump a Data object Ruby calls _dump_data. To load a Data object Ruby calls _load_data with the state of the object on a newly allocated instance.</p>
<h3 id="label-Float">Float</h3>
<p>“f” represents a Float object. Following the type byte is a byte sequence containing the float value. The following values are special:</p>
<dl class="rdoc-list note-list"><dt>“inf”
<dd>
<p>Positive infinity</p>
</dd><dt>“-inf”
<dd>
<p>Negative infinity</p>
</dd><dt>“nan”
<dd>
<p>Not a Number</p>
</dd></dl>
<p>Otherwise the byte sequence contains a C double (loadable by strtod(3)). Older minor versions of Marshal also stored extra mantissa bits to ensure portability across platforms but 4.8 does not include these. See</p>
<dl class="rdoc-list label-list"><dt>ruby-talk:69518
<dd>
<p>for some explanation.</p>
</dd></dl>
<h3 id="label-Hash+and+Hash+with+Default+Value">Hash and Hash with Default Value</h3>
<p>“<code>represents a Hash object while “</code>” represents a Hash with a default value set (<code>Hash.new 0</code>). Following the type byte is a long indicating the number of key-value pairs in the Hash, the size. Double the given number of objects follow the size.</p>
<p>For a Hash with a default value, the default value follows all the pairs.</p>
<h3 id="label-Module+and+Old+Module">Module and Old Module</h3>
<h3 id="label-Object">Object</h3>
<p>“o” represents an object that doesn’t have any other special form (such as a user-defined or built-in format). Following the type byte is a symbol containing the class name of the object. Following the class name is a long indicating the number of instance variable names and values for the object. Double the given number of pairs of objects follow the size.</p>
<p>The keys in the pairs must be symbols containing instance variable names.</p>
<h3 id="label-Regular+Expression">Regular Expression</h3>
<p>“/” represents a regular expression. Following the type byte is a byte sequence containing the regular expression source. Following the type byte is a byte containing the regular expression options (case-insensitive, etc.) as a signed 8-bit value.</p>
<p>Regular expressions can have an encoding attached through instance variables (see above). If no encoding is attached escapes for the following regexp specials not present in ruby 1.8 must be removed: g-m, o-q, u, y, E, F, H-L, N-V, X, Y.</p>
<h3 id="label-String">String</h3>
<p>‘“’ represents a String. Following the type byte is a byte sequence containing the string content. When dumped from ruby 1.9 an encoding instance variable (<code>:E</code> see above) should be included unless the encoding is binary.</p>
<h3 id="label-Struct">Struct</h3>
<p>“S” represents a Struct. Following the type byte is a symbol containing the name of the struct. Following the name is a long indicating the number of members in the struct. Double the number of objects follow the member count. Each member is a pair containing the member’s symbol and an object for the value of that member.</p>
<p>If the struct name does not match a Struct subclass in the running ruby an exception should be raised.</p>
<p>If there is a mismatch between the struct in the currently running ruby and the member count in the marshaled struct an exception should be raised.</p>
<h3 id="label-User+Class">User Class</h3>
<p>“C” represents a subclass of a String, Regexp, Array or Hash. Following the type byte is a symbol containing the name of the subclass. Following the name is the wrapped object.</p>
<h3 id="label-User+Defined">User Defined</h3>
<p>“u” represents an object with a user-defined serialization format using the <code>_dump</code> instance method and <code>_load</code> class method. Following the type byte is a symbol containing the class name. Following the class name is a byte sequence containing the user-defined representation of the object.</p>
<p>The class method <code>_load</code> is called on the class with a string created from the byte-sequence.</p>
<h3 id="label-User+Marshal">User Marshal</h3>
<p>“U” represents an object with a user-defined serialization format using the <code>marshal_dump</code> and <code>marshal_load</code> instance methods. Following the type byte is a symbol containing the class name. Following the class name is an object containing the data.</p>
<p>Upon loading a new instance must be allocated and <code>marshal_load</code> must be called on the instance with the data.</p>
<div id='footer'></div>
</div> <!-- content -->
</div> <!-- y_main -->
</body>
</html>