Provided by: ocaml-man_4.08.1-8_all bug

NAME

       Stdlib.Marshal - no description

Module

       Module   Stdlib.Marshal

Documentation

       Module Marshal
        : (module Stdlib__marshal)

       type extern_flags =
        | No_sharing  (* Don't preserve sharing
        *)
        | Closures  (* Send function closures
        *)
        | Compat_32  (* Ensure 32-bit compatibility
        *)

       The flags to the Marshal.to_* functions below.

       val to_channel : out_channel -> 'a -> extern_flags list -> unit

       Marshal.to_channel chan v flags writes the representation of v on channel chan . The flags
       argument is a possibly empty list of flags  that  governs  the  marshaling  behavior  with
       respect to sharing, functional values, and compatibility between 32- and 64-bit platforms.

       If  flags does not contain Marshal.No_sharing , circularities and sharing inside the value
       v are detected and preserved in the  sequence  of  bytes  produced.  In  particular,  this
       guarantees  that  marshaling  always  terminates.  Sharing  between  values  marshaled  by
       successive calls to Marshal.to_channel is neither  detected  nor  preserved,  though.   If
       flags contains Marshal.No_sharing , sharing is ignored.  This results in faster marshaling
       if v contains no shared substructures, but may cause slower  marshaling  and  larger  byte
       representations  if  v  actually  contains  sharing, or even non-termination if v contains
       cycles.

       If flags does not contain  Marshal.Closures  ,  marshaling  fails  when  it  encounters  a
       functional  value inside v : only 'pure' data structures, containing neither functions nor
       objects,  can  safely  be  transmitted  between  different  programs.  If  flags  contains
       Marshal.Closures  ,  functional  values will be marshaled as a the position in the code of
       the program together with the values corresponding to the free variables captured  in  the
       closure.   In  this case, the output of marshaling can only be read back in processes that
       run exactly the same program, with exactly the same compiled code.  (This  is  checked  at
       un-marshaling  time,  using  an  MD5  digest  of  the code transmitted along with the code
       position.)

       The exact definition of which free variables are captured in a closure  is  not  specified
       and  can  vary between bytecode and native code (and according to optimization flags).  In
       particular, a function value accessing a global reference  may  or  may  not  include  the
       reference  in its closure.  If it does, unmarshaling the corresponding closure will create
       a new reference, different from the global one.

       If flags contains Marshal.Compat_32 , marshaling fails when it encounters an integer value
       outside  the  range  [-2{^30},  2{^30}-1]  of  integers that are representable on a 32-bit
       platform.  This ensures that marshaled data generated on a 64-bit platform can  be  safely
       read  back  on  a  32-bit platform.  If flags does not contain Marshal.Compat_32 , integer
       values outside the range [-2{^30}, 2{^30}-1] are marshaled, and can  be  read  back  on  a
       64-bit  platform, but will cause an error at un-marshaling time when read back on a 32-bit
       platform.  The Mashal.Compat_32 flag only matters when marshaling is performed on a 64-bit
       platform; it has no effect if marshaling is performed on a 32-bit platform.

       val to_bytes : 'a -> extern_flags list -> bytes

       Marshal.to_bytes v flags returns a byte sequence containing the representation of v .  The
       flags argument has the same meaning as for Marshal.to_channel .

       Since 4.02.0

       val to_string : 'a -> extern_flags list -> string

       Same as to_bytes but return the result as a string instead of a byte sequence.

       val to_buffer : bytes -> int -> int -> 'a -> extern_flags list -> int

       Marshal.to_buffer buff  ofs  len  v  flags  marshals  the  value  v  ,  storing  its  byte
       representation  in  the  sequence  buff  , starting at index ofs , and writing at most len
       bytes.  It returns the number of bytes actually written  to  the  sequence.  If  the  byte
       representation of v does not fit in len characters, the exception Failure is raised.

       val from_channel : in_channel -> 'a

       Marshal.from_channel  chan reads from channel chan the byte representation of a structured
       value, as produced by one of the Marshal.to_* functions, and reconstructs and returns  the
       corresponding value.

       It raises End_of_file if the function has already reached the end of file when starting to
       read from the channel, and raises Failure input_value: truncated object if it reaches  the
       end of file later during the unmarshalling.

       val from_bytes : bytes -> int -> 'a

       Marshal.from_bytes  buff ofs unmarshals a structured value like Marshal.from_channel does,
       except that the byte representation is not read from a channel, but taken  from  the  byte
       sequence buff , starting at position ofs .  The byte sequence is not mutated.

       Since 4.02.0

       val from_string : string -> int -> 'a

       Same as from_bytes but take a string as argument instead of a byte sequence.

       val header_size : int

       The  bytes  representing  a  marshaled  value  are  composed  of a fixed-size header and a
       variable-sized  data   part,   whose   size   can   be   determined   from   the   header.
       Marshal.header_size  is  the size, in bytes, of the header.  Marshal.data_size buff ofs is
       the size, in bytes, of the data part, assuming a valid header is stored in  buff  starting
       at  position  ofs  .  Finally, Marshal.total_size buff ofs is the total size, in bytes, of
       the marshaled value.  Both Marshal.data_size and Marshal.total_size raise Failure if  buff
       , ofs does not contain a valid header.

       To  read  the  byte  representation of a marshaled value into a byte sequence, the program
       needs to read first Marshal.header_size bytes into the sequence, then determine the length
       of the remainder of the representation using Marshal.data_size , make sure the sequence is
       large enough to hold the remaining data, then read it, and finally call Marshal.from_bytes
       to unmarshal the value.

       val data_size : bytes -> int -> int

       See Marshal.header_size .

       val total_size : bytes -> int -> int

       See Marshal.header_size .