3 * Copyright (C) 2009 Red Hat Inc.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 (* This script generates a large amount of code and documentation for
21 * all the daemon actions.
23 * To add a new action there are only two files you need to change,
24 * this one to describe the interface (see the big table below), and
25 * daemon/<somefile>.c to write the implementation.
27 * After editing this file, run it (./src/generator.ml) to regenerate
28 * all the output files.
30 * IMPORTANT: This script should NOT print any warnings. If it prints
31 * warnings, you should treat them as errors.
32 * [Need to add -warn-error to ocaml command line]
40 type style = ret * args
42 (* "RErr" as a return value means an int used as a simple error
43 * indication, ie. 0 or -1.
46 (* "RInt" as a return value means an int which is -1 for error
47 * or any value >= 0 on success. Only use this for smallish
48 * positive ints (0 <= i < 2^30).
51 (* "RInt64" is the same as RInt, but is guaranteed to be able
52 * to return a full 64 bit value, _except_ that -1 means error
53 * (so -1 cannot be a valid, non-error return value).
56 (* "RBool" is a bool return value which can be true/false or
60 (* "RConstString" is a string that refers to a constant value.
61 * Try to avoid using this. In particular you cannot use this
62 * for values returned from the daemon, because there is no
63 * thread-safe way to return them in the C API.
65 | RConstString of string
66 (* "RString" and "RStringList" are caller-frees. *)
68 | RStringList of string
69 (* Some limited tuples are possible: *)
70 | RIntBool of string * string
71 (* LVM PVs, VGs and LVs. *)
78 (* Key-value pairs of untyped strings. Turns into a hashtable or
79 * dictionary in languages which support it. DON'T use this as a
80 * general "bucket" for results. Prefer a stronger typed return
81 * value if one is available, or write a custom struct. Don't use
82 * this if the list could potentially be very long, since it is
83 * inefficient. Keys should be unique. NULLs are not permitted.
85 | RHashtable of string
87 and args = argt list (* Function parameters, guestfs handle is implicit. *)
89 (* Note in future we should allow a "variable args" parameter as
90 * the final parameter, to allow commands like
91 * chmod mode file [file(s)...]
92 * This is not implemented yet, but many commands (such as chmod)
93 * are currently defined with the argument order keeping this future
94 * possibility in mind.
97 | String of string (* const char *name, cannot be NULL *)
98 | OptString of string (* const char *name, may be NULL *)
99 | StringList of string(* list of strings (each string cannot be NULL) *)
100 | Bool of string (* boolean *)
101 | Int of string (* int (smallish ints, signed, <= 31 bits) *)
102 (* These are treated as filenames (simple string parameters) in
103 * the C API and bindings. But in the RPC protocol, we transfer
104 * the actual file content up to or down from the daemon.
105 * FileIn: local machine -> daemon (in request)
106 * FileOut: daemon -> local machine (in reply)
107 * In guestfish (only), the special name "-" means read from
108 * stdin or write to stdout.
114 | ProtocolLimitWarning (* display warning about protocol size limits *)
115 | DangerWillRobinson (* flags particularly dangerous commands *)
116 | FishAlias of string (* provide an alias for this cmd in guestfish *)
117 | FishAction of string (* call this function in guestfish *)
118 | NotInFish (* do not export via guestfish *)
119 | NotInDocs (* do not add this function to documentation *)
121 let protocol_limit_warning =
122 "Because of the message protocol, there is a transfer limit
123 of somewhere between 2MB and 4MB. To transfer large files you should use
126 let danger_will_robinson =
127 "B<This command is dangerous. Without careful use you
128 can easily destroy all your data>."
130 (* You can supply zero or as many tests as you want per API call.
132 * Note that the test environment has 3 block devices, of size 500MB,
133 * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and
134 * a fourth squashfs block device with some known files on it (/dev/sdd).
136 * Note for partitioning purposes, the 500MB device has 63 cylinders.
138 * The squashfs block device (/dev/sdd) comes from images/test.sqsh.
140 * To be able to run the tests in a reasonable amount of time,
141 * the virtual machine and block devices are reused between tests.
142 * So don't try testing kill_subprocess :-x
144 * Between each test we blockdev-setrw, umount-all, lvm-remove-all.
146 * Don't assume anything about the previous contents of the block
147 * devices. Use 'Init*' to create some initial scenarios.
149 * You can add a prerequisite clause to any individual test. This
150 * is a run-time check, which, if it fails, causes the test to be
151 * skipped. Useful if testing a command which might not work on
152 * all variations of libguestfs builds. A test that has prerequisite
153 * of 'Always' is run unconditionally.
155 * In addition, packagers can skip individual tests by setting the
156 * environment variables: eg:
157 * SKIP_TEST_<CMD>_<NUM>=1 SKIP_TEST_COMMAND_3=1 (skips test #3 of command)
158 * SKIP_TEST_<CMD>=1 SKIP_TEST_ZEROFREE=1 (skips all zerofree tests)
160 type tests = (test_init * test_prereq * test) list
162 (* Run the command sequence and just expect nothing to fail. *)
164 (* Run the command sequence and expect the output of the final
165 * command to be the string.
167 | TestOutput of seq * string
168 (* Run the command sequence and expect the output of the final
169 * command to be the list of strings.
171 | TestOutputList of seq * string list
172 (* Run the command sequence and expect the output of the final
173 * command to be the list of block devices (could be either
174 * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
175 * character of each string).
177 | TestOutputListOfDevices of seq * string list
178 (* Run the command sequence and expect the output of the final
179 * command to be the integer.
181 | TestOutputInt of seq * int
182 (* Run the command sequence and expect the output of the final
183 * command to be a true value (!= 0 or != NULL).
185 | TestOutputTrue of seq
186 (* Run the command sequence and expect the output of the final
187 * command to be a false value (== 0 or == NULL, but not an error).
189 | TestOutputFalse of seq
190 (* Run the command sequence and expect the output of the final
191 * command to be a list of the given length (but don't care about
194 | TestOutputLength of seq * int
195 (* Run the command sequence and expect the output of the final
196 * command to be a structure.
198 | TestOutputStruct of seq * test_field_compare list
199 (* Run the command sequence and expect the final command (only)
202 | TestLastFail of seq
204 and test_field_compare =
205 | CompareWithInt of string * int
206 | CompareWithString of string * string
207 | CompareFieldsIntEq of string * string
208 | CompareFieldsStrEq of string * string
210 (* Test prerequisites. *)
212 (* Test always runs. *)
214 (* Test is currently disabled - eg. it fails, or it tests some
215 * unimplemented feature.
218 (* 'string' is some C code (a function body) that should return
219 * true or false. The test will run if the code returns true.
222 (* As for 'If' but the test runs _unless_ the code returns true. *)
225 (* Some initial scenarios for testing. *)
227 (* Do nothing, block devices could contain random stuff including
228 * LVM PVs, and some filesystems might be mounted. This is usually
232 (* Block devices are empty and no filesystems are mounted. *)
234 (* /dev/sda contains a single partition /dev/sda1, which is formatted
235 * as ext2, empty [except for lost+found] and mounted on /.
236 * /dev/sdb and /dev/sdc may have random content.
241 * /dev/sda1 (is a PV):
242 * /dev/VG/LV (size 8MB):
243 * formatted as ext2, empty [except for lost+found], mounted on /
244 * /dev/sdb and /dev/sdc may have random content.
248 (* Sequence of commands for testing. *)
250 and cmd = string list
252 (* Note about long descriptions: When referring to another
253 * action, use the format C<guestfs_other> (ie. the full name of
254 * the C function). This will be replaced as appropriate in other
257 * Apart from that, long descriptions are just perldoc paragraphs.
260 (* These test functions are used in the language binding tests. *)
262 let test_all_args = [
265 StringList "strlist";
272 let test_all_rets = [
273 (* except for RErr, which is tested thoroughly elsewhere *)
274 "test0rint", RInt "valout";
275 "test0rint64", RInt64 "valout";
276 "test0rbool", RBool "valout";
277 "test0rconststring", RConstString "valout";
278 "test0rstring", RString "valout";
279 "test0rstringlist", RStringList "valout";
280 "test0rintbool", RIntBool ("valout", "valout");
281 "test0rpvlist", RPVList "valout";
282 "test0rvglist", RVGList "valout";
283 "test0rlvlist", RLVList "valout";
284 "test0rstat", RStat "valout";
285 "test0rstatvfs", RStatVFS "valout";
286 "test0rhashtable", RHashtable "valout";
289 let test_functions = [
290 ("test0", (RErr, test_all_args), -1, [NotInFish; NotInDocs],
292 "internal test function - do not use",
294 This is an internal test function which is used to test whether
295 the automatically generated bindings can handle every possible
296 parameter type correctly.
298 It echos the contents of each parameter to stdout.
300 You probably don't want to call this function.");
304 [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs],
306 "internal test function - do not use",
308 This is an internal test function which is used to test whether
309 the automatically generated bindings can handle every possible
310 return type correctly.
312 It converts string C<val> to the return type.
314 You probably don't want to call this function.");
315 (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs],
317 "internal test function - do not use",
319 This is an internal test function which is used to test whether
320 the automatically generated bindings can handle every possible
321 return type correctly.
323 This function always returns an error.
325 You probably don't want to call this function.")]
329 (* non_daemon_functions are any functions which don't get processed
330 * in the daemon, eg. functions for setting and getting local
331 * configuration values.
334 let non_daemon_functions = test_functions @ [
335 ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"],
337 "launch the qemu subprocess",
339 Internally libguestfs is implemented by running a virtual machine
342 You should call this after configuring the handle
343 (eg. adding drives) but before performing any actions.");
345 ("wait_ready", (RErr, []), -1, [NotInFish],
347 "wait until the qemu subprocess launches",
349 Internally libguestfs is implemented by running a virtual machine
352 You should call this after C<guestfs_launch> to wait for the launch
355 ("kill_subprocess", (RErr, []), -1, [],
357 "kill the qemu subprocess",
359 This kills the qemu subprocess. You should never need to call this.");
361 ("add_drive", (RErr, [String "filename"]), -1, [FishAlias "add"],
363 "add an image to examine or modify",
365 This function adds a virtual machine disk image C<filename> to the
366 guest. The first time you call this function, the disk appears as IDE
367 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
370 You don't necessarily need to be root when using libguestfs. However
371 you obviously do need sufficient permissions to access the filename
372 for whatever operations you want to perform (ie. read access if you
373 just want to read the image or write access if you want to modify the
376 This is equivalent to the qemu parameter C<-drive file=filename,cache=off>.
378 Note that this call checks for the existence of C<filename>. This
379 stops you from specifying other types of drive which are supported
380 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
381 the general C<guestfs_config> call instead.");
383 ("add_cdrom", (RErr, [String "filename"]), -1, [FishAlias "cdrom"],
385 "add a CD-ROM disk image to examine",
387 This function adds a virtual CD-ROM disk image to the guest.
389 This is equivalent to the qemu parameter C<-cdrom filename>.
391 Note that this call checks for the existence of C<filename>. This
392 stops you from specifying other types of drive which are supported
393 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
394 the general C<guestfs_config> call instead.");
396 ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"],
398 "add a drive in snapshot mode (read-only)",
400 This adds a drive in snapshot mode, making it effectively
403 Note that writes to the device are allowed, and will be seen for
404 the duration of the guestfs handle, but they are written
405 to a temporary file which is discarded as soon as the guestfs
406 handle is closed. We don't currently have any method to enable
407 changes to be committed, although qemu can support this.
409 This is equivalent to the qemu parameter
410 C<-drive file=filename,snapshot=on>.
412 Note that this call checks for the existence of C<filename>. This
413 stops you from specifying other types of drive which are supported
414 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
415 the general C<guestfs_config> call instead.");
417 ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"]), -1, [],
419 "add qemu parameters",
421 This can be used to add arbitrary qemu command line parameters
422 of the form C<-param value>. Actually it's not quite arbitrary - we
423 prevent you from setting some parameters which would interfere with
424 parameters that we use.
426 The first character of C<param> string must be a C<-> (dash).
428 C<value> can be NULL.");
430 ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"],
432 "set the qemu binary",
434 Set the qemu binary that we will use.
436 The default is chosen when the library was compiled by the
439 You can also override this by setting the C<LIBGUESTFS_QEMU>
440 environment variable.
442 Setting C<qemu> to C<NULL> restores the default qemu binary.");
444 ("get_qemu", (RConstString "qemu", []), -1, [],
446 "get the qemu binary",
448 Return the current qemu binary.
450 This is always non-NULL. If it wasn't set already, then this will
451 return the default qemu binary name.");
453 ("set_path", (RErr, [String "path"]), -1, [FishAlias "path"],
455 "set the search path",
457 Set the path that libguestfs searches for kernel and initrd.img.
459 The default is C<$libdir/guestfs> unless overridden by setting
460 C<LIBGUESTFS_PATH> environment variable.
462 Setting C<path> to C<NULL> restores the default path.");
464 ("get_path", (RConstString "path", []), -1, [],
466 "get the search path",
468 Return the current search path.
470 This is always non-NULL. If it wasn't set already, then this will
471 return the default path.");
473 ("set_append", (RErr, [String "append"]), -1, [FishAlias "append"],
475 "add options to kernel command line",
477 This function is used to add additional options to the
478 guest kernel command line.
480 The default is C<NULL> unless overridden by setting
481 C<LIBGUESTFS_APPEND> environment variable.
483 Setting C<append> to C<NULL> means I<no> additional options
484 are passed (libguestfs always adds a few of its own).");
486 ("get_append", (RConstString "append", []), -1, [],
488 "get the additional kernel options",
490 Return the additional kernel options which are added to the
491 guest kernel command line.
493 If C<NULL> then no options are added.");
495 ("set_autosync", (RErr, [Bool "autosync"]), -1, [FishAlias "autosync"],
499 If C<autosync> is true, this enables autosync. Libguestfs will make a
500 best effort attempt to run C<guestfs_umount_all> followed by
501 C<guestfs_sync> when the handle is closed
502 (also if the program exits without closing handles).
504 This is disabled by default (except in guestfish where it is
505 enabled by default).");
507 ("get_autosync", (RBool "autosync", []), -1, [],
511 Get the autosync flag.");
513 ("set_verbose", (RErr, [Bool "verbose"]), -1, [FishAlias "verbose"],
517 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
519 Verbose messages are disabled unless the environment variable
520 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
522 ("get_verbose", (RBool "verbose", []), -1, [],
526 This returns the verbose messages flag.");
528 ("is_ready", (RBool "ready", []), -1, [],
530 "is ready to accept commands",
532 This returns true iff this handle is ready to accept commands
533 (in the C<READY> state).
535 For more information on states, see L<guestfs(3)>.");
537 ("is_config", (RBool "config", []), -1, [],
539 "is in configuration state",
541 This returns true iff this handle is being configured
542 (in the C<CONFIG> state).
544 For more information on states, see L<guestfs(3)>.");
546 ("is_launching", (RBool "launching", []), -1, [],
548 "is launching subprocess",
550 This returns true iff this handle is launching the subprocess
551 (in the C<LAUNCHING> state).
553 For more information on states, see L<guestfs(3)>.");
555 ("is_busy", (RBool "busy", []), -1, [],
557 "is busy processing a command",
559 This returns true iff this handle is busy processing a command
560 (in the C<BUSY> state).
562 For more information on states, see L<guestfs(3)>.");
564 ("get_state", (RInt "state", []), -1, [],
566 "get the current state",
568 This returns the current state as an opaque integer. This is
569 only useful for printing debug and internal error messages.
571 For more information on states, see L<guestfs(3)>.");
573 ("set_busy", (RErr, []), -1, [NotInFish],
577 This sets the state to C<BUSY>. This is only used when implementing
578 actions using the low-level API.
580 For more information on states, see L<guestfs(3)>.");
582 ("set_ready", (RErr, []), -1, [NotInFish],
584 "set state to ready",
586 This sets the state to C<READY>. This is only used when implementing
587 actions using the low-level API.
589 For more information on states, see L<guestfs(3)>.");
591 ("end_busy", (RErr, []), -1, [NotInFish],
593 "leave the busy state",
595 This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
596 state as is. This is only used when implementing
597 actions using the low-level API.
599 For more information on states, see L<guestfs(3)>.");
603 (* daemon_functions are any functions which cause some action
604 * to take place in the daemon.
607 let daemon_functions = [
608 ("mount", (RErr, [String "device"; String "mountpoint"]), 1, [],
609 [InitEmpty, Always, TestOutput (
610 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
611 ["mkfs"; "ext2"; "/dev/sda1"];
612 ["mount"; "/dev/sda1"; "/"];
613 ["write_file"; "/new"; "new file contents"; "0"];
614 ["cat"; "/new"]], "new file contents")],
615 "mount a guest disk at a position in the filesystem",
617 Mount a guest disk at a position in the filesystem. Block devices
618 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
619 the guest. If those block devices contain partitions, they will have
620 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
623 The rules are the same as for L<mount(2)>: A filesystem must
624 first be mounted on C</> before others can be mounted. Other
625 filesystems can only be mounted on directories which already
628 The mounted filesystem is writable, if we have sufficient permissions
629 on the underlying device.
631 The filesystem options C<sync> and C<noatime> are set with this
632 call, in order to improve reliability.");
634 ("sync", (RErr, []), 2, [],
635 [ InitEmpty, Always, TestRun [["sync"]]],
636 "sync disks, writes are flushed through to the disk image",
638 This syncs the disk, so that any writes are flushed through to the
639 underlying disk image.
641 You should always call this if you have modified a disk image, before
642 closing the handle.");
644 ("touch", (RErr, [String "path"]), 3, [],
645 [InitBasicFS, Always, TestOutputTrue (
647 ["exists"; "/new"]])],
648 "update file timestamps or create a new file",
650 Touch acts like the L<touch(1)> command. It can be used to
651 update the timestamps on a file, or, if the file does not exist,
652 to create a new zero-length file.");
654 ("cat", (RString "content", [String "path"]), 4, [ProtocolLimitWarning],
655 [InitBasicFS, Always, TestOutput (
656 [["write_file"; "/new"; "new file contents"; "0"];
657 ["cat"; "/new"]], "new file contents")],
658 "list the contents of a file",
660 Return the contents of the file named C<path>.
662 Note that this function cannot correctly handle binary files
663 (specifically, files containing C<\\0> character which is treated
664 as end of string). For those you need to use the C<guestfs_download>
665 function which has a more complex interface.");
667 ("ll", (RString "listing", [String "directory"]), 5, [],
668 [], (* XXX Tricky to test because it depends on the exact format
669 * of the 'ls -l' command, which changes between F10 and F11.
671 "list the files in a directory (long format)",
673 List the files in C<directory> (relative to the root directory,
674 there is no cwd) in the format of 'ls -la'.
676 This command is mostly useful for interactive sessions. It
677 is I<not> intended that you try to parse the output string.");
679 ("ls", (RStringList "listing", [String "directory"]), 6, [],
680 [InitBasicFS, Always, TestOutputList (
683 ["touch"; "/newest"];
684 ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])],
685 "list the files in a directory",
687 List the files in C<directory> (relative to the root directory,
688 there is no cwd). The '.' and '..' entries are not returned, but
689 hidden files are shown.
691 This command is mostly useful for interactive sessions. Programs
692 should probably use C<guestfs_readdir> instead.");
694 ("list_devices", (RStringList "devices", []), 7, [],
695 [InitEmpty, Always, TestOutputListOfDevices (
696 [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
697 "list the block devices",
699 List all the block devices.
701 The full block device names are returned, eg. C</dev/sda>");
703 ("list_partitions", (RStringList "partitions", []), 8, [],
704 [InitBasicFS, Always, TestOutputListOfDevices (
705 [["list_partitions"]], ["/dev/sda1"]);
706 InitEmpty, Always, TestOutputListOfDevices (
707 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
708 ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
709 "list the partitions",
711 List all the partitions detected on all block devices.
713 The full partition device names are returned, eg. C</dev/sda1>
715 This does not return logical volumes. For that you will need to
716 call C<guestfs_lvs>.");
718 ("pvs", (RStringList "physvols", []), 9, [],
719 [InitBasicFSonLVM, Always, TestOutputListOfDevices (
720 [["pvs"]], ["/dev/sda1"]);
721 InitEmpty, Always, TestOutputListOfDevices (
722 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
723 ["pvcreate"; "/dev/sda1"];
724 ["pvcreate"; "/dev/sda2"];
725 ["pvcreate"; "/dev/sda3"];
726 ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
727 "list the LVM physical volumes (PVs)",
729 List all the physical volumes detected. This is the equivalent
730 of the L<pvs(8)> command.
732 This returns a list of just the device names that contain
733 PVs (eg. C</dev/sda2>).
735 See also C<guestfs_pvs_full>.");
737 ("vgs", (RStringList "volgroups", []), 10, [],
738 [InitBasicFSonLVM, Always, TestOutputList (
740 InitEmpty, Always, TestOutputList (
741 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
742 ["pvcreate"; "/dev/sda1"];
743 ["pvcreate"; "/dev/sda2"];
744 ["pvcreate"; "/dev/sda3"];
745 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
746 ["vgcreate"; "VG2"; "/dev/sda3"];
747 ["vgs"]], ["VG1"; "VG2"])],
748 "list the LVM volume groups (VGs)",
750 List all the volumes groups detected. This is the equivalent
751 of the L<vgs(8)> command.
753 This returns a list of just the volume group names that were
754 detected (eg. C<VolGroup00>).
756 See also C<guestfs_vgs_full>.");
758 ("lvs", (RStringList "logvols", []), 11, [],
759 [InitBasicFSonLVM, Always, TestOutputList (
760 [["lvs"]], ["/dev/VG/LV"]);
761 InitEmpty, Always, TestOutputList (
762 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
763 ["pvcreate"; "/dev/sda1"];
764 ["pvcreate"; "/dev/sda2"];
765 ["pvcreate"; "/dev/sda3"];
766 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
767 ["vgcreate"; "VG2"; "/dev/sda3"];
768 ["lvcreate"; "LV1"; "VG1"; "50"];
769 ["lvcreate"; "LV2"; "VG1"; "50"];
770 ["lvcreate"; "LV3"; "VG2"; "50"];
771 ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
772 "list the LVM logical volumes (LVs)",
774 List all the logical volumes detected. This is the equivalent
775 of the L<lvs(8)> command.
777 This returns a list of the logical volume device names
778 (eg. C</dev/VolGroup00/LogVol00>).
780 See also C<guestfs_lvs_full>.");
782 ("pvs_full", (RPVList "physvols", []), 12, [],
783 [], (* XXX how to test? *)
784 "list the LVM physical volumes (PVs)",
786 List all the physical volumes detected. This is the equivalent
787 of the L<pvs(8)> command. The \"full\" version includes all fields.");
789 ("vgs_full", (RVGList "volgroups", []), 13, [],
790 [], (* XXX how to test? *)
791 "list the LVM volume groups (VGs)",
793 List all the volumes groups detected. This is the equivalent
794 of the L<vgs(8)> command. The \"full\" version includes all fields.");
796 ("lvs_full", (RLVList "logvols", []), 14, [],
797 [], (* XXX how to test? *)
798 "list the LVM logical volumes (LVs)",
800 List all the logical volumes detected. This is the equivalent
801 of the L<lvs(8)> command. The \"full\" version includes all fields.");
803 ("read_lines", (RStringList "lines", [String "path"]), 15, [],
804 [InitBasicFS, Always, TestOutputList (
805 [["write_file"; "/new"; "line1\r\nline2\nline3"; "0"];
806 ["read_lines"; "/new"]], ["line1"; "line2"; "line3"]);
807 InitBasicFS, Always, TestOutputList (
808 [["write_file"; "/new"; ""; "0"];
809 ["read_lines"; "/new"]], [])],
810 "read file as lines",
812 Return the contents of the file named C<path>.
814 The file contents are returned as a list of lines. Trailing
815 C<LF> and C<CRLF> character sequences are I<not> returned.
817 Note that this function cannot correctly handle binary files
818 (specifically, files containing C<\\0> character which is treated
819 as end of line). For those you need to use the C<guestfs_read_file>
820 function which has a more complex interface.");
822 ("aug_init", (RErr, [String "root"; Int "flags"]), 16, [],
823 [], (* XXX Augeas code needs tests. *)
824 "create a new Augeas handle",
826 Create a new Augeas handle for editing configuration files.
827 If there was any previous Augeas handle associated with this
828 guestfs session, then it is closed.
830 You must call this before using any other C<guestfs_aug_*>
833 C<root> is the filesystem root. C<root> must not be NULL,
836 The flags are the same as the flags defined in
837 E<lt>augeas.hE<gt>, the logical I<or> of the following
842 =item C<AUG_SAVE_BACKUP> = 1
844 Keep the original file with a C<.augsave> extension.
846 =item C<AUG_SAVE_NEWFILE> = 2
848 Save changes into a file with extension C<.augnew>, and
849 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
851 =item C<AUG_TYPE_CHECK> = 4
853 Typecheck lenses (can be expensive).
855 =item C<AUG_NO_STDINC> = 8
857 Do not use standard load path for modules.
859 =item C<AUG_SAVE_NOOP> = 16
861 Make save a no-op, just record what would have been changed.
863 =item C<AUG_NO_LOAD> = 32
865 Do not load the tree in C<guestfs_aug_init>.
869 To close the handle, you can call C<guestfs_aug_close>.
871 To find out more about Augeas, see L<http://augeas.net/>.");
873 ("aug_close", (RErr, []), 26, [],
874 [], (* XXX Augeas code needs tests. *)
875 "close the current Augeas handle",
877 Close the current Augeas handle and free up any resources
878 used by it. After calling this, you have to call
879 C<guestfs_aug_init> again before you can use any other
882 ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [],
883 [], (* XXX Augeas code needs tests. *)
884 "define an Augeas variable",
886 Defines an Augeas variable C<name> whose value is the result
887 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
890 On success this returns the number of nodes in C<expr>, or
891 C<0> if C<expr> evaluates to something which is not a nodeset.");
893 ("aug_defnode", (RIntBool ("nrnodes", "created"), [String "name"; String "expr"; String "val"]), 18, [],
894 [], (* XXX Augeas code needs tests. *)
895 "define an Augeas node",
897 Defines a variable C<name> whose value is the result of
900 If C<expr> evaluates to an empty nodeset, a node is created,
901 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
902 C<name> will be the nodeset containing that single node.
904 On success this returns a pair containing the
905 number of nodes in the nodeset, and a boolean flag
906 if a node was created.");
908 ("aug_get", (RString "val", [String "path"]), 19, [],
909 [], (* XXX Augeas code needs tests. *)
910 "look up the value of an Augeas path",
912 Look up the value associated with C<path>. If C<path>
913 matches exactly one node, the C<value> is returned.");
915 ("aug_set", (RErr, [String "path"; String "val"]), 20, [],
916 [], (* XXX Augeas code needs tests. *)
917 "set Augeas path to value",
919 Set the value associated with C<path> to C<value>.");
921 ("aug_insert", (RErr, [String "path"; String "label"; Bool "before"]), 21, [],
922 [], (* XXX Augeas code needs tests. *)
923 "insert a sibling Augeas node",
925 Create a new sibling C<label> for C<path>, inserting it into
926 the tree before or after C<path> (depending on the boolean
929 C<path> must match exactly one existing node in the tree, and
930 C<label> must be a label, ie. not contain C</>, C<*> or end
931 with a bracketed index C<[N]>.");
933 ("aug_rm", (RInt "nrnodes", [String "path"]), 22, [],
934 [], (* XXX Augeas code needs tests. *)
935 "remove an Augeas path",
937 Remove C<path> and all of its children.
939 On success this returns the number of entries which were removed.");
941 ("aug_mv", (RErr, [String "src"; String "dest"]), 23, [],
942 [], (* XXX Augeas code needs tests. *)
945 Move the node C<src> to C<dest>. C<src> must match exactly
946 one node. C<dest> is overwritten if it exists.");
948 ("aug_match", (RStringList "matches", [String "path"]), 24, [],
949 [], (* XXX Augeas code needs tests. *)
950 "return Augeas nodes which match path",
952 Returns a list of paths which match the path expression C<path>.
953 The returned paths are sufficiently qualified so that they match
954 exactly one node in the current tree.");
956 ("aug_save", (RErr, []), 25, [],
957 [], (* XXX Augeas code needs tests. *)
958 "write all pending Augeas changes to disk",
960 This writes all pending changes to disk.
962 The flags which were passed to C<guestfs_aug_init> affect exactly
963 how files are saved.");
965 ("aug_load", (RErr, []), 27, [],
966 [], (* XXX Augeas code needs tests. *)
967 "load files into the tree",
969 Load files into the tree.
971 See C<aug_load> in the Augeas documentation for the full gory
974 ("aug_ls", (RStringList "matches", [String "path"]), 28, [],
975 [], (* XXX Augeas code needs tests. *)
976 "list Augeas nodes under a path",
978 This is just a shortcut for listing C<guestfs_aug_match>
979 C<path/*> and sorting the resulting nodes into alphabetical order.");
981 ("rm", (RErr, [String "path"]), 29, [],
982 [InitBasicFS, Always, TestRun
985 InitBasicFS, Always, TestLastFail
987 InitBasicFS, Always, TestLastFail
992 Remove the single file C<path>.");
994 ("rmdir", (RErr, [String "path"]), 30, [],
995 [InitBasicFS, Always, TestRun
998 InitBasicFS, Always, TestLastFail
1000 InitBasicFS, Always, TestLastFail
1002 ["rmdir"; "/new"]]],
1003 "remove a directory",
1005 Remove the single directory C<path>.");
1007 ("rm_rf", (RErr, [String "path"]), 31, [],
1008 [InitBasicFS, Always, TestOutputFalse
1010 ["mkdir"; "/new/foo"];
1011 ["touch"; "/new/foo/bar"];
1013 ["exists"; "/new"]]],
1014 "remove a file or directory recursively",
1016 Remove the file or directory C<path>, recursively removing the
1017 contents if its a directory. This is like the C<rm -rf> shell
1020 ("mkdir", (RErr, [String "path"]), 32, [],
1021 [InitBasicFS, Always, TestOutputTrue
1023 ["is_dir"; "/new"]];
1024 InitBasicFS, Always, TestLastFail
1025 [["mkdir"; "/new/foo/bar"]]],
1026 "create a directory",
1028 Create a directory named C<path>.");
1030 ("mkdir_p", (RErr, [String "path"]), 33, [],
1031 [InitBasicFS, Always, TestOutputTrue
1032 [["mkdir_p"; "/new/foo/bar"];
1033 ["is_dir"; "/new/foo/bar"]];
1034 InitBasicFS, Always, TestOutputTrue
1035 [["mkdir_p"; "/new/foo/bar"];
1036 ["is_dir"; "/new/foo"]];
1037 InitBasicFS, Always, TestOutputTrue
1038 [["mkdir_p"; "/new/foo/bar"];
1039 ["is_dir"; "/new"]];
1040 (* Regression tests for RHBZ#503133: *)
1041 InitBasicFS, Always, TestRun
1043 ["mkdir_p"; "/new"]];
1044 InitBasicFS, Always, TestLastFail
1046 ["mkdir_p"; "/new"]]],
1047 "create a directory and parents",
1049 Create a directory named C<path>, creating any parent directories
1050 as necessary. This is like the C<mkdir -p> shell command.");
1052 ("chmod", (RErr, [Int "mode"; String "path"]), 34, [],
1053 [], (* XXX Need stat command to test *)
1056 Change the mode (permissions) of C<path> to C<mode>. Only
1057 numeric modes are supported.");
1059 ("chown", (RErr, [Int "owner"; Int "group"; String "path"]), 35, [],
1060 [], (* XXX Need stat command to test *)
1061 "change file owner and group",
1063 Change the file owner to C<owner> and group to C<group>.
1065 Only numeric uid and gid are supported. If you want to use
1066 names, you will need to locate and parse the password file
1067 yourself (Augeas support makes this relatively easy).");
1069 ("exists", (RBool "existsflag", [String "path"]), 36, [],
1070 [InitBasicFS, Always, TestOutputTrue (
1072 ["exists"; "/new"]]);
1073 InitBasicFS, Always, TestOutputTrue (
1075 ["exists"; "/new"]])],
1076 "test if file or directory exists",
1078 This returns C<true> if and only if there is a file, directory
1079 (or anything) with the given C<path> name.
1081 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
1083 ("is_file", (RBool "fileflag", [String "path"]), 37, [],
1084 [InitBasicFS, Always, TestOutputTrue (
1086 ["is_file"; "/new"]]);
1087 InitBasicFS, Always, TestOutputFalse (
1089 ["is_file"; "/new"]])],
1090 "test if file exists",
1092 This returns C<true> if and only if there is a file
1093 with the given C<path> name. Note that it returns false for
1094 other objects like directories.
1096 See also C<guestfs_stat>.");
1098 ("is_dir", (RBool "dirflag", [String "path"]), 38, [],
1099 [InitBasicFS, Always, TestOutputFalse (
1101 ["is_dir"; "/new"]]);
1102 InitBasicFS, Always, TestOutputTrue (
1104 ["is_dir"; "/new"]])],
1105 "test if file exists",
1107 This returns C<true> if and only if there is a directory
1108 with the given C<path> name. Note that it returns false for
1109 other objects like files.
1111 See also C<guestfs_stat>.");
1113 ("pvcreate", (RErr, [String "device"]), 39, [],
1114 [InitEmpty, Always, TestOutputListOfDevices (
1115 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
1116 ["pvcreate"; "/dev/sda1"];
1117 ["pvcreate"; "/dev/sda2"];
1118 ["pvcreate"; "/dev/sda3"];
1119 ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1120 "create an LVM physical volume",
1122 This creates an LVM physical volume on the named C<device>,
1123 where C<device> should usually be a partition name such
1126 ("vgcreate", (RErr, [String "volgroup"; StringList "physvols"]), 40, [],
1127 [InitEmpty, Always, TestOutputList (
1128 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
1129 ["pvcreate"; "/dev/sda1"];
1130 ["pvcreate"; "/dev/sda2"];
1131 ["pvcreate"; "/dev/sda3"];
1132 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1133 ["vgcreate"; "VG2"; "/dev/sda3"];
1134 ["vgs"]], ["VG1"; "VG2"])],
1135 "create an LVM volume group",
1137 This creates an LVM volume group called C<volgroup>
1138 from the non-empty list of physical volumes C<physvols>.");
1140 ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"]), 41, [],
1141 [InitEmpty, Always, TestOutputList (
1142 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
1143 ["pvcreate"; "/dev/sda1"];
1144 ["pvcreate"; "/dev/sda2"];
1145 ["pvcreate"; "/dev/sda3"];
1146 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1147 ["vgcreate"; "VG2"; "/dev/sda3"];
1148 ["lvcreate"; "LV1"; "VG1"; "50"];
1149 ["lvcreate"; "LV2"; "VG1"; "50"];
1150 ["lvcreate"; "LV3"; "VG2"; "50"];
1151 ["lvcreate"; "LV4"; "VG2"; "50"];
1152 ["lvcreate"; "LV5"; "VG2"; "50"];
1154 ["/dev/VG1/LV1"; "/dev/VG1/LV2";
1155 "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
1156 "create an LVM volume group",
1158 This creates an LVM volume group called C<logvol>
1159 on the volume group C<volgroup>, with C<size> megabytes.");
1161 ("mkfs", (RErr, [String "fstype"; String "device"]), 42, [],
1162 [InitEmpty, Always, TestOutput (
1163 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1164 ["mkfs"; "ext2"; "/dev/sda1"];
1165 ["mount"; "/dev/sda1"; "/"];
1166 ["write_file"; "/new"; "new file contents"; "0"];
1167 ["cat"; "/new"]], "new file contents")],
1168 "make a filesystem",
1170 This creates a filesystem on C<device> (usually a partition
1171 or LVM logical volume). The filesystem type is C<fstype>, for
1174 ("sfdisk", (RErr, [String "device";
1175 Int "cyls"; Int "heads"; Int "sectors";
1176 StringList "lines"]), 43, [DangerWillRobinson],
1178 "create partitions on a block device",
1180 This is a direct interface to the L<sfdisk(8)> program for creating
1181 partitions on block devices.
1183 C<device> should be a block device, for example C</dev/sda>.
1185 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1186 and sectors on the device, which are passed directly to sfdisk as
1187 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
1188 of these, then the corresponding parameter is omitted. Usually for
1189 'large' disks, you can just pass C<0> for these, but for small
1190 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1191 out the right geometry and you will need to tell it.
1193 C<lines> is a list of lines that we feed to C<sfdisk>. For more
1194 information refer to the L<sfdisk(8)> manpage.
1196 To create a single partition occupying the whole disk, you would
1197 pass C<lines> as a single element list, when the single element being
1198 the string C<,> (comma).
1200 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>");
1202 ("write_file", (RErr, [String "path"; String "content"; Int "size"]), 44, [ProtocolLimitWarning],
1203 [InitBasicFS, Always, TestOutput (
1204 [["write_file"; "/new"; "new file contents"; "0"];
1205 ["cat"; "/new"]], "new file contents");
1206 InitBasicFS, Always, TestOutput (
1207 [["write_file"; "/new"; "\nnew file contents\n"; "0"];
1208 ["cat"; "/new"]], "\nnew file contents\n");
1209 InitBasicFS, Always, TestOutput (
1210 [["write_file"; "/new"; "\n\n"; "0"];
1211 ["cat"; "/new"]], "\n\n");
1212 InitBasicFS, Always, TestOutput (
1213 [["write_file"; "/new"; ""; "0"];
1214 ["cat"; "/new"]], "");
1215 InitBasicFS, Always, TestOutput (
1216 [["write_file"; "/new"; "\n\n\n"; "0"];
1217 ["cat"; "/new"]], "\n\n\n");
1218 InitBasicFS, Always, TestOutput (
1219 [["write_file"; "/new"; "\n"; "0"];
1220 ["cat"; "/new"]], "\n")],
1223 This call creates a file called C<path>. The contents of the
1224 file is the string C<content> (which can contain any 8 bit data),
1225 with length C<size>.
1227 As a special case, if C<size> is C<0>
1228 then the length is calculated using C<strlen> (so in this case
1229 the content cannot contain embedded ASCII NULs).
1231 I<NB.> Owing to a bug, writing content containing ASCII NUL
1232 characters does I<not> work, even if the length is specified.
1233 We hope to resolve this bug in a future version. In the meantime
1234 use C<guestfs_upload>.");
1236 ("umount", (RErr, [String "pathordevice"]), 45, [FishAlias "unmount"],
1237 [InitEmpty, Always, TestOutputListOfDevices (
1238 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1239 ["mkfs"; "ext2"; "/dev/sda1"];
1240 ["mount"; "/dev/sda1"; "/"];
1241 ["mounts"]], ["/dev/sda1"]);
1242 InitEmpty, Always, TestOutputList (
1243 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1244 ["mkfs"; "ext2"; "/dev/sda1"];
1245 ["mount"; "/dev/sda1"; "/"];
1248 "unmount a filesystem",
1250 This unmounts the given filesystem. The filesystem may be
1251 specified either by its mountpoint (path) or the device which
1252 contains the filesystem.");
1254 ("mounts", (RStringList "devices", []), 46, [],
1255 [InitBasicFS, Always, TestOutputListOfDevices (
1256 [["mounts"]], ["/dev/sda1"])],
1257 "show mounted filesystems",
1259 This returns the list of currently mounted filesystems. It returns
1260 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1262 Some internal mounts are not shown.");
1264 ("umount_all", (RErr, []), 47, [FishAlias "unmount-all"],
1265 [InitBasicFS, Always, TestOutputList (
1268 (* check that umount_all can unmount nested mounts correctly: *)
1269 InitEmpty, Always, TestOutputList (
1270 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
1271 ["mkfs"; "ext2"; "/dev/sda1"];
1272 ["mkfs"; "ext2"; "/dev/sda2"];
1273 ["mkfs"; "ext2"; "/dev/sda3"];
1274 ["mount"; "/dev/sda1"; "/"];
1276 ["mount"; "/dev/sda2"; "/mp1"];
1277 ["mkdir"; "/mp1/mp2"];
1278 ["mount"; "/dev/sda3"; "/mp1/mp2"];
1279 ["mkdir"; "/mp1/mp2/mp3"];
1282 "unmount all filesystems",
1284 This unmounts all mounted filesystems.
1286 Some internal mounts are not unmounted by this call.");
1288 ("lvm_remove_all", (RErr, []), 48, [DangerWillRobinson],
1290 "remove all LVM LVs, VGs and PVs",
1292 This command removes all LVM logical volumes, volume groups
1293 and physical volumes.");
1295 ("file", (RString "description", [String "path"]), 49, [],
1296 [InitBasicFS, Always, TestOutput (
1298 ["file"; "/new"]], "empty");
1299 InitBasicFS, Always, TestOutput (
1300 [["write_file"; "/new"; "some content\n"; "0"];
1301 ["file"; "/new"]], "ASCII text");
1302 InitBasicFS, Always, TestLastFail (
1303 [["file"; "/nofile"]])],
1304 "determine file type",
1306 This call uses the standard L<file(1)> command to determine
1307 the type or contents of the file. This also works on devices,
1308 for example to find out whether a partition contains a filesystem.
1310 The exact command which runs is C<file -bsL path>. Note in
1311 particular that the filename is not prepended to the output
1312 (the C<-b> option).");
1314 ("command", (RString "output", [StringList "arguments"]), 50, [ProtocolLimitWarning],
1315 [InitBasicFS, Always, TestOutput (
1316 [["upload"; "test-command"; "/test-command"];
1317 ["chmod"; "493"; "/test-command"];
1318 ["command"; "/test-command 1"]], "Result1");
1319 InitBasicFS, Always, TestOutput (
1320 [["upload"; "test-command"; "/test-command"];
1321 ["chmod"; "493"; "/test-command"];
1322 ["command"; "/test-command 2"]], "Result2\n");
1323 InitBasicFS, Always, TestOutput (
1324 [["upload"; "test-command"; "/test-command"];
1325 ["chmod"; "493"; "/test-command"];
1326 ["command"; "/test-command 3"]], "\nResult3");
1327 InitBasicFS, Always, TestOutput (
1328 [["upload"; "test-command"; "/test-command"];
1329 ["chmod"; "493"; "/test-command"];
1330 ["command"; "/test-command 4"]], "\nResult4\n");
1331 InitBasicFS, Always, TestOutput (
1332 [["upload"; "test-command"; "/test-command"];
1333 ["chmod"; "493"; "/test-command"];
1334 ["command"; "/test-command 5"]], "\nResult5\n\n");
1335 InitBasicFS, Always, TestOutput (
1336 [["upload"; "test-command"; "/test-command"];
1337 ["chmod"; "493"; "/test-command"];
1338 ["command"; "/test-command 6"]], "\n\nResult6\n\n");
1339 InitBasicFS, Always, TestOutput (
1340 [["upload"; "test-command"; "/test-command"];
1341 ["chmod"; "493"; "/test-command"];
1342 ["command"; "/test-command 7"]], "");
1343 InitBasicFS, Always, TestOutput (
1344 [["upload"; "test-command"; "/test-command"];
1345 ["chmod"; "493"; "/test-command"];
1346 ["command"; "/test-command 8"]], "\n");
1347 InitBasicFS, Always, TestOutput (
1348 [["upload"; "test-command"; "/test-command"];
1349 ["chmod"; "493"; "/test-command"];
1350 ["command"; "/test-command 9"]], "\n\n");
1351 InitBasicFS, Always, TestOutput (
1352 [["upload"; "test-command"; "/test-command"];
1353 ["chmod"; "493"; "/test-command"];
1354 ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n");
1355 InitBasicFS, Always, TestOutput (
1356 [["upload"; "test-command"; "/test-command"];
1357 ["chmod"; "493"; "/test-command"];
1358 ["command"; "/test-command 11"]], "Result11-1\nResult11-2");
1359 InitBasicFS, Always, TestLastFail (
1360 [["upload"; "test-command"; "/test-command"];
1361 ["chmod"; "493"; "/test-command"];
1362 ["command"; "/test-command"]])],
1363 "run a command from the guest filesystem",
1365 This call runs a command from the guest filesystem. The
1366 filesystem must be mounted, and must contain a compatible
1367 operating system (ie. something Linux, with the same
1368 or compatible processor architecture).
1370 The single parameter is an argv-style list of arguments.
1371 The first element is the name of the program to run.
1372 Subsequent elements are parameters. The list must be
1373 non-empty (ie. must contain a program name). Note that
1374 the command runs directly, and is I<not> invoked via
1375 the shell (see C<guestfs_sh>).
1377 The return value is anything printed to I<stdout> by
1380 If the command returns a non-zero exit status, then
1381 this function returns an error message. The error message
1382 string is the content of I<stderr> from the command.
1384 The C<$PATH> environment variable will contain at least
1385 C</usr/bin> and C</bin>. If you require a program from
1386 another location, you should provide the full path in the
1389 Shared libraries and data files required by the program
1390 must be available on filesystems which are mounted in the
1391 correct places. It is the caller's responsibility to ensure
1392 all filesystems that are needed are mounted at the right
1395 ("command_lines", (RStringList "lines", [StringList "arguments"]), 51, [ProtocolLimitWarning],
1396 [InitBasicFS, Always, TestOutputList (
1397 [["upload"; "test-command"; "/test-command"];
1398 ["chmod"; "493"; "/test-command"];
1399 ["command_lines"; "/test-command 1"]], ["Result1"]);
1400 InitBasicFS, Always, TestOutputList (
1401 [["upload"; "test-command"; "/test-command"];
1402 ["chmod"; "493"; "/test-command"];
1403 ["command_lines"; "/test-command 2"]], ["Result2"]);
1404 InitBasicFS, Always, TestOutputList (
1405 [["upload"; "test-command"; "/test-command"];
1406 ["chmod"; "493"; "/test-command"];
1407 ["command_lines"; "/test-command 3"]], ["";"Result3"]);
1408 InitBasicFS, Always, TestOutputList (
1409 [["upload"; "test-command"; "/test-command"];
1410 ["chmod"; "493"; "/test-command"];
1411 ["command_lines"; "/test-command 4"]], ["";"Result4"]);
1412 InitBasicFS, Always, TestOutputList (
1413 [["upload"; "test-command"; "/test-command"];
1414 ["chmod"; "493"; "/test-command"];
1415 ["command_lines"; "/test-command 5"]], ["";"Result5";""]);
1416 InitBasicFS, Always, TestOutputList (
1417 [["upload"; "test-command"; "/test-command"];
1418 ["chmod"; "493"; "/test-command"];
1419 ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]);
1420 InitBasicFS, Always, TestOutputList (
1421 [["upload"; "test-command"; "/test-command"];
1422 ["chmod"; "493"; "/test-command"];
1423 ["command_lines"; "/test-command 7"]], []);
1424 InitBasicFS, Always, TestOutputList (
1425 [["upload"; "test-command"; "/test-command"];
1426 ["chmod"; "493"; "/test-command"];
1427 ["command_lines"; "/test-command 8"]], [""]);
1428 InitBasicFS, Always, TestOutputList (
1429 [["upload"; "test-command"; "/test-command"];
1430 ["chmod"; "493"; "/test-command"];
1431 ["command_lines"; "/test-command 9"]], ["";""]);
1432 InitBasicFS, Always, TestOutputList (
1433 [["upload"; "test-command"; "/test-command"];
1434 ["chmod"; "493"; "/test-command"];
1435 ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]);
1436 InitBasicFS, Always, TestOutputList (
1437 [["upload"; "test-command"; "/test-command"];
1438 ["chmod"; "493"; "/test-command"];
1439 ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])],
1440 "run a command, returning lines",
1442 This is the same as C<guestfs_command>, but splits the
1443 result into a list of lines.
1445 See also: C<guestfs_sh_lines>");
1447 ("stat", (RStat "statbuf", [String "path"]), 52, [],
1448 [InitBasicFS, Always, TestOutputStruct (
1450 ["stat"; "/new"]], [CompareWithInt ("size", 0)])],
1451 "get file information",
1453 Returns file information for the given C<path>.
1455 This is the same as the C<stat(2)> system call.");
1457 ("lstat", (RStat "statbuf", [String "path"]), 53, [],
1458 [InitBasicFS, Always, TestOutputStruct (
1460 ["lstat"; "/new"]], [CompareWithInt ("size", 0)])],
1461 "get file information for a symbolic link",
1463 Returns file information for the given C<path>.
1465 This is the same as C<guestfs_stat> except that if C<path>
1466 is a symbolic link, then the link is stat-ed, not the file it
1469 This is the same as the C<lstat(2)> system call.");
1471 ("statvfs", (RStatVFS "statbuf", [String "path"]), 54, [],
1472 [InitBasicFS, Always, TestOutputStruct (
1473 [["statvfs"; "/"]], [CompareWithInt ("bfree", 487702);
1474 CompareWithInt ("blocks", 490020);
1475 CompareWithInt ("bsize", 1024)])],
1476 "get file system statistics",
1478 Returns file system statistics for any mounted file system.
1479 C<path> should be a file or directory in the mounted file system
1480 (typically it is the mount point itself, but it doesn't need to be).
1482 This is the same as the C<statvfs(2)> system call.");
1484 ("tune2fs_l", (RHashtable "superblock", [String "device"]), 55, [],
1486 "get ext2/ext3/ext4 superblock details",
1488 This returns the contents of the ext2, ext3 or ext4 filesystem
1489 superblock on C<device>.
1491 It is the same as running C<tune2fs -l device>. See L<tune2fs(8)>
1492 manpage for more details. The list of fields returned isn't
1493 clearly defined, and depends on both the version of C<tune2fs>
1494 that libguestfs was built against, and the filesystem itself.");
1496 ("blockdev_setro", (RErr, [String "device"]), 56, [],
1497 [InitEmpty, Always, TestOutputTrue (
1498 [["blockdev_setro"; "/dev/sda"];
1499 ["blockdev_getro"; "/dev/sda"]])],
1500 "set block device to read-only",
1502 Sets the block device named C<device> to read-only.
1504 This uses the L<blockdev(8)> command.");
1506 ("blockdev_setrw", (RErr, [String "device"]), 57, [],
1507 [InitEmpty, Always, TestOutputFalse (
1508 [["blockdev_setrw"; "/dev/sda"];
1509 ["blockdev_getro"; "/dev/sda"]])],
1510 "set block device to read-write",
1512 Sets the block device named C<device> to read-write.
1514 This uses the L<blockdev(8)> command.");
1516 ("blockdev_getro", (RBool "ro", [String "device"]), 58, [],
1517 [InitEmpty, Always, TestOutputTrue (
1518 [["blockdev_setro"; "/dev/sda"];
1519 ["blockdev_getro"; "/dev/sda"]])],
1520 "is block device set to read-only",
1522 Returns a boolean indicating if the block device is read-only
1523 (true if read-only, false if not).
1525 This uses the L<blockdev(8)> command.");
1527 ("blockdev_getss", (RInt "sectorsize", [String "device"]), 59, [],
1528 [InitEmpty, Always, TestOutputInt (
1529 [["blockdev_getss"; "/dev/sda"]], 512)],
1530 "get sectorsize of block device",
1532 This returns the size of sectors on a block device.
1533 Usually 512, but can be larger for modern devices.
1535 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
1538 This uses the L<blockdev(8)> command.");
1540 ("blockdev_getbsz", (RInt "blocksize", [String "device"]), 60, [],
1541 [InitEmpty, Always, TestOutputInt (
1542 [["blockdev_getbsz"; "/dev/sda"]], 4096)],
1543 "get blocksize of block device",
1545 This returns the block size of a device.
1547 (Note this is different from both I<size in blocks> and
1548 I<filesystem block size>).
1550 This uses the L<blockdev(8)> command.");
1552 ("blockdev_setbsz", (RErr, [String "device"; Int "blocksize"]), 61, [],
1554 "set blocksize of block device",
1556 This sets the block size of a device.
1558 (Note this is different from both I<size in blocks> and
1559 I<filesystem block size>).
1561 This uses the L<blockdev(8)> command.");
1563 ("blockdev_getsz", (RInt64 "sizeinsectors", [String "device"]), 62, [],
1564 [InitEmpty, Always, TestOutputInt (
1565 [["blockdev_getsz"; "/dev/sda"]], 1024000)],
1566 "get total size of device in 512-byte sectors",
1568 This returns the size of the device in units of 512-byte sectors
1569 (even if the sectorsize isn't 512 bytes ... weird).
1571 See also C<guestfs_blockdev_getss> for the real sector size of
1572 the device, and C<guestfs_blockdev_getsize64> for the more
1573 useful I<size in bytes>.
1575 This uses the L<blockdev(8)> command.");
1577 ("blockdev_getsize64", (RInt64 "sizeinbytes", [String "device"]), 63, [],
1578 [InitEmpty, Always, TestOutputInt (
1579 [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
1580 "get total size of device in bytes",
1582 This returns the size of the device in bytes.
1584 See also C<guestfs_blockdev_getsz>.
1586 This uses the L<blockdev(8)> command.");
1588 ("blockdev_flushbufs", (RErr, [String "device"]), 64, [],
1589 [InitEmpty, Always, TestRun
1590 [["blockdev_flushbufs"; "/dev/sda"]]],
1591 "flush device buffers",
1593 This tells the kernel to flush internal buffers associated
1596 This uses the L<blockdev(8)> command.");
1598 ("blockdev_rereadpt", (RErr, [String "device"]), 65, [],
1599 [InitEmpty, Always, TestRun
1600 [["blockdev_rereadpt"; "/dev/sda"]]],
1601 "reread partition table",
1603 Reread the partition table on C<device>.
1605 This uses the L<blockdev(8)> command.");
1607 ("upload", (RErr, [FileIn "filename"; String "remotefilename"]), 66, [],
1608 [InitBasicFS, Always, TestOutput (
1609 (* Pick a file from cwd which isn't likely to change. *)
1610 [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1611 ["checksum"; "md5"; "/COPYING.LIB"]], "e3eda01d9815f8d24aae2dbd89b68b06")],
1612 "upload a file from the local machine",
1614 Upload local file C<filename> to C<remotefilename> on the
1617 C<filename> can also be a named pipe.
1619 See also C<guestfs_download>.");
1621 ("download", (RErr, [String "remotefilename"; FileOut "filename"]), 67, [],
1622 [InitBasicFS, Always, TestOutput (
1623 (* Pick a file from cwd which isn't likely to change. *)
1624 [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1625 ["download"; "/COPYING.LIB"; "testdownload.tmp"];
1626 ["upload"; "testdownload.tmp"; "/upload"];
1627 ["checksum"; "md5"; "/upload"]], "e3eda01d9815f8d24aae2dbd89b68b06")],
1628 "download a file to the local machine",
1630 Download file C<remotefilename> and save it as C<filename>
1631 on the local machine.
1633 C<filename> can also be a named pipe.
1635 See also C<guestfs_upload>, C<guestfs_cat>.");
1637 ("checksum", (RString "checksum", [String "csumtype"; String "path"]), 68, [],
1638 [InitBasicFS, Always, TestOutput (
1639 [["write_file"; "/new"; "test\n"; "0"];
1640 ["checksum"; "crc"; "/new"]], "935282863");
1641 InitBasicFS, Always, TestLastFail (
1642 [["checksum"; "crc"; "/new"]]);
1643 InitBasicFS, Always, TestOutput (
1644 [["write_file"; "/new"; "test\n"; "0"];
1645 ["checksum"; "md5"; "/new"]], "d8e8fca2dc0f896fd7cb4cb0031ba249");
1646 InitBasicFS, Always, TestOutput (
1647 [["write_file"; "/new"; "test\n"; "0"];
1648 ["checksum"; "sha1"; "/new"]], "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83");
1649 InitBasicFS, Always, TestOutput (
1650 [["write_file"; "/new"; "test\n"; "0"];
1651 ["checksum"; "sha224"; "/new"]], "52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec");
1652 InitBasicFS, Always, TestOutput (
1653 [["write_file"; "/new"; "test\n"; "0"];
1654 ["checksum"; "sha256"; "/new"]], "f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2");
1655 InitBasicFS, Always, TestOutput (
1656 [["write_file"; "/new"; "test\n"; "0"];
1657 ["checksum"; "sha384"; "/new"]], "109bb6b5b6d5547c1ce03c7a8bd7d8f80c1cb0957f50c4f7fda04692079917e4f9cad52b878f3d8234e1a170b154b72d");
1658 InitBasicFS, Always, TestOutput (
1659 [["write_file"; "/new"; "test\n"; "0"];
1660 ["checksum"; "sha512"; "/new"]], "0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123");
1661 InitBasicFS, Always, TestOutput (
1662 (* RHEL 5 thinks this is an HFS+ filesystem unless we give
1663 * the type explicitly.
1665 [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
1666 ["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c")],
1667 "compute MD5, SHAx or CRC checksum of file",
1669 This call computes the MD5, SHAx or CRC checksum of the
1672 The type of checksum to compute is given by the C<csumtype>
1673 parameter which must have one of the following values:
1679 Compute the cyclic redundancy check (CRC) specified by POSIX
1680 for the C<cksum> command.
1684 Compute the MD5 hash (using the C<md5sum> program).
1688 Compute the SHA1 hash (using the C<sha1sum> program).
1692 Compute the SHA224 hash (using the C<sha224sum> program).
1696 Compute the SHA256 hash (using the C<sha256sum> program).
1700 Compute the SHA384 hash (using the C<sha384sum> program).
1704 Compute the SHA512 hash (using the C<sha512sum> program).
1708 The checksum is returned as a printable string.");
1710 ("tar_in", (RErr, [FileIn "tarfile"; String "directory"]), 69, [],
1711 [InitBasicFS, Always, TestOutput (
1712 [["tar_in"; "../images/helloworld.tar"; "/"];
1713 ["cat"; "/hello"]], "hello\n")],
1714 "unpack tarfile to directory",
1716 This command uploads and unpacks local file C<tarfile> (an
1717 I<uncompressed> tar file) into C<directory>.
1719 To upload a compressed tarball, use C<guestfs_tgz_in>.");
1721 ("tar_out", (RErr, [String "directory"; FileOut "tarfile"]), 70, [],
1723 "pack directory into tarfile",
1725 This command packs the contents of C<directory> and downloads
1726 it to local file C<tarfile>.
1728 To download a compressed tarball, use C<guestfs_tgz_out>.");
1730 ("tgz_in", (RErr, [FileIn "tarball"; String "directory"]), 71, [],
1731 [InitBasicFS, Always, TestOutput (
1732 [["tgz_in"; "../images/helloworld.tar.gz"; "/"];
1733 ["cat"; "/hello"]], "hello\n")],
1734 "unpack compressed tarball to directory",
1736 This command uploads and unpacks local file C<tarball> (a
1737 I<gzip compressed> tar file) into C<directory>.
1739 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
1741 ("tgz_out", (RErr, [String "directory"; FileOut "tarball"]), 72, [],
1743 "pack directory into compressed tarball",
1745 This command packs the contents of C<directory> and downloads
1746 it to local file C<tarball>.
1748 To download an uncompressed tarball, use C<guestfs_tar_out>.");
1750 ("mount_ro", (RErr, [String "device"; String "mountpoint"]), 73, [],
1751 [InitBasicFS, Always, TestLastFail (
1753 ["mount_ro"; "/dev/sda1"; "/"];
1754 ["touch"; "/new"]]);
1755 InitBasicFS, Always, TestOutput (
1756 [["write_file"; "/new"; "data"; "0"];
1758 ["mount_ro"; "/dev/sda1"; "/"];
1759 ["cat"; "/new"]], "data")],
1760 "mount a guest disk, read-only",
1762 This is the same as the C<guestfs_mount> command, but it
1763 mounts the filesystem with the read-only (I<-o ro>) flag.");
1765 ("mount_options", (RErr, [String "options"; String "device"; String "mountpoint"]), 74, [],
1767 "mount a guest disk with mount options",
1769 This is the same as the C<guestfs_mount> command, but it
1770 allows you to set the mount options as for the
1771 L<mount(8)> I<-o> flag.");
1773 ("mount_vfs", (RErr, [String "options"; String "vfstype"; String "device"; String "mountpoint"]), 75, [],
1775 "mount a guest disk with mount options and vfstype",
1777 This is the same as the C<guestfs_mount> command, but it
1778 allows you to set both the mount options and the vfstype
1779 as for the L<mount(8)> I<-o> and I<-t> flags.");
1781 ("debug", (RString "result", [String "subcmd"; StringList "extraargs"]), 76, [],
1783 "debugging and internals",
1785 The C<guestfs_debug> command exposes some internals of
1786 C<guestfsd> (the guestfs daemon) that runs inside the
1789 There is no comprehensive help for this command. You have
1790 to look at the file C<daemon/debug.c> in the libguestfs source
1791 to find out what you can do.");
1793 ("lvremove", (RErr, [String "device"]), 77, [],
1794 [InitEmpty, Always, TestOutputList (
1795 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1796 ["pvcreate"; "/dev/sda1"];
1797 ["vgcreate"; "VG"; "/dev/sda1"];
1798 ["lvcreate"; "LV1"; "VG"; "50"];
1799 ["lvcreate"; "LV2"; "VG"; "50"];
1800 ["lvremove"; "/dev/VG/LV1"];
1801 ["lvs"]], ["/dev/VG/LV2"]);
1802 InitEmpty, Always, TestOutputList (
1803 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1804 ["pvcreate"; "/dev/sda1"];
1805 ["vgcreate"; "VG"; "/dev/sda1"];
1806 ["lvcreate"; "LV1"; "VG"; "50"];
1807 ["lvcreate"; "LV2"; "VG"; "50"];
1808 ["lvremove"; "/dev/VG"];
1810 InitEmpty, Always, TestOutputList (
1811 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1812 ["pvcreate"; "/dev/sda1"];
1813 ["vgcreate"; "VG"; "/dev/sda1"];
1814 ["lvcreate"; "LV1"; "VG"; "50"];
1815 ["lvcreate"; "LV2"; "VG"; "50"];
1816 ["lvremove"; "/dev/VG"];
1818 "remove an LVM logical volume",
1820 Remove an LVM logical volume C<device>, where C<device> is
1821 the path to the LV, such as C</dev/VG/LV>.
1823 You can also remove all LVs in a volume group by specifying
1824 the VG name, C</dev/VG>.");
1826 ("vgremove", (RErr, [String "vgname"]), 78, [],
1827 [InitEmpty, Always, TestOutputList (
1828 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1829 ["pvcreate"; "/dev/sda1"];
1830 ["vgcreate"; "VG"; "/dev/sda1"];
1831 ["lvcreate"; "LV1"; "VG"; "50"];
1832 ["lvcreate"; "LV2"; "VG"; "50"];
1835 InitEmpty, Always, TestOutputList (
1836 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1837 ["pvcreate"; "/dev/sda1"];
1838 ["vgcreate"; "VG"; "/dev/sda1"];
1839 ["lvcreate"; "LV1"; "VG"; "50"];
1840 ["lvcreate"; "LV2"; "VG"; "50"];
1843 "remove an LVM volume group",
1845 Remove an LVM volume group C<vgname>, (for example C<VG>).
1847 This also forcibly removes all logical volumes in the volume
1850 ("pvremove", (RErr, [String "device"]), 79, [],
1851 [InitEmpty, Always, TestOutputListOfDevices (
1852 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1853 ["pvcreate"; "/dev/sda1"];
1854 ["vgcreate"; "VG"; "/dev/sda1"];
1855 ["lvcreate"; "LV1"; "VG"; "50"];
1856 ["lvcreate"; "LV2"; "VG"; "50"];
1858 ["pvremove"; "/dev/sda1"];
1860 InitEmpty, Always, TestOutputListOfDevices (
1861 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1862 ["pvcreate"; "/dev/sda1"];
1863 ["vgcreate"; "VG"; "/dev/sda1"];
1864 ["lvcreate"; "LV1"; "VG"; "50"];
1865 ["lvcreate"; "LV2"; "VG"; "50"];
1867 ["pvremove"; "/dev/sda1"];
1869 InitEmpty, Always, TestOutputListOfDevices (
1870 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1871 ["pvcreate"; "/dev/sda1"];
1872 ["vgcreate"; "VG"; "/dev/sda1"];
1873 ["lvcreate"; "LV1"; "VG"; "50"];
1874 ["lvcreate"; "LV2"; "VG"; "50"];
1876 ["pvremove"; "/dev/sda1"];
1878 "remove an LVM physical volume",
1880 This wipes a physical volume C<device> so that LVM will no longer
1883 The implementation uses the C<pvremove> command which refuses to
1884 wipe physical volumes that contain any volume groups, so you have
1885 to remove those first.");
1887 ("set_e2label", (RErr, [String "device"; String "label"]), 80, [],
1888 [InitBasicFS, Always, TestOutput (
1889 [["set_e2label"; "/dev/sda1"; "testlabel"];
1890 ["get_e2label"; "/dev/sda1"]], "testlabel")],
1891 "set the ext2/3/4 filesystem label",
1893 This sets the ext2/3/4 filesystem label of the filesystem on
1894 C<device> to C<label>. Filesystem labels are limited to
1897 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
1898 to return the existing label on a filesystem.");
1900 ("get_e2label", (RString "label", [String "device"]), 81, [],
1902 "get the ext2/3/4 filesystem label",
1904 This returns the ext2/3/4 filesystem label of the filesystem on
1907 ("set_e2uuid", (RErr, [String "device"; String "uuid"]), 82, [],
1908 [InitBasicFS, Always, TestOutput (
1909 [["set_e2uuid"; "/dev/sda1"; "a3a61220-882b-4f61-89f4-cf24dcc7297d"];
1910 ["get_e2uuid"; "/dev/sda1"]], "a3a61220-882b-4f61-89f4-cf24dcc7297d");
1911 InitBasicFS, Always, TestOutput (
1912 [["set_e2uuid"; "/dev/sda1"; "clear"];
1913 ["get_e2uuid"; "/dev/sda1"]], "");
1914 (* We can't predict what UUIDs will be, so just check the commands run. *)
1915 InitBasicFS, Always, TestRun (
1916 [["set_e2uuid"; "/dev/sda1"; "random"]]);
1917 InitBasicFS, Always, TestRun (
1918 [["set_e2uuid"; "/dev/sda1"; "time"]])],
1919 "set the ext2/3/4 filesystem UUID",
1921 This sets the ext2/3/4 filesystem UUID of the filesystem on
1922 C<device> to C<uuid>. The format of the UUID and alternatives
1923 such as C<clear>, C<random> and C<time> are described in the
1924 L<tune2fs(8)> manpage.
1926 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
1927 to return the existing UUID of a filesystem.");
1929 ("get_e2uuid", (RString "uuid", [String "device"]), 83, [],
1931 "get the ext2/3/4 filesystem UUID",
1933 This returns the ext2/3/4 filesystem UUID of the filesystem on
1936 ("fsck", (RInt "status", [String "fstype"; String "device"]), 84, [],
1937 [InitBasicFS, Always, TestOutputInt (
1938 [["umount"; "/dev/sda1"];
1939 ["fsck"; "ext2"; "/dev/sda1"]], 0);
1940 InitBasicFS, Always, TestOutputInt (
1941 [["umount"; "/dev/sda1"];
1942 ["zero"; "/dev/sda1"];
1943 ["fsck"; "ext2"; "/dev/sda1"]], 8)],
1944 "run the filesystem checker",
1946 This runs the filesystem checker (fsck) on C<device> which
1947 should have filesystem type C<fstype>.
1949 The returned integer is the status. See L<fsck(8)> for the
1950 list of status codes from C<fsck>.
1958 Multiple status codes can be summed together.
1962 A non-zero return code can mean \"success\", for example if
1963 errors have been corrected on the filesystem.
1967 Checking or repairing NTFS volumes is not supported
1972 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
1974 ("zero", (RErr, [String "device"]), 85, [],
1975 [InitBasicFS, Always, TestOutput (
1976 [["umount"; "/dev/sda1"];
1977 ["zero"; "/dev/sda1"];
1978 ["file"; "/dev/sda1"]], "data")],
1979 "write zeroes to the device",
1981 This command writes zeroes over the first few blocks of C<device>.
1983 How many blocks are zeroed isn't specified (but it's I<not> enough
1984 to securely wipe the device). It should be sufficient to remove
1985 any partition tables, filesystem superblocks and so on.");
1987 ("grub_install", (RErr, [String "root"; String "device"]), 86, [],
1988 [InitBasicFS, Always, TestOutputTrue (
1989 [["grub_install"; "/"; "/dev/sda1"];
1990 ["is_dir"; "/boot"]])],
1993 This command installs GRUB (the Grand Unified Bootloader) on
1994 C<device>, with the root directory being C<root>.");
1996 ("cp", (RErr, [String "src"; String "dest"]), 87, [],
1997 [InitBasicFS, Always, TestOutput (
1998 [["write_file"; "/old"; "file content"; "0"];
1999 ["cp"; "/old"; "/new"];
2000 ["cat"; "/new"]], "file content");
2001 InitBasicFS, Always, TestOutputTrue (
2002 [["write_file"; "/old"; "file content"; "0"];
2003 ["cp"; "/old"; "/new"];
2004 ["is_file"; "/old"]]);
2005 InitBasicFS, Always, TestOutput (
2006 [["write_file"; "/old"; "file content"; "0"];
2008 ["cp"; "/old"; "/dir/new"];
2009 ["cat"; "/dir/new"]], "file content")],
2012 This copies a file from C<src> to C<dest> where C<dest> is
2013 either a destination filename or destination directory.");
2015 ("cp_a", (RErr, [String "src"; String "dest"]), 88, [],
2016 [InitBasicFS, Always, TestOutput (
2017 [["mkdir"; "/olddir"];
2018 ["mkdir"; "/newdir"];
2019 ["write_file"; "/olddir/file"; "file content"; "0"];
2020 ["cp_a"; "/olddir"; "/newdir"];
2021 ["cat"; "/newdir/olddir/file"]], "file content")],
2022 "copy a file or directory recursively",
2024 This copies a file or directory from C<src> to C<dest>
2025 recursively using the C<cp -a> command.");
2027 ("mv", (RErr, [String "src"; String "dest"]), 89, [],
2028 [InitBasicFS, Always, TestOutput (
2029 [["write_file"; "/old"; "file content"; "0"];
2030 ["mv"; "/old"; "/new"];
2031 ["cat"; "/new"]], "file content");
2032 InitBasicFS, Always, TestOutputFalse (
2033 [["write_file"; "/old"; "file content"; "0"];
2034 ["mv"; "/old"; "/new"];
2035 ["is_file"; "/old"]])],
2038 This moves a file from C<src> to C<dest> where C<dest> is
2039 either a destination filename or destination directory.");
2041 ("drop_caches", (RErr, [Int "whattodrop"]), 90, [],
2042 [InitEmpty, Always, TestRun (
2043 [["drop_caches"; "3"]])],
2044 "drop kernel page cache, dentries and inodes",
2046 This instructs the guest kernel to drop its page cache,
2047 and/or dentries and inode caches. The parameter C<whattodrop>
2048 tells the kernel what precisely to drop, see
2049 L<http://linux-mm.org/Drop_Caches>
2051 Setting C<whattodrop> to 3 should drop everything.
2053 This automatically calls L<sync(2)> before the operation,
2054 so that the maximum guest memory is freed.");
2056 ("dmesg", (RString "kmsgs", []), 91, [],
2057 [InitEmpty, Always, TestRun (
2059 "return kernel messages",
2061 This returns the kernel messages (C<dmesg> output) from
2062 the guest kernel. This is sometimes useful for extended
2063 debugging of problems.
2065 Another way to get the same information is to enable
2066 verbose messages with C<guestfs_set_verbose> or by setting
2067 the environment variable C<LIBGUESTFS_DEBUG=1> before
2068 running the program.");
2070 ("ping_daemon", (RErr, []), 92, [],
2071 [InitEmpty, Always, TestRun (
2072 [["ping_daemon"]])],
2073 "ping the guest daemon",
2075 This is a test probe into the guestfs daemon running inside
2076 the qemu subprocess. Calling this function checks that the
2077 daemon responds to the ping message, without affecting the daemon
2078 or attached block device(s) in any other way.");
2080 ("equal", (RBool "equality", [String "file1"; String "file2"]), 93, [],
2081 [InitBasicFS, Always, TestOutputTrue (
2082 [["write_file"; "/file1"; "contents of a file"; "0"];
2083 ["cp"; "/file1"; "/file2"];
2084 ["equal"; "/file1"; "/file2"]]);
2085 InitBasicFS, Always, TestOutputFalse (
2086 [["write_file"; "/file1"; "contents of a file"; "0"];
2087 ["write_file"; "/file2"; "contents of another file"; "0"];
2088 ["equal"; "/file1"; "/file2"]]);
2089 InitBasicFS, Always, TestLastFail (
2090 [["equal"; "/file1"; "/file2"]])],
2091 "test if two files have equal contents",
2093 This compares the two files C<file1> and C<file2> and returns
2094 true if their content is exactly equal, or false otherwise.
2096 The external L<cmp(1)> program is used for the comparison.");
2098 ("strings", (RStringList "stringsout", [String "path"]), 94, [ProtocolLimitWarning],
2099 [InitBasicFS, Always, TestOutputList (
2100 [["write_file"; "/new"; "hello\nworld\n"; "0"];
2101 ["strings"; "/new"]], ["hello"; "world"]);
2102 InitBasicFS, Always, TestOutputList (
2104 ["strings"; "/new"]], [])],
2105 "print the printable strings in a file",
2107 This runs the L<strings(1)> command on a file and returns
2108 the list of printable strings found.");
2110 ("strings_e", (RStringList "stringsout", [String "encoding"; String "path"]), 95, [ProtocolLimitWarning],
2111 [InitBasicFS, Always, TestOutputList (
2112 [["write_file"; "/new"; "hello\nworld\n"; "0"];
2113 ["strings_e"; "b"; "/new"]], []);
2114 InitBasicFS, Disabled, TestOutputList (
2115 [["write_file"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"; "24"];
2116 ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2117 "print the printable strings in a file",
2119 This is like the C<guestfs_strings> command, but allows you to
2120 specify the encoding.
2122 See the L<strings(1)> manpage for the full list of encodings.
2124 Commonly useful encodings are C<l> (lower case L) which will
2125 show strings inside Windows/x86 files.
2127 The returned strings are transcoded to UTF-8.");
2129 ("hexdump", (RString "dump", [String "path"]), 96, [ProtocolLimitWarning],
2130 [InitBasicFS, Always, TestOutput (
2131 [["write_file"; "/new"; "hello\nworld\n"; "12"];
2132 ["hexdump"; "/new"]], "00000000 68 65 6c 6c 6f 0a 77 6f 72 6c 64 0a |hello.world.|\n0000000c\n")],
2133 "dump a file in hexadecimal",
2135 This runs C<hexdump -C> on the given C<path>. The result is
2136 the human-readable, canonical hex dump of the file.");
2138 ("zerofree", (RErr, [String "device"]), 97, [],
2139 [InitNone, Always, TestOutput (
2140 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2141 ["mkfs"; "ext3"; "/dev/sda1"];
2142 ["mount"; "/dev/sda1"; "/"];
2143 ["write_file"; "/new"; "test file"; "0"];
2144 ["umount"; "/dev/sda1"];
2145 ["zerofree"; "/dev/sda1"];
2146 ["mount"; "/dev/sda1"; "/"];
2147 ["cat"; "/new"]], "test file")],
2148 "zero unused inodes and disk blocks on ext2/3 filesystem",
2150 This runs the I<zerofree> program on C<device>. This program
2151 claims to zero unused inodes and disk blocks on an ext2/3
2152 filesystem, thus making it possible to compress the filesystem
2155 You should B<not> run this program if the filesystem is
2158 It is possible that using this program can damage the filesystem
2159 or data on the filesystem.");
2161 ("pvresize", (RErr, [String "device"]), 98, [],
2163 "resize an LVM physical volume",
2165 This resizes (expands or shrinks) an existing LVM physical
2166 volume to match the new size of the underlying device.");
2168 ("sfdisk_N", (RErr, [String "device"; Int "n";
2169 Int "cyls"; Int "heads"; Int "sectors";
2170 String "line"]), 99, [DangerWillRobinson],
2172 "modify a single partition on a block device",
2174 This runs L<sfdisk(8)> option to modify just the single
2175 partition C<n> (note: C<n> counts from 1).
2177 For other parameters, see C<guestfs_sfdisk>. You should usually
2178 pass C<0> for the cyls/heads/sectors parameters.");
2180 ("sfdisk_l", (RString "partitions", [String "device"]), 100, [],
2182 "display the partition table",
2184 This displays the partition table on C<device>, in the
2185 human-readable output of the L<sfdisk(8)> command. It is
2186 not intended to be parsed.");
2188 ("sfdisk_kernel_geometry", (RString "partitions", [String "device"]), 101, [],
2190 "display the kernel geometry",
2192 This displays the kernel's idea of the geometry of C<device>.
2194 The result is in human-readable format, and not designed to
2197 ("sfdisk_disk_geometry", (RString "partitions", [String "device"]), 102, [],
2199 "display the disk geometry from the partition table",
2201 This displays the disk geometry of C<device> read from the
2202 partition table. Especially in the case where the underlying
2203 block device has been resized, this can be different from the
2204 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2206 The result is in human-readable format, and not designed to
2209 ("vg_activate_all", (RErr, [Bool "activate"]), 103, [],
2211 "activate or deactivate all volume groups",
2213 This command activates or (if C<activate> is false) deactivates
2214 all logical volumes in all volume groups.
2215 If activated, then they are made known to the
2216 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2217 then those devices disappear.
2219 This command is the same as running C<vgchange -a y|n>");
2221 ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"]), 104, [],
2223 "activate or deactivate some volume groups",
2225 This command activates or (if C<activate> is false) deactivates
2226 all logical volumes in the listed volume groups C<volgroups>.
2227 If activated, then they are made known to the
2228 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2229 then those devices disappear.
2231 This command is the same as running C<vgchange -a y|n volgroups...>
2233 Note that if C<volgroups> is an empty list then B<all> volume groups
2234 are activated or deactivated.");
2236 ("lvresize", (RErr, [String "device"; Int "mbytes"]), 105, [],
2237 [InitNone, Always, TestOutput (
2238 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2239 ["pvcreate"; "/dev/sda1"];
2240 ["vgcreate"; "VG"; "/dev/sda1"];
2241 ["lvcreate"; "LV"; "VG"; "10"];
2242 ["mkfs"; "ext2"; "/dev/VG/LV"];
2243 ["mount"; "/dev/VG/LV"; "/"];
2244 ["write_file"; "/new"; "test content"; "0"];
2246 ["lvresize"; "/dev/VG/LV"; "20"];
2247 ["e2fsck_f"; "/dev/VG/LV"];
2248 ["resize2fs"; "/dev/VG/LV"];
2249 ["mount"; "/dev/VG/LV"; "/"];
2250 ["cat"; "/new"]], "test content")],
2251 "resize an LVM logical volume",
2253 This resizes (expands or shrinks) an existing LVM logical
2254 volume to C<mbytes>. When reducing, data in the reduced part
2257 ("resize2fs", (RErr, [String "device"]), 106, [],
2258 [], (* lvresize tests this *)
2259 "resize an ext2/ext3 filesystem",
2261 This resizes an ext2 or ext3 filesystem to match the size of
2262 the underlying device.
2264 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2265 on the C<device> before calling this command. For unknown reasons
2266 C<resize2fs> sometimes gives an error about this and sometimes not.
2267 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2268 calling this function.");
2270 ("find", (RStringList "names", [String "directory"]), 107, [],
2271 [InitBasicFS, Always, TestOutputList (
2272 [["find"; "/"]], ["lost+found"]);
2273 InitBasicFS, Always, TestOutputList (
2277 ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2278 InitBasicFS, Always, TestOutputList (
2279 [["mkdir_p"; "/a/b/c"];
2280 ["touch"; "/a/b/c/d"];
2281 ["find"; "/a/b/"]], ["c"; "c/d"])],
2282 "find all files and directories",
2284 This command lists out all files and directories, recursively,
2285 starting at C<directory>. It is essentially equivalent to
2286 running the shell command C<find directory -print> but some
2287 post-processing happens on the output, described below.
2289 This returns a list of strings I<without any prefix>. Thus
2290 if the directory structure was:
2296 then the returned list from C<guestfs_find> C</tmp> would be
2304 If C<directory> is not a directory, then this command returns
2307 The returned list is sorted.");
2309 ("e2fsck_f", (RErr, [String "device"]), 108, [],
2310 [], (* lvresize tests this *)
2311 "check an ext2/ext3 filesystem",
2313 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2314 filesystem checker on C<device>, noninteractively (C<-p>),
2315 even if the filesystem appears to be clean (C<-f>).
2317 This command is only needed because of C<guestfs_resize2fs>
2318 (q.v.). Normally you should use C<guestfs_fsck>.");
2320 ("sleep", (RErr, [Int "secs"]), 109, [],
2321 [InitNone, Always, TestRun (
2323 "sleep for some seconds",
2325 Sleep for C<secs> seconds.");
2327 ("ntfs_3g_probe", (RInt "status", [Bool "rw"; String "device"]), 110, [],
2328 [InitNone, Always, TestOutputInt (
2329 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2330 ["mkfs"; "ntfs"; "/dev/sda1"];
2331 ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2332 InitNone, Always, TestOutputInt (
2333 [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2334 ["mkfs"; "ext2"; "/dev/sda1"];
2335 ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2336 "probe NTFS volume",
2338 This command runs the L<ntfs-3g.probe(8)> command which probes
2339 an NTFS C<device> for mountability. (Not all NTFS volumes can
2340 be mounted read-write, and some cannot be mounted at all).
2342 C<rw> is a boolean flag. Set it to true if you want to test
2343 if the volume can be mounted read-write. Set it to false if
2344 you want to test if the volume can be mounted read-only.
2346 The return value is an integer which C<0> if the operation
2347 would succeed, or some non-zero value documented in the
2348 L<ntfs-3g.probe(8)> manual page.");
2350 ("sh", (RString "output", [String "command"]), 111, [],
2351 [], (* XXX needs tests *)
2352 "run a command via the shell",
2354 This call runs a command from the guest filesystem via the
2357 This is like C<guestfs_command>, but passes the command to:
2359 /bin/sh -c \"command\"
2361 Depending on the guest's shell, this usually results in
2362 wildcards being expanded, shell expressions being interpolated
2365 All the provisos about C<guestfs_command> apply to this call.");
2367 ("sh_lines", (RStringList "lines", [String "command"]), 112, [],
2368 [], (* XXX needs tests *)
2369 "run a command via the shell returning lines",
2371 This is the same as C<guestfs_sh>, but splits the result
2372 into a list of lines.
2374 See also: C<guestfs_command_lines>");
2376 ("glob_expand", (RStringList "paths", [String "pattern"]), 113, [],
2377 [InitBasicFS, Always, TestOutputList (
2378 [["mkdir_p"; "/a/b/c"];
2379 ["touch"; "/a/b/c/d"];
2380 ["touch"; "/a/b/c/e"];
2381 ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2382 InitBasicFS, Always, TestOutputList (
2383 [["mkdir_p"; "/a/b/c"];
2384 ["touch"; "/a/b/c/d"];
2385 ["touch"; "/a/b/c/e"];
2386 ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2387 InitBasicFS, Always, TestOutputList (
2388 [["mkdir_p"; "/a/b/c"];
2389 ["touch"; "/a/b/c/d"];
2390 ["touch"; "/a/b/c/e"];
2391 ["glob_expand"; "/a/*/x/*"]], [])],
2392 "expand a wildcard path",
2394 This command searches for all the pathnames matching
2395 C<pattern> according to the wildcard expansion rules
2398 If no paths match, then this returns an empty list
2399 (note: not an error).
2401 It is just a wrapper around the C L<glob(3)> function
2402 with flags C<GLOB_MARK|GLOB_BRACE>.
2403 See that manual page for more details.");
2407 let all_functions = non_daemon_functions @ daemon_functions
2409 (* In some places we want the functions to be displayed sorted
2410 * alphabetically, so this is useful:
2412 let all_functions_sorted =
2413 List.sort (fun (n1,_,_,_,_,_,_) (n2,_,_,_,_,_,_) ->
2414 compare n1 n2) all_functions
2416 (* Column names and types from LVM PVs/VGs/LVs. *)
2425 "pv_attr", `String (* XXX *);
2426 "pv_pe_count", `Int;
2427 "pv_pe_alloc_count", `Int;
2430 "pv_mda_count", `Int;
2431 "pv_mda_free", `Bytes;
2432 (* Not in Fedora 10:
2433 "pv_mda_size", `Bytes;
2440 "vg_attr", `String (* XXX *);
2443 "vg_sysid", `String;
2444 "vg_extent_size", `Bytes;
2445 "vg_extent_count", `Int;
2446 "vg_free_count", `Int;
2454 "vg_mda_count", `Int;
2455 "vg_mda_free", `Bytes;
2456 (* Not in Fedora 10:
2457 "vg_mda_size", `Bytes;
2463 "lv_attr", `String (* XXX *);
2466 "lv_kernel_major", `Int;
2467 "lv_kernel_minor", `Int;
2471 "snap_percent", `OptPercent;
2472 "copy_percent", `OptPercent;
2475 "mirror_log", `String;
2479 (* Column names and types from stat structures.
2480 * NB. Can't use things like 'st_atime' because glibc header files
2481 * define some of these as macros. Ugh.
2498 let statvfs_cols = [
2512 (* Used for testing language bindings. *)
2514 | CallString of string
2515 | CallOptString of string option
2516 | CallStringList of string list
2520 (* Useful functions.
2521 * Note we don't want to use any external OCaml libraries which
2522 * makes this a bit harder than it should be.
2524 let failwithf fs = ksprintf failwith fs
2526 let replace_char s c1 c2 =
2527 let s2 = String.copy s in
2528 let r = ref false in
2529 for i = 0 to String.length s2 - 1 do
2530 if String.unsafe_get s2 i = c1 then (
2531 String.unsafe_set s2 i c2;
2535 if not !r then s else s2
2539 (* || c = '\f' *) || c = '\n' || c = '\r' || c = '\t' (* || c = '\v' *)
2541 let triml ?(test = isspace) str =
2543 let n = ref (String.length str) in
2544 while !n > 0 && test str.[!i]; do
2549 else String.sub str !i !n
2551 let trimr ?(test = isspace) str =
2552 let n = ref (String.length str) in
2553 while !n > 0 && test str.[!n-1]; do
2556 if !n = String.length str then str
2557 else String.sub str 0 !n
2559 let trim ?(test = isspace) str =
2560 trimr ~test (triml ~test str)
2562 let rec find s sub =
2563 let len = String.length s in
2564 let sublen = String.length sub in
2566 if i <= len-sublen then (
2568 if j < sublen then (
2569 if s.[i+j] = sub.[j] then loop2 (j+1)
2575 if r = -1 then loop (i+1) else r
2581 let rec replace_str s s1 s2 =
2582 let len = String.length s in
2583 let sublen = String.length s1 in
2584 let i = find s s1 in
2587 let s' = String.sub s 0 i in
2588 let s'' = String.sub s (i+sublen) (len-i-sublen) in
2589 s' ^ s2 ^ replace_str s'' s1 s2
2592 let rec string_split sep str =
2593 let len = String.length str in
2594 let seplen = String.length sep in
2595 let i = find str sep in
2596 if i = -1 then [str]
2598 let s' = String.sub str 0 i in
2599 let s'' = String.sub str (i+seplen) (len-i-seplen) in
2600 s' :: string_split sep s''
2603 let files_equal n1 n2 =
2604 let cmd = sprintf "cmp -s %s %s" (Filename.quote n1) (Filename.quote n2) in
2605 match Sys.command cmd with
2608 | i -> failwithf "%s: failed with error code %d" cmd i
2610 let rec find_map f = function
2611 | [] -> raise Not_found
2615 | None -> find_map f xs
2618 let rec loop i = function
2620 | x :: xs -> f i x; loop (i+1) xs
2625 let rec loop i = function
2627 | x :: xs -> let r = f i x in r :: loop (i+1) xs
2631 let name_of_argt = function
2632 | String n | OptString n | StringList n | Bool n | Int n
2633 | FileIn n | FileOut n -> n
2635 let seq_of_test = function
2636 | TestRun s | TestOutput (s, _) | TestOutputList (s, _)
2637 | TestOutputListOfDevices (s, _)
2638 | TestOutputInt (s, _) | TestOutputTrue s | TestOutputFalse s
2639 | TestOutputLength (s, _) | TestOutputStruct (s, _)
2640 | TestLastFail s -> s
2642 (* Check function names etc. for consistency. *)
2643 let check_functions () =
2644 let contains_uppercase str =
2645 let len = String.length str in
2647 if i >= len then false
2650 if c >= 'A' && c <= 'Z' then true
2657 (* Check function names. *)
2659 fun (name, _, _, _, _, _, _) ->
2660 if String.length name >= 7 && String.sub name 0 7 = "guestfs" then
2661 failwithf "function name %s does not need 'guestfs' prefix" name;
2663 failwithf "function name is empty";
2664 if name.[0] < 'a' || name.[0] > 'z' then
2665 failwithf "function name %s must start with lowercase a-z" name;
2666 if String.contains name '-' then
2667 failwithf "function name %s should not contain '-', use '_' instead."
2671 (* Check function parameter/return names. *)
2673 fun (name, style, _, _, _, _, _) ->
2674 let check_arg_ret_name n =
2675 if contains_uppercase n then
2676 failwithf "%s param/ret %s should not contain uppercase chars"
2678 if String.contains n '-' || String.contains n '_' then
2679 failwithf "%s param/ret %s should not contain '-' or '_'"
2682 failwithf "%s has a param/ret called 'value', which causes conflicts in the OCaml bindings, use something like 'val' or a more descriptive name" name;
2683 if n = "int" || n = "char" || n = "short" || n = "long" then
2684 failwithf "%s has a param/ret which conflicts with a C type (eg. 'int', 'char' etc.)" name;
2686 failwithf "%s has a param/ret called 'i', which will cause some conflicts in the generated code" name;
2687 if n = "argv" || n = "args" then
2688 failwithf "%s has a param/ret called 'argv' or 'args', which will cause some conflicts in the generated code" name
2691 (match fst style with
2693 | RInt n | RInt64 n | RBool n | RConstString n | RString n
2694 | RStringList n | RPVList n | RVGList n | RLVList n
2695 | RStat n | RStatVFS n
2697 check_arg_ret_name n
2699 check_arg_ret_name n;
2700 check_arg_ret_name m
2702 List.iter (fun arg -> check_arg_ret_name (name_of_argt arg)) (snd style)
2705 (* Check short descriptions. *)
2707 fun (name, _, _, _, _, shortdesc, _) ->
2708 if shortdesc.[0] <> Char.lowercase shortdesc.[0] then
2709 failwithf "short description of %s should begin with lowercase." name;
2710 let c = shortdesc.[String.length shortdesc-1] in
2711 if c = '\n' || c = '.' then
2712 failwithf "short description of %s should not end with . or \\n." name
2715 (* Check long dscriptions. *)
2717 fun (name, _, _, _, _, _, longdesc) ->
2718 if longdesc.[String.length longdesc-1] = '\n' then
2719 failwithf "long description of %s should not end with \\n." name
2722 (* Check proc_nrs. *)
2724 fun (name, _, proc_nr, _, _, _, _) ->
2725 if proc_nr <= 0 then
2726 failwithf "daemon function %s should have proc_nr > 0" name
2730 fun (name, _, proc_nr, _, _, _, _) ->
2731 if proc_nr <> -1 then
2732 failwithf "non-daemon function %s should have proc_nr -1" name
2733 ) non_daemon_functions;
2736 List.map (fun (name, _, proc_nr, _, _, _, _) -> name, proc_nr)
2739 List.sort (fun (_,nr1) (_,nr2) -> compare nr1 nr2) proc_nrs in
2740 let rec loop = function
2743 | (name1,nr1) :: ((name2,nr2) :: _ as rest) when nr1 < nr2 ->
2745 | (name1,nr1) :: (name2,nr2) :: _ ->
2746 failwithf "%s and %s have conflicting procedure numbers (%d, %d)"
2754 (* Ignore functions that have no tests. We generate a
2755 * warning when the user does 'make check' instead.
2757 | name, _, _, _, [], _, _ -> ()
2758 | name, _, _, _, tests, _, _ ->
2762 match seq_of_test test with
2764 failwithf "%s has a test containing an empty sequence" name
2765 | cmds -> List.map List.hd cmds
2767 let funcs = List.flatten funcs in
2769 let tested = List.mem name funcs in
2772 failwithf "function %s has tests but does not test itself" name
2775 (* 'pr' prints to the current output file. *)
2776 let chan = ref stdout
2777 let pr fs = ksprintf (output_string !chan) fs
2779 (* Generate a header block in a number of standard styles. *)
2780 type comment_style = CStyle | HashStyle | OCamlStyle | HaskellStyle
2781 type license = GPLv2 | LGPLv2
2783 let generate_header comment license =
2784 let c = match comment with
2785 | CStyle -> pr "/* "; " *"
2786 | HashStyle -> pr "# "; "#"
2787 | OCamlStyle -> pr "(* "; " *"
2788 | HaskellStyle -> pr "{- "; " " in
2789 pr "libguestfs generated file\n";
2790 pr "%s WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.\n" c;
2791 pr "%s ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.\n" c;
2793 pr "%s Copyright (C) 2009 Red Hat Inc.\n" c;
2797 pr "%s This program is free software; you can redistribute it and/or modify\n" c;
2798 pr "%s it under the terms of the GNU General Public License as published by\n" c;
2799 pr "%s the Free Software Foundation; either version 2 of the License, or\n" c;
2800 pr "%s (at your option) any later version.\n" c;
2802 pr "%s This program is distributed in the hope that it will be useful,\n" c;
2803 pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
2804 pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n" c;
2805 pr "%s GNU General Public License for more details.\n" c;
2807 pr "%s You should have received a copy of the GNU General Public License along\n" c;
2808 pr "%s with this program; if not, write to the Free Software Foundation, Inc.,\n" c;
2809 pr "%s 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n" c;
2812 pr "%s This library is free software; you can redistribute it and/or\n" c;
2813 pr "%s modify it under the terms of the GNU Lesser General Public\n" c;
2814 pr "%s License as published by the Free Software Foundation; either\n" c;
2815 pr "%s version 2 of the License, or (at your option) any later version.\n" c;
2817 pr "%s This library is distributed in the hope that it will be useful,\n" c;
2818 pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
2819 pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\n" c;
2820 pr "%s Lesser General Public License for more details.\n" c;
2822 pr "%s You should have received a copy of the GNU Lesser General Public\n" c;
2823 pr "%s License along with this library; if not, write to the Free Software\n" c;
2824 pr "%s Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA\n" c;
2827 | CStyle -> pr " */\n"
2829 | OCamlStyle -> pr " *)\n"
2830 | HaskellStyle -> pr "-}\n"
2834 (* Start of main code generation functions below this line. *)
2836 (* Generate the pod documentation for the C API. *)
2837 let rec generate_actions_pod () =
2839 fun (shortname, style, _, flags, _, _, longdesc) ->
2840 if not (List.mem NotInDocs flags) then (
2841 let name = "guestfs_" ^ shortname in
2842 pr "=head2 %s\n\n" name;
2844 generate_prototype ~extern:false ~handle:"handle" name style;
2846 pr "%s\n\n" longdesc;
2847 (match fst style with
2849 pr "This function returns 0 on success or -1 on error.\n\n"
2851 pr "On error this function returns -1.\n\n"
2853 pr "On error this function returns -1.\n\n"
2855 pr "This function returns a C truth value on success or -1 on error.\n\n"
2857 pr "This function returns a string, or NULL on error.
2858 The string is owned by the guest handle and must I<not> be freed.\n\n"
2860 pr "This function returns a string, or NULL on error.
2861 I<The caller must free the returned string after use>.\n\n"
2863 pr "This function returns a NULL-terminated array of strings
2864 (like L<environ(3)>), or NULL if there was an error.
2865 I<The caller must free the strings and the array after use>.\n\n"
2867 pr "This function returns a C<struct guestfs_int_bool *>,
2868 or NULL if there was an error.
2869 I<The caller must call C<guestfs_free_int_bool> after use>.\n\n"
2871 pr "This function returns a C<struct guestfs_lvm_pv_list *>
2872 (see E<lt>guestfs-structs.hE<gt>),
2873 or NULL if there was an error.
2874 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.\n\n"
2876 pr "This function returns a C<struct guestfs_lvm_vg_list *>
2877 (see E<lt>guestfs-structs.hE<gt>),
2878 or NULL if there was an error.
2879 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.\n\n"
2881 pr "This function returns a C<struct guestfs_lvm_lv_list *>
2882 (see E<lt>guestfs-structs.hE<gt>),
2883 or NULL if there was an error.
2884 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.\n\n"
2886 pr "This function returns a C<struct guestfs_stat *>
2887 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
2888 or NULL if there was an error.
2889 I<The caller must call C<free> after use>.\n\n"
2891 pr "This function returns a C<struct guestfs_statvfs *>
2892 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
2893 or NULL if there was an error.
2894 I<The caller must call C<free> after use>.\n\n"
2896 pr "This function returns a NULL-terminated array of
2897 strings, or NULL if there was an error.
2898 The array of strings will always have length C<2n+1>, where
2899 C<n> keys and values alternate, followed by the trailing NULL entry.
2900 I<The caller must free the strings and the array after use>.\n\n"
2902 if List.mem ProtocolLimitWarning flags then
2903 pr "%s\n\n" protocol_limit_warning;
2904 if List.mem DangerWillRobinson flags then
2905 pr "%s\n\n" danger_will_robinson
2907 ) all_functions_sorted
2909 and generate_structs_pod () =
2910 (* LVM structs documentation. *)
2913 pr "=head2 guestfs_lvm_%s\n" typ;
2915 pr " struct guestfs_lvm_%s {\n" typ;
2918 | name, `String -> pr " char *%s;\n" name
2920 pr " /* The next field is NOT nul-terminated, be careful when printing it: */\n";
2921 pr " char %s[32];\n" name
2922 | name, `Bytes -> pr " uint64_t %s;\n" name
2923 | name, `Int -> pr " int64_t %s;\n" name
2924 | name, `OptPercent ->
2925 pr " /* The next field is [0..100] or -1 meaning 'not present': */\n";
2926 pr " float %s;\n" name
2929 pr " struct guestfs_lvm_%s_list {\n" typ;
2930 pr " uint32_t len; /* Number of elements in list. */\n";
2931 pr " struct guestfs_lvm_%s *val; /* Elements. */\n" typ;
2934 pr " void guestfs_free_lvm_%s_list (struct guestfs_free_lvm_%s_list *);\n"
2937 ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols]
2939 (* Generate the protocol (XDR) file, 'guestfs_protocol.x' and
2940 * indirectly 'guestfs_protocol.h' and 'guestfs_protocol.c'.
2942 * We have to use an underscore instead of a dash because otherwise
2943 * rpcgen generates incorrect code.
2945 * This header is NOT exported to clients, but see also generate_structs_h.
2947 and generate_xdr () =
2948 generate_header CStyle LGPLv2;
2950 (* This has to be defined to get around a limitation in Sun's rpcgen. *)
2951 pr "typedef string str<>;\n";
2954 (* LVM internal structures. *)
2958 pr "struct guestfs_lvm_int_%s {\n" typ;
2960 | name, `String -> pr " string %s<>;\n" name
2961 | name, `UUID -> pr " opaque %s[32];\n" name
2962 | name, `Bytes -> pr " hyper %s;\n" name
2963 | name, `Int -> pr " hyper %s;\n" name
2964 | name, `OptPercent -> pr " float %s;\n" name
2968 pr "typedef struct guestfs_lvm_int_%s guestfs_lvm_int_%s_list<>;\n" typ typ;
2970 ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
2972 (* Stat internal structures. *)
2976 pr "struct guestfs_int_%s {\n" typ;
2978 | name, `Int -> pr " hyper %s;\n" name
2982 ) ["stat", stat_cols; "statvfs", statvfs_cols];
2985 fun (shortname, style, _, _, _, _, _) ->
2986 let name = "guestfs_" ^ shortname in
2988 (match snd style with
2991 pr "struct %s_args {\n" name;
2994 | String n -> pr " string %s<>;\n" n
2995 | OptString n -> pr " str *%s;\n" n
2996 | StringList n -> pr " str %s<>;\n" n
2997 | Bool n -> pr " bool %s;\n" n
2998 | Int n -> pr " int %s;\n" n
2999 | FileIn _ | FileOut _ -> ()
3003 (match fst style with
3006 pr "struct %s_ret {\n" name;
3010 pr "struct %s_ret {\n" name;
3011 pr " hyper %s;\n" n;
3014 pr "struct %s_ret {\n" name;
3018 failwithf "RConstString cannot be returned from a daemon function"
3020 pr "struct %s_ret {\n" name;
3021 pr " string %s<>;\n" n;
3024 pr "struct %s_ret {\n" name;
3025 pr " str %s<>;\n" n;
3028 pr "struct %s_ret {\n" name;
3033 pr "struct %s_ret {\n" name;
3034 pr " guestfs_lvm_int_pv_list %s;\n" n;
3037 pr "struct %s_ret {\n" name;
3038 pr " guestfs_lvm_int_vg_list %s;\n" n;
3041 pr "struct %s_ret {\n" name;
3042 pr " guestfs_lvm_int_lv_list %s;\n" n;
3045 pr "struct %s_ret {\n" name;
3046 pr " guestfs_int_stat %s;\n" n;
3049 pr "struct %s_ret {\n" name;
3050 pr " guestfs_int_statvfs %s;\n" n;
3053 pr "struct %s_ret {\n" name;
3054 pr " str %s<>;\n" n;
3059 (* Table of procedure numbers. *)
3060 pr "enum guestfs_procedure {\n";
3062 fun (shortname, _, proc_nr, _, _, _, _) ->
3063 pr " GUESTFS_PROC_%s = %d,\n" (String.uppercase shortname) proc_nr
3065 pr " GUESTFS_PROC_NR_PROCS\n";
3069 (* Having to choose a maximum message size is annoying for several
3070 * reasons (it limits what we can do in the API), but it (a) makes
3071 * the protocol a lot simpler, and (b) provides a bound on the size
3072 * of the daemon which operates in limited memory space. For large
3073 * file transfers you should use FTP.
3075 pr "const GUESTFS_MESSAGE_MAX = %d;\n" (4 * 1024 * 1024);
3078 (* Message header, etc. *)
3080 /* The communication protocol is now documented in the guestfs(3)
3084 const GUESTFS_PROGRAM = 0x2000F5F5;
3085 const GUESTFS_PROTOCOL_VERSION = 1;
3087 /* These constants must be larger than any possible message length. */
3088 const GUESTFS_LAUNCH_FLAG = 0xf5f55ff5;
3089 const GUESTFS_CANCEL_FLAG = 0xffffeeee;
3091 enum guestfs_message_direction {
3092 GUESTFS_DIRECTION_CALL = 0, /* client -> daemon */
3093 GUESTFS_DIRECTION_REPLY = 1 /* daemon -> client */
3096 enum guestfs_message_status {
3097 GUESTFS_STATUS_OK = 0,
3098 GUESTFS_STATUS_ERROR = 1
3101 const GUESTFS_ERROR_LEN = 256;
3103 struct guestfs_message_error {
3104 string error_message<GUESTFS_ERROR_LEN>;
3107 struct guestfs_message_header {
3108 unsigned prog; /* GUESTFS_PROGRAM */
3109 unsigned vers; /* GUESTFS_PROTOCOL_VERSION */
3110 guestfs_procedure proc; /* GUESTFS_PROC_x */
3111 guestfs_message_direction direction;
3112 unsigned serial; /* message serial number */
3113 guestfs_message_status status;
3116 const GUESTFS_MAX_CHUNK_SIZE = 8192;
3118 struct guestfs_chunk {
3119 int cancel; /* if non-zero, transfer is cancelled */
3120 /* data size is 0 bytes if the transfer has finished successfully */
3121 opaque data<GUESTFS_MAX_CHUNK_SIZE>;
3125 (* Generate the guestfs-structs.h file. *)
3126 and generate_structs_h () =
3127 generate_header CStyle LGPLv2;
3129 (* This is a public exported header file containing various
3130 * structures. The structures are carefully written to have
3131 * exactly the same in-memory format as the XDR structures that
3132 * we use on the wire to the daemon. The reason for creating
3133 * copies of these structures here is just so we don't have to
3134 * export the whole of guestfs_protocol.h (which includes much
3135 * unrelated and XDR-dependent stuff that we don't want to be
3136 * public, or required by clients).
3138 * To reiterate, we will pass these structures to and from the
3139 * client with a simple assignment or memcpy, so the format
3140 * must be identical to what rpcgen / the RFC defines.
3143 (* guestfs_int_bool structure. *)
3144 pr "struct guestfs_int_bool {\n";
3150 (* LVM public structures. *)
3154 pr "struct guestfs_lvm_%s {\n" typ;
3157 | name, `String -> pr " char *%s;\n" name
3158 | name, `UUID -> pr " char %s[32]; /* this is NOT nul-terminated, be careful when printing */\n" name
3159 | name, `Bytes -> pr " uint64_t %s;\n" name
3160 | name, `Int -> pr " int64_t %s;\n" name
3161 | name, `OptPercent -> pr " float %s; /* [0..100] or -1 */\n" name
3165 pr "struct guestfs_lvm_%s_list {\n" typ;
3166 pr " uint32_t len;\n";
3167 pr " struct guestfs_lvm_%s *val;\n" typ;
3170 ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
3172 (* Stat structures. *)
3176 pr "struct guestfs_%s {\n" typ;
3179 | name, `Int -> pr " int64_t %s;\n" name
3183 ) ["stat", stat_cols; "statvfs", statvfs_cols]
3185 (* Generate the guestfs-actions.h file. *)
3186 and generate_actions_h () =
3187 generate_header CStyle LGPLv2;
3189 fun (shortname, style, _, _, _, _, _) ->
3190 let name = "guestfs_" ^ shortname in
3191 generate_prototype ~single_line:true ~newline:true ~handle:"handle"
3195 (* Generate the client-side dispatch stubs. *)
3196 and generate_client_actions () =
3197 generate_header CStyle LGPLv2;
3203 #include \"guestfs.h\"
3204 #include \"guestfs_protocol.h\"
3206 #define error guestfs_error
3207 #define perrorf guestfs_perrorf
3208 #define safe_malloc guestfs_safe_malloc
3209 #define safe_realloc guestfs_safe_realloc
3210 #define safe_strdup guestfs_safe_strdup
3211 #define safe_memdup guestfs_safe_memdup
3213 /* Check the return message from a call for validity. */
3215 check_reply_header (guestfs_h *g,
3216 const struct guestfs_message_header *hdr,
3217 int proc_nr, int serial)
3219 if (hdr->prog != GUESTFS_PROGRAM) {
3220 error (g, \"wrong program (%%d/%%d)\", hdr->prog, GUESTFS_PROGRAM);
3223 if (hdr->vers != GUESTFS_PROTOCOL_VERSION) {
3224 error (g, \"wrong protocol version (%%d/%%d)\",
3225 hdr->vers, GUESTFS_PROTOCOL_VERSION);
3228 if (hdr->direction != GUESTFS_DIRECTION_REPLY) {
3229 error (g, \"unexpected message direction (%%d/%%d)\",
3230 hdr->direction, GUESTFS_DIRECTION_REPLY);
3233 if (hdr->proc != proc_nr) {
3234 error (g, \"unexpected procedure number (%%d/%%d)\", hdr->proc, proc_nr);
3237 if (hdr->serial != serial) {
3238 error (g, \"unexpected serial (%%d/%%d)\", hdr->serial, serial);
3245 /* Check we are in the right state to run a high-level action. */
3247 check_state (guestfs_h *g, const char *caller)
3249 if (!guestfs_is_ready (g)) {
3250 if (guestfs_is_config (g))
3251 error (g, \"%%s: call launch() before using this function\",
3253 else if (guestfs_is_launching (g))
3254 error (g, \"%%s: call wait_ready() before using this function\",
3257 error (g, \"%%s called from the wrong state, %%d != READY\",
3258 caller, guestfs_get_state (g));
3266 (* Client-side stubs for each function. *)
3268 fun (shortname, style, _, _, _, _, _) ->
3269 let name = "guestfs_" ^ shortname in
3271 (* Generate the context struct which stores the high-level
3272 * state between callback functions.
3274 pr "struct %s_ctx {\n" shortname;
3275 pr " /* This flag is set by the callbacks, so we know we've done\n";
3276 pr " * the callbacks as expected, and in the right sequence.\n";
3277 pr " * 0 = not called, 1 = reply_cb called.\n";
3279 pr " int cb_sequence;\n";
3280 pr " struct guestfs_message_header hdr;\n";
3281 pr " struct guestfs_message_error err;\n";
3282 (match fst style with
3285 failwithf "RConstString cannot be returned from a daemon function"
3287 | RBool _ | RString _ | RStringList _
3289 | RPVList _ | RVGList _ | RLVList _
3290 | RStat _ | RStatVFS _
3292 pr " struct %s_ret ret;\n" name
3297 (* Generate the reply callback function. *)
3298 pr "static void %s_reply_cb (guestfs_h *g, void *data, XDR *xdr)\n" shortname;
3300 pr " guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3301 pr " struct %s_ctx *ctx = (struct %s_ctx *) data;\n" shortname shortname;
3303 pr " /* This should definitely not happen. */\n";
3304 pr " if (ctx->cb_sequence != 0) {\n";
3305 pr " ctx->cb_sequence = 9999;\n";
3306 pr " error (g, \"%%s: internal error: reply callback called twice\", \"%s\");\n" name;
3310 pr " ml->main_loop_quit (ml, g);\n";
3312 pr " if (!xdr_guestfs_message_header (xdr, &ctx->hdr)) {\n";
3313 pr " error (g, \"%%s: failed to parse reply header\", \"%s\");\n" name;
3316 pr " if (ctx->hdr.status == GUESTFS_STATUS_ERROR) {\n";
3317 pr " if (!xdr_guestfs_message_error (xdr, &ctx->err)) {\n";
3318 pr " error (g, \"%%s: failed to parse reply error\", \"%s\");\n"
3325 (match fst style with
3328 failwithf "RConstString cannot be returned from a daemon function"
3330 | RBool _ | RString _ | RStringList _
3332 | RPVList _ | RVGList _ | RLVList _
3333 | RStat _ | RStatVFS _
3335 pr " if (!xdr_%s_ret (xdr, &ctx->ret)) {\n" name;
3336 pr " error (g, \"%%s: failed to parse reply\", \"%s\");\n" name;
3342 pr " ctx->cb_sequence = 1;\n";
3345 (* Generate the action stub. *)
3346 generate_prototype ~extern:false ~semicolon:false ~newline:true
3347 ~handle:"g" name style;
3350 match fst style with
3351 | RErr | RInt _ | RInt64 _ | RBool _ -> "-1"
3353 failwithf "RConstString cannot be returned from a daemon function"
3354 | RString _ | RStringList _ | RIntBool _
3355 | RPVList _ | RVGList _ | RLVList _
3356 | RStat _ | RStatVFS _
3362 (match snd style with
3364 | _ -> pr " struct %s_args args;\n" name
3367 pr " struct %s_ctx ctx;\n" shortname;
3368 pr " guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3369 pr " int serial;\n";
3371 pr " if (check_state (g, \"%s\") == -1) return %s;\n" name error_code;
3372 pr " guestfs_set_busy (g);\n";
3374 pr " memset (&ctx, 0, sizeof ctx);\n";
3377 (* Send the main header and arguments. *)
3378 (match snd style with
3380 pr " serial = guestfs__send_sync (g, GUESTFS_PROC_%s, NULL, NULL);\n"
3381 (String.uppercase shortname)
3386 pr " args.%s = (char *) %s;\n" n n
3388 pr " args.%s = %s ? (char **) &%s : NULL;\n" n n n
3390 pr " args.%s.%s_val = (char **) %s;\n" n n n;
3391 pr " for (args.%s.%s_len = 0; %s[args.%s.%s_len]; args.%s.%s_len++) ;\n" n n n n n n n;
3393 pr " args.%s = %s;\n" n n
3395 pr " args.%s = %s;\n" n n
3396 | FileIn _ | FileOut _ -> ()
3398 pr " serial = guestfs__send_sync (g, GUESTFS_PROC_%s,\n"
3399 (String.uppercase shortname);
3400 pr " (xdrproc_t) xdr_%s_args, (char *) &args);\n"
3403 pr " if (serial == -1) {\n";
3404 pr " guestfs_end_busy (g);\n";
3405 pr " return %s;\n" error_code;
3409 (* Send any additional files (FileIn) requested. *)
3410 let need_read_reply_label = ref false in
3417 pr " r = guestfs__send_file_sync (g, %s);\n" n;
3418 pr " if (r == -1) {\n";
3419 pr " guestfs_end_busy (g);\n";
3420 pr " return %s;\n" error_code;
3422 pr " if (r == -2) /* daemon cancelled */\n";
3423 pr " goto read_reply;\n";
3424 need_read_reply_label := true;
3430 (* Wait for the reply from the remote end. *)
3431 if !need_read_reply_label then pr " read_reply:\n";
3432 pr " guestfs__switch_to_receiving (g);\n";
3433 pr " ctx.cb_sequence = 0;\n";
3434 pr " guestfs_set_reply_callback (g, %s_reply_cb, &ctx);\n" shortname;
3435 pr " (void) ml->main_loop_run (ml, g);\n";
3436 pr " guestfs_set_reply_callback (g, NULL, NULL);\n";
3437 pr " if (ctx.cb_sequence != 1) {\n";
3438 pr " error (g, \"%%s reply failed, see earlier error messages\", \"%s\");\n" name;
3439 pr " guestfs_end_busy (g);\n";
3440 pr " return %s;\n" error_code;
3444 pr " if (check_reply_header (g, &ctx.hdr, GUESTFS_PROC_%s, serial) == -1) {\n"
3445 (String.uppercase shortname);
3446 pr " guestfs_end_busy (g);\n";
3447 pr " return %s;\n" error_code;
3451 pr " if (ctx.hdr.status == GUESTFS_STATUS_ERROR) {\n";
3452 pr " error (g, \"%%s\", ctx.err.error_message);\n";
3453 pr " free (ctx.err.error_message);\n";
3454 pr " guestfs_end_busy (g);\n";
3455 pr " return %s;\n" error_code;
3459 (* Expecting to receive further files (FileOut)? *)
3463 pr " if (guestfs__receive_file_sync (g, %s) == -1) {\n" n;
3464 pr " guestfs_end_busy (g);\n";
3465 pr " return %s;\n" error_code;
3471 pr " guestfs_end_busy (g);\n";
3473 (match fst style with
3474 | RErr -> pr " return 0;\n"
3475 | RInt n | RInt64 n | RBool n ->
3476 pr " return ctx.ret.%s;\n" n
3478 failwithf "RConstString cannot be returned from a daemon function"
3480 pr " return ctx.ret.%s; /* caller will free */\n" n
3481 | RStringList n | RHashtable n ->
3482 pr " /* caller will free this, but we need to add a NULL entry */\n";
3483 pr " ctx.ret.%s.%s_val =\n" n n;
3484 pr " safe_realloc (g, ctx.ret.%s.%s_val,\n" n n;
3485 pr " sizeof (char *) * (ctx.ret.%s.%s_len + 1));\n"
3487 pr " ctx.ret.%s.%s_val[ctx.ret.%s.%s_len] = NULL;\n" n n n n;
3488 pr " return ctx.ret.%s.%s_val;\n" n n
3490 pr " /* caller with free this */\n";
3491 pr " return safe_memdup (g, &ctx.ret, sizeof (ctx.ret));\n"
3492 | RPVList n | RVGList n | RLVList n
3493 | RStat n | RStatVFS n ->
3494 pr " /* caller will free this */\n";
3495 pr " return safe_memdup (g, &ctx.ret.%s, sizeof (ctx.ret.%s));\n" n n
3501 (* Generate daemon/actions.h. *)
3502 and generate_daemon_actions_h () =
3503 generate_header CStyle GPLv2;
3505 pr "#include \"../src/guestfs_protocol.h\"\n";
3509 fun (name, style, _, _, _, _, _) ->
3511 ~single_line:true ~newline:true ~in_daemon:true ~prefix:"do_"
3515 (* Generate the server-side stubs. *)
3516 and generate_daemon_actions () =
3517 generate_header CStyle GPLv2;
3519 pr "#include <config.h>\n";
3521 pr "#include <stdio.h>\n";
3522 pr "#include <stdlib.h>\n";
3523 pr "#include <string.h>\n";
3524 pr "#include <inttypes.h>\n";
3525 pr "#include <ctype.h>\n";
3526 pr "#include <rpc/types.h>\n";
3527 pr "#include <rpc/xdr.h>\n";
3529 pr "#include \"daemon.h\"\n";
3530 pr "#include \"../src/guestfs_protocol.h\"\n";
3531 pr "#include \"actions.h\"\n";
3535 fun (name, style, _, _, _, _, _) ->
3536 (* Generate server-side stubs. *)
3537 pr "static void %s_stub (XDR *xdr_in)\n" name;
3540 match fst style with
3541 | RErr | RInt _ -> pr " int r;\n"; "-1"
3542 | RInt64 _ -> pr " int64_t r;\n"; "-1"
3543 | RBool _ -> pr " int r;\n"; "-1"
3545 failwithf "RConstString cannot be returned from a daemon function"
3546 | RString _ -> pr " char *r;\n"; "NULL"
3547 | RStringList _ | RHashtable _ -> pr " char **r;\n"; "NULL"
3548 | RIntBool _ -> pr " guestfs_%s_ret *r;\n" name; "NULL"
3549 | RPVList _ -> pr " guestfs_lvm_int_pv_list *r;\n"; "NULL"
3550 | RVGList _ -> pr " guestfs_lvm_int_vg_list *r;\n"; "NULL"
3551 | RLVList _ -> pr " guestfs_lvm_int_lv_list *r;\n"; "NULL"
3552 | RStat _ -> pr " guestfs_int_stat *r;\n"; "NULL"
3553 | RStatVFS _ -> pr " guestfs_int_statvfs *r;\n"; "NULL" in
3555 (match snd style with
3558 pr " struct guestfs_%s_args args;\n" name;
3561 (* Note we allow the string to be writable, in order to
3562 * allow device name translation. This is safe because
3563 * we can modify the string (passed from RPC).
3566 | OptString n -> pr " char *%s;\n" n
3567 | StringList n -> pr " char **%s;\n" n
3568 | Bool n -> pr " int %s;\n" n
3569 | Int n -> pr " int %s;\n" n
3570 | FileIn _ | FileOut _ -> ()
3575 (match snd style with
3578 pr " memset (&args, 0, sizeof args);\n";
3580 pr " if (!xdr_guestfs_%s_args (xdr_in, &args)) {\n" name;
3581 pr " reply_with_error (\"%%s: daemon failed to decode procedure arguments\", \"%s\");\n" name;
3586 | String n -> pr " %s = args.%s;\n" n n
3587 | OptString n -> pr " %s = args.%s ? *args.%s : NULL;\n" n n n
3589 pr " %s = realloc (args.%s.%s_val,\n" n n n;
3590 pr " sizeof (char *) * (args.%s.%s_len+1));\n" n n;
3591 pr " if (%s == NULL) {\n" n;
3592 pr " reply_with_perror (\"realloc\");\n";
3595 pr " %s[args.%s.%s_len] = NULL;\n" n n n;
3596 pr " args.%s.%s_val = %s;\n" n n n;
3597 | Bool n -> pr " %s = args.%s;\n" n n
3598 | Int n -> pr " %s = args.%s;\n" n n
3599 | FileIn _ | FileOut _ -> ()
3604 (* Don't want to call the impl with any FileIn or FileOut
3605 * parameters, since these go "outside" the RPC protocol.
3608 List.filter (function FileIn _ | FileOut _ -> false | _ -> true)
3610 pr " r = do_%s " name;
3611 generate_call_args argsnofile;
3614 pr " if (r == %s)\n" error_code;
3615 pr " /* do_%s has already called reply_with_error */\n" name;
3619 (* If there are any FileOut parameters, then the impl must
3620 * send its own reply.
3623 List.exists (function FileOut _ -> true | _ -> false) (snd style) in
3625 pr " /* do_%s has already sent a reply */\n" name
3627 match fst style with
3628 | RErr -> pr " reply (NULL, NULL);\n"
3629 | RInt n | RInt64 n | RBool n ->
3630 pr " struct guestfs_%s_ret ret;\n" name;
3631 pr " ret.%s = r;\n" n;
3632 pr " reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3635 failwithf "RConstString cannot be returned from a daemon function"
3637 pr " struct guestfs_%s_ret ret;\n" name;
3638 pr " ret.%s = r;\n" n;
3639 pr " reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3642 | RStringList n | RHashtable n ->
3643 pr " struct guestfs_%s_ret ret;\n" name;
3644 pr " ret.%s.%s_len = count_strings (r);\n" n n;
3645 pr " ret.%s.%s_val = r;\n" n n;
3646 pr " reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3648 pr " free_strings (r);\n"
3650 pr " reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) r);\n"
3652 pr " xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) r);\n" name
3653 | RPVList n | RVGList n | RLVList n
3654 | RStat n | RStatVFS n ->
3655 pr " struct guestfs_%s_ret ret;\n" name;
3656 pr " ret.%s = *r;\n" n;
3657 pr " reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
3659 pr " xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
3663 (* Free the args. *)
3664 (match snd style with
3669 pr " xdr_free ((xdrproc_t) xdr_guestfs_%s_args, (char *) &args);\n"
3676 (* Dispatch function. *)
3677 pr "void dispatch_incoming_message (XDR *xdr_in)\n";
3679 pr " switch (proc_nr) {\n";
3682 fun (name, style, _, _, _, _, _) ->
3683 pr " case GUESTFS_PROC_%s:\n" (String.uppercase name);
3684 pr " %s_stub (xdr_in);\n" name;
3689 pr " reply_with_error (\"dispatch_incoming_message: unknown procedure number %%d, set LIBGUESTFS_PATH to point to the matching libguestfs appliance directory\", proc_nr);\n";
3694 (* LVM columns and tokenization functions. *)
3695 (* XXX This generates crap code. We should rethink how we
3701 pr "static const char *lvm_%s_cols = \"%s\";\n"
3702 typ (String.concat "," (List.map fst cols));
3705 pr "static int lvm_tokenize_%s (char *str, struct guestfs_lvm_int_%s *r)\n" typ typ;
3707 pr " char *tok, *p, *next;\n";
3711 pr " fprintf (stderr, \"%%s: <<%%s>>\\n\", __func__, str);\n";
3714 pr " if (!str) {\n";
3715 pr " fprintf (stderr, \"%%s: failed: passed a NULL string\\n\", __func__);\n";
3718 pr " if (!*str || isspace (*str)) {\n";
3719 pr " fprintf (stderr, \"%%s: failed: passed a empty string or one beginning with whitespace\\n\", __func__);\n";
3724 fun (name, coltype) ->
3725 pr " if (!tok) {\n";
3726 pr " fprintf (stderr, \"%%s: failed: string finished early, around token %%s\\n\", __func__, \"%s\");\n" name;
3729 pr " p = strchrnul (tok, ',');\n";
3730 pr " if (*p) next = p+1; else next = NULL;\n";
3731 pr " *p = '\\0';\n";
3734 pr " r->%s = strdup (tok);\n" name;
3735 pr " if (r->%s == NULL) {\n" name;
3736 pr " perror (\"strdup\");\n";
3740 pr " for (i = j = 0; i < 32; ++j) {\n";
3741 pr " if (tok[j] == '\\0') {\n";
3742 pr " fprintf (stderr, \"%%s: failed to parse UUID from '%%s'\\n\", __func__, tok);\n";
3744 pr " } else if (tok[j] != '-')\n";
3745 pr " r->%s[i++] = tok[j];\n" name;
3748 pr " if (sscanf (tok, \"%%\"SCNu64, &r->%s) != 1) {\n" name;
3749 pr " fprintf (stderr, \"%%s: failed to parse size '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
3753 pr " if (sscanf (tok, \"%%\"SCNi64, &r->%s) != 1) {\n" name;
3754 pr " fprintf (stderr, \"%%s: failed to parse int '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
3758 pr " if (tok[0] == '\\0')\n";
3759 pr " r->%s = -1;\n" name;
3760 pr " else if (sscanf (tok, \"%%f\", &r->%s) != 1) {\n" name;
3761 pr " fprintf (stderr, \"%%s: failed to parse float '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
3765 pr " tok = next;\n";
3768 pr " if (tok != NULL) {\n";
3769 pr " fprintf (stderr, \"%%s: failed: extra tokens at end of string\\n\", __func__);\n";
3776 pr "guestfs_lvm_int_%s_list *\n" typ;
3777 pr "parse_command_line_%ss (void)\n" typ;
3779 pr " char *out, *err;\n";
3780 pr " char *p, *pend;\n";
3782 pr " guestfs_lvm_int_%s_list *ret;\n" typ;
3783 pr " void *newp;\n";
3785 pr " ret = malloc (sizeof *ret);\n";
3786 pr " if (!ret) {\n";
3787 pr " reply_with_perror (\"malloc\");\n";
3788 pr " return NULL;\n";
3791 pr " ret->guestfs_lvm_int_%s_list_len = 0;\n" typ;
3792 pr " ret->guestfs_lvm_int_%s_list_val = NULL;\n" typ;
3794 pr " r = command (&out, &err,\n";
3795 pr " \"/sbin/lvm\", \"%ss\",\n" typ;
3796 pr " \"-o\", lvm_%s_cols, \"--unbuffered\", \"--noheadings\",\n" typ;
3797 pr " \"--nosuffix\", \"--separator\", \",\", \"--units\", \"b\", NULL);\n";
3798 pr " if (r == -1) {\n";
3799 pr " reply_with_error (\"%%s\", err);\n";
3800 pr " free (out);\n";
3801 pr " free (err);\n";
3802 pr " free (ret);\n";
3803 pr " return NULL;\n";
3806 pr " free (err);\n";
3808 pr " /* Tokenize each line of the output. */\n";
3811 pr " while (p) {\n";
3812 pr " pend = strchr (p, '\\n'); /* Get the next line of output. */\n";
3813 pr " if (pend) {\n";
3814 pr " *pend = '\\0';\n";
3818 pr " while (*p && isspace (*p)) /* Skip any leading whitespace. */\n";
3821 pr " if (!*p) { /* Empty line? Skip it. */\n";
3826 pr " /* Allocate some space to store this next entry. */\n";
3827 pr " newp = realloc (ret->guestfs_lvm_int_%s_list_val,\n" typ;
3828 pr " sizeof (guestfs_lvm_int_%s) * (i+1));\n" typ;
3829 pr " if (newp == NULL) {\n";
3830 pr " reply_with_perror (\"realloc\");\n";
3831 pr " free (ret->guestfs_lvm_int_%s_list_val);\n" typ;
3832 pr " free (ret);\n";
3833 pr " free (out);\n";
3834 pr " return NULL;\n";
3836 pr " ret->guestfs_lvm_int_%s_list_val = newp;\n" typ;
3838 pr " /* Tokenize the next entry. */\n";
3839 pr " r = lvm_tokenize_%s (p, &ret->guestfs_lvm_int_%s_list_val[i]);\n" typ typ;
3840 pr " if (r == -1) {\n";
3841 pr " reply_with_error (\"failed to parse output of '%ss' command\");\n" typ;
3842 pr " free (ret->guestfs_lvm_int_%s_list_val);\n" typ;
3843 pr " free (ret);\n";
3844 pr " free (out);\n";
3845 pr " return NULL;\n";
3852 pr " ret->guestfs_lvm_int_%s_list_len = i;\n" typ;
3854 pr " free (out);\n";
3855 pr " return ret;\n";
3858 ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols]
3860 (* Generate the tests. *)
3861 and generate_tests () =
3862 generate_header CStyle GPLv2;
3869 #include <sys/types.h>
3872 #include \"guestfs.h\"
3874 static guestfs_h *g;
3875 static int suppress_error = 0;
3877 static void print_error (guestfs_h *g, void *data, const char *msg)
3879 if (!suppress_error)
3880 fprintf (stderr, \"%%s\\n\", msg);
3883 static void print_strings (char * const * const argv)
3887 for (argc = 0; argv[argc] != NULL; ++argc)
3888 printf (\"\\t%%s\\n\", argv[argc]);
3892 static void print_table (char * const * const argv)
3896 for (i = 0; argv[i] != NULL; i += 2)
3897 printf (\"%%s: %%s\\n\", argv[i], argv[i+1]);
3901 static void no_test_warnings (void)
3907 | name, _, _, _, [], _, _ ->
3908 pr " fprintf (stderr, \"warning: \\\"guestfs_%s\\\" has no tests\\n\");\n" name
3909 | name, _, _, _, tests, _, _ -> ()
3915 (* Generate the actual tests. Note that we generate the tests
3916 * in reverse order, deliberately, so that (in general) the
3917 * newest tests run first. This makes it quicker and easier to
3922 fun (name, _, _, _, tests, _, _) ->
3923 mapi (generate_one_test name) tests
3924 ) (List.rev all_functions) in
3925 let test_names = List.concat test_names in
3926 let nr_tests = List.length test_names in
3929 int main (int argc, char *argv[])
3933 const char *filename;
3935 int nr_tests, test_num = 0;
3937 no_test_warnings ();
3939 g = guestfs_create ();
3941 printf (\"guestfs_create FAILED\\n\");
3945 guestfs_set_error_handler (g, print_error, NULL);
3947 guestfs_set_path (g, \"../appliance\");
3949 filename = \"test1.img\";
3950 fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
3955 if (lseek (fd, %d, SEEK_SET) == -1) {
3961 if (write (fd, &c, 1) == -1) {
3967 if (close (fd) == -1) {
3972 if (guestfs_add_drive (g, filename) == -1) {
3973 printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
3977 filename = \"test2.img\";
3978 fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
3983 if (lseek (fd, %d, SEEK_SET) == -1) {
3989 if (write (fd, &c, 1) == -1) {
3995 if (close (fd) == -1) {
4000 if (guestfs_add_drive (g, filename) == -1) {
4001 printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
4005 filename = \"test3.img\";
4006 fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
4011 if (lseek (fd, %d, SEEK_SET) == -1) {
4017 if (write (fd, &c, 1) == -1) {
4023 if (close (fd) == -1) {
4028 if (guestfs_add_drive (g, filename) == -1) {
4029 printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
4033 if (guestfs_add_drive_ro (g, \"../images/test.sqsh\") == -1) {
4034 printf (\"guestfs_add_drive_ro ../images/test.sqsh FAILED\\n\");
4038 if (guestfs_launch (g) == -1) {
4039 printf (\"guestfs_launch FAILED\\n\");
4043 /* Set a timeout in case qemu hangs during launch (RHBZ#505329). */
4046 if (guestfs_wait_ready (g) == -1) {
4047 printf (\"guestfs_wait_ready FAILED\\n\");
4051 /* Cancel previous alarm. */
4056 " (500 * 1024 * 1024) (50 * 1024 * 1024) (10 * 1024 * 1024) nr_tests;
4060 pr " test_num++;\n";
4061 pr " printf (\"%%3d/%%3d %s\\n\", test_num, nr_tests);\n" test_name;
4062 pr " if (%s () == -1) {\n" test_name;
4063 pr " printf (\"%s FAILED\\n\");\n" test_name;
4069 pr " guestfs_close (g);\n";
4070 pr " unlink (\"test1.img\");\n";
4071 pr " unlink (\"test2.img\");\n";
4072 pr " unlink (\"test3.img\");\n";
4075 pr " if (failed > 0) {\n";
4076 pr " printf (\"***** %%d / %%d tests FAILED *****\\n\", failed, nr_tests);\n";
4084 and generate_one_test name i (init, prereq, test) =
4085 let test_name = sprintf "test_%s_%d" name i in
4088 static int %s_skip (void)
4092 str = getenv (\"SKIP_%s\");
4093 if (str && strcmp (str, \"1\") == 0) return 1;
4094 str = getenv (\"SKIP_TEST_%s\");
4095 if (str && strcmp (str, \"1\") == 0) return 1;
4099 " test_name (String.uppercase test_name) (String.uppercase name);
4102 | Disabled | Always -> ()
4103 | If code | Unless code ->
4104 pr "static int %s_prereq (void)\n" test_name;
4112 static int %s (void)
4115 printf (\"%%s skipped (reason: SKIP_TEST_* variable set)\\n\", \"%s\");
4119 " test_name test_name test_name;
4123 pr " printf (\"%%s skipped (reason: test disabled in generator)\\n\", \"%s\");\n" test_name
4125 pr " if (! %s_prereq ()) {\n" test_name;
4126 pr " printf (\"%%s skipped (reason: test prerequisite)\\n\", \"%s\");\n" test_name;
4130 generate_one_test_body name i test_name init test;
4132 pr " if (%s_prereq ()) {\n" test_name;
4133 pr " printf (\"%%s skipped (reason: test prerequisite)\\n\", \"%s\");\n" test_name;
4137 generate_one_test_body name i test_name init test;
4139 generate_one_test_body name i test_name init test
4147 and generate_one_test_body name i test_name init test =
4151 pr " /* InitNone|InitEmpty for %s */\n" test_name;
4152 List.iter (generate_test_command_call test_name)
4153 [["blockdev_setrw"; "/dev/sda"];
4157 pr " /* InitBasicFS for %s: create ext2 on /dev/sda1 */\n" test_name;
4158 List.iter (generate_test_command_call test_name)
4159 [["blockdev_setrw"; "/dev/sda"];
4162 ["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
4163 ["mkfs"; "ext2"; "/dev/sda1"];
4164 ["mount"; "/dev/sda1"; "/"]]
4165 | InitBasicFSonLVM ->
4166 pr " /* InitBasicFSonLVM for %s: create ext2 on /dev/VG/LV */\n"
4168 List.iter (generate_test_command_call test_name)
4169 [["blockdev_setrw"; "/dev/sda"];
4172 ["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
4173 ["pvcreate"; "/dev/sda1"];
4174 ["vgcreate"; "VG"; "/dev/sda1"];
4175 ["lvcreate"; "LV"; "VG"; "8"];
4176 ["mkfs"; "ext2"; "/dev/VG/LV"];
4177 ["mount"; "/dev/VG/LV"; "/"]]
4180 let get_seq_last = function
4182 failwithf "%s: you cannot use [] (empty list) when expecting a command"
4185 let seq = List.rev seq in
4186 List.rev (List.tl seq), List.hd seq
4191 pr " /* TestRun for %s (%d) */\n" name i;
4192 List.iter (generate_test_command_call test_name) seq
4193 | TestOutput (seq, expected) ->
4194 pr " /* TestOutput for %s (%d) */\n" name i;
4195 pr " char expected[] = \"%s\";\n" (c_quote expected);
4196 let seq, last = get_seq_last seq in
4198 pr " if (strcmp (r, expected) != 0) {\n";
4199 pr " fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r);\n" test_name;
4203 List.iter (generate_test_command_call test_name) seq;
4204 generate_test_command_call ~test test_name last
4205 | TestOutputList (seq, expected) ->
4206 pr " /* TestOutputList for %s (%d) */\n" name i;
4207 let seq, last = get_seq_last seq in
4211 pr " if (!r[%d]) {\n" i;
4212 pr " fprintf (stderr, \"%s: short list returned from command\\n\");\n" test_name;
4213 pr " print_strings (r);\n";
4217 pr " char expected[] = \"%s\";\n" (c_quote str);
4218 pr " if (strcmp (r[%d], expected) != 0) {\n" i;
4219 pr " fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r[%d]);\n" test_name i;
4224 pr " if (r[%d] != NULL) {\n" (List.length expected);
4225 pr " fprintf (stderr, \"%s: extra elements returned from command\\n\");\n"
4227 pr " print_strings (r);\n";
4231 List.iter (generate_test_command_call test_name) seq;
4232 generate_test_command_call ~test test_name last
4233 | TestOutputListOfDevices (seq, expected) ->
4234 pr " /* TestOutputListOfDevices for %s (%d) */\n" name i;
4235 let seq, last = get_seq_last seq in
4239 pr " if (!r[%d]) {\n" i;
4240 pr " fprintf (stderr, \"%s: short list returned from command\\n\");\n" test_name;
4241 pr " print_strings (r);\n";
4245 pr " char expected[] = \"%s\";\n" (c_quote str);
4246 pr " r[%d][5] = 's';\n" i;
4247 pr " if (strcmp (r[%d], expected) != 0) {\n" i;
4248 pr " fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r[%d]);\n" test_name i;
4253 pr " if (r[%d] != NULL) {\n" (List.length expected);
4254 pr " fprintf (stderr, \"%s: extra elements returned from command\\n\");\n"
4256 pr " print_strings (r);\n";
4260 List.iter (generate_test_command_call test_name) seq;
4261 generate_test_command_call ~test test_name last
4262 | TestOutputInt (seq, expected) ->
4263 pr " /* TestOutputInt for %s (%d) */\n" name i;
4264 let seq, last = get_seq_last seq in
4266 pr " if (r != %d) {\n" expected;
4267 pr " fprintf (stderr, \"%s: expected %d but got %%d\\n\","
4273 List.iter (generate_test_command_call test_name) seq;
4274 generate_test_command_call ~test test_name last
4275 | TestOutputTrue seq ->
4276 pr " /* TestOutputTrue for %s (%d) */\n" name i;
4277 let seq, last = get_seq_last seq in
4280 pr " fprintf (stderr, \"%s: expected true, got false\\n\");\n"
4285 List.iter (generate_test_command_call test_name) seq;
4286 generate_test_command_call ~test test_name last
4287 | TestOutputFalse seq ->
4288 pr " /* TestOutputFalse for %s (%d) */\n" name i;
4289 let seq, last = get_seq_last seq in
4292 pr " fprintf (stderr, \"%s: expected false, got true\\n\");\n"
4297 List.iter (generate_test_command_call test_name) seq;
4298 generate_test_command_call ~test test_name last
4299 | TestOutputLength (seq, expected) ->
4300 pr " /* TestOutputLength for %s (%d) */\n" name i;
4301 let seq, last = get_seq_last seq in
4304 pr " for (j = 0; j < %d; ++j)\n" expected;
4305 pr " if (r[j] == NULL) {\n";
4306 pr " fprintf (stderr, \"%s: short list returned\\n\");\n"
4308 pr " print_strings (r);\n";
4311 pr " if (r[j] != NULL) {\n";
4312 pr " fprintf (stderr, \"%s: long list returned\\n\");\n"
4314 pr " print_strings (r);\n";
4318 List.iter (generate_test_command_call test_name) seq;
4319 generate_test_command_call ~test test_name last
4320 | TestOutputStruct (seq, checks) ->
4321 pr " /* TestOutputStruct for %s (%d) */\n" name i;
4322 let seq, last = get_seq_last seq in
4326 | CompareWithInt (field, expected) ->
4327 pr " if (r->%s != %d) {\n" field expected;
4328 pr " fprintf (stderr, \"%s: %s was %%d, expected %d\\n\",\n"
4329 test_name field expected;
4330 pr " (int) r->%s);\n" field;
4333 | CompareWithString (field, expected) ->
4334 pr " if (strcmp (r->%s, \"%s\") != 0) {\n" field expected;
4335 pr " fprintf (stderr, \"%s: %s was \"%%s\", expected \"%s\"\\n\",\n"
4336 test_name field expected;
4337 pr " r->%s);\n" field;
4340 | CompareFieldsIntEq (field1, field2) ->
4341 pr " if (r->%s != r->%s) {\n" field1 field2;
4342 pr " fprintf (stderr, \"%s: %s (%%d) <> %s (%%d)\\n\",\n"
4343 test_name field1 field2;
4344 pr " (int) r->%s, (int) r->%s);\n" field1 field2;
4347 | CompareFieldsStrEq (field1, field2) ->
4348 pr " if (strcmp (r->%s, r->%s) != 0) {\n" field1 field2;
4349 pr " fprintf (stderr, \"%s: %s (\"%%s\") <> %s (\"%%s\")\\n\",\n"
4350 test_name field1 field2;
4351 pr " r->%s, r->%s);\n" field1 field2;
4356 List.iter (generate_test_command_call test_name) seq;
4357 generate_test_command_call ~test test_name last
4358 | TestLastFail seq ->
4359 pr " /* TestLastFail for %s (%d) */\n" name i;
4360 let seq, last = get_seq_last seq in
4361 List.iter (generate_test_command_call test_name) seq;
4362 generate_test_command_call test_name ~expect_error:true last
4364 (* Generate the code to run a command, leaving the result in 'r'.
4365 * If you expect to get an error then you should set expect_error:true.
4367 and generate_test_command_call ?(expect_error = false) ?test test_name cmd =
4369 | [] -> assert false
4371 (* Look up the command to find out what args/ret it has. *)
4374 let _, style, _, _, _, _, _ =
4375 List.find (fun (n, _, _, _, _, _, _) -> n = name) all_functions in
4378 failwithf "%s: in test, command %s was not found" test_name name in
4380 if List.length (snd style) <> List.length args then
4381 failwithf "%s: in test, wrong number of args given to %s"
4388 | OptString n, "NULL" -> ()
4390 | OptString n, arg ->
4391 pr " char %s[] = \"%s\";\n" n (c_quote arg);
4394 | FileIn _, _ | FileOut _, _ -> ()
4395 | StringList n, arg ->
4396 let strs = string_split " " arg in
4399 pr " char %s_%d[] = \"%s\";\n" n i (c_quote str);
4401 pr " char *%s[] = {\n" n;
4403 fun i _ -> pr " %s_%d,\n" n i
4407 ) (List.combine (snd style) args);
4410 match fst style with
4411 | RErr | RInt _ | RBool _ -> pr " int r;\n"; "-1"
4412 | RInt64 _ -> pr " int64_t r;\n"; "-1"
4413 | RConstString _ -> pr " const char *r;\n"; "NULL"
4414 | RString _ -> pr " char *r;\n"; "NULL"
4415 | RStringList _ | RHashtable _ ->
4420 pr " struct guestfs_int_bool *r;\n"; "NULL"
4422 pr " struct guestfs_lvm_pv_list *r;\n"; "NULL"
4424 pr " struct guestfs_lvm_vg_list *r;\n"; "NULL"
4426 pr " struct guestfs_lvm_lv_list *r;\n"; "NULL"
4428 pr " struct guestfs_stat *r;\n"; "NULL"
4430 pr " struct guestfs_statvfs *r;\n"; "NULL" in
4432 pr " suppress_error = %d;\n" (if expect_error then 1 else 0);
4433 pr " r = guestfs_%s (g" name;
4435 (* Generate the parameters. *)
4438 | OptString _, "NULL" -> pr ", NULL"
4442 | FileIn _, arg | FileOut _, arg ->
4443 pr ", \"%s\"" (c_quote arg)
4444 | StringList n, _ ->
4448 try int_of_string arg
4449 with Failure "int_of_string" ->
4450 failwithf "%s: expecting an int, but got '%s'" test_name arg in
4453 let b = bool_of_string arg in pr ", %d" (if b then 1 else 0)
4454 ) (List.combine (snd style) args);
4457 if not expect_error then
4458 pr " if (r == %s)\n" error_code
4460 pr " if (r != %s)\n" error_code;
4463 (* Insert the test code. *)
4469 (match fst style with
4470 | RErr | RInt _ | RInt64 _ | RBool _ | RConstString _ -> ()
4471 | RString _ -> pr " free (r);\n"
4472 | RStringList _ | RHashtable _ ->
4473 pr " for (i = 0; r[i] != NULL; ++i)\n";
4474 pr " free (r[i]);\n";
4477 pr " guestfs_free_int_bool (r);\n"
4479 pr " guestfs_free_lvm_pv_list (r);\n"
4481 pr " guestfs_free_lvm_vg_list (r);\n"
4483 pr " guestfs_free_lvm_lv_list (r);\n"
4484 | RStat _ | RStatVFS _ ->
4491 let str = replace_str str "\r" "\\r" in
4492 let str = replace_str str "\n" "\\n" in
4493 let str = replace_str str "\t" "\\t" in
4494 let str = replace_str str "\000" "\\0" in
4497 (* Generate a lot of different functions for guestfish. *)
4498 and generate_fish_cmds () =
4499 generate_header CStyle GPLv2;
4503 fun (_, _, _, flags, _, _, _) -> not (List.mem NotInFish flags)
4505 let all_functions_sorted =
4507 fun (_, _, _, flags, _, _, _) -> not (List.mem NotInFish flags)
4508 ) all_functions_sorted in
4510 pr "#include <stdio.h>\n";
4511 pr "#include <stdlib.h>\n";
4512 pr "#include <string.h>\n";
4513 pr "#include <inttypes.h>\n";
4515 pr "#include <guestfs.h>\n";
4516 pr "#include \"fish.h\"\n";
4519 (* list_commands function, which implements guestfish -h *)
4520 pr "void list_commands (void)\n";
4522 pr " printf (\" %%-16s %%s\\n\", \"Command\", \"Description\");\n";
4523 pr " list_builtin_commands ();\n";
4525 fun (name, _, _, flags, _, shortdesc, _) ->
4526 let name = replace_char name '_' '-' in
4527 pr " printf (\"%%-20s %%s\\n\", \"%s\", \"%s\");\n"
4529 ) all_functions_sorted;
4530 pr " printf (\" Use -h <cmd> / help <cmd> to show detailed help for a command.\\n\");\n";
4534 (* display_command function, which implements guestfish -h cmd *)
4535 pr "void display_command (const char *cmd)\n";
4538 fun (name, style, _, flags, _, shortdesc, longdesc) ->
4539 let name2 = replace_char name '_' '-' in
4541 try find_map (function FishAlias n -> Some n | _ -> None) flags
4542 with Not_found -> name in
4543 let longdesc = replace_str longdesc "C<guestfs_" "C<" in
4545 match snd style with
4549 name2 (String.concat "> <" (List.map name_of_argt args)) in
4552 if List.mem ProtocolLimitWarning flags then
4553 ("\n\n" ^ protocol_limit_warning)
4556 (* For DangerWillRobinson commands, we should probably have
4557 * guestfish prompt before allowing you to use them (especially
4558 * in interactive mode). XXX
4562 if List.mem DangerWillRobinson flags then
4563 ("\n\n" ^ danger_will_robinson)
4566 let describe_alias =
4567 if name <> alias then
4568 sprintf "\n\nYou can use '%s' as an alias for this command." alias
4572 pr "strcasecmp (cmd, \"%s\") == 0" name;
4573 if name <> name2 then
4574 pr " || strcasecmp (cmd, \"%s\") == 0" name2;
4575 if name <> alias then
4576 pr " || strcasecmp (cmd, \"%s\") == 0" alias;
4578 pr " pod2text (\"%s - %s\", %S);\n"
4580 (" " ^ synopsis ^ "\n\n" ^ longdesc ^ warnings ^ describe_alias);
4583 pr " display_builtin_command (cmd);\n";
4587 (* print_{pv,vg,lv}_list functions *)
4591 pr "static void print_%s (struct guestfs_lvm_%s *%s)\n" typ typ typ;
4598 pr " printf (\"%s: %%s\\n\", %s->%s);\n" name typ name
4600 pr " printf (\"%s: \");\n" name;
4601 pr " for (i = 0; i < 32; ++i)\n";
4602 pr " printf (\"%%c\", %s->%s[i]);\n" typ name;
4603 pr " printf (\"\\n\");\n"
4605 pr " printf (\"%s: %%\" PRIu64 \"\\n\", %s->%s);\n" name typ name
4607 pr " printf (\"%s: %%\" PRIi64 \"\\n\", %s->%s);\n" name typ name
4608 | name, `OptPercent ->
4609 pr " if (%s->%s >= 0) printf (\"%s: %%g %%%%\\n\", %s->%s);\n"
4610 typ name name typ name;
4611 pr " else printf (\"%s: \\n\");\n" name
4615 pr "static void print_%s_list (struct guestfs_lvm_%s_list *%ss)\n"
4620 pr " for (i = 0; i < %ss->len; ++i)\n" typ;
4621 pr " print_%s (&%ss->val[i]);\n" typ typ;
4624 ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
4626 (* print_{stat,statvfs} functions *)
4630 pr "static void print_%s (struct guestfs_%s *%s)\n" typ typ typ;
4635 pr " printf (\"%s: %%\" PRIi64 \"\\n\", %s->%s);\n" name typ name
4639 ) ["stat", stat_cols; "statvfs", statvfs_cols];
4641 (* run_<action> actions *)
4643 fun (name, style, _, flags, _, _, _) ->
4644 pr "static int run_%s (const char *cmd, int argc, char *argv[])\n" name;
4646 (match fst style with
4649 | RBool _ -> pr " int r;\n"
4650 | RInt64 _ -> pr " int64_t r;\n"
4651 | RConstString _ -> pr " const char *r;\n"
4652 | RString _ -> pr " char *r;\n"
4653 | RStringList _ | RHashtable _ -> pr " char **r;\n"
4654 | RIntBool _ -> pr " struct guestfs_int_bool *r;\n"
4655 | RPVList _ -> pr " struct guestfs_lvm_pv_list *r;\n"
4656 | RVGList _ -> pr " struct guestfs_lvm_vg_list *r;\n"
4657 | RLVList _ -> pr " struct guestfs_lvm_lv_list *r;\n"
4658 | RStat _ -> pr " struct guestfs_stat *r;\n"
4659 | RStatVFS _ -> pr " struct guestfs_statvfs *r;\n"
4666 | FileOut n -> pr " const char *%s;\n" n
4667 | StringList n -> pr " char **%s;\n" n
4668 | Bool n -> pr " int %s;\n" n
4669 | Int n -> pr " int %s;\n" n
4672 (* Check and convert parameters. *)
4673 let argc_expected = List.length (snd style) in
4674 pr " if (argc != %d) {\n" argc_expected;
4675 pr " fprintf (stderr, \"%%s should have %d parameter(s)\\n\", cmd);\n"
4677 pr " fprintf (stderr, \"type 'help %%s' for help on %%s\\n\", cmd, cmd);\n";
4683 | String name -> pr " %s = argv[%d];\n" name i
4685 pr " %s = strcmp (argv[%d], \"\") != 0 ? argv[%d] : NULL;\n"
4688 pr " %s = strcmp (argv[%d], \"-\") != 0 ? argv[%d] : \"/dev/stdin\";\n"
4691 pr " %s = strcmp (argv[%d], \"-\") != 0 ? argv[%d] : \"/dev/stdout\";\n"
4693 | StringList name ->
4694 pr " %s = parse_string_list (argv[%d]);\n" name i
4696 pr " %s = is_true (argv[%d]) ? 1 : 0;\n" name i
4698 pr " %s = atoi (argv[%d]);\n" name i
4701 (* Call C API function. *)
4703 try find_map (function FishAction n -> Some n | _ -> None) flags
4704 with Not_found -> sprintf "guestfs_%s" name in
4706 generate_call_args ~handle:"g" (snd style);
4709 (* Check return value for errors and display command results. *)
4710 (match fst style with
4711 | RErr -> pr " return r;\n"
4713 pr " if (r == -1) return -1;\n";
4714 pr " printf (\"%%d\\n\", r);\n";
4717 pr " if (r == -1) return -1;\n";
4718 pr " printf (\"%%\" PRIi64 \"\\n\", r);\n";
4721 pr " if (r == -1) return -1;\n";
4722 pr " if (r) printf (\"true\\n\"); else printf (\"false\\n\");\n";
4725 pr " if (r == NULL) return -1;\n";
4726 pr " printf (\"%%s\\n\", r);\n";
4729 pr " if (r == NULL) return -1;\n";
4730 pr " printf (\"%%s\\n\", r);\n";
4734 pr " if (r == NULL) return -1;\n";
4735 pr " print_strings (r);\n";
4736 pr " free_strings (r);\n";
4739 pr " if (r == NULL) return -1;\n";
4740 pr " printf (\"%%d, %%s\\n\", r->i,\n";
4741 pr " r->b ? \"true\" : \"false\");\n";
4742 pr " guestfs_free_int_bool (r);\n";
4745 pr " if (r == NULL) return -1;\n";
4746 pr " print_pv_list (r);\n";
4747 pr " guestfs_free_lvm_pv_list (r);\n";
4750 pr " if (r == NULL) return -1;\n";
4751 pr " print_vg_list (r);\n";
4752 pr " guestfs_free_lvm_vg_list (r);\n";
4755 pr " if (r == NULL) return -1;\n";
4756 pr " print_lv_list (r);\n";
4757 pr " guestfs_free_lvm_lv_list (r);\n";
4760 pr " if (r == NULL) return -1;\n";
4761 pr " print_stat (r);\n";
4765 pr " if (r == NULL) return -1;\n";
4766 pr " print_statvfs (r);\n";
4770 pr " if (r == NULL) return -1;\n";
4771 pr " print_table (r);\n";
4772 pr " free_strings (r);\n";
4779 (* run_action function *)
4780 pr "int run_action (const char *cmd, int argc, char *argv[])\n";
4783 fun (name, _, _, flags, _, _, _) ->
4784 let name2 = replace_char name '_' '-' in
4786 try find_map (function FishAlias n -> Some n | _ -> None) flags
4787 with Not_found -> name in
4789 pr "strcasecmp (cmd, \"%s\") == 0" name;
4790 if name <> name2 then
4791 pr " || strcasecmp (cmd, \"%s\") == 0" name2;
4792 if name <> alias then
4793 pr " || strcasecmp (cmd, \"%s\") == 0" alias;
4795 pr " return run_%s (cmd, argc, argv);\n" name;
4799 pr " fprintf (stderr, \"%%s: unknown command\\n\", cmd);\n";
4806 (* Readline completion for guestfish. *)
4807 and generate_fish_completion () =
4808 generate_header CStyle GPLv2;
4812 fun (_, _, _, flags, _, _, _) -> not (List.mem NotInFish flags)
4822 #ifdef HAVE_LIBREADLINE
4823 #include <readline/readline.h>
4828 #ifdef HAVE_LIBREADLINE
4830 static const char *const commands[] = {
4831 BUILTIN_COMMANDS_FOR_COMPLETION,
4834 (* Get the commands, including the aliases. They don't need to be
4835 * sorted - the generator() function just does a dumb linear search.
4839 fun (name, _, _, flags, _, _, _) ->
4840 let name2 = replace_char name '_' '-' in
4842 try find_map (function FishAlias n -> Some n | _ -> None) flags
4843 with Not_found -> name in
4845 if name <> alias then [name2; alias] else [name2]
4847 let commands = List.flatten commands in
4849 List.iter (pr " \"%s\",\n") commands;
4855 generator (const char *text, int state)
4857 static int index, len;
4862 len = strlen (text);
4865 rl_attempted_completion_over = 1;
4867 while ((name = commands[index]) != NULL) {
4869 if (strncasecmp (name, text, len) == 0)
4870 return strdup (name);
4876 #endif /* HAVE_LIBREADLINE */
4878 char **do_completion (const char *text, int start, int end)
4880 char **matches = NULL;
4882 #ifdef HAVE_LIBREADLINE
4883 rl_completion_append_character = ' ';
4886 matches = rl_completion_matches (text, generator);
4887 else if (complete_dest_paths)
4888 matches = rl_completion_matches (text, complete_dest_paths_generator);
4895 (* Generate the POD documentation for guestfish. *)
4896 and generate_fish_actions_pod () =
4897 let all_functions_sorted =
4899 fun (_, _, _, flags, _, _, _) ->
4900 not (List.mem NotInFish flags || List.mem NotInDocs flags)
4901 ) all_functions_sorted in
4903 let rex = Str.regexp "C<guestfs_\\([^>]+\\)>" in
4906 fun (name, style, _, flags, _, _, longdesc) ->
4908 Str.global_substitute rex (
4911 try Str.matched_group 1 s
4913 failwithf "error substituting C<guestfs_...> in longdesc of function %s" name in
4914 "C<" ^ replace_char sub '_' '-' ^ ">"
4916 let name = replace_char name '_' '-' in
4918 try find_map (function FishAlias n -> Some n | _ -> None) flags
4919 with Not_found -> name in
4921 pr "=head2 %s" name;
4922 if name <> alias then
4929 | String n -> pr " %s" n
4930 | OptString n -> pr " %s" n
4931 | StringList n -> pr " '%s ...'" n
4932 | Bool _ -> pr " true|false"
4933 | Int n -> pr " %s" n
4934 | FileIn n | FileOut n -> pr " (%s|-)" n
4938 pr "%s\n\n" longdesc;
4940 if List.exists (function FileIn _ | FileOut _ -> true
4941 | _ -> false) (snd style) then
4942 pr "Use C<-> instead of a filename to read/write from stdin/stdout.\n\n";
4944 if List.mem ProtocolLimitWarning flags then
4945 pr "%s\n\n" protocol_limit_warning;
4947 if List.mem DangerWillRobinson flags then
4948 pr "%s\n\n" danger_will_robinson
4949 ) all_functions_sorted
4951 (* Generate a C function prototype. *)
4952 and generate_prototype ?(extern = true) ?(static = false) ?(semicolon = true)
4953 ?(single_line = false) ?(newline = false) ?(in_daemon = false)
4955 ?handle name style =
4956 if extern then pr "extern ";
4957 if static then pr "static ";
4958 (match fst style with
4960 | RInt _ -> pr "int "
4961 | RInt64 _ -> pr "int64_t "
4962 | RBool _ -> pr "int "
4963 | RConstString _ -> pr "const char *"
4964 | RString _ -> pr "char *"
4965 | RStringList _ | RHashtable _ -> pr "char **"
4967 if not in_daemon then pr "struct guestfs_int_bool *"
4968 else pr "guestfs_%s_ret *" name
4970 if not in_daemon then pr "struct guestfs_lvm_pv_list *"
4971 else pr "guestfs_lvm_int_pv_list *"
4973 if not in_daemon then pr "struct guestfs_lvm_vg_list *"
4974 else pr "guestfs_lvm_int_vg_list *"
4976 if not in_daemon then pr "struct guestfs_lvm_lv_list *"
4977 else pr "guestfs_lvm_int_lv_list *"
4979 if not in_daemon then pr "struct guestfs_stat *"
4980 else pr "guestfs_int_stat *"
4982 if not in_daemon then pr "struct guestfs_statvfs *"
4983 else pr "guestfs_int_statvfs *"
4985 pr "%s%s (" prefix name;
4986 if handle = None && List.length (snd style) = 0 then
4989 let comma = ref false in
4992 | Some handle -> pr "guestfs_h *%s" handle; comma := true
4996 if single_line then pr ", " else pr ",\n\t\t"
5005 if not in_daemon then pr "const char *%s" n
5006 else pr "char *%s" n
5009 if not in_daemon then pr "char * const* const %s" n
5010 else pr "char **%s" n
5011 | Bool n -> next (); pr "int %s" n
5012 | Int n -> next (); pr "int %s" n
5015 if not in_daemon then (next (); pr "const char *%s" n)
5019 if semicolon then pr ";";
5020 if newline then pr "\n"
5022 (* Generate C call arguments, eg "(handle, foo, bar)" *)
5023 and generate_call_args ?handle args =
5025 let comma = ref false in
5028 | Some handle -> pr "%s" handle; comma := true
5032 if !comma then pr ", ";
5034 pr "%s" (name_of_argt arg)
5038 (* Generate the OCaml bindings interface. *)
5039 and generate_ocaml_mli () =
5040 generate_header OCamlStyle LGPLv2;
5043 (** For API documentation you should refer to the C API
5044 in the guestfs(3) manual page. The OCaml API uses almost
5045 exactly the same calls. *)
5048 (** A [guestfs_h] handle. *)
5050 exception Error of string
5051 (** This exception is raised when there is an error. *)
5053 val create : unit -> t
5055 val close : t -> unit
5056 (** Handles are closed by the garbage collector when they become
5057 unreferenced, but callers can also call this in order to
5058 provide predictable cleanup. *)
5061 generate_ocaml_lvm_structure_decls ();
5063 generate_ocaml_stat_structure_decls ();
5067 fun (name, style, _, _, _, shortdesc, _) ->
5068 generate_ocaml_prototype name style;
5069 pr "(** %s *)\n" shortdesc;
5073 (* Generate the OCaml bindings implementation. *)
5074 and generate_ocaml_ml () =
5075 generate_header OCamlStyle LGPLv2;
5079 exception Error of string
5080 external create : unit -> t = \"ocaml_guestfs_create\"
5081 external close : t -> unit = \"ocaml_guestfs_close\"
5084 Callback.register_exception \"ocaml_guestfs_error\" (Error \"\")
5088 generate_ocaml_lvm_structure_decls ();
5090 generate_ocaml_stat_structure_decls ();
5094 fun (name, style, _, _, _, shortdesc, _) ->
5095 generate_ocaml_prototype ~is_external:true name style;
5098 (* Generate the OCaml bindings C implementation. *)
5099 and generate_ocaml_c () =
5100 generate_header CStyle LGPLv2;
5107 #include <caml/config.h>
5108 #include <caml/alloc.h>
5109 #include <caml/callback.h>
5110 #include <caml/fail.h>
5111 #include <caml/memory.h>
5112 #include <caml/mlvalues.h>
5113 #include <caml/signals.h>
5115 #include <guestfs.h>
5117 #include \"guestfs_c.h\"
5119 /* Copy a hashtable of string pairs into an assoc-list. We return
5120 * the list in reverse order, but hashtables aren't supposed to be
5123 static CAMLprim value
5124 copy_table (char * const * argv)
5127 CAMLlocal5 (rv, pairv, kv, vv, cons);
5131 for (i = 0; argv[i] != NULL; i += 2) {
5132 kv = caml_copy_string (argv[i]);
5133 vv = caml_copy_string (argv[i+1]);
5134 pairv = caml_alloc (2, 0);
5135 Store_field (pairv, 0, kv);
5136 Store_field (pairv, 1, vv);
5137 cons = caml_alloc (2, 0);
5138 Store_field (cons, 1, rv);
5140 Store_field (cons, 0, pairv);
5148 (* LVM struct copy functions. *)
5151 let has_optpercent_col =
5152 List.exists (function (_, `OptPercent) -> true | _ -> false) cols in
5154 pr "static CAMLprim value\n";
5155 pr "copy_lvm_%s (const struct guestfs_lvm_%s *%s)\n" typ typ typ;
5157 pr " CAMLparam0 ();\n";
5158 if has_optpercent_col then
5159 pr " CAMLlocal3 (rv, v, v2);\n"
5161 pr " CAMLlocal2 (rv, v);\n";
5163 pr " rv = caml_alloc (%d, 0);\n" (List.length cols);
5168 pr " v = caml_copy_string (%s->%s);\n" typ name
5170 pr " v = caml_alloc_string (32);\n";
5171 pr " memcpy (String_val (v), %s->%s, 32);\n" typ name
5174 pr " v = caml_copy_int64 (%s->%s);\n" typ name
5175 | name, `OptPercent ->
5176 pr " if (%s->%s >= 0) { /* Some %s */\n" typ name name;
5177 pr " v2 = caml_copy_double (%s->%s);\n" typ name;
5178 pr " v = caml_alloc (1, 0);\n";
5179 pr " Store_field (v, 0, v2);\n";
5180 pr " } else /* None */\n";
5181 pr " v = Val_int (0);\n";
5183 pr " Store_field (rv, %d, v);\n" i
5185 pr " CAMLreturn (rv);\n";
5189 pr "static CAMLprim value\n";
5190 pr "copy_lvm_%s_list (const struct guestfs_lvm_%s_list *%ss)\n"
5193 pr " CAMLparam0 ();\n";
5194 pr " CAMLlocal2 (rv, v);\n";
5197 pr " if (%ss->len == 0)\n" typ;
5198 pr " CAMLreturn (Atom (0));\n";
5200 pr " rv = caml_alloc (%ss->len, 0);\n" typ;
5201 pr " for (i = 0; i < %ss->len; ++i) {\n" typ;
5202 pr " v = copy_lvm_%s (&%ss->val[i]);\n" typ typ;
5203 pr " caml_modify (&Field (rv, i), v);\n";
5205 pr " CAMLreturn (rv);\n";
5209 ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
5211 (* Stat copy functions. *)
5214 pr "static CAMLprim value\n";
5215 pr "copy_%s (const struct guestfs_%s *%s)\n" typ typ typ;
5217 pr " CAMLparam0 ();\n";
5218 pr " CAMLlocal2 (rv, v);\n";
5220 pr " rv = caml_alloc (%d, 0);\n" (List.length cols);
5225 pr " v = caml_copy_int64 (%s->%s);\n" typ name
5227 pr " Store_field (rv, %d, v);\n" i
5229 pr " CAMLreturn (rv);\n";
5232 ) ["stat", stat_cols; "statvfs", statvfs_cols];
5236 fun (name, style, _, _, _, _, _) ->
5238 "gv" :: List.map (fun arg -> name_of_argt arg ^ "v") (snd style) in
5240 pr "CAMLprim value\n";
5241 pr "ocaml_guestfs_%s (value %s" name (List.hd params);
5242 List.iter (pr ", value %s") (List.tl params);
5247 | [p1; p2; p3; p4; p5] ->
5248 pr " CAMLparam5 (%s);\n" (String.concat ", " params)
5249 | p1 :: p2 :: p3 :: p4 :: p5 :: rest ->
5250 pr " CAMLparam5 (%s);\n" (String.concat ", " [p1; p2; p3; p4; p5]);
5251 pr " CAMLxparam%d (%s);\n"
5252 (List.length rest) (String.concat ", " rest)
5254 pr " CAMLparam%d (%s);\n" (List.length ps) (String.concat ", " ps)
5256 pr " CAMLlocal1 (rv);\n";
5259 pr " guestfs_h *g = Guestfs_val (gv);\n";
5260 pr " if (g == NULL)\n";
5261 pr " caml_failwith (\"%s: used handle after closing it\");\n" name;
5269 pr " const char *%s = String_val (%sv);\n" n n
5271 pr " const char *%s =\n" n;
5272 pr " %sv != Val_int (0) ? String_val (Field (%sv, 0)) : NULL;\n"
5275 pr " char **%s = ocaml_guestfs_strings_val (g, %sv);\n" n n
5277 pr " int %s = Bool_val (%sv);\n" n n
5279 pr " int %s = Int_val (%sv);\n" n n
5282 match fst style with
5283 | RErr -> pr " int r;\n"; "-1"
5284 | RInt _ -> pr " int r;\n"; "-1"
5285 | RInt64 _ -> pr " int64_t r;\n"; "-1"
5286 | RBool _ -> pr " int r;\n"; "-1"
5287 | RConstString _ -> pr " const char *r;\n"; "NULL"
5288 | RString _ -> pr " char *r;\n"; "NULL"
5294 pr " struct guestfs_int_bool *r;\n"; "NULL"
5296 pr " struct guestfs_lvm_pv_list *r;\n"; "NULL"
5298 pr " struct guestfs_lvm_vg_list *r;\n"; "NULL"
5300 pr " struct guestfs_lvm_lv_list *r;\n"; "NULL"
5302 pr " struct guestfs_stat *r;\n"; "NULL"
5304 pr " struct guestfs_statvfs *r;\n"; "NULL"
5311 pr " caml_enter_blocking_section ();\n";
5312 pr " r = guestfs_%s " name;
5313 generate_call_args ~handle:"g" (snd style);
5315 pr " caml_leave_blocking_section ();\n";
5320 pr " ocaml_guestfs_free_strings (%s);\n" n;
5321 | String _ | OptString _ | Bool _ | Int _ | FileIn _ | FileOut _ -> ()
5324 pr " if (r == %s)\n" error_code;
5325 pr " ocaml_guestfs_raise_error (g, \"%s\");\n" name;
5328 (match fst style with
5329 | RErr -> pr " rv = Val_unit;\n"
5330 | RInt _ -> pr " rv = Val_int (r);\n"
5332 pr " rv = caml_copy_int64 (r);\n"
5333 | RBool _ -> pr " rv = Val_bool (r);\n"
5334 | RConstString _ -> pr " rv = caml_copy_string (r);\n"
5336 pr " rv = caml_copy_string (r);\n";
5339 pr " rv = caml_copy_string_array ((const char **) r);\n";
5340 pr " for (i = 0; r[i] != NULL; ++i) free (r[i]);\n";
5343 pr " rv = caml_alloc (2, 0);\n";
5344 pr " Store_field (rv, 0, Val_int (r->i));\n";
5345 pr " Store_field (rv, 1, Val_bool (r->b));\n";
5346 pr " guestfs_free_int_bool (r);\n";
5348 pr " rv = copy_lvm_pv_list (r);\n";
5349 pr " guestfs_free_lvm_pv_list (r);\n";
5351 pr " rv = copy_lvm_vg_list (r);\n";
5352 pr " guestfs_free_lvm_vg_list (r);\n";
5354 pr " rv = copy_lvm_lv_list (r);\n";
5355 pr " guestfs_free_lvm_lv_list (r);\n";
5357 pr " rv = copy_stat (r);\n";
5360 pr " rv = copy_statvfs (r);\n";
5363 pr " rv = copy_table (r);\n";
5364 pr " for (i = 0; r[i] != NULL; ++i) free (r[i]);\n";
5368 pr " CAMLreturn (rv);\n";
5372 if List.length params > 5 then (
5373 pr "CAMLprim value\n";
5374 pr "ocaml_guestfs_%s_byte (value *argv, int argn)\n" name;
5376 pr " return ocaml_guestfs_%s (argv[0]" name;
5377 iteri (fun i _ -> pr ", argv[%d]" i) (List.tl params);
5384 and generate_ocaml_lvm_structure_decls () =
5387 pr "type lvm_%s = {\n" typ;
5390 | name, `String -> pr " %s : string;\n" name
5391 | name, `UUID -> pr " %s : string;\n" name
5392 | name, `Bytes -> pr " %s : int64;\n" name
5393 | name, `Int -> pr " %s : int64;\n" name
5394 | name, `OptPercent -> pr " %s : float option;\n" name
5398 ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols]
5400 and generate_ocaml_stat_structure_decls () =
5403 pr "type %s = {\n" typ;
5406 | name, `Int -> pr " %s : int64;\n" name
5410 ) ["stat", stat_cols; "statvfs", statvfs_cols]
5412 and generate_ocaml_prototype ?(is_external = false) name style =
5413 if is_external then pr "external " else pr "val ";
5414 pr "%s : t -> " name;
5417 | String _ | FileIn _ | FileOut _ -> pr "string -> "
5418 | OptString _ -> pr "string option -> "
5419 | StringList _ -> pr "string array -> "
5420 | Bool _ -> pr "bool -> "
5421 | Int _ -> pr "int -> "
5423 (match fst style with
5424 | RErr -> pr "unit" (* all errors are turned into exceptions *)
5425 | RInt _ -> pr "int"
5426 | RInt64 _ -> pr "int64"
5427 | RBool _ -> pr "bool"
5428 | RConstString _ -> pr "string"
5429 | RString _ -> pr "string"
5430 | RStringList _ -> pr "string array"
5431 | RIntBool _ -> pr "int * bool"
5432 | RPVList _ -> pr "lvm_pv array"
5433 | RVGList _ -> pr "lvm_vg array"
5434 | RLVList _ -> pr "lvm_lv array"
5435 | RStat _ -> pr "stat"
5436 | RStatVFS _ -> pr "statvfs"
5437 | RHashtable _ -> pr "(string * string) list"
5439 if is_external then (
5441 if List.length (snd style) + 1 > 5 then
5442 pr "\"ocaml_guestfs_%s_byte\" " name;
5443 pr "\"ocaml_guestfs_%s\"" name
5447 (* Generate Perl xs code, a sort of crazy variation of C with macros. *)
5448 and generate_perl_xs () =
5449 generate_header CStyle LGPLv2;
5452 #include \"EXTERN.h\"
5456 #include <guestfs.h>
5459 #define PRId64 \"lld\"
5463 my_newSVll(long long val) {
5464 #ifdef USE_64_BIT_ALL
5465 return newSViv(val);
5469 len = snprintf(buf, 100, \"%%\" PRId64, val);
5470 return newSVpv(buf, len);
5475 #define PRIu64 \"llu\"
5479 my_newSVull(unsigned long long val) {
5480 #ifdef USE_64_BIT_ALL
5481 return newSVuv(val);
5485 len = snprintf(buf, 100, \"%%\" PRIu64, val);
5486 return newSVpv(buf, len);
5490 /* http://www.perlmonks.org/?node_id=680842 */
5492 XS_unpack_charPtrPtr (SV *arg) {
5497 if (!arg || !SvOK (arg) || !SvROK (arg) || SvTYPE (SvRV (arg)) != SVt_PVAV)
5498 croak (\"array reference expected\");
5500 av = (AV *)SvRV (arg);
5501 ret = malloc ((av_len (av) + 1 + 1) * sizeof (char *));
5503 croak (\"malloc failed\");
5505 for (i = 0; i <= av_len (av); i++) {
5506 SV **elem = av_fetch (av, i, 0);
5508 if (!elem || !*elem)
5509 croak (\"missing element in list\");
5511 ret[i] = SvPV_nolen (*elem);
5519 MODULE = Sys::Guestfs PACKAGE = Sys::Guestfs
5526 RETVAL = guestfs_create ();
5528 croak (\"could not create guestfs handle\");
5529 guestfs_set_error_handler (RETVAL, NULL, NULL);
5542 fun (name, style, _, _, _, _, _) ->
5543 (match fst style with
5544 | RErr -> pr "void\n"
5545 | RInt _ -> pr "SV *\n"
5546 | RInt64 _ -> pr "SV *\n"
5547 | RBool _ -> pr "SV *\n"
5548 | RConstString _ -> pr "SV *\n"
5549 | RString _ -> pr "SV *\n"
5552 | RPVList _ | RVGList _ | RLVList _
5553 | RStat _ | RStatVFS _
5555 pr "void\n" (* all lists returned implictly on the stack *)
5557 (* Call and arguments. *)
5559 generate_call_args ~handle:"g" (snd style);
5561 pr " guestfs_h *g;\n";
5565 | String n | FileIn n | FileOut n -> pr " char *%s;\n" n
5567 (* http://www.perlmonks.org/?node_id=554277
5568 * Note that the implicit handle argument means we have
5569 * to add 1 to the ST(x) operator.
5571 pr " char *%s = SvOK(ST(%d)) ? SvPV_nolen(ST(%d)) : NULL;\n" n (i+1) (i+1)
5572 | StringList n -> pr " char **%s;\n" n
5573 | Bool n -> pr " int %s;\n" n
5574 | Int n -> pr " int %s;\n" n
5577 let do_cleanups () =
5580 | String _ | OptString _ | Bool _ | Int _
5581 | FileIn _ | FileOut _ -> ()
5582 | StringList n -> pr " free (%s);\n" n
5587 (match fst style with
5592 pr " r = guestfs_%s " name;
5593 generate_call_args ~handle:"g" (snd style);
5596 pr " if (r == -1)\n";
5597 pr " croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5603 pr " %s = guestfs_%s " n name;
5604 generate_call_args ~handle:"g" (snd style);
5607 pr " if (%s == -1)\n" n;
5608 pr " croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5609 pr " RETVAL = newSViv (%s);\n" n;
5614 pr " int64_t %s;\n" n;
5616 pr " %s = guestfs_%s " n name;
5617 generate_call_args ~handle:"g" (snd style);
5620 pr " if (%s == -1)\n" n;
5621 pr " croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5622 pr " RETVAL = my_newSVll (%s);\n" n;
5627 pr " const char *%s;\n" n;
5629 pr " %s = guestfs_%s " n name;
5630 generate_call_args ~handle:"g" (snd style);
5633 pr " if (%s == NULL)\n" n;
5634 pr " croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5635 pr " RETVAL = newSVpv (%s, 0);\n" n;
5640 pr " char *%s;\n" n;
5642 pr " %s = guestfs_%s " n name;
5643 generate_call_args ~handle:"g" (snd style);
5646 pr " if (%s == NULL)\n" n;
5647 pr " croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5648 pr " RETVAL = newSVpv (%s, 0);\n" n;
5649 pr " free (%s);\n" n;
5652 | RStringList n | RHashtable n ->
5654 pr " char **%s;\n" n;
5657 pr " %s = guestfs_%s " n name;
5658 generate_call_args ~handle:"g" (snd style);
5661 pr " if (%s == NULL)\n" n;
5662 pr " croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5663 pr " for (n = 0; %s[n] != NULL; ++n) /**/;\n" n;
5664 pr " EXTEND (SP, n);\n";
5665 pr " for (i = 0; i < n; ++i) {\n";
5666 pr " PUSHs (sv_2mortal (newSVpv (%s[i], 0)));\n" n;
5667 pr " free (%s[i]);\n" n;
5669 pr " free (%s);\n" n;
5672 pr " struct guestfs_int_bool *r;\n";
5674 pr " r = guestfs_%s " name;
5675 generate_call_args ~handle:"g" (snd style);
5678 pr " if (r == NULL)\n";
5679 pr " croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5680 pr " EXTEND (SP, 2);\n";
5681 pr " PUSHs (sv_2mortal (newSViv (r->i)));\n";
5682 pr " PUSHs (sv_2mortal (newSViv (r->b)));\n";
5683 pr " guestfs_free_int_bool (r);\n";
5685 generate_perl_lvm_code "pv" pv_cols name style n do_cleanups
5687 generate_perl_lvm_code "vg" vg_cols name style n do_cleanups
5689 generate_perl_lvm_code "lv" lv_cols name style n do_cleanups
5691 generate_perl_stat_code "stat" stat_cols name style n do_cleanups
5693 generate_perl_stat_code
5694 "statvfs" statvfs_cols name style n do_cleanups
5700 and generate_perl_lvm_code typ cols name style n do_cleanups =
5702 pr " struct guestfs_lvm_%s_list *%s;\n" typ n;
5706 pr " %s = guestfs_%s " n name;
5707 generate_call_args ~handle:"g" (snd style);
5710 pr " if (%s == NULL)\n" n;
5711 pr " croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5712 pr " EXTEND (SP, %s->len);\n" n;
5713 pr " for (i = 0; i < %s->len; ++i) {\n" n;
5714 pr " hv = newHV ();\n";
5718 pr " (void) hv_store (hv, \"%s\", %d, newSVpv (%s->val[i].%s, 0), 0);\n"
5719 name (String.length name) n name
5721 pr " (void) hv_store (hv, \"%s\", %d, newSVpv (%s->val[i].%s, 32), 0);\n"
5722 name (String.length name) n name
5724 pr " (void) hv_store (hv, \"%s\", %d, my_newSVull (%s->val[i].%s), 0);\n"
5725 name (String.length name) n name
5727 pr " (void) hv_store (hv, \"%s\", %d, my_newSVll (%s->val[i].%s), 0);\n"
5728 name (String.length name) n name
5729 | name, `OptPercent ->
5730 pr " (void) hv_store (hv, \"%s\", %d, newSVnv (%s->val[i].%s), 0);\n"
5731 name (String.length name) n name
5733 pr " PUSHs (sv_2mortal ((SV *) hv));\n";
5735 pr " guestfs_free_lvm_%s_list (%s);\n" typ n
5737 and generate_perl_stat_code typ cols name style n do_cleanups =
5739 pr " struct guestfs_%s *%s;\n" typ n;
5741 pr " %s = guestfs_%s " n name;
5742 generate_call_args ~handle:"g" (snd style);
5745 pr " if (%s == NULL)\n" n;
5746 pr " croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5747 pr " EXTEND (SP, %d);\n" (List.length cols);
5751 pr " PUSHs (sv_2mortal (my_newSVll (%s->%s)));\n" n name
5753 pr " free (%s);\n" n
5755 (* Generate Sys/Guestfs.pm. *)
5756 and generate_perl_pm () =
5757 generate_header HashStyle LGPLv2;
5764 Sys::Guestfs - Perl bindings for libguestfs
5770 my $h = Sys::Guestfs->new ();
5771 $h->add_drive ('guest.img');
5774 $h->mount ('/dev/sda1', '/');
5775 $h->touch ('/hello');
5780 The C<Sys::Guestfs> module provides a Perl XS binding to the
5781 libguestfs API for examining and modifying virtual machine
5784 Amongst the things this is good for: making batch configuration
5785 changes to guests, getting disk used/free statistics (see also:
5786 virt-df), migrating between virtualization systems (see also:
5787 virt-p2v), performing partial backups, performing partial guest
5788 clones, cloning guests and changing registry/UUID/hostname info, and
5791 Libguestfs uses Linux kernel and qemu code, and can access any type of
5792 guest filesystem that Linux and qemu can, including but not limited
5793 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
5794 schemes, qcow, qcow2, vmdk.
5796 Libguestfs provides ways to enumerate guest storage (eg. partitions,
5797 LVs, what filesystem is in each LV, etc.). It can also run commands
5798 in the context of the guest. Also you can access filesystems over FTP.
5802 All errors turn into calls to C<croak> (see L<Carp(3)>).
5810 package Sys::Guestfs;
5816 XSLoader::load ('Sys::Guestfs');
5818 =item $h = Sys::Guestfs->new ();
5820 Create a new guestfs handle.
5826 my $class = ref ($proto) || $proto;
5828 my $self = Sys::Guestfs::_create ();
5829 bless $self, $class;
5835 (* Actions. We only need to print documentation for these as
5836 * they are pulled in from the XS code automatically.
5839 fun (name, style, _, flags, _, _, longdesc) ->
5840 if not (List.mem NotInDocs flags) then (
5841 let longdesc = replace_str longdesc "C<guestfs_" "C<$h-E<gt>" in
5843 generate_perl_prototype name style;
5845 pr "%s\n\n" longdesc;
5846 if List.mem ProtocolLimitWarning flags then
5847 pr "%s\n\n" protocol_limit_warning;
5848 if List.mem DangerWillRobinson flags then
5849 pr "%s\n\n" danger_will_robinson
5851 ) all_functions_sorted;
5863 Copyright (C) 2009 Red Hat Inc.
5867 Please see the file COPYING.LIB for the full license.
5871 L<guestfs(3)>, L<guestfish(1)>.
5876 and generate_perl_prototype name style =
5877 (match fst style with
5883 | RString n -> pr "$%s = " n
5884 | RIntBool (n, m) -> pr "($%s, $%s) = " n m
5888 | RLVList n -> pr "@%s = " n
5891 | RHashtable n -> pr "%%%s = " n
5894 let comma = ref false in
5897 if !comma then pr ", ";
5900 | String n | OptString n | Bool n | Int n | FileIn n | FileOut n ->
5907 (* Generate Python C module. *)
5908 and generate_python_c () =
5909 generate_header CStyle LGPLv2;
5918 #include \"guestfs.h\"
5926 get_handle (PyObject *obj)
5929 assert (obj != Py_None);
5930 return ((Pyguestfs_Object *) obj)->g;
5934 put_handle (guestfs_h *g)
5938 PyCObject_FromVoidPtrAndDesc ((void *) g, (char *) \"guestfs_h\", NULL);
5941 /* This list should be freed (but not the strings) after use. */
5942 static const char **
5943 get_string_list (PyObject *obj)
5950 if (!PyList_Check (obj)) {
5951 PyErr_SetString (PyExc_RuntimeError, \"expecting a list parameter\");
5955 len = PyList_Size (obj);
5956 r = malloc (sizeof (char *) * (len+1));
5958 PyErr_SetString (PyExc_RuntimeError, \"get_string_list: out of memory\");
5962 for (i = 0; i < len; ++i)
5963 r[i] = PyString_AsString (PyList_GetItem (obj, i));
5970 put_string_list (char * const * const argv)
5975 for (argc = 0; argv[argc] != NULL; ++argc)
5978 list = PyList_New (argc);
5979 for (i = 0; i < argc; ++i)
5980 PyList_SetItem (list, i, PyString_FromString (argv[i]));
5986 put_table (char * const * const argv)
5988 PyObject *list, *item;
5991 for (argc = 0; argv[argc] != NULL; ++argc)
5994 list = PyList_New (argc >> 1);
5995 for (i = 0; i < argc; i += 2) {
5996 item = PyTuple_New (2);
5997 PyTuple_SetItem (item, 0, PyString_FromString (argv[i]));
5998 PyTuple_SetItem (item, 1, PyString_FromString (argv[i+1]));
5999 PyList_SetItem (list, i >> 1, item);
6006 free_strings (char **argv)
6010 for (argc = 0; argv[argc] != NULL; ++argc)
6016 py_guestfs_create (PyObject *self, PyObject *args)
6020 g = guestfs_create ();
6022 PyErr_SetString (PyExc_RuntimeError,
6023 \"guestfs.create: failed to allocate handle\");
6026 guestfs_set_error_handler (g, NULL, NULL);
6027 return put_handle (g);
6031 py_guestfs_close (PyObject *self, PyObject *args)
6036 if (!PyArg_ParseTuple (args, (char *) \"O:guestfs_close\", &py_g))
6038 g = get_handle (py_g);
6042 Py_INCREF (Py_None);
6048 (* LVM structures, turned into Python dictionaries. *)
6051 pr "static PyObject *\n";
6052 pr "put_lvm_%s (struct guestfs_lvm_%s *%s)\n" typ typ typ;
6054 pr " PyObject *dict;\n";
6056 pr " dict = PyDict_New ();\n";
6060 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
6061 pr " PyString_FromString (%s->%s));\n"
6064 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
6065 pr " PyString_FromStringAndSize (%s->%s, 32));\n"
6068 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
6069 pr " PyLong_FromUnsignedLongLong (%s->%s));\n"
6072 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
6073 pr " PyLong_FromLongLong (%s->%s));\n"
6075 | name, `OptPercent ->
6076 pr " if (%s->%s >= 0)\n" typ name;
6077 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
6078 pr " PyFloat_FromDouble ((double) %s->%s));\n"
6081 pr " Py_INCREF (Py_None);\n";
6082 pr " PyDict_SetItemString (dict, \"%s\", Py_None);" name;
6085 pr " return dict;\n";
6089 pr "static PyObject *\n";
6090 pr "put_lvm_%s_list (struct guestfs_lvm_%s_list *%ss)\n" typ typ typ;
6092 pr " PyObject *list;\n";
6095 pr " list = PyList_New (%ss->len);\n" typ;
6096 pr " for (i = 0; i < %ss->len; ++i)\n" typ;
6097 pr " PyList_SetItem (list, i, put_lvm_%s (&%ss->val[i]));\n" typ typ;
6098 pr " return list;\n";
6101 ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
6103 (* Stat structures, turned into Python dictionaries. *)
6106 pr "static PyObject *\n";
6107 pr "put_%s (struct guestfs_%s *%s)\n" typ typ typ;
6109 pr " PyObject *dict;\n";
6111 pr " dict = PyDict_New ();\n";
6115 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
6116 pr " PyLong_FromLongLong (%s->%s));\n"
6119 pr " return dict;\n";
6122 ) ["stat", stat_cols; "statvfs", statvfs_cols];
6124 (* Python wrapper functions. *)
6126 fun (name, style, _, _, _, _, _) ->
6127 pr "static PyObject *\n";
6128 pr "py_guestfs_%s (PyObject *self, PyObject *args)\n" name;
6131 pr " PyObject *py_g;\n";
6132 pr " guestfs_h *g;\n";
6133 pr " PyObject *py_r;\n";
6136 match fst style with
6137 | RErr | RInt _ | RBool _ -> pr " int r;\n"; "-1"
6138 | RInt64 _ -> pr " int64_t r;\n"; "-1"
6139 | RConstString _ -> pr " const char *r;\n"; "NULL"
6140 | RString _ -> pr " char *r;\n"; "NULL"
6141 | RStringList _ | RHashtable _ -> pr " char **r;\n"; "NULL"
6142 | RIntBool _ -> pr " struct guestfs_int_bool *r;\n"; "NULL"
6143 | RPVList n -> pr " struct guestfs_lvm_pv_list *r;\n"; "NULL"
6144 | RVGList n -> pr " struct guestfs_lvm_vg_list *r;\n"; "NULL"
6145 | RLVList n -> pr " struct guestfs_lvm_lv_list *r;\n"; "NULL"
6146 | RStat n -> pr " struct guestfs_stat *r;\n"; "NULL"
6147 | RStatVFS n -> pr " struct guestfs_statvfs *r;\n"; "NULL" in
6151 | String n | FileIn n | FileOut n -> pr " const char *%s;\n" n
6152 | OptString n -> pr " const char *%s;\n" n
6154 pr " PyObject *py_%s;\n" n;
6155 pr " const char **%s;\n" n
6156 | Bool n -> pr " int %s;\n" n
6157 | Int n -> pr " int %s;\n" n
6162 (* Convert the parameters. *)
6163 pr " if (!PyArg_ParseTuple (args, (char *) \"O";
6166 | String _ | FileIn _ | FileOut _ -> pr "s"
6167 | OptString _ -> pr "z"
6168 | StringList _ -> pr "O"
6169 | Bool _ -> pr "i" (* XXX Python has booleans? *)
6172 pr ":guestfs_%s\",\n" name;
6176 | String n | FileIn n | FileOut n -> pr ", &%s" n
6177 | OptString n -> pr ", &%s" n
6178 | StringList n -> pr ", &py_%s" n
6179 | Bool n -> pr ", &%s" n
6180 | Int n -> pr ", &%s" n
6184 pr " return NULL;\n";
6186 pr " g = get_handle (py_g);\n";
6189 | String _ | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ -> ()
6191 pr " %s = get_string_list (py_%s);\n" n n;
6192 pr " if (!%s) return NULL;\n" n
6197 pr " r = guestfs_%s " name;
6198 generate_call_args ~handle:"g" (snd style);
6203 | String _ | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ -> ()
6205 pr " free (%s);\n" n
6208 pr " if (r == %s) {\n" error_code;
6209 pr " PyErr_SetString (PyExc_RuntimeError, guestfs_last_error (g));\n";
6210 pr " return NULL;\n";
6214 (match fst style with
6216 pr " Py_INCREF (Py_None);\n";
6217 pr " py_r = Py_None;\n"
6219 | RBool _ -> pr " py_r = PyInt_FromLong ((long) r);\n"
6220 | RInt64 _ -> pr " py_r = PyLong_FromLongLong (r);\n"
6221 | RConstString _ -> pr " py_r = PyString_FromString (r);\n"
6223 pr " py_r = PyString_FromString (r);\n";
6226 pr " py_r = put_string_list (r);\n";
6227 pr " free_strings (r);\n"
6229 pr " py_r = PyTuple_New (2);\n";
6230 pr " PyTuple_SetItem (py_r, 0, PyInt_FromLong ((long) r->i));\n";
6231 pr " PyTuple_SetItem (py_r, 1, PyInt_FromLong ((long) r->b));\n";
6232 pr " guestfs_free_int_bool (r);\n"
6234 pr " py_r = put_lvm_pv_list (r);\n";
6235 pr " guestfs_free_lvm_pv_list (r);\n"
6237 pr " py_r = put_lvm_vg_list (r);\n";
6238 pr " guestfs_free_lvm_vg_list (r);\n"
6240 pr " py_r = put_lvm_lv_list (r);\n";
6241 pr " guestfs_free_lvm_lv_list (r);\n"
6243 pr " py_r = put_stat (r);\n";
6246 pr " py_r = put_statvfs (r);\n";
6249 pr " py_r = put_table (r);\n";
6250 pr " free_strings (r);\n"
6253 pr " return py_r;\n";
6258 (* Table of functions. *)
6259 pr "static PyMethodDef methods[] = {\n";
6260 pr " { (char *) \"create\", py_guestfs_create, METH_VARARGS, NULL },\n";
6261 pr " { (char *) \"close\", py_guestfs_close, METH_VARARGS, NULL },\n";
6263 fun (name, _, _, _, _, _, _) ->
6264 pr " { (char *) \"%s\", py_guestfs_%s, METH_VARARGS, NULL },\n"
6267 pr " { NULL, NULL, 0, NULL }\n";
6271 (* Init function. *)
6274 initlibguestfsmod (void)
6276 static int initialized = 0;
6278 if (initialized) return;
6279 Py_InitModule ((char *) \"libguestfsmod\", methods);
6284 (* Generate Python module. *)
6285 and generate_python_py () =
6286 generate_header HashStyle LGPLv2;
6289 u\"\"\"Python bindings for libguestfs
6292 g = guestfs.GuestFS ()
6293 g.add_drive (\"guest.img\")
6296 parts = g.list_partitions ()
6298 The guestfs module provides a Python binding to the libguestfs API
6299 for examining and modifying virtual machine disk images.
6301 Amongst the things this is good for: making batch configuration
6302 changes to guests, getting disk used/free statistics (see also:
6303 virt-df), migrating between virtualization systems (see also:
6304 virt-p2v), performing partial backups, performing partial guest
6305 clones, cloning guests and changing registry/UUID/hostname info, and
6308 Libguestfs uses Linux kernel and qemu code, and can access any type of
6309 guest filesystem that Linux and qemu can, including but not limited
6310 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
6311 schemes, qcow, qcow2, vmdk.
6313 Libguestfs provides ways to enumerate guest storage (eg. partitions,
6314 LVs, what filesystem is in each LV, etc.). It can also run commands
6315 in the context of the guest. Also you can access filesystems over FTP.
6317 Errors which happen while using the API are turned into Python
6318 RuntimeError exceptions.
6320 To create a guestfs handle you usually have to perform the following
6323 # Create the handle, call add_drive at least once, and possibly
6324 # several times if the guest has multiple block devices:
6325 g = guestfs.GuestFS ()
6326 g.add_drive (\"guest.img\")
6328 # Launch the qemu subprocess and wait for it to become ready:
6332 # Now you can issue commands, for example:
6337 import libguestfsmod
6340 \"\"\"Instances of this class are libguestfs API handles.\"\"\"
6342 def __init__ (self):
6343 \"\"\"Create a new libguestfs handle.\"\"\"
6344 self._o = libguestfsmod.create ()
6347 libguestfsmod.close (self._o)
6352 fun (name, style, _, flags, _, _, longdesc) ->
6354 generate_call_args ~handle:"self" (snd style);
6357 if not (List.mem NotInDocs flags) then (
6358 let doc = replace_str longdesc "C<guestfs_" "C<g." in
6360 match fst style with
6361 | RErr | RInt _ | RInt64 _ | RBool _ | RConstString _
6364 doc ^ "\n\nThis function returns a list of strings."
6366 doc ^ "\n\nThis function returns a tuple (int, bool).\n"
6368 doc ^ "\n\nThis function returns a list of PVs. Each PV is represented as a dictionary."
6370 doc ^ "\n\nThis function returns a list of VGs. Each VG is represented as a dictionary."
6372 doc ^ "\n\nThis function returns a list of LVs. Each LV is represented as a dictionary."
6374 doc ^ "\n\nThis function returns a dictionary, with keys matching the various fields in the stat structure."
6376 doc ^ "\n\nThis function returns a dictionary, with keys matching the various fields in the statvfs structure."
6378 doc ^ "\n\nThis function returns a dictionary." in
6380 if List.mem ProtocolLimitWarning flags then
6381 doc ^ "\n\n" ^ protocol_limit_warning
6384 if List.mem DangerWillRobinson flags then
6385 doc ^ "\n\n" ^ danger_will_robinson
6387 let doc = pod2text ~width:60 name doc in
6388 let doc = List.map (fun line -> replace_str line "\\" "\\\\") doc in
6389 let doc = String.concat "\n " doc in
6390 pr " u\"\"\"%s\"\"\"\n" doc;
6392 pr " return libguestfsmod.%s " name;
6393 generate_call_args ~handle:"self._o" (snd style);
6398 (* Useful if you need the longdesc POD text as plain text. Returns a
6401 * This is the slowest thing about autogeneration.
6403 and pod2text ~width name longdesc =
6404 let filename, chan = Filename.open_temp_file "gen" ".tmp" in
6405 fprintf chan "=head1 %s\n\n%s\n" name longdesc;
6407 let cmd = sprintf "pod2text -w %d %s" width (Filename.quote filename) in
6408 let chan = Unix.open_process_in cmd in
6409 let lines = ref [] in
6411 let line = input_line chan in
6412 if i = 1 then (* discard the first line of output *)
6415 let line = triml line in
6416 lines := line :: !lines;
6419 let lines = try loop 1 with End_of_file -> List.rev !lines in
6420 Unix.unlink filename;
6421 match Unix.close_process_in chan with
6422 | Unix.WEXITED 0 -> lines
6424 failwithf "pod2text: process exited with non-zero status (%d)" i
6425 | Unix.WSIGNALED i | Unix.WSTOPPED i ->
6426 failwithf "pod2text: process signalled or stopped by signal %d" i
6428 (* Generate ruby bindings. *)
6429 and generate_ruby_c () =
6430 generate_header CStyle LGPLv2;
6438 #include \"guestfs.h\"
6440 #include \"extconf.h\"
6442 /* For Ruby < 1.9 */
6444 #define RARRAY_LEN(r) (RARRAY((r))->len)
6447 static VALUE m_guestfs; /* guestfs module */
6448 static VALUE c_guestfs; /* guestfs_h handle */
6449 static VALUE e_Error; /* used for all errors */
6451 static void ruby_guestfs_free (void *p)
6454 guestfs_close ((guestfs_h *) p);
6457 static VALUE ruby_guestfs_create (VALUE m)
6461 g = guestfs_create ();
6463 rb_raise (e_Error, \"failed to create guestfs handle\");
6465 /* Don't print error messages to stderr by default. */
6466 guestfs_set_error_handler (g, NULL, NULL);
6468 /* Wrap it, and make sure the close function is called when the
6471 return Data_Wrap_Struct (c_guestfs, NULL, ruby_guestfs_free, g);
6474 static VALUE ruby_guestfs_close (VALUE gv)
6477 Data_Get_Struct (gv, guestfs_h, g);
6479 ruby_guestfs_free (g);
6480 DATA_PTR (gv) = NULL;
6488 fun (name, style, _, _, _, _, _) ->
6489 pr "static VALUE ruby_guestfs_%s (VALUE gv" name;
6490 List.iter (fun arg -> pr ", VALUE %sv" (name_of_argt arg)) (snd style);
6493 pr " guestfs_h *g;\n";
6494 pr " Data_Get_Struct (gv, guestfs_h, g);\n";
6496 pr " rb_raise (rb_eArgError, \"%%s: used handle after closing it\", \"%s\");\n"
6502 | String n | FileIn n | FileOut n ->
6503 pr " Check_Type (%sv, T_STRING);\n" n;
6504 pr " const char *%s = StringValueCStr (%sv);\n" n n;
6506 pr " rb_raise (rb_eTypeError, \"expected string for parameter %%s of %%s\",\n";
6507 pr " \"%s\", \"%s\");\n" n name
6509 pr " const char *%s = !NIL_P (%sv) ? StringValueCStr (%sv) : NULL;\n" n n n
6511 pr " char **%s;\n" n;
6512 pr " Check_Type (%sv, T_ARRAY);\n" n;
6514 pr " int i, len;\n";
6515 pr " len = RARRAY_LEN (%sv);\n" n;
6516 pr " %s = guestfs_safe_malloc (g, sizeof (char *) * (len+1));\n"
6518 pr " for (i = 0; i < len; ++i) {\n";
6519 pr " VALUE v = rb_ary_entry (%sv, i);\n" n;
6520 pr " %s[i] = StringValueCStr (v);\n" n;
6522 pr " %s[len] = NULL;\n" n;
6525 pr " int %s = RTEST (%sv);\n" n n
6527 pr " int %s = NUM2INT (%sv);\n" n n
6532 match fst style with
6533 | RErr | RInt _ | RBool _ -> pr " int r;\n"; "-1"
6534 | RInt64 _ -> pr " int64_t r;\n"; "-1"
6535 | RConstString _ -> pr " const char *r;\n"; "NULL"
6536 | RString _ -> pr " char *r;\n"; "NULL"
6537 | RStringList _ | RHashtable _ -> pr " char **r;\n"; "NULL"
6538 | RIntBool _ -> pr " struct guestfs_int_bool *r;\n"; "NULL"
6539 | RPVList n -> pr " struct guestfs_lvm_pv_list *r;\n"; "NULL"
6540 | RVGList n -> pr " struct guestfs_lvm_vg_list *r;\n"; "NULL"
6541 | RLVList n -> pr " struct guestfs_lvm_lv_list *r;\n"; "NULL"
6542 | RStat n -> pr " struct guestfs_stat *r;\n"; "NULL"
6543 | RStatVFS n -> pr " struct guestfs_statvfs *r;\n"; "NULL" in
6546 pr " r = guestfs_%s " name;
6547 generate_call_args ~handle:"g" (snd style);
6552 | String _ | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ -> ()
6554 pr " free (%s);\n" n
6557 pr " if (r == %s)\n" error_code;
6558 pr " rb_raise (e_Error, \"%%s\", guestfs_last_error (g));\n";
6561 (match fst style with
6563 pr " return Qnil;\n"
6564 | RInt _ | RBool _ ->
6565 pr " return INT2NUM (r);\n"
6567 pr " return ULL2NUM (r);\n"
6569 pr " return rb_str_new2 (r);\n";
6571 pr " VALUE rv = rb_str_new2 (r);\n";
6575 pr " int i, len = 0;\n";
6576 pr " for (i = 0; r[i] != NULL; ++i) len++;\n";
6577 pr " VALUE rv = rb_ary_new2 (len);\n";
6578 pr " for (i = 0; r[i] != NULL; ++i) {\n";
6579 pr " rb_ary_push (rv, rb_str_new2 (r[i]));\n";
6580 pr " free (r[i]);\n";
6585 pr " VALUE rv = rb_ary_new2 (2);\n";
6586 pr " rb_ary_push (rv, INT2NUM (r->i));\n";
6587 pr " rb_ary_push (rv, INT2NUM (r->b));\n";
6588 pr " guestfs_free_int_bool (r);\n";
6591 generate_ruby_lvm_code "pv" pv_cols
6593 generate_ruby_lvm_code "vg" vg_cols
6595 generate_ruby_lvm_code "lv" lv_cols
6597 pr " VALUE rv = rb_hash_new ();\n";
6601 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), ULL2NUM (r->%s));\n" name name
6606 pr " VALUE rv = rb_hash_new ();\n";
6610 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), ULL2NUM (r->%s));\n" name name
6615 pr " VALUE rv = rb_hash_new ();\n";
6617 pr " for (i = 0; r[i] != NULL; i+=2) {\n";
6618 pr " rb_hash_aset (rv, rb_str_new2 (r[i]), rb_str_new2 (r[i+1]));\n";
6619 pr " free (r[i]);\n";
6620 pr " free (r[i+1]);\n";
6631 /* Initialize the module. */
6632 void Init__guestfs ()
6634 m_guestfs = rb_define_module (\"Guestfs\");
6635 c_guestfs = rb_define_class_under (m_guestfs, \"Guestfs\", rb_cObject);
6636 e_Error = rb_define_class_under (m_guestfs, \"Error\", rb_eStandardError);
6638 rb_define_module_function (m_guestfs, \"create\", ruby_guestfs_create, 0);
6639 rb_define_method (c_guestfs, \"close\", ruby_guestfs_close, 0);
6642 (* Define the rest of the methods. *)
6644 fun (name, style, _, _, _, _, _) ->
6645 pr " rb_define_method (c_guestfs, \"%s\",\n" name;
6646 pr " ruby_guestfs_%s, %d);\n" name (List.length (snd style))
6651 (* Ruby code to return an LVM struct list. *)
6652 and generate_ruby_lvm_code typ cols =
6653 pr " VALUE rv = rb_ary_new2 (r->len);\n";
6655 pr " for (i = 0; i < r->len; ++i) {\n";
6656 pr " VALUE hv = rb_hash_new ();\n";
6660 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_str_new2 (r->val[i].%s));\n" name name
6662 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_str_new (r->val[i].%s, 32));\n" name name
6665 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), ULL2NUM (r->val[i].%s));\n" name name
6666 | name, `OptPercent ->
6667 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_dbl2big (r->val[i].%s));\n" name name
6669 pr " rb_ary_push (rv, hv);\n";
6671 pr " guestfs_free_lvm_%s_list (r);\n" typ;
6674 (* Generate Java bindings GuestFS.java file. *)
6675 and generate_java_java () =
6676 generate_header CStyle LGPLv2;
6679 package com.redhat.et.libguestfs;
6681 import java.util.HashMap;
6682 import com.redhat.et.libguestfs.LibGuestFSException;
6683 import com.redhat.et.libguestfs.PV;
6684 import com.redhat.et.libguestfs.VG;
6685 import com.redhat.et.libguestfs.LV;
6686 import com.redhat.et.libguestfs.Stat;
6687 import com.redhat.et.libguestfs.StatVFS;
6688 import com.redhat.et.libguestfs.IntBool;
6691 * The GuestFS object is a libguestfs handle.
6695 public class GuestFS {
6696 // Load the native code.
6698 System.loadLibrary (\"guestfs_jni\");
6702 * The native guestfs_h pointer.
6707 * Create a libguestfs handle.
6709 * @throws LibGuestFSException
6711 public GuestFS () throws LibGuestFSException
6715 private native long _create () throws LibGuestFSException;
6718 * Close a libguestfs handle.
6720 * You can also leave handles to be collected by the garbage
6721 * collector, but this method ensures that the resources used
6722 * by the handle are freed up immediately. If you call any
6723 * other methods after closing the handle, you will get an
6726 * @throws LibGuestFSException
6728 public void close () throws LibGuestFSException
6734 private native void _close (long g) throws LibGuestFSException;
6736 public void finalize () throws LibGuestFSException
6744 fun (name, style, _, flags, _, shortdesc, longdesc) ->
6745 if not (List.mem NotInDocs flags); then (
6746 let doc = replace_str longdesc "C<guestfs_" "C<g." in
6748 if List.mem ProtocolLimitWarning flags then
6749 doc ^ "\n\n" ^ protocol_limit_warning
6752 if List.mem DangerWillRobinson flags then
6753 doc ^ "\n\n" ^ danger_will_robinson
6755 let doc = pod2text ~width:60 name doc in
6756 let doc = List.map ( (* RHBZ#501883 *)
6759 | nonempty -> nonempty
6761 let doc = String.concat "\n * " doc in
6764 pr " * %s\n" shortdesc;
6767 pr " * @throws LibGuestFSException\n";
6771 generate_java_prototype ~public:true ~semicolon:false name style;
6774 pr " if (g == 0)\n";
6775 pr " throw new LibGuestFSException (\"%s: handle is closed\");\n"
6778 if fst style <> RErr then pr "return ";
6780 generate_call_args ~handle:"g" (snd style);
6784 generate_java_prototype ~privat:true ~native:true name style;
6791 and generate_java_prototype ?(public=false) ?(privat=false) ?(native=false)
6792 ?(semicolon=true) name style =
6793 if privat then pr "private ";
6794 if public then pr "public ";
6795 if native then pr "native ";
6798 (match fst style with
6799 | RErr -> pr "void ";
6800 | RInt _ -> pr "int ";
6801 | RInt64 _ -> pr "long ";
6802 | RBool _ -> pr "boolean ";
6803 | RConstString _ | RString _ -> pr "String ";
6804 | RStringList _ -> pr "String[] ";
6805 | RIntBool _ -> pr "IntBool ";
6806 | RPVList _ -> pr "PV[] ";
6807 | RVGList _ -> pr "VG[] ";
6808 | RLVList _ -> pr "LV[] ";
6809 | RStat _ -> pr "Stat ";
6810 | RStatVFS _ -> pr "StatVFS ";
6811 | RHashtable _ -> pr "HashMap<String,String> ";
6814 if native then pr "_%s " name else pr "%s " name;
6816 let needs_comma = ref false in
6825 if !needs_comma then pr ", ";
6826 needs_comma := true;
6843 pr " throws LibGuestFSException";
6844 if semicolon then pr ";"
6846 and generate_java_struct typ cols =
6847 generate_header CStyle LGPLv2;
6850 package com.redhat.et.libguestfs;
6853 * Libguestfs %s structure.
6864 | name, `UUID -> pr " public String %s;\n" name
6866 | name, `Int -> pr " public long %s;\n" name
6867 | name, `OptPercent ->
6868 pr " /* The next field is [0..100] or -1 meaning 'not present': */\n";
6869 pr " public float %s;\n" name
6874 and generate_java_c () =
6875 generate_header CStyle LGPLv2;
6882 #include \"com_redhat_et_libguestfs_GuestFS.h\"
6883 #include \"guestfs.h\"
6885 /* Note that this function returns. The exception is not thrown
6886 * until after the wrapper function returns.
6889 throw_exception (JNIEnv *env, const char *msg)
6892 cl = (*env)->FindClass (env,
6893 \"com/redhat/et/libguestfs/LibGuestFSException\");
6894 (*env)->ThrowNew (env, cl, msg);
6897 JNIEXPORT jlong JNICALL
6898 Java_com_redhat_et_libguestfs_GuestFS__1create
6899 (JNIEnv *env, jobject obj)
6903 g = guestfs_create ();
6905 throw_exception (env, \"GuestFS.create: failed to allocate handle\");
6908 guestfs_set_error_handler (g, NULL, NULL);
6909 return (jlong) (long) g;
6912 JNIEXPORT void JNICALL
6913 Java_com_redhat_et_libguestfs_GuestFS__1close
6914 (JNIEnv *env, jobject obj, jlong jg)
6916 guestfs_h *g = (guestfs_h *) (long) jg;
6923 fun (name, style, _, _, _, _, _) ->
6925 (match fst style with
6926 | RErr -> pr "void ";
6927 | RInt _ -> pr "jint ";
6928 | RInt64 _ -> pr "jlong ";
6929 | RBool _ -> pr "jboolean ";
6930 | RConstString _ | RString _ -> pr "jstring ";
6931 | RIntBool _ | RStat _ | RStatVFS _ | RHashtable _ ->
6933 | RStringList _ | RPVList _ | RVGList _ | RLVList _ ->
6937 pr "Java_com_redhat_et_libguestfs_GuestFS_";
6938 pr "%s" (replace_str ("_" ^ name) "_" "_1");
6940 pr " (JNIEnv *env, jobject obj, jlong jg";
6947 pr ", jstring j%s" n
6949 pr ", jobjectArray j%s" n
6951 pr ", jboolean j%s" n
6957 pr " guestfs_h *g = (guestfs_h *) (long) jg;\n";
6958 let error_code, no_ret =
6959 match fst style with
6960 | RErr -> pr " int r;\n"; "-1", ""
6962 | RInt _ -> pr " int r;\n"; "-1", "0"
6963 | RInt64 _ -> pr " int64_t r;\n"; "-1", "0"
6964 | RConstString _ -> pr " const char *r;\n"; "NULL", "NULL"
6966 pr " jstring jr;\n";
6967 pr " char *r;\n"; "NULL", "NULL"
6969 pr " jobjectArray jr;\n";
6972 pr " jstring jstr;\n";
6973 pr " char **r;\n"; "NULL", "NULL"
6975 pr " jobject jr;\n";
6977 pr " jfieldID fl;\n";
6978 pr " struct guestfs_int_bool *r;\n"; "NULL", "NULL"
6980 pr " jobject jr;\n";
6982 pr " jfieldID fl;\n";
6983 pr " struct guestfs_stat *r;\n"; "NULL", "NULL"
6985 pr " jobject jr;\n";
6987 pr " jfieldID fl;\n";
6988 pr " struct guestfs_statvfs *r;\n"; "NULL", "NULL"
6990 pr " jobjectArray jr;\n";
6992 pr " jfieldID fl;\n";
6993 pr " jobject jfl;\n";
6994 pr " struct guestfs_lvm_pv_list *r;\n"; "NULL", "NULL"
6996 pr " jobjectArray jr;\n";
6998 pr " jfieldID fl;\n";
6999 pr " jobject jfl;\n";
7000 pr " struct guestfs_lvm_vg_list *r;\n"; "NULL", "NULL"
7002 pr " jobjectArray jr;\n";
7004 pr " jfieldID fl;\n";
7005 pr " jobject jfl;\n";
7006 pr " struct guestfs_lvm_lv_list *r;\n"; "NULL", "NULL"
7007 | RHashtable _ -> pr " char **r;\n"; "NULL", "NULL" in
7014 pr " const char *%s;\n" n
7016 pr " int %s_len;\n" n;
7017 pr " const char **%s;\n" n
7024 (match fst style with
7025 | RStringList _ | RPVList _ | RVGList _ | RLVList _ -> true
7026 | RErr | RBool _ | RInt _ | RInt64 _ | RConstString _
7027 | RString _ | RIntBool _ | RStat _ | RStatVFS _
7028 | RHashtable _ -> false) ||
7029 List.exists (function StringList _ -> true | _ -> false) (snd style) in
7035 (* Get the parameters. *)
7041 pr " %s = (*env)->GetStringUTFChars (env, j%s, NULL);\n" n n
7043 (* This is completely undocumented, but Java null becomes
7046 pr " %s = j%s ? (*env)->GetStringUTFChars (env, j%s, NULL) : NULL;\n" n n n
7048 pr " %s_len = (*env)->GetArrayLength (env, j%s);\n" n n;
7049 pr " %s = guestfs_safe_malloc (g, sizeof (char *) * (%s_len+1));\n" n n;
7050 pr " for (i = 0; i < %s_len; ++i) {\n" n;
7051 pr " jobject o = (*env)->GetObjectArrayElement (env, j%s, i);\n"
7053 pr " %s[i] = (*env)->GetStringUTFChars (env, o, NULL);\n" n;
7055 pr " %s[%s_len] = NULL;\n" n n;
7058 pr " %s = j%s;\n" n n
7061 (* Make the call. *)
7062 pr " r = guestfs_%s " name;
7063 generate_call_args ~handle:"g" (snd style);
7066 (* Release the parameters. *)
7072 pr " (*env)->ReleaseStringUTFChars (env, j%s, %s);\n" n n
7075 pr " (*env)->ReleaseStringUTFChars (env, j%s, %s);\n" n n
7077 pr " for (i = 0; i < %s_len; ++i) {\n" n;
7078 pr " jobject o = (*env)->GetObjectArrayElement (env, j%s, i);\n"
7080 pr " (*env)->ReleaseStringUTFChars (env, o, %s[i]);\n" n;
7082 pr " free (%s);\n" n
7087 (* Check for errors. *)
7088 pr " if (r == %s) {\n" error_code;
7089 pr " throw_exception (env, guestfs_last_error (g));\n";
7090 pr " return %s;\n" no_ret;
7094 (match fst style with
7096 | RInt _ -> pr " return (jint) r;\n"
7097 | RBool _ -> pr " return (jboolean) r;\n"
7098 | RInt64 _ -> pr " return (jlong) r;\n"
7099 | RConstString _ -> pr " return (*env)->NewStringUTF (env, r);\n"
7101 pr " jr = (*env)->NewStringUTF (env, r);\n";
7105 pr " for (r_len = 0; r[r_len] != NULL; ++r_len) ;\n";
7106 pr " cl = (*env)->FindClass (env, \"java/lang/String\");\n";
7107 pr " jstr = (*env)->NewStringUTF (env, \"\");\n";
7108 pr " jr = (*env)->NewObjectArray (env, r_len, cl, jstr);\n";
7109 pr " for (i = 0; i < r_len; ++i) {\n";
7110 pr " jstr = (*env)->NewStringUTF (env, r[i]);\n";
7111 pr " (*env)->SetObjectArrayElement (env, jr, i, jstr);\n";
7112 pr " free (r[i]);\n";
7117 pr " cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/IntBool\");\n";
7118 pr " jr = (*env)->AllocObject (env, cl);\n";
7119 pr " fl = (*env)->GetFieldID (env, cl, \"i\", \"I\");\n";
7120 pr " (*env)->SetIntField (env, jr, fl, r->i);\n";
7121 pr " fl = (*env)->GetFieldID (env, cl, \"i\", \"Z\");\n";
7122 pr " (*env)->SetBooleanField (env, jr, fl, r->b);\n";
7123 pr " guestfs_free_int_bool (r);\n";
7126 pr " cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/Stat\");\n";
7127 pr " jr = (*env)->AllocObject (env, cl);\n";
7131 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"J\");\n"
7133 pr " (*env)->SetLongField (env, jr, fl, r->%s);\n" name;
7138 pr " cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/StatVFS\");\n";
7139 pr " jr = (*env)->AllocObject (env, cl);\n";
7143 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"J\");\n"
7145 pr " (*env)->SetLongField (env, jr, fl, r->%s);\n" name;
7150 generate_java_lvm_return "pv" "PV" pv_cols
7152 generate_java_lvm_return "vg" "VG" vg_cols
7154 generate_java_lvm_return "lv" "LV" lv_cols
7157 pr " throw_exception (env, \"%s: internal error: please let us know how to make a Java HashMap from JNI bindings!\");\n" name;
7158 pr " return NULL;\n"
7165 and generate_java_lvm_return typ jtyp cols =
7166 pr " cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/%s\");\n" jtyp;
7167 pr " jr = (*env)->NewObjectArray (env, r->len, cl, NULL);\n";
7168 pr " for (i = 0; i < r->len; ++i) {\n";
7169 pr " jfl = (*env)->AllocObject (env, cl);\n";
7173 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
7174 pr " (*env)->SetObjectField (env, jfl, fl, (*env)->NewStringUTF (env, r->val[i].%s));\n" name;
7177 pr " char s[33];\n";
7178 pr " memcpy (s, r->val[i].%s, 32);\n" name;
7180 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
7181 pr " (*env)->SetObjectField (env, jfl, fl, (*env)->NewStringUTF (env, s));\n";
7183 | name, (`Bytes|`Int) ->
7184 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"J\");\n" name;
7185 pr " (*env)->SetLongField (env, jfl, fl, r->val[i].%s);\n" name;
7186 | name, `OptPercent ->
7187 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"F\");\n" name;
7188 pr " (*env)->SetFloatField (env, jfl, fl, r->val[i].%s);\n" name;
7190 pr " (*env)->SetObjectArrayElement (env, jfl, i, jfl);\n";
7192 pr " guestfs_free_lvm_%s_list (r);\n" typ;
7195 and generate_haskell_hs () =
7196 generate_header HaskellStyle LGPLv2;
7198 (* XXX We only know how to generate partial FFI for Haskell
7199 * at the moment. Please help out!
7201 let can_generate style =
7202 let check_no_bad_args =
7203 List.for_all (function Bool _ | Int _ -> false | _ -> true)
7206 | RErr, args -> check_no_bad_args args
7219 | RHashtable _, _ -> false in
7222 {-# INCLUDE <guestfs.h> #-}
7223 {-# LANGUAGE ForeignFunctionInterface #-}
7228 (* List out the names of the actions we want to export. *)
7230 fun (name, style, _, _, _, _, _) ->
7231 if can_generate style then pr ",\n %s" name
7239 import Control.Exception
7240 import Data.Typeable
7242 data GuestfsS = GuestfsS -- represents the opaque C struct
7243 type GuestfsP = Ptr GuestfsS -- guestfs_h *
7244 type GuestfsH = ForeignPtr GuestfsS -- guestfs_h * with attached finalizer
7246 -- XXX define properly later XXX
7250 data IntBool = IntBool
7252 data StatVFS = StatVFS
7253 data Hashtable = Hashtable
7255 foreign import ccall unsafe \"guestfs_create\" c_create
7257 foreign import ccall unsafe \"&guestfs_close\" c_close
7258 :: FunPtr (GuestfsP -> IO ())
7259 foreign import ccall unsafe \"guestfs_set_error_handler\" c_set_error_handler
7260 :: GuestfsP -> Ptr CInt -> Ptr CInt -> IO ()
7262 create :: IO GuestfsH
7265 c_set_error_handler p nullPtr nullPtr
7266 h <- newForeignPtr c_close p
7269 foreign import ccall unsafe \"guestfs_last_error\" c_last_error
7270 :: GuestfsP -> IO CString
7272 -- last_error :: GuestfsH -> IO (Maybe String)
7273 -- last_error h = do
7274 -- str <- withForeignPtr h (\\p -> c_last_error p)
7275 -- maybePeek peekCString str
7277 last_error :: GuestfsH -> IO (String)
7279 str <- withForeignPtr h (\\p -> c_last_error p)
7281 then return \"no error\"
7282 else peekCString str
7286 (* Generate wrappers for each foreign function. *)
7288 fun (name, style, _, _, _, _, _) ->
7289 if can_generate style then (
7290 pr "foreign import ccall unsafe \"guestfs_%s\" c_%s\n" name name;
7292 generate_haskell_prototype ~handle:"GuestfsP" style;
7296 generate_haskell_prototype ~handle:"GuestfsH" ~hs:true style;
7298 pr "%s %s = do\n" name
7299 (String.concat " " ("h" :: List.map name_of_argt (snd style)));
7305 | String n -> pr "withCString %s $ \\%s -> " n n
7306 | OptString n -> pr "maybeWith withCString %s $ \\%s -> " n n
7307 | StringList n -> pr "withMany withCString %s $ \\%s -> withArray0 nullPtr %s $ \\%s -> " n n n n
7309 (* XXX this doesn't work *)
7311 pr " %s = case %s of\n" n n;
7314 pr " in fromIntegral %s $ \\%s ->\n" n n
7315 | Int n -> pr "fromIntegral %s $ \\%s -> " n n
7317 pr "withForeignPtr h (\\p -> c_%s %s)\n" name
7318 (String.concat " " ("p" :: List.map name_of_argt (snd style)));
7319 (match fst style with
7320 | RErr | RInt _ | RInt64 _ | RBool _ ->
7321 pr " if (r == -1)\n";
7323 pr " err <- last_error h\n";
7325 | RConstString _ | RString _ | RStringList _ | RIntBool _
7326 | RPVList _ | RVGList _ | RLVList _ | RStat _ | RStatVFS _
7328 pr " if (r == nullPtr)\n";
7330 pr " err <- last_error h\n";
7333 (match fst style with
7335 pr " else return ()\n"
7337 pr " else return (fromIntegral r)\n"
7339 pr " else return (fromIntegral r)\n"
7341 pr " else return (toBool r)\n"
7352 pr " else return ()\n" (* XXXXXXXXXXXXXXXXXXXX *)
7358 and generate_haskell_prototype ~handle ?(hs = false) style =
7360 let string = if hs then "String" else "CString" in
7361 let int = if hs then "Int" else "CInt" in
7362 let bool = if hs then "Bool" else "CInt" in
7363 let int64 = if hs then "Integer" else "Int64" in
7367 | String _ -> pr "%s" string
7368 | OptString _ -> if hs then pr "Maybe String" else pr "CString"
7369 | StringList _ -> if hs then pr "[String]" else pr "Ptr CString"
7370 | Bool _ -> pr "%s" bool
7371 | Int _ -> pr "%s" int
7372 | FileIn _ -> pr "%s" string
7373 | FileOut _ -> pr "%s" string
7378 (match fst style with
7379 | RErr -> if not hs then pr "CInt"
7380 | RInt _ -> pr "%s" int
7381 | RInt64 _ -> pr "%s" int64
7382 | RBool _ -> pr "%s" bool
7383 | RConstString _ -> pr "%s" string
7384 | RString _ -> pr "%s" string
7385 | RStringList _ -> pr "[%s]" string
7386 | RIntBool _ -> pr "IntBool"
7387 | RPVList _ -> pr "[PV]"
7388 | RVGList _ -> pr "[VG]"
7389 | RLVList _ -> pr "[LV]"
7390 | RStat _ -> pr "Stat"
7391 | RStatVFS _ -> pr "StatVFS"
7392 | RHashtable _ -> pr "Hashtable"
7396 and generate_bindtests () =
7397 generate_header CStyle LGPLv2;
7402 #include <inttypes.h>
7405 #include \"guestfs.h\"
7406 #include \"guestfs_protocol.h\"
7408 #define error guestfs_error
7411 print_strings (char * const* const argv)
7416 for (argc = 0; argv[argc] != NULL; ++argc) {
7417 if (argc > 0) printf (\", \");
7418 printf (\"\\\"%%s\\\"\", argv[argc]);
7423 /* The test0 function prints its parameters to stdout. */
7427 match test_functions with
7428 | [] -> assert false
7429 | test0 :: tests -> test0, tests in
7432 let (name, style, _, _, _, _, _) = test0 in
7433 generate_prototype ~extern:false ~semicolon:false ~newline:true
7434 ~handle:"g" ~prefix:"guestfs_" name style;
7440 | FileOut n -> pr " printf (\"%%s\\n\", %s);\n" n
7441 | OptString n -> pr " printf (\"%%s\\n\", %s ? %s : \"null\");\n" n n
7442 | StringList n -> pr " print_strings (%s);\n" n
7443 | Bool n -> pr " printf (\"%%s\\n\", %s ? \"true\" : \"false\");\n" n
7444 | Int n -> pr " printf (\"%%d\\n\", %s);\n" n
7446 pr " /* Java changes stdout line buffering so we need this: */\n";
7447 pr " fflush (stdout);\n";
7453 fun (name, style, _, _, _, _, _) ->
7454 if String.sub name (String.length name - 3) 3 <> "err" then (
7455 pr "/* Test normal return. */\n";
7456 generate_prototype ~extern:false ~semicolon:false ~newline:true
7457 ~handle:"g" ~prefix:"guestfs_" name style;
7459 (match fst style with
7464 pr " sscanf (val, \"%%d\", &r);\n";
7468 pr " sscanf (val, \"%%\" SCNi64, &r);\n";
7471 pr " return strcmp (val, \"true\") == 0;\n"
7473 (* Can't return the input string here. Return a static
7474 * string so we ensure we get a segfault if the caller
7477 pr " return \"static string\";\n"
7479 pr " return strdup (val);\n"
7481 pr " char **strs;\n";
7483 pr " sscanf (val, \"%%d\", &n);\n";
7484 pr " strs = malloc ((n+1) * sizeof (char *));\n";
7485 pr " for (i = 0; i < n; ++i) {\n";
7486 pr " strs[i] = malloc (16);\n";
7487 pr " snprintf (strs[i], 16, \"%%d\", i);\n";
7489 pr " strs[n] = NULL;\n";
7490 pr " return strs;\n"
7492 pr " struct guestfs_int_bool *r;\n";
7493 pr " r = malloc (sizeof (struct guestfs_int_bool));\n";
7494 pr " sscanf (val, \"%%\" SCNi32, &r->i);\n";
7498 pr " struct guestfs_lvm_pv_list *r;\n";
7500 pr " r = malloc (sizeof (struct guestfs_lvm_pv_list));\n";
7501 pr " sscanf (val, \"%%d\", &r->len);\n";
7502 pr " r->val = calloc (r->len, sizeof (struct guestfs_lvm_pv));\n";
7503 pr " for (i = 0; i < r->len; ++i) {\n";
7504 pr " r->val[i].pv_name = malloc (16);\n";
7505 pr " snprintf (r->val[i].pv_name, 16, \"%%d\", i);\n";
7509 pr " struct guestfs_lvm_vg_list *r;\n";
7511 pr " r = malloc (sizeof (struct guestfs_lvm_vg_list));\n";
7512 pr " sscanf (val, \"%%d\", &r->len);\n";
7513 pr " r->val = calloc (r->len, sizeof (struct guestfs_lvm_vg));\n";
7514 pr " for (i = 0; i < r->len; ++i) {\n";
7515 pr " r->val[i].vg_name = malloc (16);\n";
7516 pr " snprintf (r->val[i].vg_name, 16, \"%%d\", i);\n";
7520 pr " struct guestfs_lvm_lv_list *r;\n";
7522 pr " r = malloc (sizeof (struct guestfs_lvm_lv_list));\n";
7523 pr " sscanf (val, \"%%d\", &r->len);\n";
7524 pr " r->val = calloc (r->len, sizeof (struct guestfs_lvm_lv));\n";
7525 pr " for (i = 0; i < r->len; ++i) {\n";
7526 pr " r->val[i].lv_name = malloc (16);\n";
7527 pr " snprintf (r->val[i].lv_name, 16, \"%%d\", i);\n";
7531 pr " struct guestfs_stat *r;\n";
7532 pr " r = calloc (1, sizeof (*r));\n";
7533 pr " sscanf (val, \"%%\" SCNi64, &r->dev);\n";
7536 pr " struct guestfs_statvfs *r;\n";
7537 pr " r = calloc (1, sizeof (*r));\n";
7538 pr " sscanf (val, \"%%\" SCNi64, &r->bsize);\n";
7541 pr " char **strs;\n";
7543 pr " sscanf (val, \"%%d\", &n);\n";
7544 pr " strs = malloc ((n*2+1) * sizeof (char *));\n";
7545 pr " for (i = 0; i < n; ++i) {\n";
7546 pr " strs[i*2] = malloc (16);\n";
7547 pr " strs[i*2+1] = malloc (16);\n";
7548 pr " snprintf (strs[i*2], 16, \"%%d\", i);\n";
7549 pr " snprintf (strs[i*2+1], 16, \"%%d\", i);\n";
7551 pr " strs[n*2] = NULL;\n";
7552 pr " return strs;\n"
7557 pr "/* Test error return. */\n";
7558 generate_prototype ~extern:false ~semicolon:false ~newline:true
7559 ~handle:"g" ~prefix:"guestfs_" name style;
7561 pr " error (g, \"error\");\n";
7562 (match fst style with
7563 | RErr | RInt _ | RInt64 _ | RBool _ ->
7566 | RString _ | RStringList _ | RIntBool _
7567 | RPVList _ | RVGList _ | RLVList _ | RStat _ | RStatVFS _
7569 pr " return NULL;\n"
7576 and generate_ocaml_bindtests () =
7577 generate_header OCamlStyle GPLv2;
7581 let g = Guestfs.create () in
7588 | CallString s -> "\"" ^ s ^ "\""
7589 | CallOptString None -> "None"
7590 | CallOptString (Some s) -> sprintf "(Some \"%s\")" s
7591 | CallStringList xs ->
7592 "[|" ^ String.concat ";" (List.map (sprintf "\"%s\"") xs) ^ "|]"
7593 | CallInt i when i >= 0 -> string_of_int i
7594 | CallInt i (* when i < 0 *) -> "(" ^ string_of_int i ^ ")"
7595 | CallBool b -> string_of_bool b
7600 generate_lang_bindtests (
7601 fun f args -> pr " Guestfs.%s g %s;\n" f (mkargs args)
7604 pr "print_endline \"EOF\"\n"
7606 and generate_perl_bindtests () =
7607 pr "#!/usr/bin/perl -w\n";
7608 generate_header HashStyle GPLv2;
7615 my $g = Sys::Guestfs->new ();
7619 String.concat ", " (
7622 | CallString s -> "\"" ^ s ^ "\""
7623 | CallOptString None -> "undef"
7624 | CallOptString (Some s) -> sprintf "\"%s\"" s
7625 | CallStringList xs ->
7626 "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
7627 | CallInt i -> string_of_int i
7628 | CallBool b -> if b then "1" else "0"
7633 generate_lang_bindtests (
7634 fun f args -> pr "$g->%s (%s);\n" f (mkargs args)
7637 pr "print \"EOF\\n\"\n"
7639 and generate_python_bindtests () =
7640 generate_header HashStyle GPLv2;
7645 g = guestfs.GuestFS ()
7649 String.concat ", " (
7652 | CallString s -> "\"" ^ s ^ "\""
7653 | CallOptString None -> "None"
7654 | CallOptString (Some s) -> sprintf "\"%s\"" s
7655 | CallStringList xs ->
7656 "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
7657 | CallInt i -> string_of_int i
7658 | CallBool b -> if b then "1" else "0"
7663 generate_lang_bindtests (
7664 fun f args -> pr "g.%s (%s)\n" f (mkargs args)
7667 pr "print \"EOF\"\n"
7669 and generate_ruby_bindtests () =
7670 generate_header HashStyle GPLv2;
7675 g = Guestfs::create()
7679 String.concat ", " (
7682 | CallString s -> "\"" ^ s ^ "\""
7683 | CallOptString None -> "nil"
7684 | CallOptString (Some s) -> sprintf "\"%s\"" s
7685 | CallStringList xs ->
7686 "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
7687 | CallInt i -> string_of_int i
7688 | CallBool b -> string_of_bool b
7693 generate_lang_bindtests (
7694 fun f args -> pr "g.%s(%s)\n" f (mkargs args)
7697 pr "print \"EOF\\n\"\n"
7699 and generate_java_bindtests () =
7700 generate_header CStyle GPLv2;
7703 import com.redhat.et.libguestfs.*;
7705 public class Bindtests {
7706 public static void main (String[] argv)
7709 GuestFS g = new GuestFS ();
7713 String.concat ", " (
7716 | CallString s -> "\"" ^ s ^ "\""
7717 | CallOptString None -> "null"
7718 | CallOptString (Some s) -> sprintf "\"%s\"" s
7719 | CallStringList xs ->
7721 String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "}"
7722 | CallInt i -> string_of_int i
7723 | CallBool b -> string_of_bool b
7728 generate_lang_bindtests (
7729 fun f args -> pr " g.%s (%s);\n" f (mkargs args)
7733 System.out.println (\"EOF\");
7735 catch (Exception exn) {
7736 System.err.println (exn);
7743 and generate_haskell_bindtests () =
7744 () (* XXX Haskell bindings need to be fleshed out. *)
7746 (* Language-independent bindings tests - we do it this way to
7747 * ensure there is parity in testing bindings across all languages.
7749 and generate_lang_bindtests call =
7750 call "test0" [CallString "abc"; CallOptString (Some "def");
7751 CallStringList []; CallBool false;
7752 CallInt 0; CallString "123"; CallString "456"];
7753 call "test0" [CallString "abc"; CallOptString None;
7754 CallStringList []; CallBool false;
7755 CallInt 0; CallString "123"; CallString "456"];
7756 call "test0" [CallString ""; CallOptString (Some "def");
7757 CallStringList []; CallBool false;
7758 CallInt 0; CallString "123"; CallString "456"];
7759 call "test0" [CallString ""; CallOptString (Some "");
7760 CallStringList []; CallBool false;
7761 CallInt 0; CallString "123"; CallString "456"];
7762 call "test0" [CallString "abc"; CallOptString (Some "def");
7763 CallStringList ["1"]; CallBool false;
7764 CallInt 0; CallString "123"; CallString "456"];
7765 call "test0" [CallString "abc"; CallOptString (Some "def");
7766 CallStringList ["1"; "2"]; CallBool false;
7767 CallInt 0; CallString "123"; CallString "456"];
7768 call "test0" [CallString "abc"; CallOptString (Some "def");
7769 CallStringList ["1"]; CallBool true;
7770 CallInt 0; CallString "123"; CallString "456"];
7771 call "test0" [CallString "abc"; CallOptString (Some "def");
7772 CallStringList ["1"]; CallBool false;
7773 CallInt (-1); CallString "123"; CallString "456"];
7774 call "test0" [CallString "abc"; CallOptString (Some "def");
7775 CallStringList ["1"]; CallBool false;
7776 CallInt (-2); CallString "123"; CallString "456"];
7777 call "test0" [CallString "abc"; CallOptString (Some "def");
7778 CallStringList ["1"]; CallBool false;
7779 CallInt 1; CallString "123"; CallString "456"];
7780 call "test0" [CallString "abc"; CallOptString (Some "def");
7781 CallStringList ["1"]; CallBool false;
7782 CallInt 2; CallString "123"; CallString "456"];
7783 call "test0" [CallString "abc"; CallOptString (Some "def");
7784 CallStringList ["1"]; CallBool false;
7785 CallInt 4095; CallString "123"; CallString "456"];
7786 call "test0" [CallString "abc"; CallOptString (Some "def");
7787 CallStringList ["1"]; CallBool false;
7788 CallInt 0; CallString ""; CallString ""]
7790 (* XXX Add here tests of the return and error functions. *)
7792 let output_to filename =
7793 let filename_new = filename ^ ".new" in
7794 chan := open_out filename_new;
7799 (* Is the new file different from the current file? *)
7800 if Sys.file_exists filename && files_equal filename filename_new then
7801 Unix.unlink filename_new (* same, so skip it *)
7803 (* different, overwrite old one *)
7804 (try Unix.chmod filename 0o644 with Unix.Unix_error _ -> ());
7805 Unix.rename filename_new filename;
7806 Unix.chmod filename 0o444;
7807 printf "written %s\n%!" filename;
7816 if not (Sys.file_exists "configure.ac") then (
7818 You are probably running this from the wrong directory.
7819 Run it from the top source directory using the command
7825 let close = output_to "src/guestfs_protocol.x" in
7829 let close = output_to "src/guestfs-structs.h" in
7830 generate_structs_h ();
7833 let close = output_to "src/guestfs-actions.h" in
7834 generate_actions_h ();
7837 let close = output_to "src/guestfs-actions.c" in
7838 generate_client_actions ();
7841 let close = output_to "daemon/actions.h" in
7842 generate_daemon_actions_h ();
7845 let close = output_to "daemon/stubs.c" in
7846 generate_daemon_actions ();
7849 let close = output_to "capitests/tests.c" in
7853 let close = output_to "src/guestfs-bindtests.c" in
7854 generate_bindtests ();
7857 let close = output_to "fish/cmds.c" in
7858 generate_fish_cmds ();
7861 let close = output_to "fish/completion.c" in
7862 generate_fish_completion ();
7865 let close = output_to "guestfs-structs.pod" in
7866 generate_structs_pod ();
7869 let close = output_to "guestfs-actions.pod" in
7870 generate_actions_pod ();
7873 let close = output_to "guestfish-actions.pod" in
7874 generate_fish_actions_pod ();
7877 let close = output_to "ocaml/guestfs.mli" in
7878 generate_ocaml_mli ();
7881 let close = output_to "ocaml/guestfs.ml" in
7882 generate_ocaml_ml ();
7885 let close = output_to "ocaml/guestfs_c_actions.c" in
7886 generate_ocaml_c ();
7889 let close = output_to "ocaml/bindtests.ml" in
7890 generate_ocaml_bindtests ();
7893 let close = output_to "perl/Guestfs.xs" in
7894 generate_perl_xs ();
7897 let close = output_to "perl/lib/Sys/Guestfs.pm" in
7898 generate_perl_pm ();
7901 let close = output_to "perl/bindtests.pl" in
7902 generate_perl_bindtests ();
7905 let close = output_to "python/guestfs-py.c" in
7906 generate_python_c ();
7909 let close = output_to "python/guestfs.py" in
7910 generate_python_py ();
7913 let close = output_to "python/bindtests.py" in
7914 generate_python_bindtests ();
7917 let close = output_to "ruby/ext/guestfs/_guestfs.c" in
7921 let close = output_to "ruby/bindtests.rb" in
7922 generate_ruby_bindtests ();
7925 let close = output_to "java/com/redhat/et/libguestfs/GuestFS.java" in
7926 generate_java_java ();
7929 let close = output_to "java/com/redhat/et/libguestfs/PV.java" in
7930 generate_java_struct "PV" pv_cols;
7933 let close = output_to "java/com/redhat/et/libguestfs/VG.java" in
7934 generate_java_struct "VG" vg_cols;
7937 let close = output_to "java/com/redhat/et/libguestfs/LV.java" in
7938 generate_java_struct "LV" lv_cols;
7941 let close = output_to "java/com/redhat/et/libguestfs/Stat.java" in
7942 generate_java_struct "Stat" stat_cols;
7945 let close = output_to "java/com/redhat/et/libguestfs/StatVFS.java" in
7946 generate_java_struct "StatVFS" statvfs_cols;
7949 let close = output_to "java/com_redhat_et_libguestfs_GuestFS.c" in
7953 let close = output_to "java/Bindtests.java" in
7954 generate_java_bindtests ();
7957 let close = output_to "haskell/Guestfs.hs" in
7958 generate_haskell_hs ();
7961 let close = output_to "haskell/bindtests.hs" in
7962 generate_haskell_bindtests ();