.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "guestfs-ocaml 3"
.TH guestfs-ocaml 3 "2013-12-07" "libguestfs-1.18.1" "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
guestfs\-ocaml \- How to use libguestfs from OCaml
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Module style:
.PP
.Vb 3
\& let g = Guestfs.create () in
\& Guestfs.add_drive_opts g ~format:"raw" ~readonly:true "disk.img";
\& Guestfs.launch g;
.Ve
.PP
Object-oriented style:
.PP
.Vb 3
\& let g = new Guestfs.guestfs () in
\& g#add_drive_opts ~format:"raw" ~readonly:true "disk.img";
\& g#launch ();
\&
\& ocamlfind opt prog.ml \-package guestfs \-linkpkg \-o prog
\&or:
\& ocamlopt \-I +guestfs mlguestfs.cmxa prog.ml \-o prog
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This manual page documents how to call libguestfs from the OCaml
programming language.  This page just documents the differences from
the C \s-1API\s0 and gives some examples.  If you are not familiar with using
libguestfs, you also need to read \fIguestfs\fR\|(3).
.SS "\s-1PROGRAMMING\s0 \s-1STYLES\s0"
.IX Subsection "PROGRAMMING STYLES"
There are two different programming styles supported by the OCaml
bindings.  You can use a module style, with each C function mapped to
an OCaml function:
.PP
.Vb 1
\& int guestfs_set_verbose (guestfs_h *g, int flag);
.Ve
.PP
becomes:
.PP
.Vb 1
\& val Guestfs.set_verbose : Guestfs.t \-> bool \-> unit
.Ve
.PP
Alternately you can use an object-oriented style, calling methods
on the class \f(CW\*(C`Guestfs.guestfs\*(C'\fR:
.PP
.Vb 1
\& method set_verbose : bool \-> unit
.Ve
.PP
The object-oriented style is usually briefer, and the minor performance
penalty isn't noticeable in the general overhead of performing
libguestfs functions.
.SS "\s-1CLOSING\s0 \s-1THE\s0 \s-1HANDLE\s0"
.IX Subsection "CLOSING THE HANDLE"
The handle is closed when it is reaped by the garbage collector.
Because libguestfs handles include a lot of state, it is also
possible to close (and hence free) them explicitly by calling
\&\f(CW\*(C`Guestfs.close\*(C'\fR or the \f(CW\*(C`#close\*(C'\fR method.
.SS "\s-1EXCEPTIONS\s0"
.IX Subsection "EXCEPTIONS"
Errors from libguestfs functions are mapped into the \f(CW\*(C`Guestfs.Error\*(C'\fR
exception.  This has a single parameter which is the error message (a
string).
.PP
Calling any function/method on a closed handle raises
\&\f(CW\*(C`Guestfs.Handle_closed\*(C'\fR.  The single parameter is the name of the
function that you called.
.SH "EXAMPLE 1: CREATE A DISK IMAGE"
.IX Header "EXAMPLE 1: CREATE A DISK IMAGE"
.Vb 1
\& (* Example showing how to create a disk image. *)
\& 
\& open Unix
\& open Printf
\& 
\& let output = "disk.img"
\& 
\& let () =
\&   let g = new Guestfs.guestfs () in
\& 
\&   (* Create a raw\-format sparse disk image, 512 MB in size. *)
\&   let fd = openfile output [O_WRONLY;O_CREAT;O_TRUNC;O_NOCTTY] 0o666 in
\&   ftruncate fd (512 * 1024 * 1024);
\&   close fd;
\& 
\&   (* Set the trace flag so that we can see each libguestfs call. *)
\&   g#set_trace true;
\& 
\&   (* Set the autosync flag so that the disk will be synchronized
\&    * automatically when the libguestfs handle is closed.
\&    *)
\&   g#set_autosync true;
\& 
\&   (* Attach the disk image to libguestfs. *)
\&   g#add_drive_opts ~format:"raw" ~readonly:false output;
\& 
\&   (* Run the libguestfs back\-end. *)
\&   g#launch ();
\& 
\&   (* Get the list of devices.  Because we only added one drive
\&    * above, we expect that this list should contain a single
\&    * element.
\&    *)
\&   let devices = g#list_devices () in
\&   if Array.length devices <> 1 then
\&     failwith "error: expected a single device from list\-devices";
\& 
\&   (* Partition the disk as one single MBR partition. *)
\&   g#part_disk devices.(0) "mbr";
\& 
\&   (* Get the list of partitions.  We expect a single element, which
\&    * is the partition we have just created.
\&    *)
\&   let partitions = g#list_partitions () in
\&   if Array.length partitions <> 1 then
\&     failwith "error: expected a single partition from list\-partitions";
\& 
\&   (* Create a filesystem on the partition. *)
\&   g#mkfs "ext4" partitions.(0);
\& 
\&   (* Now mount the filesystem so that we can add files. *)
\&   g#mount_options "" partitions.(0) "/";
\& 
\&   (* Create some files and directories. *)
\&   g#touch "/empty";
\&   let message = "Hello, world\en" in
\&   g#write "/hello" message;
\&   g#mkdir "/foo";
\& 
\&   (* This one uploads the local file /etc/resolv.conf into
\&    * the disk image.
\&    *)
\&   g#upload "/etc/resolv.conf" "/foo/resolv.conf";
\& 
\&   (* Because \*(Aqautosync\*(Aq was set (above) we can just close the handle
\&    * and the disk contents will be synchronized.  You can also do
\&    * this manually by calling g#umount_all and g#sync.
\&    *
\&    * Note also that handles are automatically closed if they are
\&    * reaped by the garbage collector.  You only need to call close
\&    * if you want to close the handle right away.
\&    *)
\&   g#close ()
.Ve
.SH "EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE"
.IX Header "EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE"
.Vb 1
\& (* Example showing how to inspect a virtual machine disk. *)
\& 
\& open Printf
\& 
\& let disk =
\&   if Array.length Sys.argv = 2 then
\&     Sys.argv.(1)
\&   else
\&     failwith "usage: inspect_vm disk.img"
\& 
\& let () =
\&   let g = new Guestfs.guestfs () in
\& 
\&   (* Attach the disk image read\-only to libguestfs. *)
\&   g#add_drive_opts (*~format:"raw"*) ~readonly:true disk;
\& 
\&   (* Run the libguestfs back\-end. *)
\&   g#launch ();
\& 
\&   (* Ask libguestfs to inspect for operating systems. *)
\&   let roots = g#inspect_os () in
\&   if Array.length roots = 0 then
\&     failwith "inspect_vm: no operating systems found";
\& 
\&   Array.iter (
\&     fun root \->
\&       printf "Root device: %s\en" root;
\& 
\&       (* Print basic information about the operating system. *)
\&       printf "  Product name: %s\en" (g#inspect_get_product_name root);
\&       printf "  Version:      %d.%d\en"
\&         (g#inspect_get_major_version root)
\&         (g#inspect_get_minor_version root);
\&       printf "  Type:         %s\en" (g#inspect_get_type root);
\&       printf "  Distro:       %s\en" (g#inspect_get_distro root);
\& 
\&       (* Mount up the disks, like guestfish \-i.
\&        *
\&        * Sort keys by length, shortest first, so that we end up
\&        * mounting the filesystems in the correct order.
\&        *)
\&       let mps = g#inspect_get_mountpoints root in
\&       let cmp (a,_) (b,_) =
\&         compare (String.length a) (String.length b) in
\&       let mps = List.sort cmp mps in
\&       List.iter (
\&         fun (mp, dev) \->
\&           try g#mount_ro dev mp
\&           with Guestfs.Error msg \-> eprintf "%s (ignored)\en" msg
\&       ) mps;
\& 
\&       (* If /etc/issue.net file exists, print up to 3 lines. *)
\&       let filename = "/etc/issue.net" in
\&       if g#is_file filename then (
\&         printf "\-\-\- %s \-\-\-\en" filename;
\&         let lines = g#head_n 3 filename in
\&         Array.iter print_endline lines
\&       );
\& 
\&       (* Unmount everything. *)
\&       g#umount_all ()
\&   ) roots
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIguestfs\fR\|(3),
\&\fIguestfs\-examples\fR\|(3),
\&\fIguestfs\-erlang\fR\|(3),
\&\fIguestfs\-java\fR\|(3),
\&\fIguestfs\-perl\fR\|(3),
\&\fIguestfs\-python\fR\|(3),
\&\fIguestfs\-recipes\fR\|(1),
\&\fIguestfs\-ruby\fR\|(3),
<http://libguestfs.org/>,
<http://caml.inria.fr/>.
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2010 Red Hat Inc. <http://libguestfs.org/>
.PP
The examples in this manual page may be freely copied, modified and
distributed without any restrictions.
.PP
This library is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
.PP
This library is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the \s-1GNU\s0
Lesser General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA\s0 02110\-1301 \s-1USA\s0