=head1 NAME

guestfs-ocaml - How to use libguestfs from OCaml

=head1 SYNOPSIS

Module style:

 let g = Guestfs.create () in
 Guestfs.add_drive_opts g ~format:"raw" ~readonly:true "disk.img";
 Guestfs.launch g;

Object-oriented style:

 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

=head1 DESCRIPTION

This manual page documents how to call libguestfs from the OCaml
programming language.  This page just documents the differences from
the C API and gives some examples.  If you are not familiar with using
libguestfs, you also need to read L<guestfs(3)>.

=head2 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:

 int guestfs_set_verbose (guestfs_h *g, int flag);

becomes:

 val Guestfs.set_verbose : Guestfs.t -> bool -> unit

Alternately you can use an object-oriented style, calling methods
on the class C<Guestfs.guestfs>:

 method set_verbose : bool -> unit

The object-oriented style is usually briefer, and the minor performance
penalty isn't noticeable in the general overhead of performing
libguestfs functions.

=head2 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
C<Guestfs.close> or the C<#close> method.

=head2 EXCEPTIONS

Errors from libguestfs functions are mapped into the C<Guestfs.Error>
exception.  This has a single parameter which is the error message (a
string).

Calling any function/method on a closed handle raises
C<Guestfs.Handle_closed>.  The single parameter is the name of the
function that you called.

=head1 EXAMPLE: CREATE A DISK IMAGE

@CREATE_DISK@

=head1 EXAMPLE: INSPECT A VIRTUAL MACHINE DISK IMAGE

@INSPECT_VM@

=head1 EXAMPLE: ENABLE DEBUGGING AND LOGGING

@DEBUG_LOGGING@

=head1 SEE ALSO

L<guestfs(3)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
L<guestfs-perl(3)>,
L<guestfs-python(3)>,
L<guestfs-recipes(1)>,
L<guestfs-ruby(3)>,
L<http://libguestfs.org/>,
L<http://caml.inria.fr/>.

=head1 AUTHORS

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 COPYRIGHT

Copyright (C) 2010-2025 Red Hat Inc.
