1guestfs-ocaml(3) Virtualization Support guestfs-ocaml(3)
2
6 guestfs-ocaml - How to use libguestfs from OCaml
7
9 Module style:
10 let g = Guestfs.create () in
12 Guestfs.add_drive_opts g ~format:"raw" ~readonly:true "disk.img";
13 Guestfs.launch g;
14 Object-oriented style:
16 let g = new Guestfs.guestfs () in
18 g#add_drive_opts ~format:"raw" ~readonly:true "disk.img";
19 g#launch ();
20 ocamlfind opt prog.ml -package guestfs -linkpkg -o prog
22 or:
23 ocamlopt -I +guestfs mlguestfs.cmxa prog.ml -o prog
24
26 This manual page documents how to call libguestfs from the OCaml
27 programming language. This page just documents the differences from
28 the C API and gives some examples. If you are not familiar with using
29 libguestfs, you also need to read guestfs(3).
30 PROGRAMMING STYLES
32 There are two different programming styles supported by the OCaml
33 bindings. You can use a module style, with each C function mapped to
34 an OCaml function:
35 int guestfs_set_verbose (guestfs_h *g, int flag);
37 becomes:
39 val Guestfs.set_verbose : Guestfs.t -> bool -> unit
41 Alternately you can use an object-oriented style, calling methods on
43 the class "Guestfs.guestfs":
44 method set_verbose : bool -> unit
46 The object-oriented style is usually briefer, and the minor performance
48 penalty isn't noticeable in the general overhead of performing
49 libguestfs functions.
50 CLOSING THE HANDLE
52 The handle is closed when it is reaped by the garbage collector.
53 Because libguestfs handles include a lot of state, it is also possible
54 to close (and hence free) them explicitly by calling "Guestfs.close" or
55 the "#close" method.
56 EXCEPTIONS
58 Errors from libguestfs functions are mapped into the "Guestfs.Error"
59 exception. This has a single parameter which is the error message (a
60 string).
61 Calling any function/method on a closed handle raises
63 "Guestfs.Handle_closed". The single parameter is the name of the
64 function that you called.
65
67 (* Example showing how to create a disk image. *)
68 open Unix
70 open Printf
71 let output = "disk.img"
73 let () =
75 let g = new Guestfs.guestfs () in
76 (* Create a raw-format sparse disk image, 512 MB in size. *)
78 g#disk_create output "raw" (Int64.of_int (512 * 1024 * 1024));
79 (* Set the trace flag so that we can see each libguestfs call. *)
81 g#set_trace true;
82 (* Attach the disk image to libguestfs. *)
84 g#add_drive_opts ~format:"raw" ~readonly:false output;
85 (* Run the libguestfs back-end. *)
87 g#launch ();
88 (* Get the list of devices. Because we only added one drive
90 * above, we expect that this list should contain a single
91 * element.
92 *)
93 let devices = g#list_devices () in
94 if Array.length devices <> 1 then
95 failwith "error: expected a single device from list-devices";
96 (* Partition the disk as one single MBR partition. *)
98 g#part_disk devices.(0) "mbr";
99 (* Get the list of partitions. We expect a single element, which
101 * is the partition we have just created.
102 *)
103 let partitions = g#list_partitions () in
104 if Array.length partitions <> 1 then
105 failwith "error: expected a single partition from list-partitions";
106 (* Create a filesystem on the partition. *)
108 g#mkfs "ext4" partitions.(0);
109 (* Now mount the filesystem so that we can add files. *)
111 g#mount partitions.(0) "/";
112 (* Create some files and directories. *)
114 g#touch "/empty";
115 let message = "Hello, world\n" in
116 g#write "/hello" message;
117 g#mkdir "/foo";
118 (* This one uploads the local file /etc/resolv.conf into
120 * the disk image.
121 *)
122 g#upload "/etc/resolv.conf" "/foo/resolv.conf";
123 (* Because we wrote to the disk and we want to detect write
125 * errors, call g#shutdown. You don't need to do this:
126 * g#close will do it implicitly.
127 *)
128 g#shutdown ();
129 (* Note also that handles are automatically closed if they are
131 * reaped by the garbage collector. You only need to call close
132 * if you want to close the handle right away.
133 *)
134 g#close ()
135
137 (* Example showing how to inspect a virtual machine disk. *)
138 open Printf
140 let disk =
142 if Array.length Sys.argv = 2 then
143 Sys.argv.(1)
144 else
145 failwith "usage: inspect_vm disk.img"
146 let () =
148 let g = new Guestfs.guestfs () in
149 (* Attach the disk image read-only to libguestfs. *)
151 g#add_drive_opts (*~format:"raw"*) ~readonly:true disk;
152 (* Run the libguestfs back-end. *)
154 g#launch ();
155 (* Ask libguestfs to inspect for operating systems. *)
157 let roots = g#inspect_os () in
158 if Array.length roots = 0 then
159 failwith "inspect_vm: no operating systems found";
160 Array.iter (
162 fun root ->
163 printf "Root device: %s\n" root;
164 (* Print basic information about the operating system. *)
166 printf " Product name: %s\n" (g#inspect_get_product_name root);
167 printf " Version: %d.%d\n"
168 (g#inspect_get_major_version root)
169 (g#inspect_get_minor_version root);
170 printf " Type: %s\n" (g#inspect_get_type root);
171 printf " Distro: %s\n" (g#inspect_get_distro root);
172 (* Mount up the disks, like guestfish -i.
174 *
175 * Sort keys by length, shortest first, so that we end up
176 * mounting the filesystems in the correct order.
177 *)
178 let mps = g#inspect_get_mountpoints root in
179 let cmp (a,_) (b,_) =
180 compare (String.length a) (String.length b) in
181 let mps = List.sort cmp mps in
182 List.iter (
183 fun (mp, dev) ->
184 try g#mount_ro dev mp
185 with Guestfs.Error msg -> eprintf "%s (ignored)\n" msg
186 ) mps;
187 (* If /etc/issue.net file exists, print up to 3 lines. *)
189 let filename = "/etc/issue.net" in
190 if g#is_file filename then (
191 printf "--- %s ---\n" filename;
192 let lines = g#head_n 3 filename in
193 Array.iter print_endline lines
194 );
195 (* Unmount everything. *)
197 g#umount_all ()
198 ) roots
199
201 (* Example showing how to enable debugging, and capture it into any
202 * custom logging system.
203 *)
204 (* Events we are interested in. This bitmask covers all trace and
206 * debug messages.
207 *)
208 let event_bitmask = [
209 Guestfs.EVENT_LIBRARY;
210 Guestfs.EVENT_WARNING;
211 Guestfs.EVENT_APPLIANCE;
212 Guestfs.EVENT_TRACE
213 ]
214 let rec main () =
216 let g = new Guestfs.guestfs () in
217 (* By default, debugging information is printed on stderr. To
219 * capture it somewhere else you have to set up an event handler
220 * which will be called back as debug messages are generated. To do
221 * this use the event API.
222 *
223 * For more information see EVENTS in guestfs(3).
224 *)
225 ignore (g#set_event_callback message_callback event_bitmask);
226 (* This is how debugging is enabled:
228 *
229 * Setting the 'trace' flag in the handle means that each libguestfs
230 * call is logged (name, parameters, return). This flag is useful
231 * to see how libguestfs is being used by a program.
232 *
233 * Setting the 'verbose' flag enables a great deal of extra
234 * debugging throughout the system. This is useful if there is a
235 * libguestfs error which you don't understand.
236 *
237 * Note that you should set the flags early on after creating the
238 * handle. In particular if you set the verbose flag after launch
239 * then you won't see all messages.
240 *
241 * For more information see:
242 * http://libguestfs.org/guestfs-faq.1.html#debugging-libguestfs
243 *
244 * Error messages raised by APIs are *not* debugging information,
245 * and they are not affected by any of this. You may have to log
246 * them separately.
247 *)
248 g#set_trace true;
249 g#set_verbose true;
250 (* Do some operations which will generate plenty of trace and debug
252 * messages.
253 *)
254 g#add_drive "/dev/null";
255 g#launch ();
256 g#close ()
257 (* This function is called back by libguestfs whenever a trace or
259 * debug message is generated.
260 *
261 * For the classes of events we have registered above, 'array' and
262 * 'array_len' will not be meaningful. Only 'buf' and 'buf_len' will
263 * be interesting and these will contain the trace or debug message.
264 *
265 * This example simply redirects these messages to syslog, but
266 * obviously you could do something more advanced here.
267 *)
268 and message_callback event event_handle buf array =
269 if String.length buf > 0 then (
270 let event_name = Guestfs.event_to_string [event] in
271 Printf.printf "[%s] %S\n%!" event_name buf
272 )
273 let () = main ()
275
277 guestfs(3), guestfs-examples(3), guestfs-erlang(3), guestfs-gobject(3),
278 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-perl(3),
279 guestfs-python(3), guestfs-recipes(1), guestfs-ruby(3),
280 http://libguestfs.org/, http://caml.inria.fr/.
281
283 Richard W.M. Jones ("rjones at redhat dot com")
284
286 Copyright (C) 2010-2023 Red Hat Inc.
287
289 This manual page contains examples which we hope you will use in your
290 programs. The examples may be freely copied, modified and distributed
291 for any purpose without any restrictions.
292
294 To get a list of bugs against libguestfs, use this link:
295 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
296 To report a new bug against libguestfs, use this link:
298 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
299 When reporting a bug, please supply:
301 • The version of libguestfs.
303 • Where you got libguestfs (eg. which Linux distro, compiled from
305 source, etc)
306 • Describe the bug accurately and give a way to reproduce it.
308 • Run libguestfs-test-tool(1) and paste the complete, unedited output
310 into the bug report.
311libguestfs-1.51.9 2023-12-09 guestfs-ocaml(3)