File: Stdlib.Marshal.html

package info (click to toggle)
ocaml-doc 4.11-2
  • links: PTS, VCS
  • area: non-free
  • in suites: bookworm, bullseye, forky, sid, trixie
  • size: 20,580 kB
  • sloc: sh: 37; makefile: 11
file content (296 lines) | stat: -rw-r--r-- 18,556 bytes parent folder | download
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
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="Start" href="index.html">
<link rel="previous" href="Stdlib.Map.html">
<link rel="next" href="Stdlib.MoreLabels.html">
<link rel="Up" href="Stdlib.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of extensions" rel=Appendix href="index_extensions.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Arg" rel="Chapter" href="Arg.html">
<link title="Array" rel="Chapter" href="Array.html">
<link title="ArrayLabels" rel="Chapter" href="ArrayLabels.html">
<link title="Bigarray" rel="Chapter" href="Bigarray.html">
<link title="Bool" rel="Chapter" href="Bool.html">
<link title="Buffer" rel="Chapter" href="Buffer.html">
<link title="Bytes" rel="Chapter" href="Bytes.html">
<link title="BytesLabels" rel="Chapter" href="BytesLabels.html">
<link title="Callback" rel="Chapter" href="Callback.html">
<link title="CamlinternalFormat" rel="Chapter" href="CamlinternalFormat.html">
<link title="CamlinternalFormatBasics" rel="Chapter" href="CamlinternalFormatBasics.html">
<link title="CamlinternalLazy" rel="Chapter" href="CamlinternalLazy.html">
<link title="CamlinternalMod" rel="Chapter" href="CamlinternalMod.html">
<link title="CamlinternalOO" rel="Chapter" href="CamlinternalOO.html">
<link title="Char" rel="Chapter" href="Char.html">
<link title="Complex" rel="Chapter" href="Complex.html">
<link title="Condition" rel="Chapter" href="Condition.html">
<link title="Digest" rel="Chapter" href="Digest.html">
<link title="Dynlink" rel="Chapter" href="Dynlink.html">
<link title="Ephemeron" rel="Chapter" href="Ephemeron.html">
<link title="Event" rel="Chapter" href="Event.html">
<link title="Filename" rel="Chapter" href="Filename.html">
<link title="Float" rel="Chapter" href="Float.html">
<link title="Format" rel="Chapter" href="Format.html">
<link title="Fun" rel="Chapter" href="Fun.html">
<link title="Gc" rel="Chapter" href="Gc.html">
<link title="Genlex" rel="Chapter" href="Genlex.html">
<link title="Hashtbl" rel="Chapter" href="Hashtbl.html">
<link title="Int" rel="Chapter" href="Int.html">
<link title="Int32" rel="Chapter" href="Int32.html">
<link title="Int64" rel="Chapter" href="Int64.html">
<link title="Lazy" rel="Chapter" href="Lazy.html">
<link title="Lexing" rel="Chapter" href="Lexing.html">
<link title="List" rel="Chapter" href="List.html">
<link title="ListLabels" rel="Chapter" href="ListLabels.html">
<link title="Map" rel="Chapter" href="Map.html">
<link title="Marshal" rel="Chapter" href="Marshal.html">
<link title="MoreLabels" rel="Chapter" href="MoreLabels.html">
<link title="Mutex" rel="Chapter" href="Mutex.html">
<link title="Nativeint" rel="Chapter" href="Nativeint.html">
<link title="Obj" rel="Chapter" href="Obj.html">
<link title="Ocaml_operators" rel="Chapter" href="Ocaml_operators.html">
<link title="Oo" rel="Chapter" href="Oo.html">
<link title="Option" rel="Chapter" href="Option.html">
<link title="Parsing" rel="Chapter" href="Parsing.html">
<link title="Printexc" rel="Chapter" href="Printexc.html">
<link title="Printf" rel="Chapter" href="Printf.html">
<link title="Queue" rel="Chapter" href="Queue.html">
<link title="Random" rel="Chapter" href="Random.html">
<link title="Result" rel="Chapter" href="Result.html">
<link title="Scanf" rel="Chapter" href="Scanf.html">
<link title="Seq" rel="Chapter" href="Seq.html">
<link title="Set" rel="Chapter" href="Set.html">
<link title="Spacetime" rel="Chapter" href="Spacetime.html">
<link title="Stack" rel="Chapter" href="Stack.html">
<link title="StdLabels" rel="Chapter" href="StdLabels.html">
<link title="Stdlib" rel="Chapter" href="Stdlib.html">
<link title="Str" rel="Chapter" href="Str.html">
<link title="Stream" rel="Chapter" href="Stream.html">
<link title="String" rel="Chapter" href="String.html">
<link title="StringLabels" rel="Chapter" href="StringLabels.html">
<link title="Sys" rel="Chapter" href="Sys.html">
<link title="Thread" rel="Chapter" href="Thread.html">
<link title="ThreadUnix" rel="Chapter" href="ThreadUnix.html">
<link title="Uchar" rel="Chapter" href="Uchar.html">
<link title="Unit" rel="Chapter" href="Unit.html">
<link title="Unix" rel="Chapter" href="Unix.html">
<link title="UnixLabels" rel="Chapter" href="UnixLabels.html">
<link title="Weak" rel="Chapter" href="Weak.html"><title>Stdlib.Marshal</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Stdlib.Map.html" title="Stdlib.Map">Previous</a>
&nbsp;<a class="up" href="Stdlib.html" title="Stdlib">Up</a>
&nbsp;<a class="post" href="Stdlib.MoreLabels.html" title="Stdlib.MoreLabels">Next</a>
</div>
<h1>Module <a href="type_Stdlib.Marshal.html">Stdlib.Marshal</a></h1>

<pre><span id="MODULEMarshal"><span class="keyword">module</span> Marshal</span>: <code class="type"><a href="Marshal.html">Marshal</a></code></pre><hr width="100%">

<pre><code><span id="TYPEextern_flags"><span class="keyword">type</span> <code class="type"></code>extern_flags</span> = </code></pre><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTextern_flags.No_sharing"><span class="constructor">No_sharing</span></span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><div class="info ">
<div class="info-desc">
<p>Don't preserve sharing</p>
</div>
</div>
</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTextern_flags.Closures"><span class="constructor">Closures</span></span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><div class="info ">
<div class="info-desc">
<p>Send function closures</p>
</div>
</div>
</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTextern_flags.Compat_32"><span class="constructor">Compat_32</span></span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><div class="info ">
<div class="info-desc">
<p>Ensure 32-bit compatibility</p>
</div>
</div>
</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>

<div class="info ">
<div class="info-desc">
<p>The flags to the <code class="code"><span class="constructor">Marshal</span>.to_*</code> functions below.</p>
</div>
</div>


<pre><span id="VALto_channel"><span class="keyword">val</span> to_channel</span> : <code class="type"><a href="Stdlib.html#TYPEout_channel">out_channel</a> -> 'a -> <a href="Marshal.html#TYPEextern_flags">extern_flags</a> list -> unit</code></pre><div class="info ">
<div class="info-desc">
<p><code class="code"><span class="constructor">Marshal</span>.to_channel&nbsp;chan&nbsp;v&nbsp;flags</code> writes the representation
   of <code class="code">v</code> on channel <code class="code">chan</code>. The <code class="code">flags</code> argument is a
   possibly empty list of flags that governs the marshaling
   behavior with respect to sharing, functional values, and compatibility
   between 32- and 64-bit platforms.</p>

<p>If <code class="code">flags</code> does not contain <code class="code"><span class="constructor">Marshal</span>.<span class="constructor">No_sharing</span></code>, circularities
   and sharing inside the value <code class="code">v</code> are detected and preserved
   in the sequence of bytes produced. In particular, this
   guarantees that marshaling always terminates. Sharing
   between values marshaled by successive calls to
   <code class="code"><span class="constructor">Marshal</span>.to_channel</code> is neither detected nor preserved, though.
   If <code class="code">flags</code> contains <code class="code"><span class="constructor">Marshal</span>.<span class="constructor">No_sharing</span></code>, sharing is ignored.
   This results in faster marshaling if <code class="code">v</code> contains no shared
   substructures, but may cause slower marshaling and larger
   byte representations if <code class="code">v</code> actually contains sharing,
   or even non-termination if <code class="code">v</code> contains cycles.</p>

<p>If <code class="code">flags</code> does not contain <code class="code"><span class="constructor">Marshal</span>.<span class="constructor">Closures</span></code>, marshaling fails
   when it encounters a functional value inside <code class="code">v</code>: only 'pure' data
   structures, containing neither functions nor objects, can safely be
   transmitted between different programs. If <code class="code">flags</code> contains
   <code class="code"><span class="constructor">Marshal</span>.<span class="constructor">Closures</span></code>, functional values will be marshaled as a the
   position in the code of the program together with the values
   corresponding to the free variables captured in the closure.  In
   this case, the output of marshaling can only be read back in
   processes that run exactly the same program, with exactly the same
   compiled code. (This is checked at un-marshaling time, using an MD5
   digest of the code transmitted along with the code position.)</p>

<p>The exact definition of which free variables are captured in a
   closure is not specified and can vary between bytecode and native
   code (and according to optimization flags).  In particular, a
   function value accessing a global reference may or may not include
   the reference in its closure.  If it does, unmarshaling the
   corresponding closure will create a new reference, different from
   the global one.</p>

<p>If <code class="code">flags</code> contains <code class="code"><span class="constructor">Marshal</span>.<span class="constructor">Compat_32</span></code>, marshaling fails when
   it encounters an integer value outside the range <code class="code">[-2{^30},&nbsp;2{^30}-1]</code>
   of integers that are representable on a 32-bit platform.  This
   ensures that marshaled data generated on a 64-bit platform can be
   safely read back on a 32-bit platform.  If <code class="code">flags</code> does not
   contain <code class="code"><span class="constructor">Marshal</span>.<span class="constructor">Compat_32</span></code>, integer values outside the
   range <code class="code">[-2{^30},&nbsp;2{^30}-1]</code> are marshaled, and can be read back on
   a 64-bit platform, but will cause an error at un-marshaling time
   when read back on a 32-bit platform.  The <code class="code"><span class="constructor">Mashal</span>.<span class="constructor">Compat_32</span></code> flag
   only matters when marshaling is performed on a 64-bit platform;
   it has no effect if marshaling is performed on a 32-bit platform.</p>
</div>
</div>

<pre><span id="VALto_bytes"><span class="keyword">val</span> to_bytes</span> : <code class="type">'a -> <a href="Marshal.html#TYPEextern_flags">extern_flags</a> list -> bytes</code></pre><div class="info ">
<div class="info-desc">
<p><code class="code"><span class="constructor">Marshal</span>.to_bytes&nbsp;v&nbsp;flags</code> returns a byte sequence containing
   the representation of <code class="code">v</code>.
   The <code class="code">flags</code> argument has the same meaning as for
   <a href="Marshal.html#VALto_channel"><code class="code"><span class="constructor">Marshal</span>.to_channel</code></a>.</p>
</div>
<ul class="info-attributes">
<li><b>Since</b> 4.02.0</li>
</ul>
</div>

<pre><span id="VALto_string"><span class="keyword">val</span> to_string</span> : <code class="type">'a -> <a href="Marshal.html#TYPEextern_flags">extern_flags</a> list -> string</code></pre><div class="info ">
<div class="info-desc">
<p>Same as <code class="code">to_bytes</code> but return the result as a string instead of
    a byte sequence.</p>
</div>
</div>

<pre><span id="VALto_buffer"><span class="keyword">val</span> to_buffer</span> : <code class="type">bytes -> int -> int -> 'a -> <a href="Marshal.html#TYPEextern_flags">extern_flags</a> list -> int</code></pre><div class="info ">
<div class="info-desc">
<p><code class="code"><span class="constructor">Marshal</span>.to_buffer&nbsp;buff&nbsp;ofs&nbsp;len&nbsp;v&nbsp;flags</code> marshals the value <code class="code">v</code>,
   storing its byte representation in the sequence <code class="code">buff</code>,
   starting at index <code class="code">ofs</code>, and writing at most
   <code class="code">len</code> bytes.  It returns the number of bytes
   actually written to the sequence. If the byte representation
   of <code class="code">v</code> does not fit in <code class="code">len</code> characters, the exception <code class="code"><span class="constructor">Failure</span></code>
   is raised.</p>
</div>
</div>

<pre><span id="VALfrom_channel"><span class="keyword">val</span> from_channel</span> : <code class="type"><a href="Stdlib.html#TYPEin_channel">in_channel</a> -> 'a</code></pre><div class="info ">
<div class="info-desc">
<p><code class="code"><span class="constructor">Marshal</span>.from_channel&nbsp;chan</code> reads from channel <code class="code">chan</code> the
   byte representation of a structured value, as produced by
   one of the <code class="code"><span class="constructor">Marshal</span>.to_*</code> functions, and reconstructs and
   returns the corresponding value.</p>

<p>It raises <code class="code"><span class="constructor">End_of_file</span></code> if the function has already reached the
   end of file when starting to read from the channel, and raises
   <code class="code"><span class="constructor">Failure</span>&nbsp;<span class="string">"input_value:&nbsp;truncated&nbsp;object"</span></code> if it reaches the end
   of file later during the unmarshalling.</p>
</div>
</div>

<pre><span id="VALfrom_bytes"><span class="keyword">val</span> from_bytes</span> : <code class="type">bytes -> int -> 'a</code></pre><div class="info ">
<div class="info-desc">
<p><code class="code"><span class="constructor">Marshal</span>.from_bytes&nbsp;buff&nbsp;ofs</code> unmarshals a structured value
   like <a href="Marshal.html#VALfrom_channel"><code class="code"><span class="constructor">Marshal</span>.from_channel</code></a> does, except that the byte
   representation is not read from a channel, but taken from
   the byte sequence <code class="code">buff</code>, starting at position <code class="code">ofs</code>.
   The byte sequence is not mutated.</p>
</div>
<ul class="info-attributes">
<li><b>Since</b> 4.02.0</li>
</ul>
</div>

<pre><span id="VALfrom_string"><span class="keyword">val</span> from_string</span> : <code class="type">string -> int -> 'a</code></pre><div class="info ">
<div class="info-desc">
<p>Same as <code class="code">from_bytes</code> but take a string as argument instead of a
    byte sequence.</p>
</div>
</div>

<pre><span id="VALheader_size"><span class="keyword">val</span> header_size</span> : <code class="type">int</code></pre><div class="info ">
<div class="info-desc">
<p>The bytes representing a marshaled value are composed of
   a fixed-size header and a variable-sized data part,
   whose size can be determined from the header.
   <a href="Marshal.html#VALheader_size"><code class="code"><span class="constructor">Marshal</span>.header_size</code></a> is the size, in bytes, of the header.
   <a href="Marshal.html#VALdata_size"><code class="code"><span class="constructor">Marshal</span>.data_size</code></a><code class="code">&nbsp;buff&nbsp;ofs</code> is the size, in bytes,
   of the data part, assuming a valid header is stored in
   <code class="code">buff</code> starting at position <code class="code">ofs</code>.
   Finally, <a href="Marshal.html#VALtotal_size"><code class="code"><span class="constructor">Marshal</span>.total_size</code></a> <code class="code">buff&nbsp;ofs</code> is the total size,
   in bytes, of the marshaled value.
   Both <a href="Marshal.html#VALdata_size"><code class="code"><span class="constructor">Marshal</span>.data_size</code></a> and <a href="Marshal.html#VALtotal_size"><code class="code"><span class="constructor">Marshal</span>.total_size</code></a> raise <code class="code"><span class="constructor">Failure</span></code>
   if <code class="code">buff</code>, <code class="code">ofs</code> does not contain a valid header.</p>

<p>To read the byte representation of a marshaled value into
   a byte sequence, the program needs to read first
   <a href="Marshal.html#VALheader_size"><code class="code"><span class="constructor">Marshal</span>.header_size</code></a> bytes into the sequence,
   then determine the length of the remainder of the
   representation using <a href="Marshal.html#VALdata_size"><code class="code"><span class="constructor">Marshal</span>.data_size</code></a>,
   make sure the sequence is large enough to hold the remaining
   data, then read it, and finally call <a href="Marshal.html#VALfrom_bytes"><code class="code"><span class="constructor">Marshal</span>.from_bytes</code></a>
   to unmarshal the value.</p>
</div>
</div>

<pre><span id="VALdata_size"><span class="keyword">val</span> data_size</span> : <code class="type">bytes -> int -> int</code></pre><div class="info ">
<div class="info-desc">
<p>See <a href="Marshal.html#VALheader_size"><code class="code"><span class="constructor">Marshal</span>.header_size</code></a>.</p>
</div>
</div>

<pre><span id="VALtotal_size"><span class="keyword">val</span> total_size</span> : <code class="type">bytes -> int -> int</code></pre><div class="info ">
<div class="info-desc">
<p>See <a href="Marshal.html#VALheader_size"><code class="code"><span class="constructor">Marshal</span>.header_size</code></a>.</p>
</div>
</div>
</body></html>