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  un‐
40       marshalling  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 be‐
91       tween 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 ac‐
102       cording  to  optimization  flags).  In particular, a function value ac‐
103       cessing a global reference may or may not include the reference in  its
104       closure.   If it does, unmarshaling the corresponding closure will cre‐
105       ate 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 "in‐
159       put_value: truncated object" if it reaches the end of file later during
160       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 po‐
170       sition 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  se‐
180       quence.
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 Marshal.to‐
193       tal_size raise Failure if buff , ofs does not contain a valid header.
194
195       To read the byte representation of a marshaled value into  a  byte  se‐
196       quence,  the program needs to read first Marshal.header_size bytes into
197       the sequence, then determine the length of the remainder of the  repre‐
198       sentation  using  Marshal.data_size  ,  make sure the sequence is large
199       enough to hold the remaining data, then read it, and finally call  Mar‐
200       shal.from_bytes to unmarshal the value.
201
202
203
204       val data_size : bytes -> int -> int
205
206       See Marshal.header_size .
207
208
209
210       val total_size : bytes -> int -> int
211
212       See Marshal.header_size .
213
214
215
216
217
218OCamldoc                          2021-01-26                        Marshal(3)
Impressum