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 Objective Caml.
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 Caml  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       The representation of marshaled values is not human-readable, and  uses
38       bytes  that  are  not printable characters. Therefore, input and output
39       channels  used  in  conjunction  with   Marshal.to_channel   and   Mar‐
40       shal.from_channel   must   be   opened   in  binary  mode,  using  e.g.
41       open_out_bin or open_in_bin ; channels opened in text mode  will  cause
42       unmarshaling errors on platforms where text channels behave differently
43       than binary channels, e.g. Windows.
44
45
46
47
48
49
50       type extern_flags =
51        | No_sharing  (* Don't preserve sharing *)
52        | Closures  (* Send function closures *)
53
54
55       The flags to the Marshal.to_* functions below.
56
57
58
59
60       val to_channel : Pervasives.out_channel -> 'a -> extern_flags  list  ->
61       unit
62
63
64       Marshal.to_channel chan v flags writes the representation of v on chan‐
65       nel chan . The flags argument is a possibly empty list  of  flags  that
66       governs  the marshaling behavior with respect to sharing and functional
67       values.
68
69       If flags does not contain Marshal.No_sharing , circularities and  shar‐
70       ing  inside  the  value v are detected and preserved in the sequence of
71       bytes produced. In particular, this guarantees that  marshaling  always
72       terminates.  Sharing  between  values  marshaled by successive calls to
73       Marshal.to_channel is not detected, though.   If  flags  contains  Mar‐
74       shal.No_sharing  , sharing is ignored.  This results in faster marshal‐
75       ing if v contains no shared substructures, but may  cause  slower  mar‐
76       shaling and larger byte representations if v actually contains sharing,
77       or even non-termination if v contains cycles.
78
79       If flags does not contain Marshal.Closures , marshaling fails  when  it
80       encounters a functional value inside v : only ``pure'' data structures,
81       containing neither functions nor objects,  can  safely  be  transmitted
82       between  different programs. If flags contains Marshal.Closures , func‐
83       tional values will be marshaled as a position in the code of  the  pro‐
84       gram.  In  this case, the output of marshaling can only be read back in
85       processes that run exactly the same program, with exactly the same com‐
86       piled code. (This is checked at un-marshaling time, using an MD5 digest
87       of the code transmitted along with the code position.)
88
89
90
91
92       val to_string : 'a -> extern_flags list -> string
93
94
95       Marshal.to_string v flags returns a string containing  the  representa‐
96       tion  of  v  as  a  sequence of bytes.  The flags argument has the same
97       meaning as for Marshal.to_channel .
98
99
100
101
102       val to_buffer : string -> int -> int -> 'a -> extern_flags list -> int
103
104
105       Marshal.to_buffer buff ofs len v flags marshals the value v  ,  storing
106       its byte representation in the string buff , starting at character num‐
107       ber ofs , and writing at most len characters.  It returns the number of
108       characters  actually  written to the string. If the byte representation
109       of v does not fit in len characters, the exception Failure is raised.
110
111
112
113
114       val from_channel : Pervasives.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
122
123
124       val from_string : string -> int -> 'a
125
126
127       Marshal.from_string buff ofs unmarshals a structured  value  like  Mar‐
128       shal.from_channel does, except that the byte representation is not read
129       from a channel, but taken from the string buff , starting  at  position
130       ofs .
131
132
133
134
135       val header_size : int
136
137       The  bytes  representing a marshaled value are composed of a fixed-size
138       header and a variable-sized data part, whose  size  can  be  determined
139       from  the  header.   Marshal.header_size is the size, in characters, of
140       the header.  Marshal.data_size buff ofs is the size, in characters,  of
141       the  data  part,  assuming a valid header is stored in buff starting at
142       position ofs .  Finally, Marshal.total_size buff ofs is the total size,
143       in characters, of the marshaled value.  Both Marshal.data_size and Mar‐
144       shal.total_size raise Failure if buff , ofs does not  contain  a  valid
145       header.
146
147       To read the byte representation of a marshaled value into a string buf‐
148       fer, the program needs to  read  first  Marshal.header_size  characters
149       into the buffer, then determine the length of the remainder of the rep‐
150       resentation using Marshal.data_size , make sure  the  buffer  is  large
151       enough  to hold the remaining data, then read it, and finally call Mar‐
152       shal.from_string to unmarshal the value.
153
154
155
156
157       val data_size : string -> int -> int
158
159       See Marshal.header_size .
160
161
162
163
164       val total_size : string -> int -> int
165
166       See Marshal.header_size .
167
168
169
170
171
172
173OCamldoc                          2010-01-29                        Marshal(3)
Impressum