1Marshal(3)                         OCamldoc                         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-type.  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  unmarhsaller  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 : Pervasives.out_channel -> 'a -> extern_flags  list  ->
71       unit
72
73
74       Marshal.to_channel chan v flags writes the representation of v on chan‐
75       nel chan . The flags argument is a possibly empty list  of  flags  that
76       governs  the  marshaling  behavior  with respect to sharing, functional
77       values, and compatibility between 32- and 64-bit platforms.
78
79       If flags does not contain Marshal.No_sharing , circularities and  shar‐
80       ing  inside  the  value v are detected and preserved in the sequence of
81       bytes produced. In particular, this guarantees that  marshaling  always
82       terminates.  Sharing  between  values  marshaled by successive calls to
83       Marshal.to_channel is neither detected nor preserved, though.  If flags
84       contains  Marshal.No_sharing  ,  sharing  is  ignored.  This results in
85       faster marshaling if v contains no shared substructures, but may  cause
86       slower  marshaling  and  larger byte representations if v actually con‐
87       tains sharing, or even non-termination if v contains cycles.
88
89       If flags does not contain Marshal.Closures , marshaling fails  when  it
90       encounters  a  functional value inside v : only 'pure' data structures,
91       containing neither functions nor objects,  can  safely  be  transmitted
92       between  different programs. If flags contains Marshal.Closures , func‐
93       tional values will be marshaled as a the position in the  code  of  the
94       program  together  with  the values corresponding to the free variables
95       captured in the closure.  In this case, the output  of  marshaling  can
96       only  be read back in processes that run exactly the same program, with
97       exactly the same compiled code. (This is checked at un-marshaling time,
98       using  an  MD5 digest of the code transmitted along with the code posi‐
99       tion.)
100
101       The exact definition of which free variables are captured in a  closure
102       is  not  specified  and  can vary between bytecode and native code (and
103       according to optimization flags).   In  particular,  a  function  value
104       accessing  a  global  reference may or may not include the reference in
105       its closure.  If it does, unmarshaling the corresponding  closure  will
106       create a new reference, different from the global one.
107
108       If  flags contains Marshal.Compat_32 , marshaling fails when it encoun‐
109       ters an integer value outside the range [-2{^30}, 2{^30}-1] of integers
110       that  are  representable  on a 32-bit platform.  This ensures that mar‐
111       shaled data generated on a 64-bit platform can be safely read back on a
112       32-bit platform.  If flags does not contain Marshal.Compat_32 , integer
113       values outside the range [-2{^30}, 2{^30}-1] are marshaled, and can  be
114       read  back on a 64-bit platform, but will cause an error at un-marshal‐
115       ing time when read back on a  32-bit  platform.   The  Mashal.Compat_32
116       flag only matters when marshaling is performed on a 64-bit platform; it
117       has no effect if marshaling is performed on a 32-bit platform.
118
119
120
121       val to_bytes : 'a -> extern_flags list -> bytes
122
123
124       Marshal.to_bytes v flags returns a byte sequence containing the  repre‐
125       sentation  of  v .  The flags argument has the same meaning as for Mar‐
126       shal.to_channel .
127
128
129       Since 4.02.0
130
131
132
133       val to_string : 'a -> extern_flags list -> string
134
135       Same as to_bytes but return the result as a string instead  of  a  byte
136       sequence.
137
138
139
140       val to_buffer : bytes -> int -> int -> 'a -> extern_flags list -> int
141
142
143       Marshal.to_buffer  buff  ofs len v flags marshals the value v , storing
144       its byte representation in the sequence buff , starting at index ofs  ,
145       and writing at most len bytes.  It returns the number of bytes actually
146       written to the sequence. If the byte representation of v does  not  fit
147       in len characters, the exception Failure is raised.
148
149
150
151       val from_channel : Pervasives.in_channel -> 'a
152
153
154       Marshal.from_channel  chan reads from channel chan the byte representa‐
155       tion of a structured value, as produced  by  one  of  the  Marshal.to_*
156       functions, and reconstructs and returns the corresponding value.
157
158       It  raises  End_of_file  if the function has already reached the end of
159       file when starting  to  read  from  the  channel,  and  raises  Failure
160       input_value:  truncated object if it reaches the end of file later dur‐
161       ing the unmarshalling.
162
163
164
165       val from_bytes : bytes -> int -> 'a
166
167
168       Marshal.from_bytes buff ofs unmarshals a  structured  value  like  Mar‐
169       shal.from_channel does, except that the byte representation is not read
170       from a channel, but taken from the byte sequence  buff  ,  starting  at
171       position ofs .  The byte sequence is not mutated.
172
173
174       Since 4.02.0
175
176
177
178       val from_string : string -> int -> 'a
179
180       Same  as  from_bytes  but  take  a string as argument instead of a byte
181       sequence.
182
183
184
185       val header_size : int
186
187       The bytes representing a marshaled value are composed of  a  fixed-size
188       header  and  a  variable-sized  data part, whose size can be determined
189       from the header.  Marshal.header_size is the size,  in  bytes,  of  the
190       header.   Marshal.data_size buff ofs is the size, in bytes, of the data
191       part, assuming a valid header is stored in buff  starting  at  position
192       ofs  .   Finally,  Marshal.total_size  buff  ofs  is the total size, in
193       bytes,  of  the  marshaled  value.   Both  Marshal.data_size  and  Mar‐
194       shal.total_size  raise  Failure  if buff , ofs does not contain a valid
195       header.
196
197       To read the byte representation  of  a  marshaled  value  into  a  byte
198       sequence,  the  program  needs  to read first Marshal.header_size bytes
199       into the sequence, then determine the length of the  remainder  of  the
200       representation  using  Marshal.data_size  ,  make  sure the sequence is
201       large enough to hold the remaining data, then read it, and finally call
202       Marshal.from_bytes to unmarshal the value.
203
204
205
206       val data_size : bytes -> int -> int
207
208       See Marshal.header_size .
209
210
211
212       val total_size : bytes -> int -> int
213
214       See Marshal.header_size .
215
216
217
218
219
2202018-04-14                          source:                         Marshal(3)
Impressum