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

NAME

6       Stdlib.Marshal - no description
7

Module

9       Module   Stdlib.Marshal
10

Documentation

12       Module Marshal
13        : (module Stdlib__marshal)
14
15
16
17
18
19
20
21       type extern_flags =
22        | No_sharing  (* Don't preserve sharing
23        *)
24        | Closures  (* Send function closures
25        *)
26        | Compat_32  (* Ensure 32-bit compatibility
27        *)
28
29
30       The flags to the Marshal.to_* functions below.
31
32
33
34       val to_channel : out_channel -> 'a -> extern_flags list -> unit
35
36
37       Marshal.to_channel chan v flags writes the representation of v on chan‐
38       nel chan . The flags argument is a possibly empty list  of  flags  that
39       governs  the  marshaling  behavior  with respect to sharing, functional
40       values, and compatibility between 32- and 64-bit platforms.
41
42       If flags does not contain Marshal.No_sharing , circularities and  shar‐
43       ing  inside  the  value v are detected and preserved in the sequence of
44       bytes produced. In particular, this guarantees that  marshaling  always
45       terminates.  Sharing  between  values  marshaled by successive calls to
46       Marshal.to_channel is neither detected nor preserved, though.  If flags
47       contains  Marshal.No_sharing  ,  sharing  is  ignored.  This results in
48       faster marshaling if v contains no shared substructures, but may  cause
49       slower  marshaling  and  larger byte representations if v actually con‐
50       tains sharing, or even non-termination if v contains cycles.
51
52       If flags does not contain Marshal.Closures , marshaling fails  when  it
53       encounters  a  functional value inside v : only 'pure' data structures,
54       containing neither functions nor objects,  can  safely  be  transmitted
55       between  different programs. If flags contains Marshal.Closures , func‐
56       tional values will be marshaled as a the position in the  code  of  the
57       program  together  with  the values corresponding to the free variables
58       captured in the closure.  In this case, the output  of  marshaling  can
59       only  be read back in processes that run exactly the same program, with
60       exactly the same compiled code. (This is checked at un-marshaling time,
61       using  an  MD5 digest of the code transmitted along with the code posi‐
62       tion.)
63
64       The exact definition of which free variables are captured in a  closure
65       is  not  specified  and  can vary between bytecode and native code (and
66       according to optimization flags).   In  particular,  a  function  value
67       accessing  a  global  reference may or may not include the reference in
68       its closure.  If it does, unmarshaling the corresponding  closure  will
69       create a new reference, different from the global one.
70
71       If  flags contains Marshal.Compat_32 , marshaling fails when it encoun‐
72       ters an integer value outside the range [-2{^30}, 2{^30}-1] of integers
73       that  are  representable  on a 32-bit platform.  This ensures that mar‐
74       shaled data generated on a 64-bit platform can be safely read back on a
75       32-bit platform.  If flags does not contain Marshal.Compat_32 , integer
76       values outside the range [-2{^30}, 2{^30}-1] are marshaled, and can  be
77       read  back on a 64-bit platform, but will cause an error at un-marshal‐
78       ing time when read back on a  32-bit  platform.   The  Mashal.Compat_32
79       flag only matters when marshaling is performed on a 64-bit platform; it
80       has no effect if marshaling is performed on a 32-bit platform.
81
82
83
84       val to_bytes : 'a -> extern_flags list -> bytes
85
86
87       Marshal.to_bytes v flags returns a byte sequence containing the  repre‐
88       sentation  of  v .  The flags argument has the same meaning as for Mar‐
89       shal.to_channel .
90
91
92       Since 4.02.0
93
94
95
96       val to_string : 'a -> extern_flags list -> string
97
98       Same as to_bytes but return the result as a string instead  of  a  byte
99       sequence.
100
101
102
103       val to_buffer : bytes -> int -> int -> 'a -> extern_flags list -> int
104
105
106       Marshal.to_buffer  buff  ofs len v flags marshals the value v , storing
107       its byte representation in the sequence buff , starting at index ofs  ,
108       and writing at most len bytes.  It returns the number of bytes actually
109       written to the sequence. If the byte representation of v does  not  fit
110       in len characters, the exception Failure is raised.
111
112
113
114       val from_channel : in_channel -> 'a
115
116
117       Marshal.from_channel  chan reads from channel chan the byte representa‐
118       tion of a structured value, as produced  by  one  of  the  Marshal.to_*
119       functions, and reconstructs and returns the corresponding value.
120
121       It  raises  End_of_file  if the function has already reached the end of
122       file when starting  to  read  from  the  channel,  and  raises  Failure
123       input_value:  truncated object if it reaches the end of file later dur‐
124       ing the unmarshalling.
125
126
127
128       val from_bytes : bytes -> int -> 'a
129
130
131       Marshal.from_bytes buff ofs unmarshals a  structured  value  like  Mar‐
132       shal.from_channel does, except that the byte representation is not read
133       from a channel, but taken from the byte sequence  buff  ,  starting  at
134       position ofs .  The byte sequence is not mutated.
135
136
137       Since 4.02.0
138
139
140
141       val from_string : string -> int -> 'a
142
143       Same  as  from_bytes  but  take  a string as argument instead of a byte
144       sequence.
145
146
147
148       val header_size : int
149
150       The bytes representing a marshaled value are composed of  a  fixed-size
151       header  and  a  variable-sized  data part, whose size can be determined
152       from the header.  Marshal.header_size is the size,  in  bytes,  of  the
153       header.   Marshal.data_size buff ofs is the size, in bytes, of the data
154       part, assuming a valid header is stored in buff  starting  at  position
155       ofs  .   Finally,  Marshal.total_size  buff  ofs  is the total size, in
156       bytes,  of  the  marshaled  value.   Both  Marshal.data_size  and  Mar‐
157       shal.total_size  raise  Failure  if buff , ofs does not contain a valid
158       header.
159
160       To read the byte representation  of  a  marshaled  value  into  a  byte
161       sequence,  the  program  needs  to read first Marshal.header_size bytes
162       into the sequence, then determine the length of the  remainder  of  the
163       representation  using  Marshal.data_size  ,  make  sure the sequence is
164       large enough to hold the remaining data, then read it, and finally call
165       Marshal.from_bytes to unmarshal the value.
166
167
168
169       val data_size : bytes -> int -> int
170
171       See Marshal.header_size .
172
173
174
175       val total_size : bytes -> int -> int
176
177       See Marshal.header_size .
178
179
180
181
182
183OCamldoc                          2019-07-30                 Stdlib.Marshal(3)
Impressum