1Marshal(3)                       OCaml library                      Marshal(3)
2
3
4

NAME

6       Marshal - Marshaling of data structures.
7

Module

9       Module   Marshal
10

Documentation

12       Module Marshal
13        : sig end
14
15
16       Marshaling of data structures.
17
18       This  module  provides functions to encode arbitrary data structures as
19       sequences of bytes, which can then be written on a file or sent over  a
20       pipe  or  network  connection.   The bytes can then be read back later,
21       possibly in another process, and decoded back into  a  data  structure.
22       The format for the byte sequences is compatible across all machines for
23       a given version of OCaml.
24
25       Warning: marshaling is currently not type-safe. The type  of  marshaled
26       data is not transmitted along the value of the data, making it impossi‐
27       ble to check that the data read back possesses the type expected by the
28       context. In particular, the result type of the Marshal.from_* functions
29       is given as 'a , but this is misleading: the returned OCaml value  does
30       not  possess  type 'a for all 'a ; it has one, unique type which cannot
31       be determined at compile-time.  The programmer should  explicitly  give
32       the expected type of the returned value, using the following syntax:
33
34       - (Marshal.from_channel chan : type) .  Anything can happen at run-time
35       if the object in the file does not belong to the given type.
36
37       Values of extensible variant types, for example exceptions (of extensi‐
38       ble  type  exn  ),  returned  by  the  unmarshaller  should not be pat‐
39       tern-matched over through match ... with or  try  ...  with  ,  because
40       unmarshalling  does  not preserve the information required for matching
41       their constructors. Structural equalities with other extensible variant
42       values   does  not  work  either.   Most  other  uses  such  as  Print‐
43       exc.to_string, will still work as expected.
44
45       The representation of marshaled values is not human-readable, and  uses
46       bytes  that  are  not printable characters. Therefore, input and output
47       channels  used  in  conjunction  with   Marshal.to_channel   and   Mar‐
48       shal.from_channel   must   be   opened   in  binary  mode,  using  e.g.
49       open_out_bin or open_in_bin ; channels opened in text mode  will  cause
50       unmarshaling errors on platforms where text channels behave differently
51       than binary channels, e.g. Windows.
52
53
54
55
56
57       type extern_flags =
58        | No_sharing  (* Don't preserve sharing
59        *)
60        | Closures  (* Send function closures
61        *)
62        | Compat_32  (* Ensure 32-bit compatibility
63        *)
64
65
66       The flags to the Marshal.to_* functions below.
67
68
69
70       val to_channel : out_channel -> 'a -> extern_flags list -> unit
71
72
73       Marshal.to_channel chan v flags writes the representation of v on chan‐
74       nel  chan  .  The flags argument is a possibly empty list of flags that
75       governs the marshaling behavior with  respect  to  sharing,  functional
76       values, and compatibility between 32- and 64-bit platforms.
77
78       If  flags does not contain Marshal.No_sharing , circularities and shar‐
79       ing inside the value v are detected and preserved in  the  sequence  of
80       bytes  produced.  In particular, this guarantees that marshaling always
81       terminates. Sharing between values marshaled  by  successive  calls  to
82       Marshal.to_channel is neither detected nor preserved, though.  If flags
83       contains Marshal.No_sharing , sharing  is  ignored.   This  results  in
84       faster  marshaling if v contains no shared substructures, but may cause
85       slower marshaling and larger byte representations if  v  actually  con‐
86       tains sharing, or even non-termination if v contains cycles.
87
88       If  flags  does not contain Marshal.Closures , marshaling fails when it
89       encounters a functional value inside v : only 'pure'  data  structures,
90       containing  neither  functions  nor  objects, can safely be transmitted
91       between different programs. If flags contains Marshal.Closures ,  func‐
92       tional  values  will  be marshaled as a the position in the code of the
93       program together with the values corresponding to  the  free  variables
94       captured  in  the  closure.  In this case, the output of marshaling can
95       only be read back in processes that run exactly the same program,  with
96       exactly the same compiled code. (This is checked at un-marshaling time,
97       using an MD5 digest of the code transmitted along with the  code  posi‐
98       tion.)
99
100       The  exact definition of which free variables are captured in a closure
101       is not specified and can vary between bytecode  and  native  code  (and
102       according  to  optimization  flags).   In  particular, a function value
103       accessing a global reference may or may not include  the  reference  in
104       its  closure.   If it does, unmarshaling the corresponding closure will
105       create a new reference, different from the global one.
106
107       If flags contains Marshal.Compat_32 , marshaling fails when it  encoun‐
108       ters an integer value outside the range [-2{^30}, 2{^30}-1] of integers
109       that are representable on a 32-bit platform.  This  ensures  that  mar‐
110       shaled data generated on a 64-bit platform can be safely read back on a
111       32-bit platform.  If flags does not contain Marshal.Compat_32 , integer
112       values  outside the range [-2{^30}, 2{^30}-1] are marshaled, and can be
113       read back on a 64-bit platform, but will cause an error at  un-marshal‐
114       ing  time  when  read  back on a 32-bit platform.  The Mashal.Compat_32
115       flag only matters when marshaling is performed on a 64-bit platform; it
116       has no effect if marshaling is performed on a 32-bit platform.
117
118
119
120       val to_bytes : 'a -> extern_flags list -> bytes
121
122
123       Marshal.to_bytes  v flags returns a byte sequence containing the repre‐
124       sentation of v .  The flags argument has the same meaning as  for  Mar‐
125       shal.to_channel .
126
127
128       Since 4.02.0
129
130
131
132       val to_string : 'a -> extern_flags list -> string
133
134       Same  as  to_bytes  but return the result as a string instead of a byte
135       sequence.
136
137
138
139       val to_buffer : bytes -> int -> int -> 'a -> extern_flags list -> int
140
141
142       Marshal.to_buffer buff ofs len v flags marshals the value v  ,  storing
143       its  byte representation in the sequence buff , starting at index ofs ,
144       and writing at most len bytes.  It returns the number of bytes actually
145       written  to  the sequence. If the byte representation of v does not fit
146       in len characters, the exception Failure is raised.
147
148
149
150       val from_channel : in_channel -> 'a
151
152
153       Marshal.from_channel chan reads from channel chan the byte  representa‐
154       tion  of  a  structured  value,  as produced by one of the Marshal.to_*
155       functions, and reconstructs and returns the corresponding value.
156
157       It raises End_of_file if the function has already reached  the  end  of
158       file  when  starting  to  read  from  the  channel,  and raises Failure
159       input_value: truncated object if it reaches the end of file later  dur‐
160       ing the unmarshalling.
161
162
163
164       val from_bytes : bytes -> int -> 'a
165
166
167       Marshal.from_bytes  buff  ofs  unmarshals  a structured value like Mar‐
168       shal.from_channel does, except that the byte representation is not read
169       from  a  channel,  but  taken from the byte sequence buff , starting at
170       position ofs .  The byte sequence is not mutated.
171
172
173       Since 4.02.0
174
175
176
177       val from_string : string -> int -> 'a
178
179       Same as from_bytes but take a string as  argument  instead  of  a  byte
180       sequence.
181
182
183
184       val header_size : int
185
186       The  bytes  representing a marshaled value are composed of a fixed-size
187       header and a variable-sized data part, whose  size  can  be  determined
188       from  the  header.   Marshal.header_size  is the size, in bytes, of the
189       header.  Marshal.data_size buff ofs is the size, in bytes, of the  data
190       part,  assuming  a  valid header is stored in buff starting at position
191       ofs .  Finally, Marshal.total_size buff  ofs  is  the  total  size,  in
192       bytes,  of  the  marshaled  value.   Both  Marshal.data_size  and  Mar‐
193       shal.total_size raise Failure if buff , ofs does not  contain  a  valid
194       header.
195
196       To  read  the  byte  representation  of  a  marshaled value into a byte
197       sequence, the program needs to  read  first  Marshal.header_size  bytes
198       into  the  sequence,  then determine the length of the remainder of the
199       representation using Marshal.data_size ,  make  sure  the  sequence  is
200       large enough to hold the remaining data, then read it, and finally call
201       Marshal.from_bytes to unmarshal the value.
202
203
204
205       val data_size : bytes -> int -> int
206
207       See Marshal.header_size .
208
209
210
211       val total_size : bytes -> int -> int
212
213       See Marshal.header_size .
214
215
216
217
218
219OCamldoc                          2019-07-30                        Marshal(3)
Impressum