Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Marshal(3)			   OCamldoc			    Marshal(3)

NAME
       Marshal - Marshaling of data structures.

Module
       Module	Marshal

Documentation
       Module Marshal
	: sig end

       Marshaling of data structures.

       This  module  provides functions	to encode arbitrary data structures as
       sequences of bytes, which can then be written on	a file or sent over  a
       pipe  or	 network  connection.	The bytes can then be read back	later,
       possibly	in another process, and	decoded	back into  a  data  structure.
       The format for the byte sequences is compatible across all machines for
       a given version of OCaml.

       Warning:	marshaling is currently	not type-safe. The type	 of  marshaled
       data is not transmitted along the value of the data, making it impossi-
       ble to check that the data read back possesses the type expected	by the
       context.	In particular, the result type of the Marshal.from_* functions
       is given	as 'a ,	but this is misleading:	the returned OCaml value  does
       not  possess  type 'a for all 'a	; it has one, unique type which	cannot
       be determined at	compile-type.  The programmer should  explicitly  give
       the expected type of the	returned value,	using the following syntax:

       - (Marshal.from_channel chan : type) .  Anything	can happen at run-time
       if the object in	the file does not belong to the	given type.

       Values of extensible variant types, for example exceptions (of extensi-
       ble  type  exn  ),  returned  by	 the  unmarhsaller  should not be pat-
       tern-matched over through match ... with	or try ... with	, because  un-
       marshalling  does  not  preserve	 the information required for matching
       their constructors. Structural equalities with other extensible variant
       values	does  not  work	 either.   Most	 other	uses  such  as	Print-
       exc.to_string, will still work as expected.

       The representation of marshaled values is not human-readable, and  uses
       bytes  that  are	 not printable characters. Therefore, input and	output
       channels	 used  in  conjunction	with   Marshal.to_channel   and	  Mar-
       shal.from_channel   must	  be   opened	in  binary  mode,  using  e.g.
       open_out_bin or open_in_bin ; channels opened in	text mode  will	 cause
       unmarshaling errors on platforms	where text channels behave differently
       than binary channels, e.g. Windows.

       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 :	Pervasives.out_channel -> 'a ->	extern_flags  list  ->
       unit

       Marshal.to_channel chan v flags writes the representation of v on chan-
       nel 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	 shar-
       ing  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 con-
       tains 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 be-
       tween  different	 programs.  If flags contains Marshal.Closures , func-
       tional 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 posi-
       tion.)

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

       If  flags contains Marshal.Compat_32 , marshaling fails when it encoun-
       ters an integer value outside the range [-2{^30}, 2{^30}-1] of integers
       that  are  representable	 on a 32-bit platform.	This ensures that mar-
       shaled 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-marshal-
       ing 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	repre-
       sentation  of  v	.  The flags argument has the same meaning as for Mar-
       shal.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	: Pervasives.in_channel	-> 'a

       Marshal.from_channel  chan reads	from channel chan the byte representa-
       tion 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  in-
       put_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  Mar-
       shal.from_channel does, except that the byte representation is not read
       from a channel, but taken from the byte sequence	buff , starting	at po-
       sition 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 se-
       quence.

       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.to-
       tal_size	raise Failure if buff ,	ofs does not contain a valid header.

       To  read	 the  byte representation of a marshaled value into a byte se-
       quence, the program needs to read first Marshal.header_size bytes  into
       the  sequence, then determine the length	of the remainder of the	repre-
       sentation using Marshal.data_size , make	sure  the  sequence  is	 large
       enough  to hold the remaining data, then	read it, and finally call Mar-
       shal.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 .

2020-08-11			    source:			    Marshal(3)

NAME | Module | Documentation

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Marshal&sektion=3o&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help