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       Raises Failure if chan is not in binary mode.
120
121
122
123       val to_bytes : 'a -> extern_flags list -> bytes
124
125
126       Marshal.to_bytes  v flags returns a byte sequence containing the repre‐
127       sentation of v .  The flags argument has the same meaning as  for  Mar‐
128       shal.to_channel .
129
130
131       Since 4.02.0
132
133
134
135       val to_string : 'a -> extern_flags list -> string
136
137       Same  as  to_bytes  but return the result as a string instead of a byte
138       sequence.
139
140
141
142       val to_buffer : bytes -> int -> int -> 'a -> extern_flags list -> int
143
144
145       Marshal.to_buffer buff ofs len v flags marshals the value v  ,  storing
146       its  byte representation in the sequence buff , starting at index ofs ,
147       and writing at most len bytes.  It returns the number of bytes actually
148       written  to  the sequence. If the byte representation of v does not fit
149       in len characters, the exception Failure is raised.
150
151
152
153       val from_channel : in_channel -> 'a
154
155
156       Marshal.from_channel chan reads from channel chan the byte  representa‐
157       tion  of  a  structured  value,  as produced by one of the Marshal.to_*
158       functions, and reconstructs and returns the corresponding value.
159
160
161       Raises End_of_file if chan is already at the end of the file.
162
163
164       Raises Failure if the end of the file is reached  during  unmarshalling
165       itself or if chan is not in binary mode.
166
167
168
169       val from_bytes : bytes -> int -> 'a
170
171
172       Marshal.from_bytes  buff  ofs  unmarshals  a structured value like Mar‐
173       shal.from_channel does, except that the byte representation is not read
174       from a channel, but taken from the byte sequence buff , starting at po‐
175       sition ofs .  The byte sequence is not mutated.
176
177
178       Since 4.02.0
179
180
181
182       val from_string : string -> int -> 'a
183
184       Same as from_bytes but take a string as argument instead of a byte  se‐
185       quence.
186
187
188
189       val header_size : int
190
191       The  bytes  representing a marshaled value are composed of a fixed-size
192       header and a variable-sized data part, whose  size  can  be  determined
193       from  the  header.   Marshal.header_size  is the size, in bytes, of the
194       header.  Marshal.data_size buff ofs is the size, in bytes, of the  data
195       part,  assuming  a  valid header is stored in buff starting at position
196       ofs .  Finally, Marshal.total_size buff  ofs  is  the  total  size,  in
197       bytes,  of the marshaled value.  Both Marshal.data_size and Marshal.to‐
198       tal_size raise Failure if buff , ofs does not contain a valid header.
199
200       To read the byte representation of a marshaled value into  a  byte  se‐
201       quence,  the program needs to read first Marshal.header_size bytes into
202       the sequence, then determine the length of the remainder of the  repre‐
203       sentation  using  Marshal.data_size  ,  make sure the sequence is large
204       enough to hold the remaining data, then read it, and finally call  Mar‐
205       shal.from_bytes to unmarshal the value.
206
207
208
209       val data_size : bytes -> int -> int
210
211       See Marshal.header_size .
212
213
214
215       val total_size : bytes -> int -> int
216
217       See Marshal.header_size .
218
219
220
221
222
223OCamldoc                          2022-02-04                        Marshal(3)
Impressum