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
|
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="Start" href="index.html">
<link rel="previous" href="Map.html">
<link rel="next" href="MoreLabels.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.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="Arith_status" rel="Chapter" href="Arith_status.html">
<link title="Array" rel="Chapter" href="Array.html">
<link title="ArrayLabels" rel="Chapter" href="ArrayLabels.html">
<link title="Big_int" rel="Chapter" href="Big_int.html">
<link title="Bigarray" rel="Chapter" href="Bigarray.html">
<link title="Buffer" rel="Chapter" href="Buffer.html">
<link title="Callback" rel="Chapter" href="Callback.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="Dbm" rel="Chapter" href="Dbm.html">
<link title="Digest" rel="Chapter" href="Digest.html">
<link title="Dynlink" rel="Chapter" href="Dynlink.html">
<link title="Event" rel="Chapter" href="Event.html">
<link title="Filename" rel="Chapter" href="Filename.html">
<link title="Format" rel="Chapter" href="Format.html">
<link title="Gc" rel="Chapter" href="Gc.html">
<link title="Genlex" rel="Chapter" href="Genlex.html">
<link title="Graphics" rel="Chapter" href="Graphics.html">
<link title="GraphicsX11" rel="Chapter" href="GraphicsX11.html">
<link title="Hashtbl" rel="Chapter" href="Hashtbl.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="Num" rel="Chapter" href="Num.html">
<link title="Obj" rel="Chapter" href="Obj.html">
<link title="Oo" rel="Chapter" href="Oo.html">
<link title="Parsing" rel="Chapter" href="Parsing.html">
<link title="Pervasives" rel="Chapter" href="Pervasives.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="Scanf" rel="Chapter" href="Scanf.html">
<link title="Set" rel="Chapter" href="Set.html">
<link title="Sort" rel="Chapter" href="Sort.html">
<link title="Stack" rel="Chapter" href="Stack.html">
<link title="StdLabels" rel="Chapter" href="StdLabels.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="Unix" rel="Chapter" href="Unix.html">
<link title="UnixLabels" rel="Chapter" href="UnixLabels.html">
<link title="Weak" rel="Chapter" href="Weak.html"><title>Marshal</title>
</head>
<body>
<div class="navbar"><a href="Map.html">Previous</a>
<a href="index.html">Up</a>
<a href="MoreLabels.html">Next</a>
</div>
<center><h1>Module <a href="type_Marshal.html">Marshal</a></h1></center>
<br>
<pre><span class="keyword">module</span> Marshal: <code class="code"><span class="keyword">sig</span></code> <a href="Marshal.html">..</a> <code class="code"><span class="keyword">end</span></code></pre>Marshaling of data structures.
<p>
This module provides functions to encode arbitrary data structures
as sequences of bytes, which can then be written on a file or
sent over a pipe or network connection. The bytes can then
be read back later, possibly in another process, and decoded back
into a data structure. The format for the byte sequences
is compatible across all machines for a given version of Objective Caml.
<p>
Warning: marshaling is currently not type-safe. The type
of marshaled data is not transmitted along the value of the data,
making it impossible to check that the data read back possesses the
type expected by the context. In particular, the result type of
the <code class="code"><span class="constructor">Marshal</span>.from_*</code> functions is given as <code class="code"><span class="keywordsign">'</span>a</code>, but this is
misleading: the returned Caml value does not possess type <code class="code"><span class="keywordsign">'</span>a</code>
for all <code class="code"><span class="keywordsign">'</span>a</code>; it has one, unique type which cannot be determined
at compile-type. The programmer should explicitly give the expected
type of the returned value, using the following syntax:<ul>
<li><code class="code">(<span class="constructor">Marshal</span>.from_channel chan : <span class="keyword">type</span>)</code>.
Anything can happen at run-time if the object in the file does not
belong to the given type.</li>
</ul>
The representation of marshaled values is not human-readable,
and uses bytes that are not printable characters. Therefore,
input and output channels used in conjunction with <code class="code"><span class="constructor">Marshal</span>.to_channel</code>
and <code class="code"><span class="constructor">Marshal</span>.from_channel</code> must be opened in binary mode, using e.g.
<code class="code">open_out_bin</code> or <code class="code">open_in_bin</code>; channels opened in text mode will
cause unmarshaling errors on platforms where text channels behave
differently than binary channels, e.g. Windows.<br>
<hr width="100%">
<br><code><span class="keyword">type</span> <a name="TYPEextern_flags"></a><code class="type"></code>extern_flags = </code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">No_sharing</span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >Don't preserve sharing</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 class="constructor">Closures</span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >Send function closures</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
<div class="info">
The flags to the <code class="code"><span class="constructor">Marshal</span>.to_*</code> functions below.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALto_channel"></a>to_channel : <code class="type"><a href="Pervasives.html#TYPEout_channel">out_channel</a> -> 'a -> <a href="Marshal.html#TYPEextern_flags">extern_flags</a> list -> unit</code></pre><div class="info">
<code class="code"><span class="constructor">Marshal</span>.to_channel chan v 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 and functional values.
<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 not detected, 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>
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 position in the code
of the program. 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.)<br>
</div>
<pre><span class="keyword">val</span> <a name="VALto_string"></a>to_string : <code class="type">'a -> <a href="Marshal.html#TYPEextern_flags">extern_flags</a> list -> string</code></pre><div class="info">
<code class="code"><span class="constructor">Marshal</span>.to_string v flags</code> returns a string containing
the representation of <code class="code">v</code> as a sequence of bytes.
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>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALto_buffer"></a>to_buffer : <code class="type">string -> int -> int -> 'a -> <a href="Marshal.html#TYPEextern_flags">extern_flags</a> list -> int</code></pre><div class="info">
<code class="code"><span class="constructor">Marshal</span>.to_buffer buff ofs len v flags</code> marshals the value <code class="code">v</code>,
storing its byte representation in the string <code class="code">buff</code>,
starting at character number <code class="code">ofs</code>, and writing at most
<code class="code">len</code> characters. It returns the number of characters
actually written to the string. 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.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfrom_channel"></a>from_channel : <code class="type"><a href="Pervasives.html#TYPEin_channel">in_channel</a> -> 'a</code></pre><div class="info">
<code class="code"><span class="constructor">Marshal</span>.from_channel 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.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfrom_string"></a>from_string : <code class="type">string -> int -> 'a</code></pre><div class="info">
<code class="code"><span class="constructor">Marshal</span>.from_string buff 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 string <code class="code">buff</code>, starting at position <code class="code">ofs</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALheader_size"></a>header_size : <code class="type">int</code></pre><div class="info">
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 characters, of the header.
<a href="Marshal.html#VALdata_size"><code class="code"><span class="constructor">Marshal</span>.data_size</code></a><code class="code"> buff ofs</code> is the size, in characters,
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 ofs</code> is the total size,
in characters, 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>
To read the byte representation of a marshaled value into
a string buffer, the program needs to read first
<a href="Marshal.html#VALheader_size"><code class="code"><span class="constructor">Marshal</span>.header_size</code></a> characters into the buffer,
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 buffer is large enough to hold the remaining
data, then read it, and finally call <a href="Marshal.html#VALfrom_string"><code class="code"><span class="constructor">Marshal</span>.from_string</code></a>
to unmarshal the value.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALdata_size"></a>data_size : <code class="type">string -> int -> int</code></pre><div class="info">
See <a href="Marshal.html#VALheader_size"><code class="code"><span class="constructor">Marshal</span>.header_size</code></a>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALtotal_size"></a>total_size : <code class="type">string -> int -> int</code></pre><div class="info">
See <a href="Marshal.html#VALheader_size"><code class="code"><span class="constructor">Marshal</span>.header_size</code></a>.<br>
</div>
</body></html>
|
