.TH "Stdlib.Marshal" 3 2024-05-31 OCamldoc "OCaml library" .SH NAME Stdlib.Marshal \- no description .SH Module Module Stdlib.Marshal .SH Documentation .sp Module .BI "Marshal" : .B (module Stdlib__Marshal) .sp .sp .sp .sp .I type extern_flags = | No_sharing (* Don\&'t preserve sharing *) | Closures (* Send function closures *) | Compat_32 (* Ensure 32\-bit compatibility *) .sp .sp .PP The flags to the .ft B Marshal\&.to_* .ft R functions below\&. .PP .I val to_channel : .B out_channel -> 'a -> extern_flags list -> unit .sp .ft B Marshal\&.to_channel chan v flags .ft R writes the representation of .ft B v .ft R on channel .ft B chan .ft R \&. The .ft B flags .ft R 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\&. .sp If .ft B flags .ft R does not contain .ft B Marshal\&.No_sharing .ft R , circularities and sharing inside the value .ft B v .ft R 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 .ft B Marshal\&.to_channel .ft R is neither detected nor preserved, though\&. If .ft B flags .ft R contains .ft B Marshal\&.No_sharing .ft R , sharing is ignored\&. This results in faster marshaling if .ft B v .ft R contains no shared substructures, but may cause slower marshaling and larger byte representations if .ft B v .ft R actually contains sharing, or even non\-termination if .ft B v .ft R contains cycles\&. .sp If .ft B flags .ft R does not contain .ft B Marshal\&.Closures .ft R , marshaling fails when it encounters a functional value inside .ft B v .ft R : only \&'pure\&' data structures, containing neither functions nor objects, can safely be transmitted between different programs\&. If .ft B flags .ft R contains .ft B Marshal\&.Closures .ft R , 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\&.) .sp 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\&. .sp If .ft B flags .ft R contains .ft B Marshal\&.Compat_32 .ft R , marshaling fails when it encounters an integer value outside the range .ft B \-2 .ft R ^ .ft B 30 .ft R , .ft B 2 .ft R ^ .ft B 30 .ft R .ft B \-1 .ft R 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 .ft B flags .ft R does not contain .ft B Marshal\&.Compat_32 .ft R , integer values outside the range .ft B \-2 .ft R ^ .ft B 30 .ft R , .ft B 2 .ft R ^ .ft B 30 .ft R .ft B \-1 .ft R 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 .ft B Mashal\&.Compat_32 .ft R 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\&. .sp .B "Raises Failure" if .ft B chan .ft R is not in binary mode\&. .sp .I val to_bytes : .B 'a -> extern_flags list -> bytes .sp .ft B Marshal\&.to_bytes v flags .ft R returns a byte sequence containing the representation of .ft B v .ft R \&. The .ft B flags .ft R argument has the same meaning as for .ft B Marshal\&.to_channel .ft R \&. .sp .B "Since" 4.02 .sp .I val to_string : .B 'a -> extern_flags list -> string .sp Same as .ft B to_bytes .ft R but return the result as a string instead of a byte sequence\&. .sp .I val to_buffer : .B bytes -> int -> int -> 'a -> extern_flags list -> int .sp .ft B Marshal\&.to_buffer buff ofs len v flags .ft R marshals the value .ft B v .ft R , storing its byte representation in the sequence .ft B buff .ft R , starting at index .ft B ofs .ft R , and writing at most .ft B len .ft R bytes\&. It returns the number of bytes actually written to the sequence\&. If the byte representation of .ft B v .ft R does not fit in .ft B len .ft R characters, the exception .ft B Failure .ft R is raised\&. .sp .I val from_channel : .B in_channel -> 'a .sp .ft B Marshal\&.from_channel chan .ft R reads from channel .ft B chan .ft R the byte representation of a structured value, as produced by one of the .ft B Marshal\&.to_* .ft R functions, and reconstructs and returns the corresponding value\&. .sp .B "Raises End_of_file" if .ft B chan .ft R is already at the end of the file\&. .sp .B "Raises Failure" if the end of the file is reached during unmarshalling itself or if .ft B chan .ft R is not in binary mode\&. .sp .I val from_bytes : .B bytes -> int -> 'a .sp .ft B Marshal\&.from_bytes buff ofs .ft R unmarshals a structured value like .ft B Marshal\&.from_channel .ft R does, except that the byte representation is not read from a channel, but taken from the byte sequence .ft B buff .ft R , starting at position .ft B ofs .ft R \&. The byte sequence is not mutated\&. .sp .B "Since" 4.02 .sp .I val from_string : .B string -> int -> 'a .sp Same as .ft B from_bytes .ft R but take a string as argument instead of a byte sequence\&. .sp .I val header_size : .B int .sp 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\&. .ft B Marshal\&.header_size .ft R is the size, in bytes, of the header\&. .ft B Marshal\&.data_size .ft R .ft B buff ofs .ft R is the size, in bytes, of the data part, assuming a valid header is stored in .ft B buff .ft R starting at position .ft B ofs .ft R \&. Finally, .ft B Marshal\&.total_size .ft R .ft B buff ofs .ft R is the total size, in bytes, of the marshaled value\&. Both .ft B Marshal\&.data_size .ft R and .ft B Marshal\&.total_size .ft R raise .ft B Failure .ft R if .ft B buff .ft R , .ft B ofs .ft R does not contain a valid header\&. .sp To read the byte representation of a marshaled value into a byte sequence, the program needs to read first .ft B Marshal\&.header_size .ft R bytes into the sequence, then determine the length of the remainder of the representation using .ft B Marshal\&.data_size .ft R , make sure the sequence is large enough to hold the remaining data, then read it, and finally call .ft B Marshal\&.from_bytes .ft R to unmarshal the value\&. .sp .I val data_size : .B bytes -> int -> int .sp See .ft B Marshal\&.header_size .ft R \&. .sp .I val total_size : .B bytes -> int -> int .sp See .ft B Marshal\&.header_size .ft R \&. .sp .PP .SS Marshal and domain safety .sp Care must be taken when marshaling a mutable value that may be modified by a different domain\&. Mutating a value that is being marshaled (i\&.e\&., turned into a sequence of bytes) is a programming error and might result in suprising values (when unmarshaling) due to tearing, since marshaling involves byte\-per\-byte copy\&. .PP