3 * Copyright (C) 2009-2010 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 of
25 * 'daemon_functions' below), and daemon/<somefile>.c to write the
28 * After editing this file, run it (./src/generator.ml) to regenerate
29 * all the output files. 'make' will rerun this automatically when
30 * necessary. Note that if you are using a separate build directory
31 * you must run generator.ml from the _source_ directory.
33 * IMPORTANT: This script should NOT print any warnings. If it prints
34 * warnings, you should treat them as errors.
37 * (1) In emacs, install tuareg-mode to display and format OCaml code
38 * correctly. 'vim' comes with a good OCaml editing mode by default.
39 * (2) Read the resources at http://ocaml-tutorial.org/
44 #directory "+xml-light";;
45 #directory "+../pkg-lib/xml-light";; (* for GODI users *)
46 #load "xml-light.cma";;
51 type style = ret * args
53 (* "RErr" as a return value means an int used as a simple error
54 * indication, ie. 0 or -1.
58 (* "RInt" as a return value means an int which is -1 for error
59 * or any value >= 0 on success. Only use this for smallish
60 * positive ints (0 <= i < 2^30).
64 (* "RInt64" is the same as RInt, but is guaranteed to be able
65 * to return a full 64 bit value, _except_ that -1 means error
66 * (so -1 cannot be a valid, non-error return value).
70 (* "RBool" is a bool return value which can be true/false or
75 (* "RConstString" is a string that refers to a constant value.
76 * The return value must NOT be NULL (since NULL indicates
79 * Try to avoid using this. In particular you cannot use this
80 * for values returned from the daemon, because there is no
81 * thread-safe way to return them in the C API.
83 | RConstString of string
85 (* "RConstOptString" is an even more broken version of
86 * "RConstString". The returned string may be NULL and there
87 * is no way to return an error indication. Avoid using this!
89 | RConstOptString of string
91 (* "RString" is a returned string. It must NOT be NULL, since
92 * a NULL return indicates an error. The caller frees this.
96 (* "RStringList" is a list of strings. No string in the list
97 * can be NULL. The caller frees the strings and the array.
99 | RStringList of string
101 (* "RStruct" is a function which returns a single named structure
102 * or an error indication (in C, a struct, and in other languages
103 * with varying representations, but usually very efficient). See
104 * after the function list below for the structures.
106 | RStruct of string * string (* name of retval, name of struct *)
108 (* "RStructList" is a function which returns either a list/array
109 * of structures (could be zero-length), or an error indication.
111 | RStructList of string * string (* name of retval, name of struct *)
113 (* Key-value pairs of untyped strings. Turns into a hashtable or
114 * dictionary in languages which support it. DON'T use this as a
115 * general "bucket" for results. Prefer a stronger typed return
116 * value if one is available, or write a custom struct. Don't use
117 * this if the list could potentially be very long, since it is
118 * inefficient. Keys should be unique. NULLs are not permitted.
120 | RHashtable of string
122 (* "RBufferOut" is handled almost exactly like RString, but
123 * it allows the string to contain arbitrary 8 bit data including
124 * ASCII NUL. In the C API this causes an implicit extra parameter
125 * to be added of type <size_t *size_r>. The extra parameter
126 * returns the actual size of the return buffer in bytes.
128 * Other programming languages support strings with arbitrary 8 bit
131 * At the RPC layer we have to use the opaque<> type instead of
132 * string<>. Returned data is still limited to the max message
135 | RBufferOut of string
137 and args = argt list (* Function parameters, guestfs handle is implicit. *)
139 (* Note in future we should allow a "variable args" parameter as
140 * the final parameter, to allow commands like
141 * chmod mode file [file(s)...]
142 * This is not implemented yet, but many commands (such as chmod)
143 * are currently defined with the argument order keeping this future
144 * possibility in mind.
147 | String of string (* const char *name, cannot be NULL *)
148 | Device of string (* /dev device name, cannot be NULL *)
149 | Pathname of string (* file name, cannot be NULL *)
150 | Dev_or_Path of string (* /dev device name or Pathname, cannot be NULL *)
151 | OptString of string (* const char *name, may be NULL *)
152 | StringList of string(* list of strings (each string cannot be NULL) *)
153 | DeviceList of string(* list of Device names (each cannot be NULL) *)
154 | Bool of string (* boolean *)
155 | Int of string (* int (smallish ints, signed, <= 31 bits) *)
156 | Int64 of string (* any 64 bit int *)
157 (* These are treated as filenames (simple string parameters) in
158 * the C API and bindings. But in the RPC protocol, we transfer
159 * the actual file content up to or down from the daemon.
160 * FileIn: local machine -> daemon (in request)
161 * FileOut: daemon -> local machine (in reply)
162 * In guestfish (only), the special name "-" means read from
163 * stdin or write to stdout.
168 (* Opaque buffer which can contain arbitrary 8 bit data.
169 * In the C API, this is expressed as <char *, int> pair.
170 * Most other languages have a string type which can contain
171 * ASCII NUL. We use whatever type is appropriate for each
173 * Buffers are limited by the total message size. To transfer
174 * large blocks of data, use FileIn/FileOut parameters instead.
175 * To return an arbitrary buffer, use RBufferOut.
181 | ProtocolLimitWarning (* display warning about protocol size limits *)
182 | DangerWillRobinson (* flags particularly dangerous commands *)
183 | FishAlias of string (* provide an alias for this cmd in guestfish *)
184 | FishAction of string (* call this function in guestfish *)
185 | FishOutput of fish_output_t (* how to display output in guestfish *)
186 | NotInFish (* do not export via guestfish *)
187 | NotInDocs (* do not add this function to documentation *)
188 | DeprecatedBy of string (* function is deprecated, use .. instead *)
189 | Optional of string (* function is part of an optional group *)
192 | FishOutputOctal (* for int return, print in octal *)
193 | FishOutputHexadecimal (* for int return, print in hex *)
195 (* You can supply zero or as many tests as you want per API call.
197 * Note that the test environment has 3 block devices, of size 500MB,
198 * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and
199 * a fourth ISO block device with some known files on it (/dev/sdd).
201 * Note for partitioning purposes, the 500MB device has 1015 cylinders.
202 * Number of cylinders was 63 for IDE emulated disks with precisely
203 * the same size. How exactly this is calculated is a mystery.
205 * The ISO block device (/dev/sdd) comes from images/test.iso.
207 * To be able to run the tests in a reasonable amount of time,
208 * the virtual machine and block devices are reused between tests.
209 * So don't try testing kill_subprocess :-x
211 * Between each test we blockdev-setrw, umount-all, lvm-remove-all.
213 * Don't assume anything about the previous contents of the block
214 * devices. Use 'Init*' to create some initial scenarios.
216 * You can add a prerequisite clause to any individual test. This
217 * is a run-time check, which, if it fails, causes the test to be
218 * skipped. Useful if testing a command which might not work on
219 * all variations of libguestfs builds. A test that has prerequisite
220 * of 'Always' is run unconditionally.
222 * In addition, packagers can skip individual tests by setting the
223 * environment variables: eg:
224 * SKIP_TEST_<CMD>_<NUM>=1 SKIP_TEST_COMMAND_3=1 (skips test #3 of command)
225 * SKIP_TEST_<CMD>=1 SKIP_TEST_ZEROFREE=1 (skips all zerofree tests)
227 type tests = (test_init * test_prereq * test) list
229 (* Run the command sequence and just expect nothing to fail. *)
232 (* Run the command sequence and expect the output of the final
233 * command to be the string.
235 | TestOutput of seq * string
237 (* Run the command sequence and expect the output of the final
238 * command to be the list of strings.
240 | TestOutputList of seq * string list
242 (* Run the command sequence and expect the output of the final
243 * command to be the list of block devices (could be either
244 * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
245 * character of each string).
247 | TestOutputListOfDevices of seq * string list
249 (* Run the command sequence and expect the output of the final
250 * command to be the integer.
252 | TestOutputInt of seq * int
254 (* Run the command sequence and expect the output of the final
255 * command to be <op> <int>, eg. ">=", "1".
257 | TestOutputIntOp of seq * string * int
259 (* Run the command sequence and expect the output of the final
260 * command to be a true value (!= 0 or != NULL).
262 | TestOutputTrue of seq
264 (* Run the command sequence and expect the output of the final
265 * command to be a false value (== 0 or == NULL, but not an error).
267 | TestOutputFalse of seq
269 (* Run the command sequence and expect the output of the final
270 * command to be a list of the given length (but don't care about
273 | TestOutputLength of seq * int
275 (* Run the command sequence and expect the output of the final
276 * command to be a buffer (RBufferOut), ie. string + size.
278 | TestOutputBuffer of seq * string
280 (* Run the command sequence and expect the output of the final
281 * command to be a structure.
283 | TestOutputStruct of seq * test_field_compare list
285 (* Run the command sequence and expect the final command (only)
288 | TestLastFail of seq
290 and test_field_compare =
291 | CompareWithInt of string * int
292 | CompareWithIntOp of string * string * int
293 | CompareWithString of string * string
294 | CompareFieldsIntEq of string * string
295 | CompareFieldsStrEq of string * string
297 (* Test prerequisites. *)
299 (* Test always runs. *)
302 (* Test is currently disabled - eg. it fails, or it tests some
303 * unimplemented feature.
307 (* 'string' is some C code (a function body) that should return
308 * true or false. The test will run if the code returns true.
312 (* As for 'If' but the test runs _unless_ the code returns true. *)
315 (* Some initial scenarios for testing. *)
317 (* Do nothing, block devices could contain random stuff including
318 * LVM PVs, and some filesystems might be mounted. This is usually
323 (* Block devices are empty and no filesystems are mounted. *)
326 (* /dev/sda contains a single partition /dev/sda1, with random
327 * content. /dev/sdb and /dev/sdc may have random content.
332 (* /dev/sda contains a single partition /dev/sda1, which is formatted
333 * as ext2, empty [except for lost+found] and mounted on /.
334 * /dev/sdb and /dev/sdc may have random content.
340 * /dev/sda1 (is a PV):
341 * /dev/VG/LV (size 8MB):
342 * formatted as ext2, empty [except for lost+found], mounted on /
343 * /dev/sdb and /dev/sdc may have random content.
347 (* /dev/sdd (the ISO, see images/ directory in source)
352 (* Sequence of commands for testing. *)
354 and cmd = string list
356 (* Note about long descriptions: When referring to another
357 * action, use the format C<guestfs_other> (ie. the full name of
358 * the C function). This will be replaced as appropriate in other
361 * Apart from that, long descriptions are just perldoc paragraphs.
364 (* Generate a random UUID (used in tests). *)
366 let chan = open_process_in "uuidgen" in
367 let uuid = input_line chan in
368 (match close_process_in chan with
371 failwith "uuidgen: process exited with non-zero status"
372 | WSIGNALED _ | WSTOPPED _ ->
373 failwith "uuidgen: process signalled or stopped by signal"
377 (* These test functions are used in the language binding tests. *)
379 let test_all_args = [
382 StringList "strlist";
390 let test_all_rets = [
391 (* except for RErr, which is tested thoroughly elsewhere *)
392 "test0rint", RInt "valout";
393 "test0rint64", RInt64 "valout";
394 "test0rbool", RBool "valout";
395 "test0rconststring", RConstString "valout";
396 "test0rconstoptstring", RConstOptString "valout";
397 "test0rstring", RString "valout";
398 "test0rstringlist", RStringList "valout";
399 "test0rstruct", RStruct ("valout", "lvm_pv");
400 "test0rstructlist", RStructList ("valout", "lvm_pv");
401 "test0rhashtable", RHashtable "valout";
404 let test_functions = [
405 ("test0", (RErr, test_all_args), -1, [NotInFish; NotInDocs],
407 "internal test function - do not use",
409 This is an internal test function which is used to test whether
410 the automatically generated bindings can handle every possible
411 parameter type correctly.
413 It echos the contents of each parameter to stdout.
415 You probably don't want to call this function.");
419 [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs],
421 "internal test function - do not use",
423 This is an internal test function which is used to test whether
424 the automatically generated bindings can handle every possible
425 return type correctly.
427 It converts string C<val> to the return type.
429 You probably don't want to call this function.");
430 (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs],
432 "internal test function - do not use",
434 This is an internal test function which is used to test whether
435 the automatically generated bindings can handle every possible
436 return type correctly.
438 This function always returns an error.
440 You probably don't want to call this function.")]
444 (* non_daemon_functions are any functions which don't get processed
445 * in the daemon, eg. functions for setting and getting local
446 * configuration values.
449 let non_daemon_functions = test_functions @ [
450 ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"],
452 "launch the qemu subprocess",
454 Internally libguestfs is implemented by running a virtual machine
457 You should call this after configuring the handle
458 (eg. adding drives) but before performing any actions.");
460 ("wait_ready", (RErr, []), -1, [NotInFish],
462 "wait until the qemu subprocess launches (no op)",
464 This function is a no op.
466 In versions of the API E<lt> 1.0.71 you had to call this function
467 just after calling C<guestfs_launch> to wait for the launch
468 to complete. However this is no longer necessary because
469 C<guestfs_launch> now does the waiting.
471 If you see any calls to this function in code then you can just
472 remove them, unless you want to retain compatibility with older
473 versions of the API.");
475 ("kill_subprocess", (RErr, []), -1, [],
477 "kill the qemu subprocess",
479 This kills the qemu subprocess. You should never need to call this.");
481 ("add_drive", (RErr, [String "filename"]), -1, [FishAlias "add"],
483 "add an image to examine or modify",
485 This function adds a virtual machine disk image C<filename> to the
486 guest. The first time you call this function, the disk appears as IDE
487 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
490 You don't necessarily need to be root when using libguestfs. However
491 you obviously do need sufficient permissions to access the filename
492 for whatever operations you want to perform (ie. read access if you
493 just want to read the image or write access if you want to modify the
496 This is equivalent to the qemu parameter
497 C<-drive file=filename,cache=off,if=...>.
499 C<cache=off> is omitted in cases where it is not supported by
500 the underlying filesystem.
502 C<if=...> is set at compile time by the configuration option
503 C<./configure --with-drive-if=...>. In the rare case where you
504 might need to change this at run time, use C<guestfs_add_drive_with_if>
505 or C<guestfs_add_drive_ro_with_if>.
507 Note that this call checks for the existence of C<filename>. This
508 stops you from specifying other types of drive which are supported
509 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
510 the general C<guestfs_config> call instead.");
512 ("add_cdrom", (RErr, [String "filename"]), -1, [FishAlias "cdrom"],
514 "add a CD-ROM disk image to examine",
516 This function adds a virtual CD-ROM disk image to the guest.
518 This is equivalent to the qemu parameter C<-cdrom filename>.
526 This call checks for the existence of C<filename>. This
527 stops you from specifying other types of drive which are supported
528 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
529 the general C<guestfs_config> call instead.
533 If you just want to add an ISO file (often you use this as an
534 efficient way to transfer large files into the guest), then you
535 should probably use C<guestfs_add_drive_ro> instead.
539 ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"],
541 "add a drive in snapshot mode (read-only)",
543 This adds a drive in snapshot mode, making it effectively
546 Note that writes to the device are allowed, and will be seen for
547 the duration of the guestfs handle, but they are written
548 to a temporary file which is discarded as soon as the guestfs
549 handle is closed. We don't currently have any method to enable
550 changes to be committed, although qemu can support this.
552 This is equivalent to the qemu parameter
553 C<-drive file=filename,snapshot=on,readonly=on,if=...>.
555 C<if=...> is set at compile time by the configuration option
556 C<./configure --with-drive-if=...>. In the rare case where you
557 might need to change this at run time, use C<guestfs_add_drive_with_if>
558 or C<guestfs_add_drive_ro_with_if>.
560 C<readonly=on> is only added where qemu supports this option.
562 Note that this call checks for the existence of C<filename>. This
563 stops you from specifying other types of drive which are supported
564 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
565 the general C<guestfs_config> call instead.");
567 ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"]), -1, [],
569 "add qemu parameters",
571 This can be used to add arbitrary qemu command line parameters
572 of the form C<-param value>. Actually it's not quite arbitrary - we
573 prevent you from setting some parameters which would interfere with
574 parameters that we use.
576 The first character of C<param> string must be a C<-> (dash).
578 C<value> can be NULL.");
580 ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"],
582 "set the qemu binary",
584 Set the qemu binary that we will use.
586 The default is chosen when the library was compiled by the
589 You can also override this by setting the C<LIBGUESTFS_QEMU>
590 environment variable.
592 Setting C<qemu> to C<NULL> restores the default qemu binary.
594 Note that you should call this function as early as possible
595 after creating the handle. This is because some pre-launch
596 operations depend on testing qemu features (by running C<qemu -help>).
597 If the qemu binary changes, we don't retest features, and
598 so you might see inconsistent results. Using the environment
599 variable C<LIBGUESTFS_QEMU> is safest of all since that picks
600 the qemu binary at the same time as the handle is created.");
602 ("get_qemu", (RConstString "qemu", []), -1, [],
603 [InitNone, Always, TestRun (
605 "get the qemu binary",
607 Return the current qemu binary.
609 This is always non-NULL. If it wasn't set already, then this will
610 return the default qemu binary name.");
612 ("set_path", (RErr, [String "searchpath"]), -1, [FishAlias "path"],
614 "set the search path",
616 Set the path that libguestfs searches for kernel and initrd.img.
618 The default is C<$libdir/guestfs> unless overridden by setting
619 C<LIBGUESTFS_PATH> environment variable.
621 Setting C<path> to C<NULL> restores the default path.");
623 ("get_path", (RConstString "path", []), -1, [],
624 [InitNone, Always, TestRun (
626 "get the search path",
628 Return the current search path.
630 This is always non-NULL. If it wasn't set already, then this will
631 return the default path.");
633 ("set_append", (RErr, [OptString "append"]), -1, [FishAlias "append"],
635 "add options to kernel command line",
637 This function is used to add additional options to the
638 guest kernel command line.
640 The default is C<NULL> unless overridden by setting
641 C<LIBGUESTFS_APPEND> environment variable.
643 Setting C<append> to C<NULL> means I<no> additional options
644 are passed (libguestfs always adds a few of its own).");
646 ("get_append", (RConstOptString "append", []), -1, [],
647 (* This cannot be tested with the current framework. The
648 * function can return NULL in normal operations, which the
649 * test framework interprets as an error.
652 "get the additional kernel options",
654 Return the additional kernel options which are added to the
655 guest kernel command line.
657 If C<NULL> then no options are added.");
659 ("set_autosync", (RErr, [Bool "autosync"]), -1, [FishAlias "autosync"],
663 If C<autosync> is true, this enables autosync. Libguestfs will make a
664 best effort attempt to run C<guestfs_umount_all> followed by
665 C<guestfs_sync> when the handle is closed
666 (also if the program exits without closing handles).
668 This is disabled by default (except in guestfish where it is
669 enabled by default).");
671 ("get_autosync", (RBool "autosync", []), -1, [],
672 [InitNone, Always, TestRun (
673 [["get_autosync"]])],
676 Get the autosync flag.");
678 ("set_verbose", (RErr, [Bool "verbose"]), -1, [FishAlias "verbose"],
682 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
684 Verbose messages are disabled unless the environment variable
685 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
687 ("get_verbose", (RBool "verbose", []), -1, [],
691 This returns the verbose messages flag.");
693 ("is_ready", (RBool "ready", []), -1, [],
694 [InitNone, Always, TestOutputTrue (
696 "is ready to accept commands",
698 This returns true iff this handle is ready to accept commands
699 (in the C<READY> state).
701 For more information on states, see L<guestfs(3)>.");
703 ("is_config", (RBool "config", []), -1, [],
704 [InitNone, Always, TestOutputFalse (
706 "is in configuration state",
708 This returns true iff this handle is being configured
709 (in the C<CONFIG> state).
711 For more information on states, see L<guestfs(3)>.");
713 ("is_launching", (RBool "launching", []), -1, [],
714 [InitNone, Always, TestOutputFalse (
715 [["is_launching"]])],
716 "is launching subprocess",
718 This returns true iff this handle is launching the subprocess
719 (in the C<LAUNCHING> state).
721 For more information on states, see L<guestfs(3)>.");
723 ("is_busy", (RBool "busy", []), -1, [],
724 [InitNone, Always, TestOutputFalse (
726 "is busy processing a command",
728 This returns true iff this handle is busy processing a command
729 (in the C<BUSY> state).
731 For more information on states, see L<guestfs(3)>.");
733 ("get_state", (RInt "state", []), -1, [],
735 "get the current state",
737 This returns the current state as an opaque integer. This is
738 only useful for printing debug and internal error messages.
740 For more information on states, see L<guestfs(3)>.");
742 ("set_memsize", (RErr, [Int "memsize"]), -1, [FishAlias "memsize"],
743 [InitNone, Always, TestOutputInt (
744 [["set_memsize"; "500"];
745 ["get_memsize"]], 500)],
746 "set memory allocated to the qemu subprocess",
748 This sets the memory size in megabytes allocated to the
749 qemu subprocess. This only has any effect if called before
752 You can also change this by setting the environment
753 variable C<LIBGUESTFS_MEMSIZE> before the handle is
756 For more information on the architecture of libguestfs,
757 see L<guestfs(3)>.");
759 ("get_memsize", (RInt "memsize", []), -1, [],
760 [InitNone, Always, TestOutputIntOp (
761 [["get_memsize"]], ">=", 256)],
762 "get memory allocated to the qemu subprocess",
764 This gets the memory size in megabytes allocated to the
767 If C<guestfs_set_memsize> was not called
768 on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
769 then this returns the compiled-in default value for memsize.
771 For more information on the architecture of libguestfs,
772 see L<guestfs(3)>.");
774 ("get_pid", (RInt "pid", []), -1, [FishAlias "pid"],
775 [InitNone, Always, TestOutputIntOp (
776 [["get_pid"]], ">=", 1)],
777 "get PID of qemu subprocess",
779 Return the process ID of the qemu subprocess. If there is no
780 qemu subprocess, then this will return an error.
782 This is an internal call used for debugging and testing.");
784 ("version", (RStruct ("version", "version"), []), -1, [],
785 [InitNone, Always, TestOutputStruct (
786 [["version"]], [CompareWithInt ("major", 1)])],
787 "get the library version number",
789 Return the libguestfs version number that the program is linked
792 Note that because of dynamic linking this is not necessarily
793 the version of libguestfs that you compiled against. You can
794 compile the program, and then at runtime dynamically link
795 against a completely different C<libguestfs.so> library.
797 This call was added in version C<1.0.58>. In previous
798 versions of libguestfs there was no way to get the version
799 number. From C code you can use ELF weak linking tricks to find out if
800 this symbol exists (if it doesn't, then it's an earlier version).
802 The call returns a structure with four elements. The first
803 three (C<major>, C<minor> and C<release>) are numbers and
804 correspond to the usual version triplet. The fourth element
805 (C<extra>) is a string and is normally empty, but may be
806 used for distro-specific information.
808 To construct the original version string:
809 C<$major.$minor.$release$extra>
811 I<Note:> Don't use this call to test for availability
812 of features. Distro backports makes this unreliable. Use
813 C<guestfs_available> instead.");
815 ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"],
816 [InitNone, Always, TestOutputTrue (
817 [["set_selinux"; "true"];
819 "set SELinux enabled or disabled at appliance boot",
821 This sets the selinux flag that is passed to the appliance
822 at boot time. The default is C<selinux=0> (disabled).
824 Note that if SELinux is enabled, it is always in
825 Permissive mode (C<enforcing=0>).
827 For more information on the architecture of libguestfs,
828 see L<guestfs(3)>.");
830 ("get_selinux", (RBool "selinux", []), -1, [],
832 "get SELinux enabled flag",
834 This returns the current setting of the selinux flag which
835 is passed to the appliance at boot time. See C<guestfs_set_selinux>.
837 For more information on the architecture of libguestfs,
838 see L<guestfs(3)>.");
840 ("set_trace", (RErr, [Bool "trace"]), -1, [FishAlias "trace"],
841 [InitNone, Always, TestOutputFalse (
842 [["set_trace"; "false"];
844 "enable or disable command traces",
846 If the command trace flag is set to 1, then commands are
847 printed on stdout before they are executed in a format
848 which is very similar to the one used by guestfish. In
849 other words, you can run a program with this enabled, and
850 you will get out a script which you can feed to guestfish
851 to perform the same set of actions.
853 If you want to trace C API calls into libguestfs (and
854 other libraries) then possibly a better way is to use
855 the external ltrace(1) command.
857 Command traces are disabled unless the environment variable
858 C<LIBGUESTFS_TRACE> is defined and set to C<1>.");
860 ("get_trace", (RBool "trace", []), -1, [],
862 "get command trace enabled flag",
864 Return the command trace flag.");
866 ("set_direct", (RErr, [Bool "direct"]), -1, [FishAlias "direct"],
867 [InitNone, Always, TestOutputFalse (
868 [["set_direct"; "false"];
870 "enable or disable direct appliance mode",
872 If the direct appliance mode flag is enabled, then stdin and
873 stdout are passed directly through to the appliance once it
876 One consequence of this is that log messages aren't caught
877 by the library and handled by C<guestfs_set_log_message_callback>,
878 but go straight to stdout.
880 You probably don't want to use this unless you know what you
883 The default is disabled.");
885 ("get_direct", (RBool "direct", []), -1, [],
887 "get direct appliance mode flag",
889 Return the direct appliance mode flag.");
891 ("set_recovery_proc", (RErr, [Bool "recoveryproc"]), -1, [FishAlias "recovery-proc"],
892 [InitNone, Always, TestOutputTrue (
893 [["set_recovery_proc"; "true"];
894 ["get_recovery_proc"]])],
895 "enable or disable the recovery process",
897 If this is called with the parameter C<false> then
898 C<guestfs_launch> does not create a recovery process. The
899 purpose of the recovery process is to stop runaway qemu
900 processes in the case where the main program aborts abruptly.
902 This only has any effect if called before C<guestfs_launch>,
903 and the default is true.
905 About the only time when you would want to disable this is
906 if the main process will fork itself into the background
907 (\"daemonize\" itself). In this case the recovery process
908 thinks that the main program has disappeared and so kills
909 qemu, which is not very helpful.");
911 ("get_recovery_proc", (RBool "recoveryproc", []), -1, [],
913 "get recovery process enabled flag",
915 Return the recovery process enabled flag.");
917 ("add_drive_with_if", (RErr, [String "filename"; String "iface"]), -1, [],
919 "add a drive specifying the QEMU block emulation to use",
921 This is the same as C<guestfs_add_drive> but it allows you
922 to specify the QEMU interface emulation to use at run time.");
924 ("add_drive_ro_with_if", (RErr, [String "filename"; String "iface"]), -1, [],
926 "add a drive read-only specifying the QEMU block emulation to use",
928 This is the same as C<guestfs_add_drive_ro> but it allows you
929 to specify the QEMU interface emulation to use at run time.");
933 (* daemon_functions are any functions which cause some action
934 * to take place in the daemon.
937 let daemon_functions = [
938 ("mount", (RErr, [Device "device"; String "mountpoint"]), 1, [],
939 [InitEmpty, Always, TestOutput (
940 [["part_disk"; "/dev/sda"; "mbr"];
941 ["mkfs"; "ext2"; "/dev/sda1"];
942 ["mount"; "/dev/sda1"; "/"];
943 ["write_file"; "/new"; "new file contents"; "0"];
944 ["cat"; "/new"]], "new file contents")],
945 "mount a guest disk at a position in the filesystem",
947 Mount a guest disk at a position in the filesystem. Block devices
948 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
949 the guest. If those block devices contain partitions, they will have
950 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
953 The rules are the same as for L<mount(2)>: A filesystem must
954 first be mounted on C</> before others can be mounted. Other
955 filesystems can only be mounted on directories which already
958 The mounted filesystem is writable, if we have sufficient permissions
959 on the underlying device.
961 The filesystem options C<sync> and C<noatime> are set with this
962 call, in order to improve reliability.");
964 ("sync", (RErr, []), 2, [],
965 [ InitEmpty, Always, TestRun [["sync"]]],
966 "sync disks, writes are flushed through to the disk image",
968 This syncs the disk, so that any writes are flushed through to the
969 underlying disk image.
971 You should always call this if you have modified a disk image, before
972 closing the handle.");
974 ("touch", (RErr, [Pathname "path"]), 3, [],
975 [InitBasicFS, Always, TestOutputTrue (
977 ["exists"; "/new"]])],
978 "update file timestamps or create a new file",
980 Touch acts like the L<touch(1)> command. It can be used to
981 update the timestamps on a file, or, if the file does not exist,
982 to create a new zero-length file.");
984 ("cat", (RString "content", [Pathname "path"]), 4, [ProtocolLimitWarning],
985 [InitISOFS, Always, TestOutput (
986 [["cat"; "/known-2"]], "abcdef\n")],
987 "list the contents of a file",
989 Return the contents of the file named C<path>.
991 Note that this function cannot correctly handle binary files
992 (specifically, files containing C<\\0> character which is treated
993 as end of string). For those you need to use the C<guestfs_read_file>
994 or C<guestfs_download> functions which have a more complex interface.");
996 ("ll", (RString "listing", [Pathname "directory"]), 5, [],
997 [], (* XXX Tricky to test because it depends on the exact format
998 * of the 'ls -l' command, which changes between F10 and F11.
1000 "list the files in a directory (long format)",
1002 List the files in C<directory> (relative to the root directory,
1003 there is no cwd) in the format of 'ls -la'.
1005 This command is mostly useful for interactive sessions. It
1006 is I<not> intended that you try to parse the output string.");
1008 ("ls", (RStringList "listing", [Pathname "directory"]), 6, [],
1009 [InitBasicFS, Always, TestOutputList (
1011 ["touch"; "/newer"];
1012 ["touch"; "/newest"];
1013 ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])],
1014 "list the files in a directory",
1016 List the files in C<directory> (relative to the root directory,
1017 there is no cwd). The '.' and '..' entries are not returned, but
1018 hidden files are shown.
1020 This command is mostly useful for interactive sessions. Programs
1021 should probably use C<guestfs_readdir> instead.");
1023 ("list_devices", (RStringList "devices", []), 7, [],
1024 [InitEmpty, Always, TestOutputListOfDevices (
1025 [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
1026 "list the block devices",
1028 List all the block devices.
1030 The full block device names are returned, eg. C</dev/sda>");
1032 ("list_partitions", (RStringList "partitions", []), 8, [],
1033 [InitBasicFS, Always, TestOutputListOfDevices (
1034 [["list_partitions"]], ["/dev/sda1"]);
1035 InitEmpty, Always, TestOutputListOfDevices (
1036 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1037 ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1038 "list the partitions",
1040 List all the partitions detected on all block devices.
1042 The full partition device names are returned, eg. C</dev/sda1>
1044 This does not return logical volumes. For that you will need to
1045 call C<guestfs_lvs>.");
1047 ("pvs", (RStringList "physvols", []), 9, [Optional "lvm2"],
1048 [InitBasicFSonLVM, Always, TestOutputListOfDevices (
1049 [["pvs"]], ["/dev/sda1"]);
1050 InitEmpty, Always, TestOutputListOfDevices (
1051 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1052 ["pvcreate"; "/dev/sda1"];
1053 ["pvcreate"; "/dev/sda2"];
1054 ["pvcreate"; "/dev/sda3"];
1055 ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1056 "list the LVM physical volumes (PVs)",
1058 List all the physical volumes detected. This is the equivalent
1059 of the L<pvs(8)> command.
1061 This returns a list of just the device names that contain
1062 PVs (eg. C</dev/sda2>).
1064 See also C<guestfs_pvs_full>.");
1066 ("vgs", (RStringList "volgroups", []), 10, [Optional "lvm2"],
1067 [InitBasicFSonLVM, Always, TestOutputList (
1069 InitEmpty, Always, TestOutputList (
1070 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1071 ["pvcreate"; "/dev/sda1"];
1072 ["pvcreate"; "/dev/sda2"];
1073 ["pvcreate"; "/dev/sda3"];
1074 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1075 ["vgcreate"; "VG2"; "/dev/sda3"];
1076 ["vgs"]], ["VG1"; "VG2"])],
1077 "list the LVM volume groups (VGs)",
1079 List all the volumes groups detected. This is the equivalent
1080 of the L<vgs(8)> command.
1082 This returns a list of just the volume group names that were
1083 detected (eg. C<VolGroup00>).
1085 See also C<guestfs_vgs_full>.");
1087 ("lvs", (RStringList "logvols", []), 11, [Optional "lvm2"],
1088 [InitBasicFSonLVM, Always, TestOutputList (
1089 [["lvs"]], ["/dev/VG/LV"]);
1090 InitEmpty, Always, TestOutputList (
1091 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1092 ["pvcreate"; "/dev/sda1"];
1093 ["pvcreate"; "/dev/sda2"];
1094 ["pvcreate"; "/dev/sda3"];
1095 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1096 ["vgcreate"; "VG2"; "/dev/sda3"];
1097 ["lvcreate"; "LV1"; "VG1"; "50"];
1098 ["lvcreate"; "LV2"; "VG1"; "50"];
1099 ["lvcreate"; "LV3"; "VG2"; "50"];
1100 ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
1101 "list the LVM logical volumes (LVs)",
1103 List all the logical volumes detected. This is the equivalent
1104 of the L<lvs(8)> command.
1106 This returns a list of the logical volume device names
1107 (eg. C</dev/VolGroup00/LogVol00>).
1109 See also C<guestfs_lvs_full>.");
1111 ("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 12, [Optional "lvm2"],
1112 [], (* XXX how to test? *)
1113 "list the LVM physical volumes (PVs)",
1115 List all the physical volumes detected. This is the equivalent
1116 of the L<pvs(8)> command. The \"full\" version includes all fields.");
1118 ("vgs_full", (RStructList ("volgroups", "lvm_vg"), []), 13, [Optional "lvm2"],
1119 [], (* XXX how to test? *)
1120 "list the LVM volume groups (VGs)",
1122 List all the volumes groups detected. This is the equivalent
1123 of the L<vgs(8)> command. The \"full\" version includes all fields.");
1125 ("lvs_full", (RStructList ("logvols", "lvm_lv"), []), 14, [Optional "lvm2"],
1126 [], (* XXX how to test? *)
1127 "list the LVM logical volumes (LVs)",
1129 List all the logical volumes detected. This is the equivalent
1130 of the L<lvs(8)> command. The \"full\" version includes all fields.");
1132 ("read_lines", (RStringList "lines", [Pathname "path"]), 15, [],
1133 [InitISOFS, Always, TestOutputList (
1134 [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]);
1135 InitISOFS, Always, TestOutputList (
1136 [["read_lines"; "/empty"]], [])],
1137 "read file as lines",
1139 Return the contents of the file named C<path>.
1141 The file contents are returned as a list of lines. Trailing
1142 C<LF> and C<CRLF> character sequences are I<not> returned.
1144 Note that this function cannot correctly handle binary files
1145 (specifically, files containing C<\\0> character which is treated
1146 as end of line). For those you need to use the C<guestfs_read_file>
1147 function which has a more complex interface.");
1149 ("aug_init", (RErr, [Pathname "root"; Int "flags"]), 16, [Optional "augeas"],
1150 [], (* XXX Augeas code needs tests. *)
1151 "create a new Augeas handle",
1153 Create a new Augeas handle for editing configuration files.
1154 If there was any previous Augeas handle associated with this
1155 guestfs session, then it is closed.
1157 You must call this before using any other C<guestfs_aug_*>
1160 C<root> is the filesystem root. C<root> must not be NULL,
1163 The flags are the same as the flags defined in
1164 E<lt>augeas.hE<gt>, the logical I<or> of the following
1169 =item C<AUG_SAVE_BACKUP> = 1
1171 Keep the original file with a C<.augsave> extension.
1173 =item C<AUG_SAVE_NEWFILE> = 2
1175 Save changes into a file with extension C<.augnew>, and
1176 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
1178 =item C<AUG_TYPE_CHECK> = 4
1180 Typecheck lenses (can be expensive).
1182 =item C<AUG_NO_STDINC> = 8
1184 Do not use standard load path for modules.
1186 =item C<AUG_SAVE_NOOP> = 16
1188 Make save a no-op, just record what would have been changed.
1190 =item C<AUG_NO_LOAD> = 32
1192 Do not load the tree in C<guestfs_aug_init>.
1196 To close the handle, you can call C<guestfs_aug_close>.
1198 To find out more about Augeas, see L<http://augeas.net/>.");
1200 ("aug_close", (RErr, []), 26, [Optional "augeas"],
1201 [], (* XXX Augeas code needs tests. *)
1202 "close the current Augeas handle",
1204 Close the current Augeas handle and free up any resources
1205 used by it. After calling this, you have to call
1206 C<guestfs_aug_init> again before you can use any other
1207 Augeas functions.");
1209 ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [Optional "augeas"],
1210 [], (* XXX Augeas code needs tests. *)
1211 "define an Augeas variable",
1213 Defines an Augeas variable C<name> whose value is the result
1214 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
1217 On success this returns the number of nodes in C<expr>, or
1218 C<0> if C<expr> evaluates to something which is not a nodeset.");
1220 ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"]), 18, [Optional "augeas"],
1221 [], (* XXX Augeas code needs tests. *)
1222 "define an Augeas node",
1224 Defines a variable C<name> whose value is the result of
1227 If C<expr> evaluates to an empty nodeset, a node is created,
1228 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
1229 C<name> will be the nodeset containing that single node.
1231 On success this returns a pair containing the
1232 number of nodes in the nodeset, and a boolean flag
1233 if a node was created.");
1235 ("aug_get", (RString "val", [String "augpath"]), 19, [Optional "augeas"],
1236 [], (* XXX Augeas code needs tests. *)
1237 "look up the value of an Augeas path",
1239 Look up the value associated with C<path>. If C<path>
1240 matches exactly one node, the C<value> is returned.");
1242 ("aug_set", (RErr, [String "augpath"; String "val"]), 20, [Optional "augeas"],
1243 [], (* XXX Augeas code needs tests. *)
1244 "set Augeas path to value",
1246 Set the value associated with C<path> to C<val>.
1248 In the Augeas API, it is possible to clear a node by setting
1249 the value to NULL. Due to an oversight in the libguestfs API
1250 you cannot do that with this call. Instead you must use the
1251 C<guestfs_aug_clear> call.");
1253 ("aug_insert", (RErr, [String "augpath"; String "label"; Bool "before"]), 21, [Optional "augeas"],
1254 [], (* XXX Augeas code needs tests. *)
1255 "insert a sibling Augeas node",
1257 Create a new sibling C<label> for C<path>, inserting it into
1258 the tree before or after C<path> (depending on the boolean
1261 C<path> must match exactly one existing node in the tree, and
1262 C<label> must be a label, ie. not contain C</>, C<*> or end
1263 with a bracketed index C<[N]>.");
1265 ("aug_rm", (RInt "nrnodes", [String "augpath"]), 22, [Optional "augeas"],
1266 [], (* XXX Augeas code needs tests. *)
1267 "remove an Augeas path",
1269 Remove C<path> and all of its children.
1271 On success this returns the number of entries which were removed.");
1273 ("aug_mv", (RErr, [String "src"; String "dest"]), 23, [Optional "augeas"],
1274 [], (* XXX Augeas code needs tests. *)
1277 Move the node C<src> to C<dest>. C<src> must match exactly
1278 one node. C<dest> is overwritten if it exists.");
1280 ("aug_match", (RStringList "matches", [String "augpath"]), 24, [Optional "augeas"],
1281 [], (* XXX Augeas code needs tests. *)
1282 "return Augeas nodes which match augpath",
1284 Returns a list of paths which match the path expression C<path>.
1285 The returned paths are sufficiently qualified so that they match
1286 exactly one node in the current tree.");
1288 ("aug_save", (RErr, []), 25, [Optional "augeas"],
1289 [], (* XXX Augeas code needs tests. *)
1290 "write all pending Augeas changes to disk",
1292 This writes all pending changes to disk.
1294 The flags which were passed to C<guestfs_aug_init> affect exactly
1295 how files are saved.");
1297 ("aug_load", (RErr, []), 27, [Optional "augeas"],
1298 [], (* XXX Augeas code needs tests. *)
1299 "load files into the tree",
1301 Load files into the tree.
1303 See C<aug_load> in the Augeas documentation for the full gory
1306 ("aug_ls", (RStringList "matches", [String "augpath"]), 28, [Optional "augeas"],
1307 [], (* XXX Augeas code needs tests. *)
1308 "list Augeas nodes under augpath",
1310 This is just a shortcut for listing C<guestfs_aug_match>
1311 C<path/*> and sorting the resulting nodes into alphabetical order.");
1313 ("rm", (RErr, [Pathname "path"]), 29, [],
1314 [InitBasicFS, Always, TestRun
1317 InitBasicFS, Always, TestLastFail
1319 InitBasicFS, Always, TestLastFail
1324 Remove the single file C<path>.");
1326 ("rmdir", (RErr, [Pathname "path"]), 30, [],
1327 [InitBasicFS, Always, TestRun
1330 InitBasicFS, Always, TestLastFail
1331 [["rmdir"; "/new"]];
1332 InitBasicFS, Always, TestLastFail
1334 ["rmdir"; "/new"]]],
1335 "remove a directory",
1337 Remove the single directory C<path>.");
1339 ("rm_rf", (RErr, [Pathname "path"]), 31, [],
1340 [InitBasicFS, Always, TestOutputFalse
1342 ["mkdir"; "/new/foo"];
1343 ["touch"; "/new/foo/bar"];
1345 ["exists"; "/new"]]],
1346 "remove a file or directory recursively",
1348 Remove the file or directory C<path>, recursively removing the
1349 contents if its a directory. This is like the C<rm -rf> shell
1352 ("mkdir", (RErr, [Pathname "path"]), 32, [],
1353 [InitBasicFS, Always, TestOutputTrue
1355 ["is_dir"; "/new"]];
1356 InitBasicFS, Always, TestLastFail
1357 [["mkdir"; "/new/foo/bar"]]],
1358 "create a directory",
1360 Create a directory named C<path>.");
1362 ("mkdir_p", (RErr, [Pathname "path"]), 33, [],
1363 [InitBasicFS, Always, TestOutputTrue
1364 [["mkdir_p"; "/new/foo/bar"];
1365 ["is_dir"; "/new/foo/bar"]];
1366 InitBasicFS, Always, TestOutputTrue
1367 [["mkdir_p"; "/new/foo/bar"];
1368 ["is_dir"; "/new/foo"]];
1369 InitBasicFS, Always, TestOutputTrue
1370 [["mkdir_p"; "/new/foo/bar"];
1371 ["is_dir"; "/new"]];
1372 (* Regression tests for RHBZ#503133: *)
1373 InitBasicFS, Always, TestRun
1375 ["mkdir_p"; "/new"]];
1376 InitBasicFS, Always, TestLastFail
1378 ["mkdir_p"; "/new"]]],
1379 "create a directory and parents",
1381 Create a directory named C<path>, creating any parent directories
1382 as necessary. This is like the C<mkdir -p> shell command.");
1384 ("chmod", (RErr, [Int "mode"; Pathname "path"]), 34, [],
1385 [], (* XXX Need stat command to test *)
1388 Change the mode (permissions) of C<path> to C<mode>. Only
1389 numeric modes are supported.
1391 I<Note>: When using this command from guestfish, C<mode>
1392 by default would be decimal, unless you prefix it with
1393 C<0> to get octal, ie. use C<0700> not C<700>.
1395 The mode actually set is affected by the umask.");
1397 ("chown", (RErr, [Int "owner"; Int "group"; Pathname "path"]), 35, [],
1398 [], (* XXX Need stat command to test *)
1399 "change file owner and group",
1401 Change the file owner to C<owner> and group to C<group>.
1403 Only numeric uid and gid are supported. If you want to use
1404 names, you will need to locate and parse the password file
1405 yourself (Augeas support makes this relatively easy).");
1407 ("exists", (RBool "existsflag", [Pathname "path"]), 36, [],
1408 [InitISOFS, Always, TestOutputTrue (
1409 [["exists"; "/empty"]]);
1410 InitISOFS, Always, TestOutputTrue (
1411 [["exists"; "/directory"]])],
1412 "test if file or directory exists",
1414 This returns C<true> if and only if there is a file, directory
1415 (or anything) with the given C<path> name.
1417 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
1419 ("is_file", (RBool "fileflag", [Pathname "path"]), 37, [],
1420 [InitISOFS, Always, TestOutputTrue (
1421 [["is_file"; "/known-1"]]);
1422 InitISOFS, Always, TestOutputFalse (
1423 [["is_file"; "/directory"]])],
1424 "test if file exists",
1426 This returns C<true> if and only if there is a file
1427 with the given C<path> name. Note that it returns false for
1428 other objects like directories.
1430 See also C<guestfs_stat>.");
1432 ("is_dir", (RBool "dirflag", [Pathname "path"]), 38, [],
1433 [InitISOFS, Always, TestOutputFalse (
1434 [["is_dir"; "/known-3"]]);
1435 InitISOFS, Always, TestOutputTrue (
1436 [["is_dir"; "/directory"]])],
1437 "test if file exists",
1439 This returns C<true> if and only if there is a directory
1440 with the given C<path> name. Note that it returns false for
1441 other objects like files.
1443 See also C<guestfs_stat>.");
1445 ("pvcreate", (RErr, [Device "device"]), 39, [Optional "lvm2"],
1446 [InitEmpty, Always, TestOutputListOfDevices (
1447 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1448 ["pvcreate"; "/dev/sda1"];
1449 ["pvcreate"; "/dev/sda2"];
1450 ["pvcreate"; "/dev/sda3"];
1451 ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1452 "create an LVM physical volume",
1454 This creates an LVM physical volume on the named C<device>,
1455 where C<device> should usually be a partition name such
1458 ("vgcreate", (RErr, [String "volgroup"; DeviceList "physvols"]), 40, [Optional "lvm2"],
1459 [InitEmpty, Always, TestOutputList (
1460 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1461 ["pvcreate"; "/dev/sda1"];
1462 ["pvcreate"; "/dev/sda2"];
1463 ["pvcreate"; "/dev/sda3"];
1464 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1465 ["vgcreate"; "VG2"; "/dev/sda3"];
1466 ["vgs"]], ["VG1"; "VG2"])],
1467 "create an LVM volume group",
1469 This creates an LVM volume group called C<volgroup>
1470 from the non-empty list of physical volumes C<physvols>.");
1472 ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"]), 41, [Optional "lvm2"],
1473 [InitEmpty, Always, TestOutputList (
1474 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1475 ["pvcreate"; "/dev/sda1"];
1476 ["pvcreate"; "/dev/sda2"];
1477 ["pvcreate"; "/dev/sda3"];
1478 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1479 ["vgcreate"; "VG2"; "/dev/sda3"];
1480 ["lvcreate"; "LV1"; "VG1"; "50"];
1481 ["lvcreate"; "LV2"; "VG1"; "50"];
1482 ["lvcreate"; "LV3"; "VG2"; "50"];
1483 ["lvcreate"; "LV4"; "VG2"; "50"];
1484 ["lvcreate"; "LV5"; "VG2"; "50"];
1486 ["/dev/VG1/LV1"; "/dev/VG1/LV2";
1487 "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
1488 "create an LVM logical volume",
1490 This creates an LVM logical volume called C<logvol>
1491 on the volume group C<volgroup>, with C<size> megabytes.");
1493 ("mkfs", (RErr, [String "fstype"; Device "device"]), 42, [],
1494 [InitEmpty, Always, TestOutput (
1495 [["part_disk"; "/dev/sda"; "mbr"];
1496 ["mkfs"; "ext2"; "/dev/sda1"];
1497 ["mount_options"; ""; "/dev/sda1"; "/"];
1498 ["write_file"; "/new"; "new file contents"; "0"];
1499 ["cat"; "/new"]], "new file contents")],
1500 "make a filesystem",
1502 This creates a filesystem on C<device> (usually a partition
1503 or LVM logical volume). The filesystem type is C<fstype>, for
1506 ("sfdisk", (RErr, [Device "device";
1507 Int "cyls"; Int "heads"; Int "sectors";
1508 StringList "lines"]), 43, [DangerWillRobinson],
1510 "create partitions on a block device",
1512 This is a direct interface to the L<sfdisk(8)> program for creating
1513 partitions on block devices.
1515 C<device> should be a block device, for example C</dev/sda>.
1517 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1518 and sectors on the device, which are passed directly to sfdisk as
1519 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
1520 of these, then the corresponding parameter is omitted. Usually for
1521 'large' disks, you can just pass C<0> for these, but for small
1522 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1523 out the right geometry and you will need to tell it.
1525 C<lines> is a list of lines that we feed to C<sfdisk>. For more
1526 information refer to the L<sfdisk(8)> manpage.
1528 To create a single partition occupying the whole disk, you would
1529 pass C<lines> as a single element list, when the single element being
1530 the string C<,> (comma).
1532 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>,
1533 C<guestfs_part_init>");
1535 ("write_file", (RErr, [Pathname "path"; String "content"; Int "size"]), 44, [ProtocolLimitWarning],
1536 [InitBasicFS, Always, TestOutput (
1537 [["write_file"; "/new"; "new file contents"; "0"];
1538 ["cat"; "/new"]], "new file contents");
1539 InitBasicFS, Always, TestOutput (
1540 [["write_file"; "/new"; "\nnew file contents\n"; "0"];
1541 ["cat"; "/new"]], "\nnew file contents\n");
1542 InitBasicFS, Always, TestOutput (
1543 [["write_file"; "/new"; "\n\n"; "0"];
1544 ["cat"; "/new"]], "\n\n");
1545 InitBasicFS, Always, TestOutput (
1546 [["write_file"; "/new"; ""; "0"];
1547 ["cat"; "/new"]], "");
1548 InitBasicFS, Always, TestOutput (
1549 [["write_file"; "/new"; "\n\n\n"; "0"];
1550 ["cat"; "/new"]], "\n\n\n");
1551 InitBasicFS, Always, TestOutput (
1552 [["write_file"; "/new"; "\n"; "0"];
1553 ["cat"; "/new"]], "\n")],
1556 This call creates a file called C<path>. The contents of the
1557 file is the string C<content> (which can contain any 8 bit data),
1558 with length C<size>.
1560 As a special case, if C<size> is C<0>
1561 then the length is calculated using C<strlen> (so in this case
1562 the content cannot contain embedded ASCII NULs).
1564 I<NB.> Owing to a bug, writing content containing ASCII NUL
1565 characters does I<not> work, even if the length is specified.
1566 We hope to resolve this bug in a future version. In the meantime
1567 use C<guestfs_upload>.");
1569 ("umount", (RErr, [String "pathordevice"]), 45, [FishAlias "unmount"],
1570 [InitEmpty, Always, TestOutputListOfDevices (
1571 [["part_disk"; "/dev/sda"; "mbr"];
1572 ["mkfs"; "ext2"; "/dev/sda1"];
1573 ["mount_options"; ""; "/dev/sda1"; "/"];
1574 ["mounts"]], ["/dev/sda1"]);
1575 InitEmpty, Always, TestOutputList (
1576 [["part_disk"; "/dev/sda"; "mbr"];
1577 ["mkfs"; "ext2"; "/dev/sda1"];
1578 ["mount_options"; ""; "/dev/sda1"; "/"];
1581 "unmount a filesystem",
1583 This unmounts the given filesystem. The filesystem may be
1584 specified either by its mountpoint (path) or the device which
1585 contains the filesystem.");
1587 ("mounts", (RStringList "devices", []), 46, [],
1588 [InitBasicFS, Always, TestOutputListOfDevices (
1589 [["mounts"]], ["/dev/sda1"])],
1590 "show mounted filesystems",
1592 This returns the list of currently mounted filesystems. It returns
1593 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1595 Some internal mounts are not shown.
1597 See also: C<guestfs_mountpoints>");
1599 ("umount_all", (RErr, []), 47, [FishAlias "unmount-all"],
1600 [InitBasicFS, Always, TestOutputList (
1603 (* check that umount_all can unmount nested mounts correctly: *)
1604 InitEmpty, Always, TestOutputList (
1605 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1606 ["mkfs"; "ext2"; "/dev/sda1"];
1607 ["mkfs"; "ext2"; "/dev/sda2"];
1608 ["mkfs"; "ext2"; "/dev/sda3"];
1609 ["mount_options"; ""; "/dev/sda1"; "/"];
1611 ["mount_options"; ""; "/dev/sda2"; "/mp1"];
1612 ["mkdir"; "/mp1/mp2"];
1613 ["mount_options"; ""; "/dev/sda3"; "/mp1/mp2"];
1614 ["mkdir"; "/mp1/mp2/mp3"];
1617 "unmount all filesystems",
1619 This unmounts all mounted filesystems.
1621 Some internal mounts are not unmounted by this call.");
1623 ("lvm_remove_all", (RErr, []), 48, [DangerWillRobinson; Optional "lvm2"],
1625 "remove all LVM LVs, VGs and PVs",
1627 This command removes all LVM logical volumes, volume groups
1628 and physical volumes.");
1630 ("file", (RString "description", [Dev_or_Path "path"]), 49, [],
1631 [InitISOFS, Always, TestOutput (
1632 [["file"; "/empty"]], "empty");
1633 InitISOFS, Always, TestOutput (
1634 [["file"; "/known-1"]], "ASCII text");
1635 InitISOFS, Always, TestLastFail (
1636 [["file"; "/notexists"]])],
1637 "determine file type",
1639 This call uses the standard L<file(1)> command to determine
1640 the type or contents of the file. This also works on devices,
1641 for example to find out whether a partition contains a filesystem.
1643 This call will also transparently look inside various types
1646 The exact command which runs is C<file -zbsL path>. Note in
1647 particular that the filename is not prepended to the output
1648 (the C<-b> option).");
1650 ("command", (RString "output", [StringList "arguments"]), 50, [ProtocolLimitWarning],
1651 [InitBasicFS, Always, TestOutput (
1652 [["upload"; "test-command"; "/test-command"];
1653 ["chmod"; "0o755"; "/test-command"];
1654 ["command"; "/test-command 1"]], "Result1");
1655 InitBasicFS, Always, TestOutput (
1656 [["upload"; "test-command"; "/test-command"];
1657 ["chmod"; "0o755"; "/test-command"];
1658 ["command"; "/test-command 2"]], "Result2\n");
1659 InitBasicFS, Always, TestOutput (
1660 [["upload"; "test-command"; "/test-command"];
1661 ["chmod"; "0o755"; "/test-command"];
1662 ["command"; "/test-command 3"]], "\nResult3");
1663 InitBasicFS, Always, TestOutput (
1664 [["upload"; "test-command"; "/test-command"];
1665 ["chmod"; "0o755"; "/test-command"];
1666 ["command"; "/test-command 4"]], "\nResult4\n");
1667 InitBasicFS, Always, TestOutput (
1668 [["upload"; "test-command"; "/test-command"];
1669 ["chmod"; "0o755"; "/test-command"];
1670 ["command"; "/test-command 5"]], "\nResult5\n\n");
1671 InitBasicFS, Always, TestOutput (
1672 [["upload"; "test-command"; "/test-command"];
1673 ["chmod"; "0o755"; "/test-command"];
1674 ["command"; "/test-command 6"]], "\n\nResult6\n\n");
1675 InitBasicFS, Always, TestOutput (
1676 [["upload"; "test-command"; "/test-command"];
1677 ["chmod"; "0o755"; "/test-command"];
1678 ["command"; "/test-command 7"]], "");
1679 InitBasicFS, Always, TestOutput (
1680 [["upload"; "test-command"; "/test-command"];
1681 ["chmod"; "0o755"; "/test-command"];
1682 ["command"; "/test-command 8"]], "\n");
1683 InitBasicFS, Always, TestOutput (
1684 [["upload"; "test-command"; "/test-command"];
1685 ["chmod"; "0o755"; "/test-command"];
1686 ["command"; "/test-command 9"]], "\n\n");
1687 InitBasicFS, Always, TestOutput (
1688 [["upload"; "test-command"; "/test-command"];
1689 ["chmod"; "0o755"; "/test-command"];
1690 ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n");
1691 InitBasicFS, Always, TestOutput (
1692 [["upload"; "test-command"; "/test-command"];
1693 ["chmod"; "0o755"; "/test-command"];
1694 ["command"; "/test-command 11"]], "Result11-1\nResult11-2");
1695 InitBasicFS, Always, TestLastFail (
1696 [["upload"; "test-command"; "/test-command"];
1697 ["chmod"; "0o755"; "/test-command"];
1698 ["command"; "/test-command"]])],
1699 "run a command from the guest filesystem",
1701 This call runs a command from the guest filesystem. The
1702 filesystem must be mounted, and must contain a compatible
1703 operating system (ie. something Linux, with the same
1704 or compatible processor architecture).
1706 The single parameter is an argv-style list of arguments.
1707 The first element is the name of the program to run.
1708 Subsequent elements are parameters. The list must be
1709 non-empty (ie. must contain a program name). Note that
1710 the command runs directly, and is I<not> invoked via
1711 the shell (see C<guestfs_sh>).
1713 The return value is anything printed to I<stdout> by
1716 If the command returns a non-zero exit status, then
1717 this function returns an error message. The error message
1718 string is the content of I<stderr> from the command.
1720 The C<$PATH> environment variable will contain at least
1721 C</usr/bin> and C</bin>. If you require a program from
1722 another location, you should provide the full path in the
1725 Shared libraries and data files required by the program
1726 must be available on filesystems which are mounted in the
1727 correct places. It is the caller's responsibility to ensure
1728 all filesystems that are needed are mounted at the right
1731 ("command_lines", (RStringList "lines", [StringList "arguments"]), 51, [ProtocolLimitWarning],
1732 [InitBasicFS, Always, TestOutputList (
1733 [["upload"; "test-command"; "/test-command"];
1734 ["chmod"; "0o755"; "/test-command"];
1735 ["command_lines"; "/test-command 1"]], ["Result1"]);
1736 InitBasicFS, Always, TestOutputList (
1737 [["upload"; "test-command"; "/test-command"];
1738 ["chmod"; "0o755"; "/test-command"];
1739 ["command_lines"; "/test-command 2"]], ["Result2"]);
1740 InitBasicFS, Always, TestOutputList (
1741 [["upload"; "test-command"; "/test-command"];
1742 ["chmod"; "0o755"; "/test-command"];
1743 ["command_lines"; "/test-command 3"]], ["";"Result3"]);
1744 InitBasicFS, Always, TestOutputList (
1745 [["upload"; "test-command"; "/test-command"];
1746 ["chmod"; "0o755"; "/test-command"];
1747 ["command_lines"; "/test-command 4"]], ["";"Result4"]);
1748 InitBasicFS, Always, TestOutputList (
1749 [["upload"; "test-command"; "/test-command"];
1750 ["chmod"; "0o755"; "/test-command"];
1751 ["command_lines"; "/test-command 5"]], ["";"Result5";""]);
1752 InitBasicFS, Always, TestOutputList (
1753 [["upload"; "test-command"; "/test-command"];
1754 ["chmod"; "0o755"; "/test-command"];
1755 ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]);
1756 InitBasicFS, Always, TestOutputList (
1757 [["upload"; "test-command"; "/test-command"];
1758 ["chmod"; "0o755"; "/test-command"];
1759 ["command_lines"; "/test-command 7"]], []);
1760 InitBasicFS, Always, TestOutputList (
1761 [["upload"; "test-command"; "/test-command"];
1762 ["chmod"; "0o755"; "/test-command"];
1763 ["command_lines"; "/test-command 8"]], [""]);
1764 InitBasicFS, Always, TestOutputList (
1765 [["upload"; "test-command"; "/test-command"];
1766 ["chmod"; "0o755"; "/test-command"];
1767 ["command_lines"; "/test-command 9"]], ["";""]);
1768 InitBasicFS, Always, TestOutputList (
1769 [["upload"; "test-command"; "/test-command"];
1770 ["chmod"; "0o755"; "/test-command"];
1771 ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]);
1772 InitBasicFS, Always, TestOutputList (
1773 [["upload"; "test-command"; "/test-command"];
1774 ["chmod"; "0o755"; "/test-command"];
1775 ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])],
1776 "run a command, returning lines",
1778 This is the same as C<guestfs_command>, but splits the
1779 result into a list of lines.
1781 See also: C<guestfs_sh_lines>");
1783 ("stat", (RStruct ("statbuf", "stat"), [Pathname "path"]), 52, [],
1784 [InitISOFS, Always, TestOutputStruct (
1785 [["stat"; "/empty"]], [CompareWithInt ("size", 0)])],
1786 "get file information",
1788 Returns file information for the given C<path>.
1790 This is the same as the C<stat(2)> system call.");
1792 ("lstat", (RStruct ("statbuf", "stat"), [Pathname "path"]), 53, [],
1793 [InitISOFS, Always, TestOutputStruct (
1794 [["lstat"; "/empty"]], [CompareWithInt ("size", 0)])],
1795 "get file information for a symbolic link",
1797 Returns file information for the given C<path>.
1799 This is the same as C<guestfs_stat> except that if C<path>
1800 is a symbolic link, then the link is stat-ed, not the file it
1803 This is the same as the C<lstat(2)> system call.");
1805 ("statvfs", (RStruct ("statbuf", "statvfs"), [Pathname "path"]), 54, [],
1806 [InitISOFS, Always, TestOutputStruct (
1807 [["statvfs"; "/"]], [CompareWithInt ("namemax", 255)])],
1808 "get file system statistics",
1810 Returns file system statistics for any mounted file system.
1811 C<path> should be a file or directory in the mounted file system
1812 (typically it is the mount point itself, but it doesn't need to be).
1814 This is the same as the C<statvfs(2)> system call.");
1816 ("tune2fs_l", (RHashtable "superblock", [Device "device"]), 55, [],
1818 "get ext2/ext3/ext4 superblock details",
1820 This returns the contents of the ext2, ext3 or ext4 filesystem
1821 superblock on C<device>.
1823 It is the same as running C<tune2fs -l device>. See L<tune2fs(8)>
1824 manpage for more details. The list of fields returned isn't
1825 clearly defined, and depends on both the version of C<tune2fs>
1826 that libguestfs was built against, and the filesystem itself.");
1828 ("blockdev_setro", (RErr, [Device "device"]), 56, [],
1829 [InitEmpty, Always, TestOutputTrue (
1830 [["blockdev_setro"; "/dev/sda"];
1831 ["blockdev_getro"; "/dev/sda"]])],
1832 "set block device to read-only",
1834 Sets the block device named C<device> to read-only.
1836 This uses the L<blockdev(8)> command.");
1838 ("blockdev_setrw", (RErr, [Device "device"]), 57, [],
1839 [InitEmpty, Always, TestOutputFalse (
1840 [["blockdev_setrw"; "/dev/sda"];
1841 ["blockdev_getro"; "/dev/sda"]])],
1842 "set block device to read-write",
1844 Sets the block device named C<device> to read-write.
1846 This uses the L<blockdev(8)> command.");
1848 ("blockdev_getro", (RBool "ro", [Device "device"]), 58, [],
1849 [InitEmpty, Always, TestOutputTrue (
1850 [["blockdev_setro"; "/dev/sda"];
1851 ["blockdev_getro"; "/dev/sda"]])],
1852 "is block device set to read-only",
1854 Returns a boolean indicating if the block device is read-only
1855 (true if read-only, false if not).
1857 This uses the L<blockdev(8)> command.");
1859 ("blockdev_getss", (RInt "sectorsize", [Device "device"]), 59, [],
1860 [InitEmpty, Always, TestOutputInt (
1861 [["blockdev_getss"; "/dev/sda"]], 512)],
1862 "get sectorsize of block device",
1864 This returns the size of sectors on a block device.
1865 Usually 512, but can be larger for modern devices.
1867 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
1870 This uses the L<blockdev(8)> command.");
1872 ("blockdev_getbsz", (RInt "blocksize", [Device "device"]), 60, [],
1873 [InitEmpty, Always, TestOutputInt (
1874 [["blockdev_getbsz"; "/dev/sda"]], 4096)],
1875 "get blocksize of block device",
1877 This returns the block size of a device.
1879 (Note this is different from both I<size in blocks> and
1880 I<filesystem block size>).
1882 This uses the L<blockdev(8)> command.");
1884 ("blockdev_setbsz", (RErr, [Device "device"; Int "blocksize"]), 61, [],
1886 "set blocksize of block device",
1888 This sets the block size of a device.
1890 (Note this is different from both I<size in blocks> and
1891 I<filesystem block size>).
1893 This uses the L<blockdev(8)> command.");
1895 ("blockdev_getsz", (RInt64 "sizeinsectors", [Device "device"]), 62, [],
1896 [InitEmpty, Always, TestOutputInt (
1897 [["blockdev_getsz"; "/dev/sda"]], 1024000)],
1898 "get total size of device in 512-byte sectors",
1900 This returns the size of the device in units of 512-byte sectors
1901 (even if the sectorsize isn't 512 bytes ... weird).
1903 See also C<guestfs_blockdev_getss> for the real sector size of
1904 the device, and C<guestfs_blockdev_getsize64> for the more
1905 useful I<size in bytes>.
1907 This uses the L<blockdev(8)> command.");
1909 ("blockdev_getsize64", (RInt64 "sizeinbytes", [Device "device"]), 63, [],
1910 [InitEmpty, Always, TestOutputInt (
1911 [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
1912 "get total size of device in bytes",
1914 This returns the size of the device in bytes.
1916 See also C<guestfs_blockdev_getsz>.
1918 This uses the L<blockdev(8)> command.");
1920 ("blockdev_flushbufs", (RErr, [Device "device"]), 64, [],
1921 [InitEmpty, Always, TestRun
1922 [["blockdev_flushbufs"; "/dev/sda"]]],
1923 "flush device buffers",
1925 This tells the kernel to flush internal buffers associated
1928 This uses the L<blockdev(8)> command.");
1930 ("blockdev_rereadpt", (RErr, [Device "device"]), 65, [],
1931 [InitEmpty, Always, TestRun
1932 [["blockdev_rereadpt"; "/dev/sda"]]],
1933 "reread partition table",
1935 Reread the partition table on C<device>.
1937 This uses the L<blockdev(8)> command.");
1939 ("upload", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"]), 66, [],
1940 [InitBasicFS, Always, TestOutput (
1941 (* Pick a file from cwd which isn't likely to change. *)
1942 [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1943 ["checksum"; "md5"; "/COPYING.LIB"]],
1944 Digest.to_hex (Digest.file "COPYING.LIB"))],
1945 "upload a file from the local machine",
1947 Upload local file C<filename> to C<remotefilename> on the
1950 C<filename> can also be a named pipe.
1952 See also C<guestfs_download>.");
1954 ("download", (RErr, [Dev_or_Path "remotefilename"; FileOut "filename"]), 67, [],
1955 [InitBasicFS, Always, TestOutput (
1956 (* Pick a file from cwd which isn't likely to change. *)
1957 [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1958 ["download"; "/COPYING.LIB"; "testdownload.tmp"];
1959 ["upload"; "testdownload.tmp"; "/upload"];
1960 ["checksum"; "md5"; "/upload"]],
1961 Digest.to_hex (Digest.file "COPYING.LIB"))],
1962 "download a file to the local machine",
1964 Download file C<remotefilename> and save it as C<filename>
1965 on the local machine.
1967 C<filename> can also be a named pipe.
1969 See also C<guestfs_upload>, C<guestfs_cat>.");
1971 ("checksum", (RString "checksum", [String "csumtype"; Pathname "path"]), 68, [],
1972 [InitISOFS, Always, TestOutput (
1973 [["checksum"; "crc"; "/known-3"]], "2891671662");
1974 InitISOFS, Always, TestLastFail (
1975 [["checksum"; "crc"; "/notexists"]]);
1976 InitISOFS, Always, TestOutput (
1977 [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c");
1978 InitISOFS, Always, TestOutput (
1979 [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15");
1980 InitISOFS, Always, TestOutput (
1981 [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741");
1982 InitISOFS, Always, TestOutput (
1983 [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30");
1984 InitISOFS, Always, TestOutput (
1985 [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640");
1986 InitISOFS, Always, TestOutput (
1987 [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6")],
1988 "compute MD5, SHAx or CRC checksum of file",
1990 This call computes the MD5, SHAx or CRC checksum of the
1993 The type of checksum to compute is given by the C<csumtype>
1994 parameter which must have one of the following values:
2000 Compute the cyclic redundancy check (CRC) specified by POSIX
2001 for the C<cksum> command.
2005 Compute the MD5 hash (using the C<md5sum> program).
2009 Compute the SHA1 hash (using the C<sha1sum> program).
2013 Compute the SHA224 hash (using the C<sha224sum> program).
2017 Compute the SHA256 hash (using the C<sha256sum> program).
2021 Compute the SHA384 hash (using the C<sha384sum> program).
2025 Compute the SHA512 hash (using the C<sha512sum> program).
2029 The checksum is returned as a printable string.
2031 To get the checksum for a device, use C<guestfs_checksum_device>.
2033 To get the checksums for many files, use C<guestfs_checksums_out>.");
2035 ("tar_in", (RErr, [FileIn "tarfile"; Pathname "directory"]), 69, [],
2036 [InitBasicFS, Always, TestOutput (
2037 [["tar_in"; "../images/helloworld.tar"; "/"];
2038 ["cat"; "/hello"]], "hello\n")],
2039 "unpack tarfile to directory",
2041 This command uploads and unpacks local file C<tarfile> (an
2042 I<uncompressed> tar file) into C<directory>.
2044 To upload a compressed tarball, use C<guestfs_tgz_in>
2045 or C<guestfs_txz_in>.");
2047 ("tar_out", (RErr, [String "directory"; FileOut "tarfile"]), 70, [],
2049 "pack directory into tarfile",
2051 This command packs the contents of C<directory> and downloads
2052 it to local file C<tarfile>.
2054 To download a compressed tarball, use C<guestfs_tgz_out>
2055 or C<guestfs_txz_out>.");
2057 ("tgz_in", (RErr, [FileIn "tarball"; Pathname "directory"]), 71, [],
2058 [InitBasicFS, Always, TestOutput (
2059 [["tgz_in"; "../images/helloworld.tar.gz"; "/"];
2060 ["cat"; "/hello"]], "hello\n")],
2061 "unpack compressed tarball to directory",
2063 This command uploads and unpacks local file C<tarball> (a
2064 I<gzip compressed> tar file) into C<directory>.
2066 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
2068 ("tgz_out", (RErr, [Pathname "directory"; FileOut "tarball"]), 72, [],
2070 "pack directory into compressed tarball",
2072 This command packs the contents of C<directory> and downloads
2073 it to local file C<tarball>.
2075 To download an uncompressed tarball, use C<guestfs_tar_out>.");
2077 ("mount_ro", (RErr, [Device "device"; String "mountpoint"]), 73, [],
2078 [InitBasicFS, Always, TestLastFail (
2080 ["mount_ro"; "/dev/sda1"; "/"];
2081 ["touch"; "/new"]]);
2082 InitBasicFS, Always, TestOutput (
2083 [["write_file"; "/new"; "data"; "0"];
2085 ["mount_ro"; "/dev/sda1"; "/"];
2086 ["cat"; "/new"]], "data")],
2087 "mount a guest disk, read-only",
2089 This is the same as the C<guestfs_mount> command, but it
2090 mounts the filesystem with the read-only (I<-o ro>) flag.");
2092 ("mount_options", (RErr, [String "options"; Device "device"; String "mountpoint"]), 74, [],
2094 "mount a guest disk with mount options",
2096 This is the same as the C<guestfs_mount> command, but it
2097 allows you to set the mount options as for the
2098 L<mount(8)> I<-o> flag.");
2100 ("mount_vfs", (RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"]), 75, [],
2102 "mount a guest disk with mount options and vfstype",
2104 This is the same as the C<guestfs_mount> command, but it
2105 allows you to set both the mount options and the vfstype
2106 as for the L<mount(8)> I<-o> and I<-t> flags.");
2108 ("debug", (RString "result", [String "subcmd"; StringList "extraargs"]), 76, [],
2110 "debugging and internals",
2112 The C<guestfs_debug> command exposes some internals of
2113 C<guestfsd> (the guestfs daemon) that runs inside the
2116 There is no comprehensive help for this command. You have
2117 to look at the file C<daemon/debug.c> in the libguestfs source
2118 to find out what you can do.");
2120 ("lvremove", (RErr, [Device "device"]), 77, [Optional "lvm2"],
2121 [InitEmpty, Always, TestOutputList (
2122 [["part_disk"; "/dev/sda"; "mbr"];
2123 ["pvcreate"; "/dev/sda1"];
2124 ["vgcreate"; "VG"; "/dev/sda1"];
2125 ["lvcreate"; "LV1"; "VG"; "50"];
2126 ["lvcreate"; "LV2"; "VG"; "50"];
2127 ["lvremove"; "/dev/VG/LV1"];
2128 ["lvs"]], ["/dev/VG/LV2"]);
2129 InitEmpty, Always, TestOutputList (
2130 [["part_disk"; "/dev/sda"; "mbr"];
2131 ["pvcreate"; "/dev/sda1"];
2132 ["vgcreate"; "VG"; "/dev/sda1"];
2133 ["lvcreate"; "LV1"; "VG"; "50"];
2134 ["lvcreate"; "LV2"; "VG"; "50"];
2135 ["lvremove"; "/dev/VG"];
2137 InitEmpty, Always, TestOutputList (
2138 [["part_disk"; "/dev/sda"; "mbr"];
2139 ["pvcreate"; "/dev/sda1"];
2140 ["vgcreate"; "VG"; "/dev/sda1"];
2141 ["lvcreate"; "LV1"; "VG"; "50"];
2142 ["lvcreate"; "LV2"; "VG"; "50"];
2143 ["lvremove"; "/dev/VG"];
2145 "remove an LVM logical volume",
2147 Remove an LVM logical volume C<device>, where C<device> is
2148 the path to the LV, such as C</dev/VG/LV>.
2150 You can also remove all LVs in a volume group by specifying
2151 the VG name, C</dev/VG>.");
2153 ("vgremove", (RErr, [String "vgname"]), 78, [Optional "lvm2"],
2154 [InitEmpty, Always, TestOutputList (
2155 [["part_disk"; "/dev/sda"; "mbr"];
2156 ["pvcreate"; "/dev/sda1"];
2157 ["vgcreate"; "VG"; "/dev/sda1"];
2158 ["lvcreate"; "LV1"; "VG"; "50"];
2159 ["lvcreate"; "LV2"; "VG"; "50"];
2162 InitEmpty, Always, TestOutputList (
2163 [["part_disk"; "/dev/sda"; "mbr"];
2164 ["pvcreate"; "/dev/sda1"];
2165 ["vgcreate"; "VG"; "/dev/sda1"];
2166 ["lvcreate"; "LV1"; "VG"; "50"];
2167 ["lvcreate"; "LV2"; "VG"; "50"];
2170 "remove an LVM volume group",
2172 Remove an LVM volume group C<vgname>, (for example C<VG>).
2174 This also forcibly removes all logical volumes in the volume
2177 ("pvremove", (RErr, [Device "device"]), 79, [Optional "lvm2"],
2178 [InitEmpty, Always, TestOutputListOfDevices (
2179 [["part_disk"; "/dev/sda"; "mbr"];
2180 ["pvcreate"; "/dev/sda1"];
2181 ["vgcreate"; "VG"; "/dev/sda1"];
2182 ["lvcreate"; "LV1"; "VG"; "50"];
2183 ["lvcreate"; "LV2"; "VG"; "50"];
2185 ["pvremove"; "/dev/sda1"];
2187 InitEmpty, Always, TestOutputListOfDevices (
2188 [["part_disk"; "/dev/sda"; "mbr"];
2189 ["pvcreate"; "/dev/sda1"];
2190 ["vgcreate"; "VG"; "/dev/sda1"];
2191 ["lvcreate"; "LV1"; "VG"; "50"];
2192 ["lvcreate"; "LV2"; "VG"; "50"];
2194 ["pvremove"; "/dev/sda1"];
2196 InitEmpty, Always, TestOutputListOfDevices (
2197 [["part_disk"; "/dev/sda"; "mbr"];
2198 ["pvcreate"; "/dev/sda1"];
2199 ["vgcreate"; "VG"; "/dev/sda1"];
2200 ["lvcreate"; "LV1"; "VG"; "50"];
2201 ["lvcreate"; "LV2"; "VG"; "50"];
2203 ["pvremove"; "/dev/sda1"];
2205 "remove an LVM physical volume",
2207 This wipes a physical volume C<device> so that LVM will no longer
2210 The implementation uses the C<pvremove> command which refuses to
2211 wipe physical volumes that contain any volume groups, so you have
2212 to remove those first.");
2214 ("set_e2label", (RErr, [Device "device"; String "label"]), 80, [],
2215 [InitBasicFS, Always, TestOutput (
2216 [["set_e2label"; "/dev/sda1"; "testlabel"];
2217 ["get_e2label"; "/dev/sda1"]], "testlabel")],
2218 "set the ext2/3/4 filesystem label",
2220 This sets the ext2/3/4 filesystem label of the filesystem on
2221 C<device> to C<label>. Filesystem labels are limited to
2224 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
2225 to return the existing label on a filesystem.");
2227 ("get_e2label", (RString "label", [Device "device"]), 81, [],
2229 "get the ext2/3/4 filesystem label",
2231 This returns the ext2/3/4 filesystem label of the filesystem on
2234 ("set_e2uuid", (RErr, [Device "device"; String "uuid"]), 82, [],
2235 (let uuid = uuidgen () in
2236 [InitBasicFS, Always, TestOutput (
2237 [["set_e2uuid"; "/dev/sda1"; uuid];
2238 ["get_e2uuid"; "/dev/sda1"]], uuid);
2239 InitBasicFS, Always, TestOutput (
2240 [["set_e2uuid"; "/dev/sda1"; "clear"];
2241 ["get_e2uuid"; "/dev/sda1"]], "");
2242 (* We can't predict what UUIDs will be, so just check the commands run. *)
2243 InitBasicFS, Always, TestRun (
2244 [["set_e2uuid"; "/dev/sda1"; "random"]]);
2245 InitBasicFS, Always, TestRun (
2246 [["set_e2uuid"; "/dev/sda1"; "time"]])]),
2247 "set the ext2/3/4 filesystem UUID",
2249 This sets the ext2/3/4 filesystem UUID of the filesystem on
2250 C<device> to C<uuid>. The format of the UUID and alternatives
2251 such as C<clear>, C<random> and C<time> are described in the
2252 L<tune2fs(8)> manpage.
2254 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
2255 to return the existing UUID of a filesystem.");
2257 ("get_e2uuid", (RString "uuid", [Device "device"]), 83, [],
2259 "get the ext2/3/4 filesystem UUID",
2261 This returns the ext2/3/4 filesystem UUID of the filesystem on
2264 ("fsck", (RInt "status", [String "fstype"; Device "device"]), 84, [FishOutput FishOutputHexadecimal],
2265 [InitBasicFS, Always, TestOutputInt (
2266 [["umount"; "/dev/sda1"];
2267 ["fsck"; "ext2"; "/dev/sda1"]], 0);
2268 InitBasicFS, Always, TestOutputInt (
2269 [["umount"; "/dev/sda1"];
2270 ["zero"; "/dev/sda1"];
2271 ["fsck"; "ext2"; "/dev/sda1"]], 8)],
2272 "run the filesystem checker",
2274 This runs the filesystem checker (fsck) on C<device> which
2275 should have filesystem type C<fstype>.
2277 The returned integer is the status. See L<fsck(8)> for the
2278 list of status codes from C<fsck>.
2286 Multiple status codes can be summed together.
2290 A non-zero return code can mean \"success\", for example if
2291 errors have been corrected on the filesystem.
2295 Checking or repairing NTFS volumes is not supported
2300 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
2302 ("zero", (RErr, [Device "device"]), 85, [],
2303 [InitBasicFS, Always, TestOutput (
2304 [["umount"; "/dev/sda1"];
2305 ["zero"; "/dev/sda1"];
2306 ["file"; "/dev/sda1"]], "data")],
2307 "write zeroes to the device",
2309 This command writes zeroes over the first few blocks of C<device>.
2311 How many blocks are zeroed isn't specified (but it's I<not> enough
2312 to securely wipe the device). It should be sufficient to remove
2313 any partition tables, filesystem superblocks and so on.
2315 See also: C<guestfs_zero_device>, C<guestfs_scrub_device>.");
2317 ("grub_install", (RErr, [Pathname "root"; Device "device"]), 86, [],
2318 (* Test disabled because grub-install incompatible with virtio-blk driver.
2319 * See also: https://bugzilla.redhat.com/show_bug.cgi?id=479760
2321 [InitBasicFS, Disabled, TestOutputTrue (
2322 [["grub_install"; "/"; "/dev/sda1"];
2323 ["is_dir"; "/boot"]])],
2326 This command installs GRUB (the Grand Unified Bootloader) on
2327 C<device>, with the root directory being C<root>.");
2329 ("cp", (RErr, [Pathname "src"; Pathname "dest"]), 87, [],
2330 [InitBasicFS, Always, TestOutput (
2331 [["write_file"; "/old"; "file content"; "0"];
2332 ["cp"; "/old"; "/new"];
2333 ["cat"; "/new"]], "file content");
2334 InitBasicFS, Always, TestOutputTrue (
2335 [["write_file"; "/old"; "file content"; "0"];
2336 ["cp"; "/old"; "/new"];
2337 ["is_file"; "/old"]]);
2338 InitBasicFS, Always, TestOutput (
2339 [["write_file"; "/old"; "file content"; "0"];
2341 ["cp"; "/old"; "/dir/new"];
2342 ["cat"; "/dir/new"]], "file content")],
2345 This copies a file from C<src> to C<dest> where C<dest> is
2346 either a destination filename or destination directory.");
2348 ("cp_a", (RErr, [Pathname "src"; Pathname "dest"]), 88, [],
2349 [InitBasicFS, Always, TestOutput (
2350 [["mkdir"; "/olddir"];
2351 ["mkdir"; "/newdir"];
2352 ["write_file"; "/olddir/file"; "file content"; "0"];
2353 ["cp_a"; "/olddir"; "/newdir"];
2354 ["cat"; "/newdir/olddir/file"]], "file content")],
2355 "copy a file or directory recursively",
2357 This copies a file or directory from C<src> to C<dest>
2358 recursively using the C<cp -a> command.");
2360 ("mv", (RErr, [Pathname "src"; Pathname "dest"]), 89, [],
2361 [InitBasicFS, Always, TestOutput (
2362 [["write_file"; "/old"; "file content"; "0"];
2363 ["mv"; "/old"; "/new"];
2364 ["cat"; "/new"]], "file content");
2365 InitBasicFS, Always, TestOutputFalse (
2366 [["write_file"; "/old"; "file content"; "0"];
2367 ["mv"; "/old"; "/new"];
2368 ["is_file"; "/old"]])],
2371 This moves a file from C<src> to C<dest> where C<dest> is
2372 either a destination filename or destination directory.");
2374 ("drop_caches", (RErr, [Int "whattodrop"]), 90, [],
2375 [InitEmpty, Always, TestRun (
2376 [["drop_caches"; "3"]])],
2377 "drop kernel page cache, dentries and inodes",
2379 This instructs the guest kernel to drop its page cache,
2380 and/or dentries and inode caches. The parameter C<whattodrop>
2381 tells the kernel what precisely to drop, see
2382 L<http://linux-mm.org/Drop_Caches>
2384 Setting C<whattodrop> to 3 should drop everything.
2386 This automatically calls L<sync(2)> before the operation,
2387 so that the maximum guest memory is freed.");
2389 ("dmesg", (RString "kmsgs", []), 91, [],
2390 [InitEmpty, Always, TestRun (
2392 "return kernel messages",
2394 This returns the kernel messages (C<dmesg> output) from
2395 the guest kernel. This is sometimes useful for extended
2396 debugging of problems.
2398 Another way to get the same information is to enable
2399 verbose messages with C<guestfs_set_verbose> or by setting
2400 the environment variable C<LIBGUESTFS_DEBUG=1> before
2401 running the program.");
2403 ("ping_daemon", (RErr, []), 92, [],
2404 [InitEmpty, Always, TestRun (
2405 [["ping_daemon"]])],
2406 "ping the guest daemon",
2408 This is a test probe into the guestfs daemon running inside
2409 the qemu subprocess. Calling this function checks that the
2410 daemon responds to the ping message, without affecting the daemon
2411 or attached block device(s) in any other way.");
2413 ("equal", (RBool "equality", [Pathname "file1"; Pathname "file2"]), 93, [],
2414 [InitBasicFS, Always, TestOutputTrue (
2415 [["write_file"; "/file1"; "contents of a file"; "0"];
2416 ["cp"; "/file1"; "/file2"];
2417 ["equal"; "/file1"; "/file2"]]);
2418 InitBasicFS, Always, TestOutputFalse (
2419 [["write_file"; "/file1"; "contents of a file"; "0"];
2420 ["write_file"; "/file2"; "contents of another file"; "0"];
2421 ["equal"; "/file1"; "/file2"]]);
2422 InitBasicFS, Always, TestLastFail (
2423 [["equal"; "/file1"; "/file2"]])],
2424 "test if two files have equal contents",
2426 This compares the two files C<file1> and C<file2> and returns
2427 true if their content is exactly equal, or false otherwise.
2429 The external L<cmp(1)> program is used for the comparison.");
2431 ("strings", (RStringList "stringsout", [Pathname "path"]), 94, [ProtocolLimitWarning],
2432 [InitISOFS, Always, TestOutputList (
2433 [["strings"; "/known-5"]], ["abcdefghi"; "jklmnopqr"]);
2434 InitISOFS, Always, TestOutputList (
2435 [["strings"; "/empty"]], [])],
2436 "print the printable strings in a file",
2438 This runs the L<strings(1)> command on a file and returns
2439 the list of printable strings found.");
2441 ("strings_e", (RStringList "stringsout", [String "encoding"; Pathname "path"]), 95, [ProtocolLimitWarning],
2442 [InitISOFS, Always, TestOutputList (
2443 [["strings_e"; "b"; "/known-5"]], []);
2444 InitBasicFS, Disabled, TestOutputList (
2445 [["write_file"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"; "24"];
2446 ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2447 "print the printable strings in a file",
2449 This is like the C<guestfs_strings> command, but allows you to
2450 specify the encoding.
2452 See the L<strings(1)> manpage for the full list of encodings.
2454 Commonly useful encodings are C<l> (lower case L) which will
2455 show strings inside Windows/x86 files.
2457 The returned strings are transcoded to UTF-8.");
2459 ("hexdump", (RString "dump", [Pathname "path"]), 96, [ProtocolLimitWarning],
2460 [InitISOFS, Always, TestOutput (
2461 [["hexdump"; "/known-4"]], "00000000 61 62 63 0a 64 65 66 0a 67 68 69 |abc.def.ghi|\n0000000b\n");
2462 (* Test for RHBZ#501888c2 regression which caused large hexdump
2463 * commands to segfault.
2465 InitISOFS, Always, TestRun (
2466 [["hexdump"; "/100krandom"]])],
2467 "dump a file in hexadecimal",
2469 This runs C<hexdump -C> on the given C<path>. The result is
2470 the human-readable, canonical hex dump of the file.");
2472 ("zerofree", (RErr, [Device "device"]), 97, [Optional "zerofree"],
2473 [InitNone, Always, TestOutput (
2474 [["part_disk"; "/dev/sda"; "mbr"];
2475 ["mkfs"; "ext3"; "/dev/sda1"];
2476 ["mount_options"; ""; "/dev/sda1"; "/"];
2477 ["write_file"; "/new"; "test file"; "0"];
2478 ["umount"; "/dev/sda1"];
2479 ["zerofree"; "/dev/sda1"];
2480 ["mount_options"; ""; "/dev/sda1"; "/"];
2481 ["cat"; "/new"]], "test file")],
2482 "zero unused inodes and disk blocks on ext2/3 filesystem",
2484 This runs the I<zerofree> program on C<device>. This program
2485 claims to zero unused inodes and disk blocks on an ext2/3
2486 filesystem, thus making it possible to compress the filesystem
2489 You should B<not> run this program if the filesystem is
2492 It is possible that using this program can damage the filesystem
2493 or data on the filesystem.");
2495 ("pvresize", (RErr, [Device "device"]), 98, [Optional "lvm2"],
2497 "resize an LVM physical volume",
2499 This resizes (expands or shrinks) an existing LVM physical
2500 volume to match the new size of the underlying device.");
2502 ("sfdisk_N", (RErr, [Device "device"; Int "partnum";
2503 Int "cyls"; Int "heads"; Int "sectors";
2504 String "line"]), 99, [DangerWillRobinson],
2506 "modify a single partition on a block device",
2508 This runs L<sfdisk(8)> option to modify just the single
2509 partition C<n> (note: C<n> counts from 1).
2511 For other parameters, see C<guestfs_sfdisk>. You should usually
2512 pass C<0> for the cyls/heads/sectors parameters.
2514 See also: C<guestfs_part_add>");
2516 ("sfdisk_l", (RString "partitions", [Device "device"]), 100, [],
2518 "display the partition table",
2520 This displays the partition table on C<device>, in the
2521 human-readable output of the L<sfdisk(8)> command. It is
2522 not intended to be parsed.
2524 See also: C<guestfs_part_list>");
2526 ("sfdisk_kernel_geometry", (RString "partitions", [Device "device"]), 101, [],
2528 "display the kernel geometry",
2530 This displays the kernel's idea of the geometry of C<device>.
2532 The result is in human-readable format, and not designed to
2535 ("sfdisk_disk_geometry", (RString "partitions", [Device "device"]), 102, [],
2537 "display the disk geometry from the partition table",
2539 This displays the disk geometry of C<device> read from the
2540 partition table. Especially in the case where the underlying
2541 block device has been resized, this can be different from the
2542 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2544 The result is in human-readable format, and not designed to
2547 ("vg_activate_all", (RErr, [Bool "activate"]), 103, [Optional "lvm2"],
2549 "activate or deactivate all volume groups",
2551 This command activates or (if C<activate> is false) deactivates
2552 all logical volumes in all volume groups.
2553 If activated, then they are made known to the
2554 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2555 then those devices disappear.
2557 This command is the same as running C<vgchange -a y|n>");
2559 ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"]), 104, [Optional "lvm2"],
2561 "activate or deactivate some volume groups",
2563 This command activates or (if C<activate> is false) deactivates
2564 all logical volumes in the listed volume groups C<volgroups>.
2565 If activated, then they are made known to the
2566 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2567 then those devices disappear.
2569 This command is the same as running C<vgchange -a y|n volgroups...>
2571 Note that if C<volgroups> is an empty list then B<all> volume groups
2572 are activated or deactivated.");
2574 ("lvresize", (RErr, [Device "device"; Int "mbytes"]), 105, [Optional "lvm2"],
2575 [InitNone, Always, TestOutput (
2576 [["part_disk"; "/dev/sda"; "mbr"];
2577 ["pvcreate"; "/dev/sda1"];
2578 ["vgcreate"; "VG"; "/dev/sda1"];
2579 ["lvcreate"; "LV"; "VG"; "10"];
2580 ["mkfs"; "ext2"; "/dev/VG/LV"];
2581 ["mount_options"; ""; "/dev/VG/LV"; "/"];
2582 ["write_file"; "/new"; "test content"; "0"];
2584 ["lvresize"; "/dev/VG/LV"; "20"];
2585 ["e2fsck_f"; "/dev/VG/LV"];
2586 ["resize2fs"; "/dev/VG/LV"];
2587 ["mount_options"; ""; "/dev/VG/LV"; "/"];
2588 ["cat"; "/new"]], "test content");
2589 InitNone, Always, TestRun (
2590 (* Make an LV smaller to test RHBZ#587484. *)
2591 [["part_disk"; "/dev/sda"; "mbr"];
2592 ["pvcreate"; "/dev/sda1"];
2593 ["vgcreate"; "VG"; "/dev/sda1"];
2594 ["lvcreate"; "LV"; "VG"; "20"];
2595 ["lvresize"; "/dev/VG/LV"; "10"]])],
2596 "resize an LVM logical volume",
2598 This resizes (expands or shrinks) an existing LVM logical
2599 volume to C<mbytes>. When reducing, data in the reduced part
2602 ("resize2fs", (RErr, [Device "device"]), 106, [],
2603 [], (* lvresize tests this *)
2604 "resize an ext2/ext3 filesystem",
2606 This resizes an ext2 or ext3 filesystem to match the size of
2607 the underlying device.
2609 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2610 on the C<device> before calling this command. For unknown reasons
2611 C<resize2fs> sometimes gives an error about this and sometimes not.
2612 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2613 calling this function.");
2615 ("find", (RStringList "names", [Pathname "directory"]), 107, [ProtocolLimitWarning],
2616 [InitBasicFS, Always, TestOutputList (
2617 [["find"; "/"]], ["lost+found"]);
2618 InitBasicFS, Always, TestOutputList (
2622 ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2623 InitBasicFS, Always, TestOutputList (
2624 [["mkdir_p"; "/a/b/c"];
2625 ["touch"; "/a/b/c/d"];
2626 ["find"; "/a/b/"]], ["c"; "c/d"])],
2627 "find all files and directories",
2629 This command lists out all files and directories, recursively,
2630 starting at C<directory>. It is essentially equivalent to
2631 running the shell command C<find directory -print> but some
2632 post-processing happens on the output, described below.
2634 This returns a list of strings I<without any prefix>. Thus
2635 if the directory structure was:
2641 then the returned list from C<guestfs_find> C</tmp> would be
2649 If C<directory> is not a directory, then this command returns
2652 The returned list is sorted.
2654 See also C<guestfs_find0>.");
2656 ("e2fsck_f", (RErr, [Device "device"]), 108, [],
2657 [], (* lvresize tests this *)
2658 "check an ext2/ext3 filesystem",
2660 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2661 filesystem checker on C<device>, noninteractively (C<-p>),
2662 even if the filesystem appears to be clean (C<-f>).
2664 This command is only needed because of C<guestfs_resize2fs>
2665 (q.v.). Normally you should use C<guestfs_fsck>.");
2667 ("sleep", (RErr, [Int "secs"]), 109, [],
2668 [InitNone, Always, TestRun (
2670 "sleep for some seconds",
2672 Sleep for C<secs> seconds.");
2674 ("ntfs_3g_probe", (RInt "status", [Bool "rw"; Device "device"]), 110, [Optional "ntfs3g"],
2675 [InitNone, Always, TestOutputInt (
2676 [["part_disk"; "/dev/sda"; "mbr"];
2677 ["mkfs"; "ntfs"; "/dev/sda1"];
2678 ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2679 InitNone, Always, TestOutputInt (
2680 [["part_disk"; "/dev/sda"; "mbr"];
2681 ["mkfs"; "ext2"; "/dev/sda1"];
2682 ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2683 "probe NTFS volume",
2685 This command runs the L<ntfs-3g.probe(8)> command which probes
2686 an NTFS C<device> for mountability. (Not all NTFS volumes can
2687 be mounted read-write, and some cannot be mounted at all).
2689 C<rw> is a boolean flag. Set it to true if you want to test
2690 if the volume can be mounted read-write. Set it to false if
2691 you want to test if the volume can be mounted read-only.
2693 The return value is an integer which C<0> if the operation
2694 would succeed, or some non-zero value documented in the
2695 L<ntfs-3g.probe(8)> manual page.");
2697 ("sh", (RString "output", [String "command"]), 111, [],
2698 [], (* XXX needs tests *)
2699 "run a command via the shell",
2701 This call runs a command from the guest filesystem via the
2704 This is like C<guestfs_command>, but passes the command to:
2706 /bin/sh -c \"command\"
2708 Depending on the guest's shell, this usually results in
2709 wildcards being expanded, shell expressions being interpolated
2712 All the provisos about C<guestfs_command> apply to this call.");
2714 ("sh_lines", (RStringList "lines", [String "command"]), 112, [],
2715 [], (* XXX needs tests *)
2716 "run a command via the shell returning lines",
2718 This is the same as C<guestfs_sh>, but splits the result
2719 into a list of lines.
2721 See also: C<guestfs_command_lines>");
2723 ("glob_expand", (RStringList "paths", [Pathname "pattern"]), 113, [],
2724 (* Use Pathname here, and hence ABS_PATH (pattern,... in generated
2725 * code in stubs.c, since all valid glob patterns must start with "/".
2726 * There is no concept of "cwd" in libguestfs, hence no "."-relative names.
2728 [InitBasicFS, Always, TestOutputList (
2729 [["mkdir_p"; "/a/b/c"];
2730 ["touch"; "/a/b/c/d"];
2731 ["touch"; "/a/b/c/e"];
2732 ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2733 InitBasicFS, Always, TestOutputList (
2734 [["mkdir_p"; "/a/b/c"];
2735 ["touch"; "/a/b/c/d"];
2736 ["touch"; "/a/b/c/e"];
2737 ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2738 InitBasicFS, Always, TestOutputList (
2739 [["mkdir_p"; "/a/b/c"];
2740 ["touch"; "/a/b/c/d"];
2741 ["touch"; "/a/b/c/e"];
2742 ["glob_expand"; "/a/*/x/*"]], [])],
2743 "expand a wildcard path",
2745 This command searches for all the pathnames matching
2746 C<pattern> according to the wildcard expansion rules
2749 If no paths match, then this returns an empty list
2750 (note: not an error).
2752 It is just a wrapper around the C L<glob(3)> function
2753 with flags C<GLOB_MARK|GLOB_BRACE>.
2754 See that manual page for more details.");
2756 ("scrub_device", (RErr, [Device "device"]), 114, [DangerWillRobinson; Optional "scrub"],
2757 [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *)
2758 [["scrub_device"; "/dev/sdc"]])],
2759 "scrub (securely wipe) a device",
2761 This command writes patterns over C<device> to make data retrieval
2764 It is an interface to the L<scrub(1)> program. See that
2765 manual page for more details.");
2767 ("scrub_file", (RErr, [Pathname "file"]), 115, [Optional "scrub"],
2768 [InitBasicFS, Always, TestRun (
2769 [["write_file"; "/file"; "content"; "0"];
2770 ["scrub_file"; "/file"]])],
2771 "scrub (securely wipe) a file",
2773 This command writes patterns over a file to make data retrieval
2776 The file is I<removed> after scrubbing.
2778 It is an interface to the L<scrub(1)> program. See that
2779 manual page for more details.");
2781 ("scrub_freespace", (RErr, [Pathname "dir"]), 116, [Optional "scrub"],
2782 [], (* XXX needs testing *)
2783 "scrub (securely wipe) free space",
2785 This command creates the directory C<dir> and then fills it
2786 with files until the filesystem is full, and scrubs the files
2787 as for C<guestfs_scrub_file>, and deletes them.
2788 The intention is to scrub any free space on the partition
2791 It is an interface to the L<scrub(1)> program. See that
2792 manual page for more details.");
2794 ("mkdtemp", (RString "dir", [Pathname "template"]), 117, [],
2795 [InitBasicFS, Always, TestRun (
2797 ["mkdtemp"; "/tmp/tmpXXXXXX"]])],
2798 "create a temporary directory",
2800 This command creates a temporary directory. The
2801 C<template> parameter should be a full pathname for the
2802 temporary directory name with the final six characters being
2805 For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
2806 the second one being suitable for Windows filesystems.
2808 The name of the temporary directory that was created
2811 The temporary directory is created with mode 0700
2812 and is owned by root.
2814 The caller is responsible for deleting the temporary
2815 directory and its contents after use.
2817 See also: L<mkdtemp(3)>");
2819 ("wc_l", (RInt "lines", [Pathname "path"]), 118, [],
2820 [InitISOFS, Always, TestOutputInt (
2821 [["wc_l"; "/10klines"]], 10000)],
2822 "count lines in a file",
2824 This command counts the lines in a file, using the
2825 C<wc -l> external command.");
2827 ("wc_w", (RInt "words", [Pathname "path"]), 119, [],
2828 [InitISOFS, Always, TestOutputInt (
2829 [["wc_w"; "/10klines"]], 10000)],
2830 "count words in a file",
2832 This command counts the words in a file, using the
2833 C<wc -w> external command.");
2835 ("wc_c", (RInt "chars", [Pathname "path"]), 120, [],
2836 [InitISOFS, Always, TestOutputInt (
2837 [["wc_c"; "/100kallspaces"]], 102400)],
2838 "count characters in a file",
2840 This command counts the characters in a file, using the
2841 C<wc -c> external command.");
2843 ("head", (RStringList "lines", [Pathname "path"]), 121, [ProtocolLimitWarning],
2844 [InitISOFS, Always, TestOutputList (
2845 [["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])],
2846 "return first 10 lines of a file",
2848 This command returns up to the first 10 lines of a file as
2849 a list of strings.");
2851 ("head_n", (RStringList "lines", [Int "nrlines"; Pathname "path"]), 122, [ProtocolLimitWarning],
2852 [InitISOFS, Always, TestOutputList (
2853 [["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
2854 InitISOFS, Always, TestOutputList (
2855 [["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
2856 InitISOFS, Always, TestOutputList (
2857 [["head_n"; "0"; "/10klines"]], [])],
2858 "return first N lines of a file",
2860 If the parameter C<nrlines> is a positive number, this returns the first
2861 C<nrlines> lines of the file C<path>.
2863 If the parameter C<nrlines> is a negative number, this returns lines
2864 from the file C<path>, excluding the last C<nrlines> lines.
2866 If the parameter C<nrlines> is zero, this returns an empty list.");
2868 ("tail", (RStringList "lines", [Pathname "path"]), 123, [ProtocolLimitWarning],
2869 [InitISOFS, Always, TestOutputList (
2870 [["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])],
2871 "return last 10 lines of a file",
2873 This command returns up to the last 10 lines of a file as
2874 a list of strings.");
2876 ("tail_n", (RStringList "lines", [Int "nrlines"; Pathname "path"]), 124, [ProtocolLimitWarning],
2877 [InitISOFS, Always, TestOutputList (
2878 [["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
2879 InitISOFS, Always, TestOutputList (
2880 [["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
2881 InitISOFS, Always, TestOutputList (
2882 [["tail_n"; "0"; "/10klines"]], [])],
2883 "return last N lines of a file",
2885 If the parameter C<nrlines> is a positive number, this returns the last
2886 C<nrlines> lines of the file C<path>.
2888 If the parameter C<nrlines> is a negative number, this returns lines
2889 from the file C<path>, starting with the C<-nrlines>th line.
2891 If the parameter C<nrlines> is zero, this returns an empty list.");
2893 ("df", (RString "output", []), 125, [],
2894 [], (* XXX Tricky to test because it depends on the exact format
2895 * of the 'df' command and other imponderables.
2897 "report file system disk space usage",
2899 This command runs the C<df> command to report disk space used.
2901 This command is mostly useful for interactive sessions. It
2902 is I<not> intended that you try to parse the output string.
2903 Use C<statvfs> from programs.");
2905 ("df_h", (RString "output", []), 126, [],
2906 [], (* XXX Tricky to test because it depends on the exact format
2907 * of the 'df' command and other imponderables.
2909 "report file system disk space usage (human readable)",
2911 This command runs the C<df -h> command to report disk space used
2912 in human-readable format.
2914 This command is mostly useful for interactive sessions. It
2915 is I<not> intended that you try to parse the output string.
2916 Use C<statvfs> from programs.");
2918 ("du", (RInt64 "sizekb", [Pathname "path"]), 127, [],
2919 [InitISOFS, Always, TestOutputInt (
2920 [["du"; "/directory"]], 2 (* ISO fs blocksize is 2K *))],
2921 "estimate file space usage",
2923 This command runs the C<du -s> command to estimate file space
2926 C<path> can be a file or a directory. If C<path> is a directory
2927 then the estimate includes the contents of the directory and all
2928 subdirectories (recursively).
2930 The result is the estimated size in I<kilobytes>
2931 (ie. units of 1024 bytes).");
2933 ("initrd_list", (RStringList "filenames", [Pathname "path"]), 128, [],
2934 [InitISOFS, Always, TestOutputList (
2935 [["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3";"known-4"; "known-5"])],
2936 "list files in an initrd",
2938 This command lists out files contained in an initrd.
2940 The files are listed without any initial C</> character. The
2941 files are listed in the order they appear (not necessarily
2942 alphabetical). Directory names are listed as separate items.
2944 Old Linux kernels (2.4 and earlier) used a compressed ext2
2945 filesystem as initrd. We I<only> support the newer initramfs
2946 format (compressed cpio files).");
2948 ("mount_loop", (RErr, [Pathname "file"; Pathname "mountpoint"]), 129, [],
2950 "mount a file using the loop device",
2952 This command lets you mount C<file> (a filesystem image
2953 in a file) on a mount point. It is entirely equivalent to
2954 the command C<mount -o loop file mountpoint>.");
2956 ("mkswap", (RErr, [Device "device"]), 130, [],
2957 [InitEmpty, Always, TestRun (
2958 [["part_disk"; "/dev/sda"; "mbr"];
2959 ["mkswap"; "/dev/sda1"]])],
2960 "create a swap partition",
2962 Create a swap partition on C<device>.");
2964 ("mkswap_L", (RErr, [String "label"; Device "device"]), 131, [],
2965 [InitEmpty, Always, TestRun (
2966 [["part_disk"; "/dev/sda"; "mbr"];
2967 ["mkswap_L"; "hello"; "/dev/sda1"]])],
2968 "create a swap partition with a label",
2970 Create a swap partition on C<device> with label C<label>.
2972 Note that you cannot attach a swap label to a block device
2973 (eg. C</dev/sda>), just to a partition. This appears to be
2974 a limitation of the kernel or swap tools.");
2976 ("mkswap_U", (RErr, [String "uuid"; Device "device"]), 132, [Optional "linuxfsuuid"],
2977 (let uuid = uuidgen () in
2978 [InitEmpty, Always, TestRun (
2979 [["part_disk"; "/dev/sda"; "mbr"];
2980 ["mkswap_U"; uuid; "/dev/sda1"]])]),
2981 "create a swap partition with an explicit UUID",
2983 Create a swap partition on C<device> with UUID C<uuid>.");
2985 ("mknod", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"]), 133, [Optional "mknod"],
2986 [InitBasicFS, Always, TestOutputStruct (
2987 [["mknod"; "0o10777"; "0"; "0"; "/node"];
2988 (* NB: default umask 022 means 0777 -> 0755 in these tests *)
2989 ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)]);
2990 InitBasicFS, Always, TestOutputStruct (
2991 [["mknod"; "0o60777"; "66"; "99"; "/node"];
2992 ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
2993 "make block, character or FIFO devices",
2995 This call creates block or character special devices, or
2996 named pipes (FIFOs).
2998 The C<mode> parameter should be the mode, using the standard
2999 constants. C<devmajor> and C<devminor> are the
3000 device major and minor numbers, only used when creating block
3001 and character special devices.
3003 Note that, just like L<mknod(2)>, the mode must be bitwise
3004 OR'd with S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call
3005 just creates a regular file). These constants are
3006 available in the standard Linux header files, or you can use
3007 C<guestfs_mknod_b>, C<guestfs_mknod_c> or C<guestfs_mkfifo>
3008 which are wrappers around this command which bitwise OR
3009 in the appropriate constant for you.
3011 The mode actually set is affected by the umask.");
3013 ("mkfifo", (RErr, [Int "mode"; Pathname "path"]), 134, [Optional "mknod"],
3014 [InitBasicFS, Always, TestOutputStruct (
3015 [["mkfifo"; "0o777"; "/node"];
3016 ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)])],
3017 "make FIFO (named pipe)",
3019 This call creates a FIFO (named pipe) called C<path> with
3020 mode C<mode>. It is just a convenient wrapper around
3023 The mode actually set is affected by the umask.");
3025 ("mknod_b", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"]), 135, [Optional "mknod"],
3026 [InitBasicFS, Always, TestOutputStruct (
3027 [["mknod_b"; "0o777"; "99"; "66"; "/node"];
3028 ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
3029 "make block device node",
3031 This call creates a block device node called C<path> with
3032 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3033 It is just a convenient wrapper around C<guestfs_mknod>.
3035 The mode actually set is affected by the umask.");
3037 ("mknod_c", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"]), 136, [Optional "mknod"],
3038 [InitBasicFS, Always, TestOutputStruct (
3039 [["mknod_c"; "0o777"; "99"; "66"; "/node"];
3040 ["stat"; "/node"]], [CompareWithInt ("mode", 0o20755)])],
3041 "make char device node",
3043 This call creates a char device node called C<path> with
3044 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3045 It is just a convenient wrapper around C<guestfs_mknod>.
3047 The mode actually set is affected by the umask.");
3049 ("umask", (RInt "oldmask", [Int "mask"]), 137, [FishOutput FishOutputOctal],
3050 [InitEmpty, Always, TestOutputInt (
3051 [["umask"; "0o22"]], 0o22)],
3052 "set file mode creation mask (umask)",
3054 This function sets the mask used for creating new files and
3055 device nodes to C<mask & 0777>.
3057 Typical umask values would be C<022> which creates new files
3058 with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and
3059 C<002> which creates new files with permissions like
3060 \"-rw-rw-r--\" or \"-rwxrwxr-x\".
3062 The default umask is C<022>. This is important because it
3063 means that directories and device nodes will be created with
3064 C<0644> or C<0755> mode even if you specify C<0777>.
3066 See also C<guestfs_get_umask>,
3067 L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
3069 This call returns the previous umask.");
3071 ("readdir", (RStructList ("entries", "dirent"), [Pathname "dir"]), 138, [],
3073 "read directories entries",
3075 This returns the list of directory entries in directory C<dir>.
3077 All entries in the directory are returned, including C<.> and
3078 C<..>. The entries are I<not> sorted, but returned in the same
3079 order as the underlying filesystem.
3081 Also this call returns basic file type information about each
3082 file. The C<ftyp> field will contain one of the following characters:
3120 The L<readdir(3)> returned a C<d_type> field with an
3125 This function is primarily intended for use by programs. To
3126 get a simple list of names, use C<guestfs_ls>. To get a printable
3127 directory for human consumption, use C<guestfs_ll>.");
3129 ("sfdiskM", (RErr, [Device "device"; StringList "lines"]), 139, [DangerWillRobinson],
3131 "create partitions on a block device",
3133 This is a simplified interface to the C<guestfs_sfdisk>
3134 command, where partition sizes are specified in megabytes
3135 only (rounded to the nearest cylinder) and you don't need
3136 to specify the cyls, heads and sectors parameters which
3137 were rarely if ever used anyway.
3139 See also: C<guestfs_sfdisk>, the L<sfdisk(8)> manpage
3140 and C<guestfs_part_disk>");
3142 ("zfile", (RString "description", [String "meth"; Pathname "path"]), 140, [DeprecatedBy "file"],
3144 "determine file type inside a compressed file",
3146 This command runs C<file> after first decompressing C<path>
3149 C<method> must be one of C<gzip>, C<compress> or C<bzip2>.
3151 Since 1.0.63, use C<guestfs_file> instead which can now
3152 process compressed files.");
3154 ("getxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"]), 141, [Optional "linuxxattrs"],
3156 "list extended attributes of a file or directory",
3158 This call lists the extended attributes of the file or directory
3161 At the system call level, this is a combination of the
3162 L<listxattr(2)> and L<getxattr(2)> calls.
3164 See also: C<guestfs_lgetxattrs>, L<attr(5)>.");
3166 ("lgetxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"]), 142, [Optional "linuxxattrs"],
3168 "list extended attributes of a file or directory",
3170 This is the same as C<guestfs_getxattrs>, but if C<path>
3171 is a symbolic link, then it returns the extended attributes
3172 of the link itself.");
3174 ("setxattr", (RErr, [String "xattr";
3175 String "val"; Int "vallen"; (* will be BufferIn *)
3176 Pathname "path"]), 143, [Optional "linuxxattrs"],
3178 "set extended attribute of a file or directory",
3180 This call sets the extended attribute named C<xattr>
3181 of the file C<path> to the value C<val> (of length C<vallen>).
3182 The value is arbitrary 8 bit data.
3184 See also: C<guestfs_lsetxattr>, L<attr(5)>.");
3186 ("lsetxattr", (RErr, [String "xattr";
3187 String "val"; Int "vallen"; (* will be BufferIn *)
3188 Pathname "path"]), 144, [Optional "linuxxattrs"],
3190 "set extended attribute of a file or directory",
3192 This is the same as C<guestfs_setxattr>, but if C<path>
3193 is a symbolic link, then it sets an extended attribute
3194 of the link itself.");
3196 ("removexattr", (RErr, [String "xattr"; Pathname "path"]), 145, [Optional "linuxxattrs"],
3198 "remove extended attribute of a file or directory",
3200 This call removes the extended attribute named C<xattr>
3201 of the file C<path>.
3203 See also: C<guestfs_lremovexattr>, L<attr(5)>.");
3205 ("lremovexattr", (RErr, [String "xattr"; Pathname "path"]), 146, [Optional "linuxxattrs"],
3207 "remove extended attribute of a file or directory",
3209 This is the same as C<guestfs_removexattr>, but if C<path>
3210 is a symbolic link, then it removes an extended attribute
3211 of the link itself.");
3213 ("mountpoints", (RHashtable "mps", []), 147, [],
3217 This call is similar to C<guestfs_mounts>. That call returns
3218 a list of devices. This one returns a hash table (map) of
3219 device name to directory where the device is mounted.");
3221 ("mkmountpoint", (RErr, [String "exemptpath"]), 148, [],
3222 (* This is a special case: while you would expect a parameter
3223 * of type "Pathname", that doesn't work, because it implies
3224 * NEED_ROOT in the generated calling code in stubs.c, and
3225 * this function cannot use NEED_ROOT.
3228 "create a mountpoint",
3230 C<guestfs_mkmountpoint> and C<guestfs_rmmountpoint> are
3231 specialized calls that can be used to create extra mountpoints
3232 before mounting the first filesystem.
3234 These calls are I<only> necessary in some very limited circumstances,
3235 mainly the case where you want to mount a mix of unrelated and/or
3236 read-only filesystems together.
3238 For example, live CDs often contain a \"Russian doll\" nest of
3239 filesystems, an ISO outer layer, with a squashfs image inside, with
3240 an ext2/3 image inside that. You can unpack this as follows
3243 add-ro Fedora-11-i686-Live.iso
3246 mkmountpoint /squash
3249 mount-loop /cd/LiveOS/squashfs.img /squash
3250 mount-loop /squash/LiveOS/ext3fs.img /ext3
3252 The inner filesystem is now unpacked under the /ext3 mountpoint.");
3254 ("rmmountpoint", (RErr, [String "exemptpath"]), 149, [],
3256 "remove a mountpoint",
3258 This calls removes a mountpoint that was previously created
3259 with C<guestfs_mkmountpoint>. See C<guestfs_mkmountpoint>
3260 for full details.");
3262 ("read_file", (RBufferOut "content", [Pathname "path"]), 150, [ProtocolLimitWarning],
3263 [InitISOFS, Always, TestOutputBuffer (
3264 [["read_file"; "/known-4"]], "abc\ndef\nghi")],
3267 This calls returns the contents of the file C<path> as a
3270 Unlike C<guestfs_cat>, this function can correctly
3271 handle files that contain embedded ASCII NUL characters.
3272 However unlike C<guestfs_download>, this function is limited
3273 in the total size of file that can be handled.");
3275 ("grep", (RStringList "lines", [String "regex"; Pathname "path"]), 151, [ProtocolLimitWarning],
3276 [InitISOFS, Always, TestOutputList (
3277 [["grep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"]);
3278 InitISOFS, Always, TestOutputList (
3279 [["grep"; "nomatch"; "/test-grep.txt"]], [])],
3280 "return lines matching a pattern",
3282 This calls the external C<grep> program and returns the
3285 ("egrep", (RStringList "lines", [String "regex"; Pathname "path"]), 152, [ProtocolLimitWarning],
3286 [InitISOFS, Always, TestOutputList (
3287 [["egrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3288 "return lines matching a pattern",
3290 This calls the external C<egrep> program and returns the
3293 ("fgrep", (RStringList "lines", [String "pattern"; Pathname "path"]), 153, [ProtocolLimitWarning],
3294 [InitISOFS, Always, TestOutputList (
3295 [["fgrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3296 "return lines matching a pattern",
3298 This calls the external C<fgrep> program and returns the
3301 ("grepi", (RStringList "lines", [String "regex"; Pathname "path"]), 154, [ProtocolLimitWarning],
3302 [InitISOFS, Always, TestOutputList (
3303 [["grepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3304 "return lines matching a pattern",
3306 This calls the external C<grep -i> program and returns the
3309 ("egrepi", (RStringList "lines", [String "regex"; Pathname "path"]), 155, [ProtocolLimitWarning],
3310 [InitISOFS, Always, TestOutputList (
3311 [["egrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3312 "return lines matching a pattern",
3314 This calls the external C<egrep -i> program and returns the
3317 ("fgrepi", (RStringList "lines", [String "pattern"; Pathname "path"]), 156, [ProtocolLimitWarning],
3318 [InitISOFS, Always, TestOutputList (
3319 [["fgrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3320 "return lines matching a pattern",
3322 This calls the external C<fgrep -i> program and returns the
3325 ("zgrep", (RStringList "lines", [String "regex"; Pathname "path"]), 157, [ProtocolLimitWarning],
3326 [InitISOFS, Always, TestOutputList (
3327 [["zgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3328 "return lines matching a pattern",
3330 This calls the external C<zgrep> program and returns the
3333 ("zegrep", (RStringList "lines", [String "regex"; Pathname "path"]), 158, [ProtocolLimitWarning],
3334 [InitISOFS, Always, TestOutputList (
3335 [["zegrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3336 "return lines matching a pattern",
3338 This calls the external C<zegrep> program and returns the
3341 ("zfgrep", (RStringList "lines", [String "pattern"; Pathname "path"]), 159, [ProtocolLimitWarning],
3342 [InitISOFS, Always, TestOutputList (
3343 [["zfgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3344 "return lines matching a pattern",
3346 This calls the external C<zfgrep> program and returns the
3349 ("zgrepi", (RStringList "lines", [String "regex"; Pathname "path"]), 160, [ProtocolLimitWarning],
3350 [InitISOFS, Always, TestOutputList (
3351 [["zgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3352 "return lines matching a pattern",
3354 This calls the external C<zgrep -i> program and returns the
3357 ("zegrepi", (RStringList "lines", [String "regex"; Pathname "path"]), 161, [ProtocolLimitWarning],
3358 [InitISOFS, Always, TestOutputList (
3359 [["zegrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3360 "return lines matching a pattern",
3362 This calls the external C<zegrep -i> program and returns the
3365 ("zfgrepi", (RStringList "lines", [String "pattern"; Pathname "path"]), 162, [ProtocolLimitWarning],
3366 [InitISOFS, Always, TestOutputList (
3367 [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3368 "return lines matching a pattern",
3370 This calls the external C<zfgrep -i> program and returns the
3373 ("realpath", (RString "rpath", [Pathname "path"]), 163, [Optional "realpath"],
3374 [InitISOFS, Always, TestOutput (
3375 [["realpath"; "/../directory"]], "/directory")],
3376 "canonicalized absolute pathname",
3378 Return the canonicalized absolute pathname of C<path>. The
3379 returned path has no C<.>, C<..> or symbolic link path elements.");
3381 ("ln", (RErr, [String "target"; Pathname "linkname"]), 164, [],
3382 [InitBasicFS, Always, TestOutputStruct (
3385 ["stat"; "/b"]], [CompareWithInt ("nlink", 2)])],
3386 "create a hard link",
3388 This command creates a hard link using the C<ln> command.");
3390 ("ln_f", (RErr, [String "target"; Pathname "linkname"]), 165, [],
3391 [InitBasicFS, Always, TestOutputStruct (
3394 ["ln_f"; "/a"; "/b"];
3395 ["stat"; "/b"]], [CompareWithInt ("nlink", 2)])],
3396 "create a hard link",
3398 This command creates a hard link using the C<ln -f> command.
3399 The C<-f> option removes the link (C<linkname>) if it exists already.");
3401 ("ln_s", (RErr, [String "target"; Pathname "linkname"]), 166, [],
3402 [InitBasicFS, Always, TestOutputStruct (
3404 ["ln_s"; "a"; "/b"];
3405 ["lstat"; "/b"]], [CompareWithInt ("mode", 0o120777)])],
3406 "create a symbolic link",
3408 This command creates a symbolic link using the C<ln -s> command.");
3410 ("ln_sf", (RErr, [String "target"; Pathname "linkname"]), 167, [],
3411 [InitBasicFS, Always, TestOutput (
3412 [["mkdir_p"; "/a/b"];
3413 ["touch"; "/a/b/c"];
3414 ["ln_sf"; "../d"; "/a/b/c"];
3415 ["readlink"; "/a/b/c"]], "../d")],
3416 "create a symbolic link",
3418 This command creates a symbolic link using the C<ln -sf> command,
3419 The C<-f> option removes the link (C<linkname>) if it exists already.");
3421 ("readlink", (RString "link", [Pathname "path"]), 168, [],
3422 [] (* XXX tested above *),
3423 "read the target of a symbolic link",
3425 This command reads the target of a symbolic link.");
3427 ("fallocate", (RErr, [Pathname "path"; Int "len"]), 169, [],
3428 [InitBasicFS, Always, TestOutputStruct (
3429 [["fallocate"; "/a"; "1000000"];
3430 ["stat"; "/a"]], [CompareWithInt ("size", 1_000_000)])],
3431 "preallocate a file in the guest filesystem",
3433 This command preallocates a file (containing zero bytes) named
3434 C<path> of size C<len> bytes. If the file exists already, it
3437 Do not confuse this with the guestfish-specific
3438 C<alloc> command which allocates a file in the host and
3439 attaches it as a device.");
3441 ("swapon_device", (RErr, [Device "device"]), 170, [],
3442 [InitPartition, Always, TestRun (
3443 [["mkswap"; "/dev/sda1"];
3444 ["swapon_device"; "/dev/sda1"];
3445 ["swapoff_device"; "/dev/sda1"]])],
3446 "enable swap on device",
3448 This command enables the libguestfs appliance to use the
3449 swap device or partition named C<device>. The increased
3450 memory is made available for all commands, for example
3451 those run using C<guestfs_command> or C<guestfs_sh>.
3453 Note that you should not swap to existing guest swap
3454 partitions unless you know what you are doing. They may
3455 contain hibernation information, or other information that
3456 the guest doesn't want you to trash. You also risk leaking
3457 information about the host to the guest this way. Instead,
3458 attach a new host device to the guest and swap on that.");
3460 ("swapoff_device", (RErr, [Device "device"]), 171, [],
3461 [], (* XXX tested by swapon_device *)
3462 "disable swap on device",
3464 This command disables the libguestfs appliance swap
3465 device or partition named C<device>.
3466 See C<guestfs_swapon_device>.");
3468 ("swapon_file", (RErr, [Pathname "file"]), 172, [],
3469 [InitBasicFS, Always, TestRun (
3470 [["fallocate"; "/swap"; "8388608"];
3471 ["mkswap_file"; "/swap"];
3472 ["swapon_file"; "/swap"];
3473 ["swapoff_file"; "/swap"]])],
3474 "enable swap on file",
3476 This command enables swap to a file.
3477 See C<guestfs_swapon_device> for other notes.");
3479 ("swapoff_file", (RErr, [Pathname "file"]), 173, [],
3480 [], (* XXX tested by swapon_file *)
3481 "disable swap on file",
3483 This command disables the libguestfs appliance swap on file.");
3485 ("swapon_label", (RErr, [String "label"]), 174, [],
3486 [InitEmpty, Always, TestRun (
3487 [["part_disk"; "/dev/sdb"; "mbr"];
3488 ["mkswap_L"; "swapit"; "/dev/sdb1"];
3489 ["swapon_label"; "swapit"];
3490 ["swapoff_label"; "swapit"];
3491 ["zero"; "/dev/sdb"];
3492 ["blockdev_rereadpt"; "/dev/sdb"]])],
3493 "enable swap on labeled swap partition",
3495 This command enables swap to a labeled swap partition.
3496 See C<guestfs_swapon_device> for other notes.");
3498 ("swapoff_label", (RErr, [String "label"]), 175, [],
3499 [], (* XXX tested by swapon_label *)
3500 "disable swap on labeled swap partition",
3502 This command disables the libguestfs appliance swap on
3503 labeled swap partition.");
3505 ("swapon_uuid", (RErr, [String "uuid"]), 176, [Optional "linuxfsuuid"],
3506 (let uuid = uuidgen () in
3507 [InitEmpty, Always, TestRun (
3508 [["mkswap_U"; uuid; "/dev/sdb"];
3509 ["swapon_uuid"; uuid];
3510 ["swapoff_uuid"; uuid]])]),
3511 "enable swap on swap partition by UUID",
3513 This command enables swap to a swap partition with the given UUID.
3514 See C<guestfs_swapon_device> for other notes.");
3516 ("swapoff_uuid", (RErr, [String "uuid"]), 177, [Optional "linuxfsuuid"],
3517 [], (* XXX tested by swapon_uuid *)
3518 "disable swap on swap partition by UUID",
3520 This command disables the libguestfs appliance swap partition
3521 with the given UUID.");
3523 ("mkswap_file", (RErr, [Pathname "path"]), 178, [],
3524 [InitBasicFS, Always, TestRun (
3525 [["fallocate"; "/swap"; "8388608"];
3526 ["mkswap_file"; "/swap"]])],
3527 "create a swap file",
3531 This command just writes a swap file signature to an existing
3532 file. To create the file itself, use something like C<guestfs_fallocate>.");
3534 ("inotify_init", (RErr, [Int "maxevents"]), 179, [Optional "inotify"],
3535 [InitISOFS, Always, TestRun (
3536 [["inotify_init"; "0"]])],
3537 "create an inotify handle",
3539 This command creates a new inotify handle.
3540 The inotify subsystem can be used to notify events which happen to
3541 objects in the guest filesystem.
3543 C<maxevents> is the maximum number of events which will be
3544 queued up between calls to C<guestfs_inotify_read> or
3545 C<guestfs_inotify_files>.
3546 If this is passed as C<0>, then the kernel (or previously set)
3547 default is used. For Linux 2.6.29 the default was 16384 events.
3548 Beyond this limit, the kernel throws away events, but records
3549 the fact that it threw them away by setting a flag
3550 C<IN_Q_OVERFLOW> in the returned structure list (see
3551 C<guestfs_inotify_read>).
3553 Before any events are generated, you have to add some
3554 watches to the internal watch list. See:
3555 C<guestfs_inotify_add_watch>,
3556 C<guestfs_inotify_rm_watch> and
3557 C<guestfs_inotify_watch_all>.
3559 Queued up events should be read periodically by calling
3560 C<guestfs_inotify_read>
3561 (or C<guestfs_inotify_files> which is just a helpful
3562 wrapper around C<guestfs_inotify_read>). If you don't
3563 read the events out often enough then you risk the internal
3566 The handle should be closed after use by calling
3567 C<guestfs_inotify_close>. This also removes any
3568 watches automatically.
3570 See also L<inotify(7)> for an overview of the inotify interface
3571 as exposed by the Linux kernel, which is roughly what we expose
3572 via libguestfs. Note that there is one global inotify handle
3573 per libguestfs instance.");
3575 ("inotify_add_watch", (RInt64 "wd", [Pathname "path"; Int "mask"]), 180, [Optional "inotify"],
3576 [InitBasicFS, Always, TestOutputList (
3577 [["inotify_init"; "0"];
3578 ["inotify_add_watch"; "/"; "1073741823"];
3581 ["inotify_files"]], ["a"; "b"])],
3582 "add an inotify watch",
3584 Watch C<path> for the events listed in C<mask>.
3586 Note that if C<path> is a directory then events within that
3587 directory are watched, but this does I<not> happen recursively
3588 (in subdirectories).
3590 Note for non-C or non-Linux callers: the inotify events are
3591 defined by the Linux kernel ABI and are listed in
3592 C</usr/include/sys/inotify.h>.");
3594 ("inotify_rm_watch", (RErr, [Int(*XXX64*) "wd"]), 181, [Optional "inotify"],
3596 "remove an inotify watch",
3598 Remove a previously defined inotify watch.
3599 See C<guestfs_inotify_add_watch>.");
3601 ("inotify_read", (RStructList ("events", "inotify_event"), []), 182, [Optional "inotify"],
3603 "return list of inotify events",
3605 Return the complete queue of events that have happened
3606 since the previous read call.
3608 If no events have happened, this returns an empty list.
3610 I<Note>: In order to make sure that all events have been
3611 read, you must call this function repeatedly until it
3612 returns an empty list. The reason is that the call will
3613 read events up to the maximum appliance-to-host message
3614 size and leave remaining events in the queue.");
3616 ("inotify_files", (RStringList "paths", []), 183, [Optional "inotify"],
3618 "return list of watched files that had events",
3620 This function is a helpful wrapper around C<guestfs_inotify_read>
3621 which just returns a list of pathnames of objects that were
3622 touched. The returned pathnames are sorted and deduplicated.");
3624 ("inotify_close", (RErr, []), 184, [Optional "inotify"],
3626 "close the inotify handle",
3628 This closes the inotify handle which was previously
3629 opened by inotify_init. It removes all watches, throws
3630 away any pending events, and deallocates all resources.");
3632 ("setcon", (RErr, [String "context"]), 185, [Optional "selinux"],
3634 "set SELinux security context",
3636 This sets the SELinux security context of the daemon
3637 to the string C<context>.
3639 See the documentation about SELINUX in L<guestfs(3)>.");
3641 ("getcon", (RString "context", []), 186, [Optional "selinux"],
3643 "get SELinux security context",
3645 This gets the SELinux security context of the daemon.
3647 See the documentation about SELINUX in L<guestfs(3)>,
3648 and C<guestfs_setcon>");
3650 ("mkfs_b", (RErr, [String "fstype"; Int "blocksize"; Device "device"]), 187, [],
3651 [InitEmpty, Always, TestOutput (
3652 [["part_disk"; "/dev/sda"; "mbr"];
3653 ["mkfs_b"; "ext2"; "4096"; "/dev/sda1"];
3654 ["mount_options"; ""; "/dev/sda1"; "/"];
3655 ["write_file"; "/new"; "new file contents"; "0"];
3656 ["cat"; "/new"]], "new file contents")],
3657 "make a filesystem with block size",
3659 This call is similar to C<guestfs_mkfs>, but it allows you to
3660 control the block size of the resulting filesystem. Supported
3661 block sizes depend on the filesystem type, but typically they
3662 are C<1024>, C<2048> or C<4096> only.");
3664 ("mke2journal", (RErr, [Int "blocksize"; Device "device"]), 188, [],
3665 [InitEmpty, Always, TestOutput (
3666 [["sfdiskM"; "/dev/sda"; ",100 ,"];
3667 ["mke2journal"; "4096"; "/dev/sda1"];
3668 ["mke2fs_J"; "ext2"; "4096"; "/dev/sda2"; "/dev/sda1"];
3669 ["mount_options"; ""; "/dev/sda2"; "/"];
3670 ["write_file"; "/new"; "new file contents"; "0"];
3671 ["cat"; "/new"]], "new file contents")],
3672 "make ext2/3/4 external journal",
3674 This creates an ext2 external journal on C<device>. It is equivalent
3677 mke2fs -O journal_dev -b blocksize device");
3679 ("mke2journal_L", (RErr, [Int "blocksize"; String "label"; Device "device"]), 189, [],
3680 [InitEmpty, Always, TestOutput (
3681 [["sfdiskM"; "/dev/sda"; ",100 ,"];
3682 ["mke2journal_L"; "4096"; "JOURNAL"; "/dev/sda1"];
3683 ["mke2fs_JL"; "ext2"; "4096"; "/dev/sda2"; "JOURNAL"];
3684 ["mount_options"; ""; "/dev/sda2"; "/"];
3685 ["write_file"; "/new"; "new file contents"; "0"];
3686 ["cat"; "/new"]], "new file contents")],
3687 "make ext2/3/4 external journal with label",
3689 This creates an ext2 external journal on C<device> with label C<label>.");
3691 ("mke2journal_U", (RErr, [Int "blocksize"; String "uuid"; Device "device"]), 190, [Optional "linuxfsuuid"],
3692 (let uuid = uuidgen () in
3693 [InitEmpty, Always, TestOutput (
3694 [["sfdiskM"; "/dev/sda"; ",100 ,"];
3695 ["mke2journal_U"; "4096"; uuid; "/dev/sda1"];
3696 ["mke2fs_JU"; "ext2"; "4096"; "/dev/sda2"; uuid];
3697 ["mount_options"; ""; "/dev/sda2"; "/"];
3698 ["write_file"; "/new"; "new file contents"; "0"];
3699 ["cat"; "/new"]], "new file contents")]),
3700 "make ext2/3/4 external journal with UUID",
3702 This creates an ext2 external journal on C<device> with UUID C<uuid>.");
3704 ("mke2fs_J", (RErr, [String "fstype"; Int "blocksize"; Device "device"; Device "journal"]), 191, [],
3706 "make ext2/3/4 filesystem with external journal",
3708 This creates an ext2/3/4 filesystem on C<device> with
3709 an external journal on C<journal>. It is equivalent
3712 mke2fs -t fstype -b blocksize -J device=<journal> <device>
3714 See also C<guestfs_mke2journal>.");
3716 ("mke2fs_JL", (RErr, [String "fstype"; Int "blocksize"; Device "device"; String "label"]), 192, [],
3718 "make ext2/3/4 filesystem with external journal",
3720 This creates an ext2/3/4 filesystem on C<device> with
3721 an external journal on the journal labeled C<label>.
3723 See also C<guestfs_mke2journal_L>.");
3725 ("mke2fs_JU", (RErr, [String "fstype"; Int "blocksize"; Device "device"; String "uuid"]), 193, [Optional "linuxfsuuid"],
3727 "make ext2/3/4 filesystem with external journal",
3729 This creates an ext2/3/4 filesystem on C<device> with
3730 an external journal on the journal with UUID C<uuid>.
3732 See also C<guestfs_mke2journal_U>.");
3734 ("modprobe", (RErr, [String "modulename"]), 194, [Optional "linuxmodules"],
3735 [InitNone, Always, TestRun [["modprobe"; "fat"]]],
3736 "load a kernel module",
3738 This loads a kernel module in the appliance.
3740 The kernel module must have been whitelisted when libguestfs
3741 was built (see C<appliance/kmod.whitelist.in> in the source).");
3743 ("echo_daemon", (RString "output", [StringList "words"]), 195, [],
3744 [InitNone, Always, TestOutput (
3745 [["echo_daemon"; "This is a test"]], "This is a test"
3747 "echo arguments back to the client",
3749 This command concatenate the list of C<words> passed with single spaces between
3750 them and returns the resulting string.
3752 You can use this command to test the connection through to the daemon.
3754 See also C<guestfs_ping_daemon>.");
3756 ("find0", (RErr, [Pathname "directory"; FileOut "files"]), 196, [],
3757 [], (* There is a regression test for this. *)
3758 "find all files and directories, returning NUL-separated list",
3760 This command lists out all files and directories, recursively,
3761 starting at C<directory>, placing the resulting list in the
3762 external file called C<files>.
3764 This command works the same way as C<guestfs_find> with the
3765 following exceptions:
3771 The resulting list is written to an external file.
3775 Items (filenames) in the result are separated
3776 by C<\\0> characters. See L<find(1)> option I<-print0>.
3780 This command is not limited in the number of names that it
3785 The result list is not sorted.
3789 ("case_sensitive_path", (RString "rpath", [Pathname "path"]), 197, [],
3790 [InitISOFS, Always, TestOutput (
3791 [["case_sensitive_path"; "/DIRECTORY"]], "/directory");
3792 InitISOFS, Always, TestOutput (
3793 [["case_sensitive_path"; "/DIRECTORY/"]], "/directory");
3794 InitISOFS, Always, TestOutput (
3795 [["case_sensitive_path"; "/Known-1"]], "/known-1");
3796 InitISOFS, Always, TestLastFail (
3797 [["case_sensitive_path"; "/Known-1/"]]);
3798 InitBasicFS, Always, TestOutput (
3800 ["mkdir"; "/a/bbb"];
3801 ["touch"; "/a/bbb/c"];
3802 ["case_sensitive_path"; "/A/bbB/C"]], "/a/bbb/c");
3803 InitBasicFS, Always, TestOutput (
3805 ["mkdir"; "/a/bbb"];
3806 ["touch"; "/a/bbb/c"];
3807 ["case_sensitive_path"; "/A////bbB/C"]], "/a/bbb/c");
3808 InitBasicFS, Always, TestLastFail (
3810 ["mkdir"; "/a/bbb"];
3811 ["touch"; "/a/bbb/c"];
3812 ["case_sensitive_path"; "/A/bbb/../bbb/C"]])],
3813 "return true path on case-insensitive filesystem",
3815 This can be used to resolve case insensitive paths on
3816 a filesystem which is case sensitive. The use case is
3817 to resolve paths which you have read from Windows configuration
3818 files or the Windows Registry, to the true path.
3820 The command handles a peculiarity of the Linux ntfs-3g
3821 filesystem driver (and probably others), which is that although
3822 the underlying filesystem is case-insensitive, the driver
3823 exports the filesystem to Linux as case-sensitive.
3825 One consequence of this is that special directories such
3826 as C<c:\\windows> may appear as C</WINDOWS> or C</windows>
3827 (or other things) depending on the precise details of how
3828 they were created. In Windows itself this would not be
3831 Bug or feature? You decide:
3832 L<http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
3834 This function resolves the true case of each element in the
3835 path and returns the case-sensitive path.
3837 Thus C<guestfs_case_sensitive_path> (\"/Windows/System32\")
3838 might return C<\"/WINDOWS/system32\"> (the exact return value
3839 would depend on details of how the directories were originally
3840 created under Windows).
3843 This function does not handle drive names, backslashes etc.
3845 See also C<guestfs_realpath>.");
3847 ("vfs_type", (RString "fstype", [Device "device"]), 198, [],
3848 [InitBasicFS, Always, TestOutput (
3849 [["vfs_type"; "/dev/sda1"]], "ext2")],
3850 "get the Linux VFS type corresponding to a mounted device",
3852 This command gets the block device type corresponding to
3853 a mounted device called C<device>.
3855 Usually the result is the name of the Linux VFS module that
3856 is used to mount this device (probably determined automatically
3857 if you used the C<guestfs_mount> call).");
3859 ("truncate", (RErr, [Pathname "path"]), 199, [],
3860 [InitBasicFS, Always, TestOutputStruct (
3861 [["write_file"; "/test"; "some stuff so size is not zero"; "0"];
3862 ["truncate"; "/test"];
3863 ["stat"; "/test"]], [CompareWithInt ("size", 0)])],
3864 "truncate a file to zero size",
3866 This command truncates C<path> to a zero-length file. The
3867 file must exist already.");
3869 ("truncate_size", (RErr, [Pathname "path"; Int64 "size"]), 200, [],
3870 [InitBasicFS, Always, TestOutputStruct (
3871 [["touch"; "/test"];
3872 ["truncate_size"; "/test"; "1000"];
3873 ["stat"; "/test"]], [CompareWithInt ("size", 1000)])],
3874 "truncate a file to a particular size",
3876 This command truncates C<path> to size C<size> bytes. The file
3877 must exist already. If the file is smaller than C<size> then
3878 the file is extended to the required size with null bytes.");
3880 ("utimens", (RErr, [Pathname "path"; Int64 "atsecs"; Int64 "atnsecs"; Int64 "mtsecs"; Int64 "mtnsecs"]), 201, [],
3881 [InitBasicFS, Always, TestOutputStruct (
3882 [["touch"; "/test"];
3883 ["utimens"; "/test"; "12345"; "67890"; "9876"; "5432"];
3884 ["stat"; "/test"]], [CompareWithInt ("mtime", 9876)])],
3885 "set timestamp of a file with nanosecond precision",
3887 This command sets the timestamps of a file with nanosecond
3890 C<atsecs, atnsecs> are the last access time (atime) in secs and
3891 nanoseconds from the epoch.
3893 C<mtsecs, mtnsecs> are the last modification time (mtime) in
3894 secs and nanoseconds from the epoch.
3896 If the C<*nsecs> field contains the special value C<-1> then
3897 the corresponding timestamp is set to the current time. (The
3898 C<*secs> field is ignored in this case).
3900 If the C<*nsecs> field contains the special value C<-2> then
3901 the corresponding timestamp is left unchanged. (The
3902 C<*secs> field is ignored in this case).");
3904 ("mkdir_mode", (RErr, [Pathname "path"; Int "mode"]), 202, [],
3905 [InitBasicFS, Always, TestOutputStruct (
3906 [["mkdir_mode"; "/test"; "0o111"];
3907 ["stat"; "/test"]], [CompareWithInt ("mode", 0o40111)])],
3908 "create a directory with a particular mode",
3910 This command creates a directory, setting the initial permissions
3911 of the directory to C<mode>.
3913 For common Linux filesystems, the actual mode which is set will
3914 be C<mode & ~umask & 01777>. Non-native-Linux filesystems may
3915 interpret the mode in other ways.
3917 See also C<guestfs_mkdir>, C<guestfs_umask>");
3919 ("lchown", (RErr, [Int "owner"; Int "group"; Pathname "path"]), 203, [],
3921 "change file owner and group",
3923 Change the file owner to C<owner> and group to C<group>.
3924 This is like C<guestfs_chown> but if C<path> is a symlink then
3925 the link itself is changed, not the target.
3927 Only numeric uid and gid are supported. If you want to use
3928 names, you will need to locate and parse the password file
3929 yourself (Augeas support makes this relatively easy).");
3931 ("lstatlist", (RStructList ("statbufs", "stat"), [Pathname "path"; StringList "names"]), 204, [],
3933 "lstat on multiple files",
3935 This call allows you to perform the C<guestfs_lstat> operation
3936 on multiple files, where all files are in the directory C<path>.
3937 C<names> is the list of files from this directory.
3939 On return you get a list of stat structs, with a one-to-one
3940 correspondence to the C<names> list. If any name did not exist
3941 or could not be lstat'd, then the C<ino> field of that structure
3944 This call is intended for programs that want to efficiently
3945 list a directory contents without making many round-trips.
3946 See also C<guestfs_lxattrlist> for a similarly efficient call
3947 for getting extended attributes. Very long directory listings
3948 might cause the protocol message size to be exceeded, causing
3949 this call to fail. The caller must split up such requests
3950 into smaller groups of names.");
3952 ("lxattrlist", (RStructList ("xattrs", "xattr"), [Pathname "path"; StringList "names"]), 205, [Optional "linuxxattrs"],
3954 "lgetxattr on multiple files",
3956 This call allows you to get the extended attributes
3957 of multiple files, where all files are in the directory C<path>.
3958 C<names> is the list of files from this directory.
3960 On return you get a flat list of xattr structs which must be
3961 interpreted sequentially. The first xattr struct always has a zero-length
3962 C<attrname>. C<attrval> in this struct is zero-length
3963 to indicate there was an error doing C<lgetxattr> for this
3964 file, I<or> is a C string which is a decimal number
3965 (the number of following attributes for this file, which could
3966 be C<\"0\">). Then after the first xattr struct are the
3967 zero or more attributes for the first named file.
3968 This repeats for the second and subsequent files.
3970 This call is intended for programs that want to efficiently
3971 list a directory contents without making many round-trips.
3972 See also C<guestfs_lstatlist> for a similarly efficient call
3973 for getting standard stats. Very long directory listings
3974 might cause the protocol message size to be exceeded, causing
3975 this call to fail. The caller must split up such requests
3976 into smaller groups of names.");
3978 ("readlinklist", (RStringList "links", [Pathname "path"; StringList "names"]), 206, [],
3980 "readlink on multiple files",
3982 This call allows you to do a C<readlink> operation
3983 on multiple files, where all files are in the directory C<path>.
3984 C<names> is the list of files from this directory.
3986 On return you get a list of strings, with a one-to-one
3987 correspondence to the C<names> list. Each string is the
3988 value of the symbol link.
3990 If the C<readlink(2)> operation fails on any name, then
3991 the corresponding result string is the empty string C<\"\">.
3992 However the whole operation is completed even if there
3993 were C<readlink(2)> errors, and so you can call this
3994 function with names where you don't know if they are
3995 symbolic links already (albeit slightly less efficient).
3997 This call is intended for programs that want to efficiently
3998 list a directory contents without making many round-trips.
3999 Very long directory listings might cause the protocol
4000 message size to be exceeded, causing
4001 this call to fail. The caller must split up such requests
4002 into smaller groups of names.");
4004 ("pread", (RBufferOut "content", [Pathname "path"; Int "count"; Int64 "offset"]), 207, [ProtocolLimitWarning],
4005 [InitISOFS, Always, TestOutputBuffer (
4006 [["pread"; "/known-4"; "1"; "3"]], "\n");
4007 InitISOFS, Always, TestOutputBuffer (
4008 [["pread"; "/empty"; "0"; "100"]], "")],
4009 "read part of a file",
4011 This command lets you read part of a file. It reads C<count>
4012 bytes of the file, starting at C<offset>, from file C<path>.
4014 This may read fewer bytes than requested. For further details
4015 see the L<pread(2)> system call.");
4017 ("part_init", (RErr, [Device "device"; String "parttype"]), 208, [],
4018 [InitEmpty, Always, TestRun (
4019 [["part_init"; "/dev/sda"; "gpt"]])],
4020 "create an empty partition table",
4022 This creates an empty partition table on C<device> of one of the
4023 partition types listed below. Usually C<parttype> should be
4024 either C<msdos> or C<gpt> (for large disks).
4026 Initially there are no partitions. Following this, you should
4027 call C<guestfs_part_add> for each partition required.
4029 Possible values for C<parttype> are:
4033 =item B<efi> | B<gpt>
4035 Intel EFI / GPT partition table.
4037 This is recommended for >= 2 TB partitions that will be accessed
4038 from Linux and Intel-based Mac OS X. It also has limited backwards
4039 compatibility with the C<mbr> format.
4041 =item B<mbr> | B<msdos>
4043 The standard PC \"Master Boot Record\" (MBR) format used
4044 by MS-DOS and Windows. This partition type will B<only> work
4045 for device sizes up to 2 TB. For large disks we recommend
4050 Other partition table types that may work but are not
4059 =item B<amiga> | B<rdb>
4061 Amiga \"Rigid Disk Block\" format.
4069 DASD, used on IBM mainframes.
4077 Old Mac partition format. Modern Macs use C<gpt>.
4081 NEC PC-98 format, common in Japan apparently.
4089 ("part_add", (RErr, [Device "device"; String "prlogex"; Int64 "startsect"; Int64 "endsect"]), 209, [],
4090 [InitEmpty, Always, TestRun (
4091 [["part_init"; "/dev/sda"; "mbr"];
4092 ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]]);
4093 InitEmpty, Always, TestRun (
4094 [["part_init"; "/dev/sda"; "gpt"];
4095 ["part_add"; "/dev/sda"; "primary"; "34"; "127"];
4096 ["part_add"; "/dev/sda"; "primary"; "128"; "-34"]]);
4097 InitEmpty, Always, TestRun (
4098 [["part_init"; "/dev/sda"; "mbr"];
4099 ["part_add"; "/dev/sda"; "primary"; "32"; "127"];
4100 ["part_add"; "/dev/sda"; "primary"; "128"; "255"];
4101 ["part_add"; "/dev/sda"; "primary"; "256"; "511"];
4102 ["part_add"; "/dev/sda"; "primary"; "512"; "-1"]])],
4103 "add a partition to the device",
4105 This command adds a partition to C<device>. If there is no partition
4106 table on the device, call C<guestfs_part_init> first.
4108 The C<prlogex> parameter is the type of partition. Normally you
4109 should pass C<p> or C<primary> here, but MBR partition tables also
4110 support C<l> (or C<logical>) and C<e> (or C<extended>) partition
4113 C<startsect> and C<endsect> are the start and end of the partition
4114 in I<sectors>. C<endsect> may be negative, which means it counts
4115 backwards from the end of the disk (C<-1> is the last sector).
4117 Creating a partition which covers the whole disk is not so easy.
4118 Use C<guestfs_part_disk> to do that.");
4120 ("part_disk", (RErr, [Device "device"; String "parttype"]), 210, [DangerWillRobinson],
4121 [InitEmpty, Always, TestRun (
4122 [["part_disk"; "/dev/sda"; "mbr"]]);
4123 InitEmpty, Always, TestRun (
4124 [["part_disk"; "/dev/sda"; "gpt"]])],
4125 "partition whole disk with a single primary partition",
4127 This command is simply a combination of C<guestfs_part_init>
4128 followed by C<guestfs_part_add> to create a single primary partition
4129 covering the whole disk.
4131 C<parttype> is the partition table type, usually C<mbr> or C<gpt>,
4132 but other possible values are described in C<guestfs_part_init>.");
4134 ("part_set_bootable", (RErr, [Device "device"; Int "partnum"; Bool "bootable"]), 211, [],
4135 [InitEmpty, Always, TestRun (
4136 [["part_disk"; "/dev/sda"; "mbr"];
4137 ["part_set_bootable"; "/dev/sda"; "1"; "true"]])],
4138 "make a partition bootable",
4140 This sets the bootable flag on partition numbered C<partnum> on
4141 device C<device>. Note that partitions are numbered from 1.
4143 The bootable flag is used by some operating systems (notably
4144 Windows) to determine which partition to boot from. It is by
4145 no means universally recognized.");
4147 ("part_set_name", (RErr, [Device "device"; Int "partnum"; String "name"]), 212, [],
4148 [InitEmpty, Always, TestRun (
4149 [["part_disk"; "/dev/sda"; "gpt"];
4150 ["part_set_name"; "/dev/sda"; "1"; "thepartname"]])],
4151 "set partition name",
4153 This sets the partition name on partition numbered C<partnum> on
4154 device C<device>. Note that partitions are numbered from 1.
4156 The partition name can only be set on certain types of partition
4157 table. This works on C<gpt> but not on C<mbr> partitions.");
4159 ("part_list", (RStructList ("partitions", "partition"), [Device "device"]), 213, [],
4160 [], (* XXX Add a regression test for this. *)
4161 "list partitions on a device",
4163 This command parses the partition table on C<device> and
4164 returns the list of partitions found.
4166 The fields in the returned structure are:
4172 Partition number, counting from 1.
4176 Start of the partition I<in bytes>. To get sectors you have to
4177 divide by the device's sector size, see C<guestfs_blockdev_getss>.
4181 End of the partition in bytes.
4185 Size of the partition in bytes.
4189 ("part_get_parttype", (RString "parttype", [Device "device"]), 214, [],
4190 [InitEmpty, Always, TestOutput (
4191 [["part_disk"; "/dev/sda"; "gpt"];
4192 ["part_get_parttype"; "/dev/sda"]], "gpt")],
4193 "get the partition table type",
4195 This command examines the partition table on C<device> and
4196 returns the partition table type (format) being used.
4198 Common return values include: C<msdos> (a DOS/Windows style MBR
4199 partition table), C<gpt> (a GPT/EFI-style partition table). Other
4200 values are possible, although unusual. See C<guestfs_part_init>
4203 ("fill", (RErr, [Int "c"; Int "len"; Pathname "path"]), 215, [],
4204 [InitBasicFS, Always, TestOutputBuffer (
4205 [["fill"; "0x63"; "10"; "/test"];
4206 ["read_file"; "/test"]], "cccccccccc")],
4207 "fill a file with octets",
4209 This command creates a new file called C<path>. The initial
4210 content of the file is C<len> octets of C<c>, where C<c>
4211 must be a number in the range C<[0..255]>.
4213 To fill a file with zero bytes (sparsely), it is
4214 much more efficient to use C<guestfs_truncate_size>.");
4216 ("available", (RErr, [StringList "groups"]), 216, [],
4217 [InitNone, Always, TestRun [["available"; ""]]],
4218 "test availability of some parts of the API",
4220 This command is used to check the availability of some
4221 groups of functionality in the appliance, which not all builds of
4222 the libguestfs appliance will be able to provide.
4224 The libguestfs groups, and the functions that those
4225 groups correspond to, are listed in L<guestfs(3)/AVAILABILITY>.
4227 The argument C<groups> is a list of group names, eg:
4228 C<[\"inotify\", \"augeas\"]> would check for the availability of
4229 the Linux inotify functions and Augeas (configuration file
4232 The command returns no error if I<all> requested groups are available.
4234 It fails with an error if one or more of the requested
4235 groups is unavailable in the appliance.
4237 If an unknown group name is included in the
4238 list of groups then an error is always returned.
4246 You must call C<guestfs_launch> before calling this function.
4248 The reason is because we don't know what groups are
4249 supported by the appliance/daemon until it is running and can
4254 If a group of functions is available, this does not necessarily
4255 mean that they will work. You still have to check for errors
4256 when calling individual API functions even if they are
4261 It is usually the job of distro packagers to build
4262 complete functionality into the libguestfs appliance.
4263 Upstream libguestfs, if built from source with all
4264 requirements satisfied, will support everything.
4268 This call was added in version C<1.0.80>. In previous
4269 versions of libguestfs all you could do would be to speculatively
4270 execute a command to find out if the daemon implemented it.
4271 See also C<guestfs_version>.
4275 ("dd", (RErr, [Dev_or_Path "src"; Dev_or_Path "dest"]), 217, [],
4276 [InitBasicFS, Always, TestOutputBuffer (
4277 [["write_file"; "/src"; "hello, world"; "0"];
4278 ["dd"; "/src"; "/dest"];
4279 ["read_file"; "/dest"]], "hello, world")],
4280 "copy from source to destination using dd",
4282 This command copies from one source device or file C<src>
4283 to another destination device or file C<dest>. Normally you
4284 would use this to copy to or from a device or partition, for
4285 example to duplicate a filesystem.
4287 If the destination is a device, it must be as large or larger
4288 than the source file or device, otherwise the copy will fail.
4289 This command cannot do partial copies (see C<guestfs_copy_size>).");
4291 ("filesize", (RInt64 "size", [Pathname "file"]), 218, [],
4292 [InitBasicFS, Always, TestOutputInt (
4293 [["write_file"; "/file"; "hello, world"; "0"];
4294 ["filesize"; "/file"]], 12)],
4295 "return the size of the file in bytes",
4297 This command returns the size of C<file> in bytes.
4299 To get other stats about a file, use C<guestfs_stat>, C<guestfs_lstat>,
4300 C<guestfs_is_dir>, C<guestfs_is_file> etc.
4301 To get the size of block devices, use C<guestfs_blockdev_getsize64>.");
4303 ("lvrename", (RErr, [String "logvol"; String "newlogvol"]), 219, [],
4304 [InitBasicFSonLVM, Always, TestOutputList (
4305 [["lvrename"; "/dev/VG/LV"; "/dev/VG/LV2"];
4306 ["lvs"]], ["/dev/VG/LV2"])],
4307 "rename an LVM logical volume",
4309 Rename a logical volume C<logvol> with the new name C<newlogvol>.");
4311 ("vgrename", (RErr, [String "volgroup"; String "newvolgroup"]), 220, [],
4312 [InitBasicFSonLVM, Always, TestOutputList (
4314 ["vg_activate"; "false"; "VG"];
4315 ["vgrename"; "VG"; "VG2"];
4316 ["vg_activate"; "true"; "VG2"];
4317 ["mount_options"; ""; "/dev/VG2/LV"; "/"];
4318 ["vgs"]], ["VG2"])],
4319 "rename an LVM volume group",
4321 Rename a volume group C<volgroup> with the new name C<newvolgroup>.");
4323 ("initrd_cat", (RBufferOut "content", [Pathname "initrdpath"; String "filename"]), 221, [ProtocolLimitWarning],
4324 [InitISOFS, Always, TestOutputBuffer (
4325 [["initrd_cat"; "/initrd"; "known-4"]], "abc\ndef\nghi")],
4326 "list the contents of a single file in an initrd",
4328 This command unpacks the file C<filename> from the initrd file
4329 called C<initrdpath>. The filename must be given I<without> the
4330 initial C</> character.
4332 For example, in guestfish you could use the following command
4333 to examine the boot script (usually called C</init>)
4334 contained in a Linux initrd or initramfs image:
4336 initrd-cat /boot/initrd-<version>.img init
4338 See also C<guestfs_initrd_list>.");
4340 ("pvuuid", (RString "uuid", [Device "device"]), 222, [],
4342 "get the UUID of a physical volume",
4344 This command returns the UUID of the LVM PV C<device>.");
4346 ("vguuid", (RString "uuid", [String "vgname"]), 223, [],
4348 "get the UUID of a volume group",
4350 This command returns the UUID of the LVM VG named C<vgname>.");
4352 ("lvuuid", (RString "uuid", [Device "device"]), 224, [],
4354 "get the UUID of a logical volume",
4356 This command returns the UUID of the LVM LV C<device>.");
4358 ("vgpvuuids", (RStringList "uuids", [String "vgname"]), 225, [],
4360 "get the PV UUIDs containing the volume group",
4362 Given a VG called C<vgname>, this returns the UUIDs of all
4363 the physical volumes that this volume group resides on.
4365 You can use this along with C<guestfs_pvs> and C<guestfs_pvuuid>
4366 calls to associate physical volumes and volume groups.
4368 See also C<guestfs_vglvuuids>.");
4370 ("vglvuuids", (RStringList "uuids", [String "vgname"]), 226, [],
4372 "get the LV UUIDs of all LVs in the volume group",
4374 Given a VG called C<vgname>, this returns the UUIDs of all
4375 the logical volumes created in this volume group.
4377 You can use this along with C<guestfs_lvs> and C<guestfs_lvuuid>
4378 calls to associate logical volumes and volume groups.
4380 See also C<guestfs_vgpvuuids>.");
4382 ("copy_size", (RErr, [Dev_or_Path "src"; Dev_or_Path "dest"; Int64 "size"]), 227, [],
4383 [InitBasicFS, Always, TestOutputBuffer (
4384 [["write_file"; "/src"; "hello, world"; "0"];
4385 ["copy_size"; "/src"; "/dest"; "5"];
4386 ["read_file"; "/dest"]], "hello")],
4387 "copy size bytes from source to destination using dd",
4389 This command copies exactly C<size> bytes from one source device
4390 or file C<src> to another destination device or file C<dest>.
4392 Note this will fail if the source is too short or if the destination
4393 is not large enough.");
4395 ("zero_device", (RErr, [Device "device"]), 228, [DangerWillRobinson],
4396 [InitBasicFSonLVM, Always, TestRun (
4397 [["zero_device"; "/dev/VG/LV"]])],
4398 "write zeroes to an entire device",
4400 This command writes zeroes over the entire C<device>. Compare
4401 with C<guestfs_zero> which just zeroes the first few blocks of
4404 ("txz_in", (RErr, [FileIn "tarball"; Pathname "directory"]), 229, [],
4405 [InitBasicFS, Always, TestOutput (
4406 [["txz_in"; "../images/helloworld.tar.xz"; "/"];
4407 ["cat"; "/hello"]], "hello\n")],
4408 "unpack compressed tarball to directory",
4410 This command uploads and unpacks local file C<tarball> (an
4411 I<xz compressed> tar file) into C<directory>.");
4413 ("txz_out", (RErr, [Pathname "directory"; FileOut "tarball"]), 230, [],
4415 "pack directory into compressed tarball",
4417 This command packs the contents of C<directory> and downloads
4418 it to local file C<tarball> (as an xz compressed tar archive).");
4420 ("ntfsresize", (RErr, [Device "device"]), 231, [Optional "ntfsprogs"],
4422 "resize an NTFS filesystem",
4424 This command resizes an NTFS filesystem, expanding or
4425 shrinking it to the size of the underlying device.
4426 See also L<ntfsresize(8)>.");
4428 ("vgscan", (RErr, []), 232, [],
4429 [InitEmpty, Always, TestRun (
4431 "rescan for LVM physical volumes, volume groups and logical volumes",
4433 This rescans all block devices and rebuilds the list of LVM
4434 physical volumes, volume groups and logical volumes.");
4436 ("part_del", (RErr, [Device "device"; Int "partnum"]), 233, [],
4437 [InitEmpty, Always, TestRun (
4438 [["part_init"; "/dev/sda"; "mbr"];
4439 ["part_add"; "/dev/sda"; "primary"; "1"; "-1"];
4440 ["part_del"; "/dev/sda"; "1"]])],
4441 "delete a partition",
4443 This command deletes the partition numbered C<partnum> on C<device>.
4445 Note that in the case of MBR partitioning, deleting an
4446 extended partition also deletes any logical partitions
4449 ("part_get_bootable", (RBool "bootable", [Device "device"; Int "partnum"]), 234, [],
4450 [InitEmpty, Always, TestOutputTrue (
4451 [["part_init"; "/dev/sda"; "mbr"];
4452 ["part_add"; "/dev/sda"; "primary"; "1"; "-1"];
4453 ["part_set_bootable"; "/dev/sda"; "1"; "true"];
4454 ["part_get_bootable"; "/dev/sda"; "1"]])],
4455 "return true if a partition is bootable",
4457 This command returns true if the partition C<partnum> on
4458 C<device> has the bootable flag set.
4460 See also C<guestfs_part_set_bootable>.");
4462 ("part_get_mbr_id", (RInt "idbyte", [Device "device"; Int "partnum"]), 235, [FishOutput FishOutputHexadecimal],
4463 [InitEmpty, Always, TestOutputInt (
4464 [["part_init"; "/dev/sda"; "mbr"];
4465 ["part_add"; "/dev/sda"; "primary"; "1"; "-1"];
4466 ["part_set_mbr_id"; "/dev/sda"; "1"; "0x7f"];
4467 ["part_get_mbr_id"; "/dev/sda"; "1"]], 0x7f)],
4468 "get the MBR type byte (ID byte) from a partition",
4470 Returns the MBR type byte (also known as the ID byte) from
4471 the numbered partition C<partnum>.
4473 Note that only MBR (old DOS-style) partitions have type bytes.
4474 You will get undefined results for other partition table
4475 types (see C<guestfs_part_get_parttype>).");
4477 ("part_set_mbr_id", (RErr, [Device "device"; Int "partnum"; Int "idbyte"]), 236, [],
4478 [], (* tested by part_get_mbr_id *)
4479 "set the MBR type byte (ID byte) of a partition",
4481 Sets the MBR type byte (also known as the ID byte) of
4482 the numbered partition C<partnum> to C<idbyte>. Note
4483 that the type bytes quoted in most documentation are
4484 in fact hexadecimal numbers, but usually documented
4485 without any leading \"0x\" which might be confusing.
4487 Note that only MBR (old DOS-style) partitions have type bytes.
4488 You will get undefined results for other partition table
4489 types (see C<guestfs_part_get_parttype>).");
4491 ("checksum_device", (RString "checksum", [String "csumtype"; Device "device"]), 237, [],
4492 [InitISOFS, Always, TestOutput (
4493 [["checksum_device"; "md5"; "/dev/sdd"]],
4494 (Digest.to_hex (Digest.file "images/test.iso")))],
4495 "compute MD5, SHAx or CRC checksum of the contents of a device",
4497 This call computes the MD5, SHAx or CRC checksum of the
4498 contents of the device named C<device>. For the types of
4499 checksums supported see the C<guestfs_checksum> command.");
4501 ("lvresize_free", (RErr, [Device "lv"; Int "percent"]), 238, [Optional "lvm2"],
4502 [InitNone, Always, TestRun (
4503 [["part_disk"; "/dev/sda"; "mbr"];
4504 ["pvcreate"; "/dev/sda1"];
4505 ["vgcreate"; "VG"; "/dev/sda1"];
4506 ["lvcreate"; "LV"; "VG"; "10"];
4507 ["lvresize_free"; "/dev/VG/LV"; "100"]])],
4508 "expand an LV to fill free space",
4510 This expands an existing logical volume C<lv> so that it fills
4511 C<pc>% of the remaining free space in the volume group. Commonly
4512 you would call this with pc = 100 which expands the logical volume
4513 as much as possible, using all remaining free space in the volume
4516 ("aug_clear", (RErr, [String "augpath"]), 239, [Optional "augeas"],
4517 [], (* XXX Augeas code needs tests. *)
4518 "clear Augeas path",
4520 Set the value associated with C<path> to C<NULL>. This
4521 is the same as the L<augtool(1)> C<clear> command.");
4523 ("get_umask", (RInt "mask", []), 240, [FishOutput FishOutputOctal],
4524 [InitEmpty, Always, TestOutputInt (
4525 [["get_umask"]], 0o22)],
4526 "get the current umask",
4528 Return the current umask. By default the umask is C<022>
4529 unless it has been set by calling C<guestfs_umask>.");
4531 ("debug_upload", (RErr, [FileIn "filename"; String "tmpname"; Int "mode"]), 241, [],
4533 "upload a file to the appliance (internal use only)",
4535 The C<guestfs_debug_upload> command uploads a file to
4536 the libguestfs appliance.
4538 There is no comprehensive help for this command. You have
4539 to look at the file C<daemon/debug.c> in the libguestfs source
4540 to find out what it is for.");
4542 ("base64_in", (RErr, [FileIn "base64file"; Pathname "filename"]), 242, [],
4543 [InitBasicFS, Always, TestOutput (
4544 [["base64_in"; "../images/hello.b64"; "/hello"];
4545 ["cat"; "/hello"]], "hello\n")],
4546 "upload base64-encoded data to file",
4548 This command uploads base64-encoded data from C<base64file>
4551 ("base64_out", (RErr, [Pathname "filename"; FileOut "base64file"]), 243, [],
4553 "download file and encode as base64",
4555 This command downloads the contents of C<filename>, writing
4556 it out to local file C<base64file> encoded as base64.");
4558 ("checksums_out", (RErr, [String "csumtype"; Pathname "directory"; FileOut "sumsfile"]), 244, [],
4560 "compute MD5, SHAx or CRC checksum of files in a directory",
4562 This command computes the checksums of all regular files in
4563 C<directory> and then emits a list of those checksums to
4564 the local output file C<sumsfile>.
4566 This can be used for verifying the integrity of a virtual
4567 machine. However to be properly secure you should pay
4568 attention to the output of the checksum command (it uses
4569 the ones from GNU coreutils). In particular when the
4570 filename is not printable, coreutils uses a special
4571 backslash syntax. For more information, see the GNU
4572 coreutils info file.");
4576 let all_functions = non_daemon_functions @ daemon_functions
4578 (* In some places we want the functions to be displayed sorted
4579 * alphabetically, so this is useful:
4581 let all_functions_sorted =
4582 List.sort (fun (n1,_,_,_,_,_,_) (n2,_,_,_,_,_,_) ->
4583 compare n1 n2) all_functions
4585 (* Field types for structures. *)
4587 | FChar (* C 'char' (really, a 7 bit byte). *)
4588 | FString (* nul-terminated ASCII string, NOT NULL. *)
4589 | FBuffer (* opaque buffer of bytes, (char *, int) pair *)
4594 | FBytes (* Any int measure that counts bytes. *)
4595 | FUUID (* 32 bytes long, NOT nul-terminated. *)
4596 | FOptPercent (* [0..100], or -1 meaning "not present". *)
4598 (* Because we generate extra parsing code for LVM command line tools,
4599 * we have to pull out the LVM columns separately here.
4609 "pv_attr", FString (* XXX *);
4610 "pv_pe_count", FInt64;
4611 "pv_pe_alloc_count", FInt64;
4614 "pv_mda_count", FInt64;
4615 "pv_mda_free", FBytes;
4616 (* Not in Fedora 10:
4617 "pv_mda_size", FBytes;
4624 "vg_attr", FString (* XXX *);
4627 "vg_sysid", FString;
4628 "vg_extent_size", FBytes;
4629 "vg_extent_count", FInt64;
4630 "vg_free_count", FInt64;
4635 "snap_count", FInt64;
4638 "vg_mda_count", FInt64;
4639 "vg_mda_free", FBytes;
4640 (* Not in Fedora 10:
4641 "vg_mda_size", FBytes;
4647 "lv_attr", FString (* XXX *);
4650 "lv_kernel_major", FInt64;
4651 "lv_kernel_minor", FInt64;
4653 "seg_count", FInt64;
4655 "snap_percent", FOptPercent;
4656 "copy_percent", FOptPercent;
4659 "mirror_log", FString;
4663 (* Names and fields in all structures (in RStruct and RStructList)
4667 (* The old RIntBool return type, only ever used for aug_defnode. Do
4668 * not use this struct in any new code.
4671 "i", FInt32; (* for historical compatibility *)
4672 "b", FInt32; (* for historical compatibility *)
4675 (* LVM PVs, VGs, LVs. *)
4676 "lvm_pv", lvm_pv_cols;
4677 "lvm_vg", lvm_vg_cols;
4678 "lvm_lv", lvm_lv_cols;
4680 (* Column names and types from stat structures.
4681 * NB. Can't use things like 'st_atime' because glibc header files
4682 * define some of these as macros. Ugh.
4713 (* Column names in dirent structure. *)
4716 (* 'b' 'c' 'd' 'f' (FIFO) 'l' 'r' (regular file) 's' 'u' '?' *)
4721 (* Version numbers. *)
4729 (* Extended attribute. *)
4731 "attrname", FString;
4735 (* Inotify events. *)
4739 "in_cookie", FUInt32;
4743 (* Partition table entry. *)
4746 "part_start", FBytes;
4748 "part_size", FBytes;
4750 ] (* end of structs *)
4752 (* Ugh, Java has to be different ..
4753 * These names are also used by the Haskell bindings.
4755 let java_structs = [
4756 "int_bool", "IntBool";
4761 "statvfs", "StatVFS";
4763 "version", "Version";
4765 "inotify_event", "INotifyEvent";
4766 "partition", "Partition";
4769 (* What structs are actually returned. *)
4770 type rstructs_used_t = RStructOnly | RStructListOnly | RStructAndList
4772 (* Returns a list of RStruct/RStructList structs that are returned
4773 * by any function. Each element of returned list is a pair:
4775 * (structname, RStructOnly)
4776 * == there exists function which returns RStruct (_, structname)
4777 * (structname, RStructListOnly)
4778 * == there exists function which returns RStructList (_, structname)
4779 * (structname, RStructAndList)
4780 * == there are functions returning both RStruct (_, structname)
4781 * and RStructList (_, structname)
4783 let rstructs_used_by functions =
4784 (* ||| is a "logical OR" for rstructs_used_t *)
4788 | _, RStructAndList -> RStructAndList
4789 | RStructOnly, RStructListOnly
4790 | RStructListOnly, RStructOnly -> RStructAndList
4791 | RStructOnly, RStructOnly -> RStructOnly
4792 | RStructListOnly, RStructListOnly -> RStructListOnly
4795 let h = Hashtbl.create 13 in
4797 (* if elem->oldv exists, update entry using ||| operator,
4798 * else just add elem->newv to the hash
4800 let update elem newv =
4801 try let oldv = Hashtbl.find h elem in
4802 Hashtbl.replace h elem (newv ||| oldv)
4803 with Not_found -> Hashtbl.add h elem newv
4807 fun (_, style, _, _, _, _, _) ->
4808 match fst style with
4809 | RStruct (_, structname) -> update structname RStructOnly
4810 | RStructList (_, structname) -> update structname RStructListOnly
4814 (* return key->values as a list of (key,value) *)
4815 Hashtbl.fold (fun key value xs -> (key, value) :: xs) h []
4817 (* Used for testing language bindings. *)
4819 | CallString of string
4820 | CallOptString of string option
4821 | CallStringList of string list
4823 | CallInt64 of int64
4826 (* Used to memoize the result of pod2text. *)
4827 let pod2text_memo_filename = "src/.pod2text.data"
4828 let pod2text_memo : ((int * string * string), string list) Hashtbl.t =
4830 let chan = open_in pod2text_memo_filename in
4831 let v = input_value chan in
4835 _ -> Hashtbl.create 13
4836 let pod2text_memo_updated () =
4837 let chan = open_out pod2text_memo_filename in
4838 output_value chan pod2text_memo;
4841 (* Useful functions.
4842 * Note we don't want to use any external OCaml libraries which
4843 * makes this a bit harder than it should be.
4845 module StringMap = Map.Make (String)
4847 let failwithf fs = ksprintf failwith fs
4849 let unique = let i = ref 0 in fun () -> incr i; !i
4851 let replace_char s c1 c2 =
4852 let s2 = String.copy s in
4853 let r = ref false in
4854 for i = 0 to String.length s2 - 1 do
4855 if String.unsafe_get s2 i = c1 then (
4856 String.unsafe_set s2 i c2;
4860 if not !r then s else s2
4864 (* || c = '\f' *) || c = '\n' || c = '\r' || c = '\t' (* || c = '\v' *)
4866 let triml ?(test = isspace) str =
4868 let n = ref (String.length str) in
4869 while !n > 0 && test str.[!i]; do
4874 else String.sub str !i !n
4876 let trimr ?(test = isspace) str =
4877 let n = ref (String.length str) in
4878 while !n > 0 && test str.[!n-1]; do
4881 if !n = String.length str then str
4882 else String.sub str 0 !n
4884 let trim ?(test = isspace) str =
4885 trimr ~test (triml ~test str)
4887 let rec find s sub =
4888 let len = String.length s in
4889 let sublen = String.length sub in
4891 if i <= len-sublen then (
4893 if j < sublen then (
4894 if s.[i+j] = sub.[j] then loop2 (j+1)
4900 if r = -1 then loop (i+1) else r
4906 let rec replace_str s s1 s2 =
4907 let len = String.length s in
4908 let sublen = String.length s1 in
4909 let i = find s s1 in
4912 let s' = String.sub s 0 i in
4913 let s'' = String.sub s (i+sublen) (len-i-sublen) in
4914 s' ^ s2 ^ replace_str s'' s1 s2
4917 let rec string_split sep str =
4918 let len = String.length str in
4919 let seplen = String.length sep in
4920 let i = find str sep in
4921 if i = -1 then [str]
4923 let s' = String.sub str 0 i in
4924 let s'' = String.sub str (i+seplen) (len-i-seplen) in
4925 s' :: string_split sep s''
4928 let files_equal n1 n2 =
4929 let cmd = sprintf "cmp -s %s %s" (Filename.quote n1) (Filename.quote n2) in
4930 match Sys.command cmd with
4933 | i -> failwithf "%s: failed with error code %d" cmd i
4935 let rec filter_map f = function
4939 | Some y -> y :: filter_map f xs
4940 | None -> filter_map f xs
4942 let rec find_map f = function
4943 | [] -> raise Not_found
4947 | None -> find_map f xs
4950 let rec loop i = function
4952 | x :: xs -> f i x; loop (i+1) xs
4957 let rec loop i = function
4959 | x :: xs -> let r = f i x in r :: loop (i+1) xs
4963 let count_chars c str =
4964 let count = ref 0 in
4965 for i = 0 to String.length str - 1 do
4966 if c = String.unsafe_get str i then incr count
4970 let name_of_argt = function
4971 | Pathname n | Device n | Dev_or_Path n | String n | OptString n
4972 | StringList n | DeviceList n | Bool n | Int n | Int64 n
4973 | FileIn n | FileOut n -> n
4975 let java_name_of_struct typ =
4976 try List.assoc typ java_structs
4979 "java_name_of_struct: no java_structs entry corresponding to %s" typ
4981 let cols_of_struct typ =
4982 try List.assoc typ structs
4984 failwithf "cols_of_struct: unknown struct %s" typ
4986 let seq_of_test = function
4987 | TestRun s | TestOutput (s, _) | TestOutputList (s, _)
4988 | TestOutputListOfDevices (s, _)
4989 | TestOutputInt (s, _) | TestOutputIntOp (s, _, _)
4990 | TestOutputTrue s | TestOutputFalse s
4991 | TestOutputLength (s, _) | TestOutputBuffer (s, _)
4992 | TestOutputStruct (s, _)
4993 | TestLastFail s -> s
4995 (* Handling for function flags. *)
4996 let protocol_limit_warning =
4997 "Because of the message protocol, there is a transfer limit
4998 of somewhere between 2MB and 4MB. See L<guestfs(3)/PROTOCOL LIMITS>."
5000 let danger_will_robinson =
5001 "B<This command is dangerous. Without careful use you
5002 can easily destroy all your data>."
5004 let deprecation_notice flags =
5007 find_map (function DeprecatedBy str -> Some str | _ -> None) flags in
5009 sprintf "This function is deprecated.
5010 In new code, use the C<%s> call instead.
5012 Deprecated functions will not be removed from the API, but the
5013 fact that they are deprecated indicates that there are problems
5014 with correct use of these functions." alt in
5019 (* Create list of optional groups. *)
5021 let h = Hashtbl.create 13 in
5023 fun (name, _, _, flags, _, _, _) ->
5027 let names = try Hashtbl.find h group with Not_found -> [] in
5028 Hashtbl.replace h group (name :: names)
5032 let groups = Hashtbl.fold (fun k _ ks -> k :: ks) h [] in
5035 fun group -> group, List.sort compare (Hashtbl.find h group)
5037 List.sort (fun x y -> compare (fst x) (fst y)) groups
5039 (* Check function names etc. for consistency. *)
5040 let check_functions () =
5041 let contains_uppercase str =
5042 let len = String.length str in
5044 if i >= len then false
5047 if c >= 'A' && c <= 'Z' then true
5054 (* Check function names. *)
5056 fun (name, _, _, _, _, _, _) ->
5057 if String.length name >= 7 && String.sub name 0 7 = "guestfs" then
5058 failwithf "function name %s does not need 'guestfs' prefix" name;
5060 failwithf "function name is empty";
5061 if name.[0] < 'a' || name.[0] > 'z' then
5062 failwithf "function name %s must start with lowercase a-z" name;
5063 if String.contains name '-' then
5064 failwithf "function name %s should not contain '-', use '_' instead."
5068 (* Check function parameter/return names. *)
5070 fun (name, style, _, _, _, _, _) ->
5071 let check_arg_ret_name n =
5072 if contains_uppercase n then
5073 failwithf "%s param/ret %s should not contain uppercase chars"
5075 if String.contains n '-' || String.contains n '_' then
5076 failwithf "%s param/ret %s should not contain '-' or '_'"
5079 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;
5080 if n = "int" || n = "char" || n = "short" || n = "long" then
5081 failwithf "%s has a param/ret which conflicts with a C type (eg. 'int', 'char' etc.)" name;
5082 if n = "i" || n = "n" then
5083 failwithf "%s has a param/ret called 'i' or 'n', which will cause some conflicts in the generated code" name;
5084 if n = "argv" || n = "args" then
5085 failwithf "%s has a param/ret called 'argv' or 'args', which will cause some conflicts in the generated code" name;
5087 (* List Haskell, OCaml and C keywords here.
5088 * http://www.haskell.org/haskellwiki/Keywords
5089 * http://caml.inria.fr/pub/docs/manual-ocaml/lex.html#operator-char
5090 * http://en.wikipedia.org/wiki/C_syntax#Reserved_keywords
5091 * Formatted via: cat c haskell ocaml|sort -u|grep -vE '_|^val$' \
5092 * |perl -pe 's/(.+)/"$1";/'|fmt -70
5093 * Omitting _-containing words, since they're handled above.
5094 * Omitting the OCaml reserved word, "val", is ok,
5095 * and saves us from renaming several parameters.
5098 "and"; "as"; "asr"; "assert"; "auto"; "begin"; "break"; "case";
5099 "char"; "class"; "const"; "constraint"; "continue"; "data";
5100 "default"; "deriving"; "do"; "done"; "double"; "downto"; "else";
5101 "end"; "enum"; "exception"; "extern"; "external"; "false"; "float";
5102 "for"; "forall"; "foreign"; "fun"; "function"; "functor"; "goto";
5103 "hiding"; "if"; "import"; "in"; "include"; "infix"; "infixl";
5104 "infixr"; "inherit"; "initializer"; "inline"; "instance"; "int";
5106 "land"; "lazy"; "let"; "long"; "lor"; "lsl"; "lsr"; "lxor";
5107 "match"; "mdo"; "method"; "mod"; "module"; "mutable"; "new";
5108 "newtype"; "object"; "of"; "open"; "or"; "private"; "qualified";
5109 "rec"; "register"; "restrict"; "return"; "short"; "sig"; "signed";
5110 "sizeof"; "static"; "struct"; "switch"; "then"; "to"; "true"; "try";
5111 "type"; "typedef"; "union"; "unsigned"; "virtual"; "void";
5112 "volatile"; "when"; "where"; "while";
5114 if List.mem n reserved then
5115 failwithf "%s has param/ret using reserved word %s" name n;
5118 (match fst style with
5120 | RInt n | RInt64 n | RBool n
5121 | RConstString n | RConstOptString n | RString n
5122 | RStringList n | RStruct (n, _) | RStructList (n, _)
5123 | RHashtable n | RBufferOut n ->
5124 check_arg_ret_name n
5126 List.iter (fun arg -> check_arg_ret_name (name_of_argt arg)) (snd style)
5129 (* Check short descriptions. *)
5131 fun (name, _, _, _, _, shortdesc, _) ->
5132 if shortdesc.[0] <> Char.lowercase shortdesc.[0] then
5133 failwithf "short description of %s should begin with lowercase." name;
5134 let c = shortdesc.[String.length shortdesc-1] in
5135 if c = '\n' || c = '.' then
5136 failwithf "short description of %s should not end with . or \\n." name
5139 (* Check long descriptions. *)
5141 fun (name, _, _, _, _, _, longdesc) ->
5142 if longdesc.[String.length longdesc-1] = '\n' then
5143 failwithf "long description of %s should not end with \\n." name
5146 (* Check proc_nrs. *)
5148 fun (name, _, proc_nr, _, _, _, _) ->
5149 if proc_nr <= 0 then
5150 failwithf "daemon function %s should have proc_nr > 0" name
5154 fun (name, _, proc_nr, _, _, _, _) ->
5155 if proc_nr <> -1 then
5156 failwithf "non-daemon function %s should have proc_nr -1" name
5157 ) non_daemon_functions;
5160 List.map (fun (name, _, proc_nr, _, _, _, _) -> name, proc_nr)
5163 List.sort (fun (_,nr1) (_,nr2) -> compare nr1 nr2) proc_nrs in
5164 let rec loop = function
5167 | (name1,nr1) :: ((name2,nr2) :: _ as rest) when nr1 < nr2 ->
5169 | (name1,nr1) :: (name2,nr2) :: _ ->
5170 failwithf "%s and %s have conflicting procedure numbers (%d, %d)"
5178 (* Ignore functions that have no tests. We generate a
5179 * warning when the user does 'make check' instead.
5181 | name, _, _, _, [], _, _ -> ()
5182 | name, _, _, _, tests, _, _ ->
5186 match seq_of_test test with
5188 failwithf "%s has a test containing an empty sequence" name
5189 | cmds -> List.map List.hd cmds
5191 let funcs = List.flatten funcs in
5193 let tested = List.mem name funcs in
5196 failwithf "function %s has tests but does not test itself" name
5199 (* 'pr' prints to the current output file. *)
5200 let chan = ref Pervasives.stdout
5205 let i = count_chars '\n' str in
5206 lines := !lines + i;
5207 output_string !chan str
5210 let copyright_years =
5211 let this_year = 1900 + (localtime (time ())).tm_year in
5212 if this_year > 2009 then sprintf "2009-%04d" this_year else "2009"
5214 (* Generate a header block in a number of standard styles. *)
5215 type comment_style =
5216 CStyle | CPlusPlusStyle | HashStyle | OCamlStyle | HaskellStyle
5217 type license = GPLv2plus | LGPLv2plus
5219 let generate_header ?(extra_inputs = []) comment license =
5220 let inputs = "src/generator.ml" :: extra_inputs in
5221 let c = match comment with
5222 | CStyle -> pr "/* "; " *"
5223 | CPlusPlusStyle -> pr "// "; "//"
5224 | HashStyle -> pr "# "; "#"
5225 | OCamlStyle -> pr "(* "; " *"
5226 | HaskellStyle -> pr "{- "; " " in
5227 pr "libguestfs generated file\n";
5228 pr "%s WARNING: THIS FILE IS GENERATED FROM:\n" c;
5229 List.iter (pr "%s %s\n" c) inputs;
5230 pr "%s ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.\n" c;
5232 pr "%s Copyright (C) %s Red Hat Inc.\n" c copyright_years;
5236 pr "%s This program is free software; you can redistribute it and/or modify\n" c;
5237 pr "%s it under the terms of the GNU General Public License as published by\n" c;
5238 pr "%s the Free Software Foundation; either version 2 of the License, or\n" c;
5239 pr "%s (at your option) any later version.\n" c;
5241 pr "%s This program is distributed in the hope that it will be useful,\n" c;
5242 pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
5243 pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n" c;
5244 pr "%s GNU General Public License for more details.\n" c;
5246 pr "%s You should have received a copy of the GNU General Public License along\n" c;
5247 pr "%s with this program; if not, write to the Free Software Foundation, Inc.,\n" c;
5248 pr "%s 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n" c;
5251 pr "%s This library is free software; you can redistribute it and/or\n" c;
5252 pr "%s modify it under the terms of the GNU Lesser General Public\n" c;
5253 pr "%s License as published by the Free Software Foundation; either\n" c;
5254 pr "%s version 2 of the License, or (at your option) any later version.\n" c;
5256 pr "%s This library is distributed in the hope that it will be useful,\n" c;
5257 pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
5258 pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\n" c;
5259 pr "%s Lesser General Public License for more details.\n" c;
5261 pr "%s You should have received a copy of the GNU Lesser General Public\n" c;
5262 pr "%s License along with this library; if not, write to the Free Software\n" c;
5263 pr "%s Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA\n" c;
5266 | CStyle -> pr " */\n"
5269 | OCamlStyle -> pr " *)\n"
5270 | HaskellStyle -> pr "-}\n"
5274 (* Start of main code generation functions below this line. *)
5276 (* Generate the pod documentation for the C API. *)
5277 let rec generate_actions_pod () =
5279 fun (shortname, style, _, flags, _, _, longdesc) ->
5280 if not (List.mem NotInDocs flags) then (
5281 let name = "guestfs_" ^ shortname in
5282 pr "=head2 %s\n\n" name;
5284 generate_prototype ~extern:false ~handle:"g" name style;
5286 pr "%s\n\n" longdesc;
5287 (match fst style with
5289 pr "This function returns 0 on success or -1 on error.\n\n"
5291 pr "On error this function returns -1.\n\n"
5293 pr "On error this function returns -1.\n\n"
5295 pr "This function returns a C truth value on success or -1 on error.\n\n"
5297 pr "This function returns a string, or NULL on error.
5298 The string is owned by the guest handle and must I<not> be freed.\n\n"
5299 | RConstOptString _ ->
5300 pr "This function returns a string which may be NULL.
5301 There is way to return an error from this function.
5302 The string is owned by the guest handle and must I<not> be freed.\n\n"
5304 pr "This function returns a string, or NULL on error.
5305 I<The caller must free the returned string after use>.\n\n"
5307 pr "This function returns a NULL-terminated array of strings
5308 (like L<environ(3)>), or NULL if there was an error.
5309 I<The caller must free the strings and the array after use>.\n\n"
5310 | RStruct (_, typ) ->
5311 pr "This function returns a C<struct guestfs_%s *>,
5312 or NULL if there was an error.
5313 I<The caller must call C<guestfs_free_%s> after use>.\n\n" typ typ
5314 | RStructList (_, typ) ->
5315 pr "This function returns a C<struct guestfs_%s_list *>
5316 (see E<lt>guestfs-structs.hE<gt>),
5317 or NULL if there was an error.
5318 I<The caller must call C<guestfs_free_%s_list> after use>.\n\n" typ typ
5320 pr "This function returns a NULL-terminated array of
5321 strings, or NULL if there was an error.
5322 The array of strings will always have length C<2n+1>, where
5323 C<n> keys and values alternate, followed by the trailing NULL entry.
5324 I<The caller must free the strings and the array after use>.\n\n"
5326 pr "This function returns a buffer, or NULL on error.
5327 The size of the returned buffer is written to C<*size_r>.
5328 I<The caller must free the returned buffer after use>.\n\n"
5330 if List.mem ProtocolLimitWarning flags then
5331 pr "%s\n\n" protocol_limit_warning;
5332 if List.mem DangerWillRobinson flags then
5333 pr "%s\n\n" danger_will_robinson;
5334 match deprecation_notice flags with
5336 | Some txt -> pr "%s\n\n" txt
5338 ) all_functions_sorted
5340 and generate_structs_pod () =
5341 (* Structs documentation. *)
5344 pr "=head2 guestfs_%s\n" typ;
5346 pr " struct guestfs_%s {\n" typ;
5349 | name, FChar -> pr " char %s;\n" name
5350 | name, FUInt32 -> pr " uint32_t %s;\n" name
5351 | name, FInt32 -> pr " int32_t %s;\n" name
5352 | name, (FUInt64|FBytes) -> pr " uint64_t %s;\n" name
5353 | name, FInt64 -> pr " int64_t %s;\n" name
5354 | name, FString -> pr " char *%s;\n" name
5356 pr " /* The next two fields describe a byte array. */\n";
5357 pr " uint32_t %s_len;\n" name;
5358 pr " char *%s;\n" name
5360 pr " /* The next field is NOT nul-terminated, be careful when printing it: */\n";
5361 pr " char %s[32];\n" name
5362 | name, FOptPercent ->
5363 pr " /* The next field is [0..100] or -1 meaning 'not present': */\n";
5364 pr " float %s;\n" name
5368 pr " struct guestfs_%s_list {\n" typ;
5369 pr " uint32_t len; /* Number of elements in list. */\n";
5370 pr " struct guestfs_%s *val; /* Elements. */\n" typ;
5373 pr " void guestfs_free_%s (struct guestfs_free_%s *);\n" typ typ;
5374 pr " void guestfs_free_%s_list (struct guestfs_free_%s_list *);\n"
5379 and generate_availability_pod () =
5380 (* Availability documentation. *)
5384 fun (group, functions) ->
5385 pr "=item B<%s>\n" group;
5387 pr "The following functions:\n";
5388 List.iter (pr "L</guestfs_%s>\n") functions;
5394 (* Generate the protocol (XDR) file, 'guestfs_protocol.x' and
5395 * indirectly 'guestfs_protocol.h' and 'guestfs_protocol.c'.
5397 * We have to use an underscore instead of a dash because otherwise
5398 * rpcgen generates incorrect code.
5400 * This header is NOT exported to clients, but see also generate_structs_h.
5402 and generate_xdr () =
5403 generate_header CStyle LGPLv2plus;
5405 (* This has to be defined to get around a limitation in Sun's rpcgen. *)
5406 pr "typedef string str<>;\n";
5409 (* Internal structures. *)
5413 pr "struct guestfs_int_%s {\n" typ;
5415 | name, FChar -> pr " char %s;\n" name
5416 | name, FString -> pr " string %s<>;\n" name
5417 | name, FBuffer -> pr " opaque %s<>;\n" name
5418 | name, FUUID -> pr " opaque %s[32];\n" name
5419 | name, (FInt32|FUInt32) -> pr " int %s;\n" name
5420 | name, (FInt64|FUInt64|FBytes) -> pr " hyper %s;\n" name
5421 | name, FOptPercent -> pr " float %s;\n" name
5425 pr "typedef struct guestfs_int_%s guestfs_int_%s_list<>;\n" typ typ;
5430 fun (shortname, style, _, _, _, _, _) ->
5431 let name = "guestfs_" ^ shortname in
5433 (match snd style with
5436 pr "struct %s_args {\n" name;
5439 | Pathname n | Device n | Dev_or_Path n | String n ->
5440 pr " string %s<>;\n" n
5441 | OptString n -> pr " str *%s;\n" n
5442 | StringList n | DeviceList n -> pr " str %s<>;\n" n
5443 | Bool n -> pr " bool %s;\n" n
5444 | Int n -> pr " int %s;\n" n
5445 | Int64 n -> pr " hyper %s;\n" n
5446 | FileIn _ | FileOut _ -> ()
5450 (match fst style with
5453 pr "struct %s_ret {\n" name;
5457 pr "struct %s_ret {\n" name;
5458 pr " hyper %s;\n" n;
5461 pr "struct %s_ret {\n" name;
5464 | RConstString _ | RConstOptString _ ->
5465 failwithf "RConstString|RConstOptString cannot be used by daemon functions"
5467 pr "struct %s_ret {\n" name;
5468 pr " string %s<>;\n" n;
5471 pr "struct %s_ret {\n" name;
5472 pr " str %s<>;\n" n;
5474 | RStruct (n, typ) ->
5475 pr "struct %s_ret {\n" name;
5476 pr " guestfs_int_%s %s;\n" typ n;
5478 | RStructList (n, typ) ->
5479 pr "struct %s_ret {\n" name;
5480 pr " guestfs_int_%s_list %s;\n" typ n;
5483 pr "struct %s_ret {\n" name;
5484 pr " str %s<>;\n" n;
5487 pr "struct %s_ret {\n" name;
5488 pr " opaque %s<>;\n" n;
5493 (* Table of procedure numbers. *)
5494 pr "enum guestfs_procedure {\n";
5496 fun (shortname, _, proc_nr, _, _, _, _) ->
5497 pr " GUESTFS_PROC_%s = %d,\n" (String.uppercase shortname) proc_nr
5499 pr " GUESTFS_PROC_NR_PROCS\n";
5503 (* Having to choose a maximum message size is annoying for several
5504 * reasons (it limits what we can do in the API), but it (a) makes
5505 * the protocol a lot simpler, and (b) provides a bound on the size
5506 * of the daemon which operates in limited memory space.
5508 pr "const GUESTFS_MESSAGE_MAX = %d;\n" (4 * 1024 * 1024);
5511 (* Message header, etc. *)
5513 /* The communication protocol is now documented in the guestfs(3)
5517 const GUESTFS_PROGRAM = 0x2000F5F5;
5518 const GUESTFS_PROTOCOL_VERSION = 1;
5520 /* These constants must be larger than any possible message length. */
5521 const GUESTFS_LAUNCH_FLAG = 0xf5f55ff5;
5522 const GUESTFS_CANCEL_FLAG = 0xffffeeee;
5524 enum guestfs_message_direction {
5525 GUESTFS_DIRECTION_CALL = 0, /* client -> daemon */
5526 GUESTFS_DIRECTION_REPLY = 1 /* daemon -> client */
5529 enum guestfs_message_status {
5530 GUESTFS_STATUS_OK = 0,
5531 GUESTFS_STATUS_ERROR = 1
5534 const GUESTFS_ERROR_LEN = 256;
5536 struct guestfs_message_error {
5537 string error_message<GUESTFS_ERROR_LEN>;
5540 struct guestfs_message_header {
5541 unsigned prog; /* GUESTFS_PROGRAM */
5542 unsigned vers; /* GUESTFS_PROTOCOL_VERSION */
5543 guestfs_procedure proc; /* GUESTFS_PROC_x */
5544 guestfs_message_direction direction;
5545 unsigned serial; /* message serial number */
5546 guestfs_message_status status;
5549 const GUESTFS_MAX_CHUNK_SIZE = 8192;
5551 struct guestfs_chunk {
5552 int cancel; /* if non-zero, transfer is cancelled */
5553 /* data size is 0 bytes if the transfer has finished successfully */
5554 opaque data<GUESTFS_MAX_CHUNK_SIZE>;
5558 (* Generate the guestfs-structs.h file. *)
5559 and generate_structs_h () =
5560 generate_header CStyle LGPLv2plus;
5562 (* This is a public exported header file containing various
5563 * structures. The structures are carefully written to have
5564 * exactly the same in-memory format as the XDR structures that
5565 * we use on the wire to the daemon. The reason for creating
5566 * copies of these structures here is just so we don't have to
5567 * export the whole of guestfs_protocol.h (which includes much
5568 * unrelated and XDR-dependent stuff that we don't want to be
5569 * public, or required by clients).
5571 * To reiterate, we will pass these structures to and from the
5572 * client with a simple assignment or memcpy, so the format
5573 * must be identical to what rpcgen / the RFC defines.
5576 (* Public structures. *)
5579 pr "struct guestfs_%s {\n" typ;
5582 | name, FChar -> pr " char %s;\n" name
5583 | name, FString -> pr " char *%s;\n" name
5585 pr " uint32_t %s_len;\n" name;
5586 pr " char *%s;\n" name
5587 | name, FUUID -> pr " char %s[32]; /* this is NOT nul-terminated, be careful when printing */\n" name
5588 | name, FUInt32 -> pr " uint32_t %s;\n" name
5589 | name, FInt32 -> pr " int32_t %s;\n" name
5590 | name, (FUInt64|FBytes) -> pr " uint64_t %s;\n" name
5591 | name, FInt64 -> pr " int64_t %s;\n" name
5592 | name, FOptPercent -> pr " float %s; /* [0..100] or -1 */\n" name
5596 pr "struct guestfs_%s_list {\n" typ;
5597 pr " uint32_t len;\n";
5598 pr " struct guestfs_%s *val;\n" typ;
5601 pr "extern void guestfs_free_%s (struct guestfs_%s *);\n" typ typ;
5602 pr "extern void guestfs_free_%s_list (struct guestfs_%s_list *);\n" typ typ;
5606 (* Generate the guestfs-actions.h file. *)
5607 and generate_actions_h () =
5608 generate_header CStyle LGPLv2plus;
5610 fun (shortname, style, _, _, _, _, _) ->
5611 let name = "guestfs_" ^ shortname in
5612 generate_prototype ~single_line:true ~newline:true ~handle:"g"
5616 (* Generate the guestfs-internal-actions.h file. *)
5617 and generate_internal_actions_h () =
5618 generate_header CStyle LGPLv2plus;
5620 fun (shortname, style, _, _, _, _, _) ->
5621 let name = "guestfs__" ^ shortname in
5622 generate_prototype ~single_line:true ~newline:true ~handle:"g"
5624 ) non_daemon_functions
5626 (* Generate the client-side dispatch stubs. *)
5627 and generate_client_actions () =
5628 generate_header CStyle LGPLv2plus;
5635 #include <inttypes.h>
5637 #include \"guestfs.h\"
5638 #include \"guestfs-internal.h\"
5639 #include \"guestfs-internal-actions.h\"
5640 #include \"guestfs_protocol.h\"
5642 #define error guestfs_error
5643 //#define perrorf guestfs_perrorf
5644 #define safe_malloc guestfs_safe_malloc
5645 #define safe_realloc guestfs_safe_realloc
5646 //#define safe_strdup guestfs_safe_strdup
5647 #define safe_memdup guestfs_safe_memdup
5649 /* Check the return message from a call for validity. */
5651 check_reply_header (guestfs_h *g,
5652 const struct guestfs_message_header *hdr,
5653 unsigned int proc_nr, unsigned int serial)
5655 if (hdr->prog != GUESTFS_PROGRAM) {
5656 error (g, \"wrong program (%%d/%%d)\", hdr->prog, GUESTFS_PROGRAM);
5659 if (hdr->vers != GUESTFS_PROTOCOL_VERSION) {
5660 error (g, \"wrong protocol version (%%d/%%d)\",
5661 hdr->vers, GUESTFS_PROTOCOL_VERSION);
5664 if (hdr->direction != GUESTFS_DIRECTION_REPLY) {
5665 error (g, \"unexpected message direction (%%d/%%d)\",
5666 hdr->direction, GUESTFS_DIRECTION_REPLY);
5669 if (hdr->proc != proc_nr) {
5670 error (g, \"unexpected procedure number (%%d/%%d)\", hdr->proc, proc_nr);
5673 if (hdr->serial != serial) {
5674 error (g, \"unexpected serial (%%d/%%d)\", hdr->serial, serial);
5681 /* Check we are in the right state to run a high-level action. */
5683 check_state (guestfs_h *g, const char *caller)
5685 if (!guestfs__is_ready (g)) {
5686 if (guestfs__is_config (g) || guestfs__is_launching (g))
5687 error (g, \"%%s: call launch before using this function\\n(in guestfish, don't forget to use the 'run' command)\",
5690 error (g, \"%%s called from the wrong state, %%d != READY\",
5691 caller, guestfs__get_state (g));
5699 (* Generate code to generate guestfish call traces. *)
5700 let trace_call shortname style =
5701 pr " if (guestfs__get_trace (g)) {\n";
5704 List.exists (function
5705 | StringList _ | DeviceList _ -> true
5706 | _ -> false) (snd style) in
5712 pr " printf (\"%s\");\n" shortname;
5715 | String n (* strings *)
5721 (* guestfish doesn't support string escaping, so neither do we *)
5722 pr " printf (\" \\\"%%s\\\"\", %s);\n" n
5723 | OptString n -> (* string option *)
5724 pr " if (%s) printf (\" \\\"%%s\\\"\", %s);\n" n n;
5725 pr " else printf (\" null\");\n"
5727 | DeviceList n -> (* string list *)
5728 pr " putchar (' ');\n";
5729 pr " putchar ('\"');\n";
5730 pr " for (i = 0; %s[i]; ++i) {\n" n;
5731 pr " if (i > 0) putchar (' ');\n";
5732 pr " fputs (%s[i], stdout);\n" n;
5734 pr " putchar ('\"');\n";
5735 | Bool n -> (* boolean *)
5736 pr " fputs (%s ? \" true\" : \" false\", stdout);\n" n
5737 | Int n -> (* int *)
5738 pr " printf (\" %%d\", %s);\n" n
5740 pr " printf (\" %%\" PRIi64, %s);\n" n
5742 pr " putchar ('\\n');\n";
5747 (* For non-daemon functions, generate a wrapper around each function. *)
5749 fun (shortname, style, _, _, _, _, _) ->
5750 let name = "guestfs_" ^ shortname in
5752 generate_prototype ~extern:false ~semicolon:false ~newline:true
5753 ~handle:"g" name style;
5755 trace_call shortname style;
5756 pr " return guestfs__%s " shortname;
5757 generate_c_call_args ~handle:"g" style;
5761 ) non_daemon_functions;
5763 (* Client-side stubs for each function. *)
5765 fun (shortname, style, _, _, _, _, _) ->
5766 let name = "guestfs_" ^ shortname in
5768 (* Generate the action stub. *)
5769 generate_prototype ~extern:false ~semicolon:false ~newline:true
5770 ~handle:"g" name style;
5773 match fst style with
5774 | RErr | RInt _ | RInt64 _ | RBool _ -> "-1"
5775 | RConstString _ | RConstOptString _ ->
5776 failwithf "RConstString|RConstOptString cannot be used by daemon functions"
5777 | RString _ | RStringList _
5778 | RStruct _ | RStructList _
5779 | RHashtable _ | RBufferOut _ ->
5784 (match snd style with
5786 | _ -> pr " struct %s_args args;\n" name
5789 pr " guestfs_message_header hdr;\n";
5790 pr " guestfs_message_error err;\n";
5792 match fst style with
5794 | RConstString _ | RConstOptString _ ->
5795 failwithf "RConstString|RConstOptString cannot be used by daemon functions"
5797 | RBool _ | RString _ | RStringList _
5798 | RStruct _ | RStructList _
5799 | RHashtable _ | RBufferOut _ ->
5800 pr " struct %s_ret ret;\n" name;
5803 pr " int serial;\n";
5806 trace_call shortname style;
5807 pr " if (check_state (g, \"%s\") == -1) return %s;\n"
5808 shortname error_code;
5809 pr " guestfs___set_busy (g);\n";
5812 (* Send the main header and arguments. *)
5813 (match snd style with
5815 pr " serial = guestfs___send (g, GUESTFS_PROC_%s, NULL, NULL);\n"
5816 (String.uppercase shortname)
5820 | Pathname n | Device n | Dev_or_Path n | String n ->
5821 pr " args.%s = (char *) %s;\n" n n
5823 pr " args.%s = %s ? (char **) &%s : NULL;\n" n n n
5824 | StringList n | DeviceList n ->
5825 pr " args.%s.%s_val = (char **) %s;\n" n n n;
5826 pr " for (args.%s.%s_len = 0; %s[args.%s.%s_len]; args.%s.%s_len++) ;\n" n n n n n n n;
5828 pr " args.%s = %s;\n" n n
5830 pr " args.%s = %s;\n" n n
5832 pr " args.%s = %s;\n" n n
5833 | FileIn _ | FileOut _ -> ()
5835 pr " serial = guestfs___send (g, GUESTFS_PROC_%s,\n"
5836 (String.uppercase shortname);
5837 pr " (xdrproc_t) xdr_%s_args, (char *) &args);\n"
5840 pr " if (serial == -1) {\n";
5841 pr " guestfs___end_busy (g);\n";
5842 pr " return %s;\n" error_code;
5846 (* Send any additional files (FileIn) requested. *)
5847 let need_read_reply_label = ref false in
5851 pr " r = guestfs___send_file (g, %s);\n" n;
5852 pr " if (r == -1) {\n";
5853 pr " guestfs___end_busy (g);\n";
5854 pr " return %s;\n" error_code;
5856 pr " if (r == -2) /* daemon cancelled */\n";
5857 pr " goto read_reply;\n";
5858 need_read_reply_label := true;
5863 (* Wait for the reply from the remote end. *)
5864 if !need_read_reply_label then pr " read_reply:\n";
5865 pr " memset (&hdr, 0, sizeof hdr);\n";
5866 pr " memset (&err, 0, sizeof err);\n";
5867 if has_ret then pr " memset (&ret, 0, sizeof ret);\n";
5869 pr " r = guestfs___recv (g, \"%s\", &hdr, &err,\n " shortname;
5873 pr "(xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret" shortname;
5876 pr " if (r == -1) {\n";
5877 pr " guestfs___end_busy (g);\n";
5878 pr " return %s;\n" error_code;
5882 pr " if (check_reply_header (g, &hdr, GUESTFS_PROC_%s, serial) == -1) {\n"
5883 (String.uppercase shortname);
5884 pr " guestfs___end_busy (g);\n";
5885 pr " return %s;\n" error_code;
5889 pr " if (hdr.status == GUESTFS_STATUS_ERROR) {\n";
5890 pr " error (g, \"%%s: %%s\", \"%s\", err.error_message);\n" shortname;
5891 pr " free (err.error_message);\n";
5892 pr " guestfs___end_busy (g);\n";
5893 pr " return %s;\n" error_code;
5897 (* Expecting to receive further files (FileOut)? *)
5901 pr " if (guestfs___recv_file (g, %s) == -1) {\n" n;
5902 pr " guestfs___end_busy (g);\n";
5903 pr " return %s;\n" error_code;
5909 pr " guestfs___end_busy (g);\n";
5911 (match fst style with
5912 | RErr -> pr " return 0;\n"
5913 | RInt n | RInt64 n | RBool n ->
5914 pr " return ret.%s;\n" n
5915 | RConstString _ | RConstOptString _ ->
5916 failwithf "RConstString|RConstOptString cannot be used by daemon functions"
5918 pr " return ret.%s; /* caller will free */\n" n
5919 | RStringList n | RHashtable n ->
5920 pr " /* caller will free this, but we need to add a NULL entry */\n";
5921 pr " ret.%s.%s_val =\n" n n;
5922 pr " safe_realloc (g, ret.%s.%s_val,\n" n n;
5923 pr " sizeof (char *) * (ret.%s.%s_len + 1));\n"
5925 pr " ret.%s.%s_val[ret.%s.%s_len] = NULL;\n" n n n n;
5926 pr " return ret.%s.%s_val;\n" n n
5928 pr " /* caller will free this */\n";
5929 pr " return safe_memdup (g, &ret.%s, sizeof (ret.%s));\n" n n
5930 | RStructList (n, _) ->
5931 pr " /* caller will free this */\n";
5932 pr " return safe_memdup (g, &ret.%s, sizeof (ret.%s));\n" n n
5934 pr " /* RBufferOut is tricky: If the buffer is zero-length, then\n";
5935 pr " * _val might be NULL here. To make the API saner for\n";
5936 pr " * callers, we turn this case into a unique pointer (using\n";
5937 pr " * malloc(1)).\n";
5939 pr " if (ret.%s.%s_len > 0) {\n" n n;
5940 pr " *size_r = ret.%s.%s_len;\n" n n;
5941 pr " return ret.%s.%s_val; /* caller will free */\n" n n;
5943 pr " free (ret.%s.%s_val);\n" n n;
5944 pr " char *p = safe_malloc (g, 1);\n";
5945 pr " *size_r = ret.%s.%s_len;\n" n n;
5953 (* Functions to free structures. *)
5954 pr "/* Structure-freeing functions. These rely on the fact that the\n";
5955 pr " * structure format is identical to the XDR format. See note in\n";
5956 pr " * generator.ml.\n";
5963 pr "guestfs_free_%s (struct guestfs_%s *x)\n" typ typ;
5965 pr " xdr_free ((xdrproc_t) xdr_guestfs_int_%s, (char *) x);\n" typ;
5971 pr "guestfs_free_%s_list (struct guestfs_%s_list *x)\n" typ typ;
5973 pr " xdr_free ((xdrproc_t) xdr_guestfs_int_%s_list, (char *) x);\n" typ;
5980 (* Generate daemon/actions.h. *)
5981 and generate_daemon_actions_h () =
5982 generate_header CStyle GPLv2plus;
5984 pr "#include \"../src/guestfs_protocol.h\"\n";
5988 fun (name, style, _, _, _, _, _) ->
5990 ~single_line:true ~newline:true ~in_daemon:true ~prefix:"do_"
5994 (* Generate the linker script which controls the visibility of
5995 * symbols in the public ABI and ensures no other symbols get
5996 * exported accidentally.
5998 and generate_linker_script () =
5999 generate_header HashStyle GPLv2plus;
6004 "guestfs_get_error_handler";
6005 "guestfs_get_out_of_memory_handler";
6006 "guestfs_last_error";
6007 "guestfs_set_error_handler";
6008 "guestfs_set_launch_done_callback";
6009 "guestfs_set_log_message_callback";
6010 "guestfs_set_out_of_memory_handler";
6011 "guestfs_set_subprocess_quit_callback";
6013 (* Unofficial parts of the API: the bindings code use these
6014 * functions, so it is useful to export them.
6016 "guestfs_safe_calloc";
6017 "guestfs_safe_malloc";
6020 List.map (fun (name, _, _, _, _, _, _) -> "guestfs_" ^ name)
6024 List.map (fun (typ, _) ->
6025 ["guestfs_free_" ^ typ; "guestfs_free_" ^ typ ^ "_list"])
6028 let globals = List.sort compare (globals @ functions @ structs) in
6032 List.iter (pr " %s;\n") globals;
6039 (* Generate the server-side stubs. *)
6040 and generate_daemon_actions () =
6041 generate_header CStyle GPLv2plus;
6043 pr "#include <config.h>\n";
6045 pr "#include <stdio.h>\n";
6046 pr "#include <stdlib.h>\n";
6047 pr "#include <string.h>\n";
6048 pr "#include <inttypes.h>\n";
6049 pr "#include <rpc/types.h>\n";
6050 pr "#include <rpc/xdr.h>\n";
6052 pr "#include \"daemon.h\"\n";
6053 pr "#include \"c-ctype.h\"\n";
6054 pr "#include \"../src/guestfs_protocol.h\"\n";
6055 pr "#include \"actions.h\"\n";
6059 fun (name, style, _, _, _, _, _) ->
6060 (* Generate server-side stubs. *)
6061 pr "static void %s_stub (XDR *xdr_in)\n" name;
6064 match fst style with
6065 | RErr | RInt _ -> pr " int r;\n"; "-1"
6066 | RInt64 _ -> pr " int64_t r;\n"; "-1"
6067 | RBool _ -> pr " int r;\n"; "-1"
6068 | RConstString _ | RConstOptString _ ->
6069 failwithf "RConstString|RConstOptString cannot be used by daemon functions"
6070 | RString _ -> pr " char *r;\n"; "NULL"
6071 | RStringList _ | RHashtable _ -> pr " char **r;\n"; "NULL"
6072 | RStruct (_, typ) -> pr " guestfs_int_%s *r;\n" typ; "NULL"
6073 | RStructList (_, typ) -> pr " guestfs_int_%s_list *r;\n" typ; "NULL"
6075 pr " size_t size = 1;\n";
6079 (match snd style with
6082 pr " struct guestfs_%s_args args;\n" name;
6085 | Device n | Dev_or_Path n
6088 | OptString n -> pr " char *%s;\n" n
6089 | StringList n | DeviceList n -> pr " char **%s;\n" n
6090 | Bool n -> pr " int %s;\n" n
6091 | Int n -> pr " int %s;\n" n
6092 | Int64 n -> pr " int64_t %s;\n" n
6093 | FileIn _ | FileOut _ -> ()
6099 List.exists (function FileIn _ -> true | _ -> false) (snd style) in
6101 (match snd style with
6104 pr " memset (&args, 0, sizeof args);\n";
6106 pr " if (!xdr_guestfs_%s_args (xdr_in, &args)) {\n" name;
6108 pr " cancel_receive ();\n";
6109 pr " reply_with_error (\"daemon failed to decode procedure arguments\");\n";
6113 pr " char *%s = args.%s;\n" n n
6115 let pr_list_handling_code n =
6116 pr " %s = realloc (args.%s.%s_val,\n" n n n;
6117 pr " sizeof (char *) * (args.%s.%s_len+1));\n" n n;
6118 pr " if (%s == NULL) {\n" n;
6120 pr " cancel_receive ();\n";
6121 pr " reply_with_perror (\"realloc\");\n";
6124 pr " %s[args.%s.%s_len] = NULL;\n" n n n;
6125 pr " args.%s.%s_val = %s;\n" n n n;
6131 pr " ABS_PATH (%s, %s, goto done);\n"
6132 n (if is_filein then "cancel_receive ()" else "");
6135 pr " RESOLVE_DEVICE (%s, %s, goto done);\n"
6136 n (if is_filein then "cancel_receive ()" else "");
6139 pr " REQUIRE_ROOT_OR_RESOLVE_DEVICE (%s, %s, goto done);\n"
6140 n (if is_filein then "cancel_receive ()" else "");
6141 | String n -> pr_args n
6142 | OptString n -> pr " %s = args.%s ? *args.%s : NULL;\n" n n n
6144 pr_list_handling_code n;
6146 pr_list_handling_code n;
6147 pr " /* Ensure that each is a device,\n";
6148 pr " * and perform device name translation. */\n";
6149 pr " { int pvi; for (pvi = 0; physvols[pvi] != NULL; ++pvi)\n";
6150 pr " RESOLVE_DEVICE (physvols[pvi], %s, goto done);\n"
6151 (if is_filein then "cancel_receive ()" else "");
6153 | Bool n -> pr " %s = args.%s;\n" n n
6154 | Int n -> pr " %s = args.%s;\n" n n
6155 | Int64 n -> pr " %s = args.%s;\n" n n
6156 | FileIn _ | FileOut _ -> ()
6162 (* this is used at least for do_equal *)
6163 if List.exists (function Pathname _ -> true | _ -> false) (snd style) then (
6164 (* Emit NEED_ROOT just once, even when there are two or
6165 more Pathname args *)
6166 pr " NEED_ROOT (%s, goto done);\n"
6167 (if is_filein then "cancel_receive ()" else "");
6170 (* Don't want to call the impl with any FileIn or FileOut
6171 * parameters, since these go "outside" the RPC protocol.
6174 List.filter (function FileIn _ | FileOut _ -> false | _ -> true)
6176 pr " r = do_%s " name;
6177 generate_c_call_args (fst style, args');
6180 (match fst style with
6181 | RErr | RInt _ | RInt64 _ | RBool _
6182 | RConstString _ | RConstOptString _
6183 | RString _ | RStringList _ | RHashtable _
6184 | RStruct (_, _) | RStructList (_, _) ->
6185 pr " if (r == %s)\n" error_code;
6186 pr " /* do_%s has already called reply_with_error */\n" name;
6190 pr " /* size == 0 && r == NULL could be a non-error case (just\n";
6191 pr " * an ordinary zero-length buffer), so be careful ...\n";
6193 pr " if (size == 1 && r == %s)\n" error_code;
6194 pr " /* do_%s has already called reply_with_error */\n" name;
6199 (* If there are any FileOut parameters, then the impl must
6200 * send its own reply.
6203 List.exists (function FileOut _ -> true | _ -> false) (snd style) in
6205 pr " /* do_%s has already sent a reply */\n" name
6207 match fst style with
6208 | RErr -> pr " reply (NULL, NULL);\n"
6209 | RInt n | RInt64 n | RBool n ->
6210 pr " struct guestfs_%s_ret ret;\n" name;
6211 pr " ret.%s = r;\n" n;
6212 pr " reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
6214 | RConstString _ | RConstOptString _ ->
6215 failwithf "RConstString|RConstOptString cannot be used by daemon functions"
6217 pr " struct guestfs_%s_ret ret;\n" name;
6218 pr " ret.%s = r;\n" n;
6219 pr " reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
6222 | RStringList n | RHashtable n ->
6223 pr " struct guestfs_%s_ret ret;\n" name;
6224 pr " ret.%s.%s_len = count_strings (r);\n" n n;
6225 pr " ret.%s.%s_val = r;\n" n n;
6226 pr " reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
6228 pr " free_strings (r);\n"
6230 pr " struct guestfs_%s_ret ret;\n" name;
6231 pr " ret.%s = *r;\n" n;
6232 pr " reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
6234 pr " xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
6236 | RStructList (n, _) ->
6237 pr " struct guestfs_%s_ret ret;\n" name;
6238 pr " ret.%s = *r;\n" n;
6239 pr " reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
6241 pr " xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
6244 pr " struct guestfs_%s_ret ret;\n" name;
6245 pr " ret.%s.%s_val = r;\n" n n;
6246 pr " ret.%s.%s_len = size;\n" n n;
6247 pr " reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
6252 (* Free the args. *)
6254 (match snd style with
6257 pr " xdr_free ((xdrproc_t) xdr_guestfs_%s_args, (char *) &args);\n"
6264 (* Dispatch function. *)
6265 pr "void dispatch_incoming_message (XDR *xdr_in)\n";
6267 pr " switch (proc_nr) {\n";
6270 fun (name, style, _, _, _, _, _) ->
6271 pr " case GUESTFS_PROC_%s:\n" (String.uppercase name);
6272 pr " %s_stub (xdr_in);\n" name;
6277 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";
6282 (* LVM columns and tokenization functions. *)
6283 (* XXX This generates crap code. We should rethink how we
6289 pr "static const char *lvm_%s_cols = \"%s\";\n"
6290 typ (String.concat "," (List.map fst cols));
6293 pr "static int lvm_tokenize_%s (char *str, guestfs_int_lvm_%s *r)\n" typ typ;
6295 pr " char *tok, *p, *next;\n";
6299 pr " fprintf (stderr, \"%%s: <<%%s>>\\n\", __func__, str);\n";
6302 pr " if (!str) {\n";
6303 pr " fprintf (stderr, \"%%s: failed: passed a NULL string\\n\", __func__);\n";
6306 pr " if (!*str || c_isspace (*str)) {\n";
6307 pr " fprintf (stderr, \"%%s: failed: passed a empty string or one beginning with whitespace\\n\", __func__);\n";
6312 fun (name, coltype) ->
6313 pr " if (!tok) {\n";
6314 pr " fprintf (stderr, \"%%s: failed: string finished early, around token %%s\\n\", __func__, \"%s\");\n" name;
6317 pr " p = strchrnul (tok, ',');\n";
6318 pr " if (*p) next = p+1; else next = NULL;\n";
6319 pr " *p = '\\0';\n";
6322 pr " r->%s = strdup (tok);\n" name;
6323 pr " if (r->%s == NULL) {\n" name;
6324 pr " perror (\"strdup\");\n";
6328 pr " for (i = j = 0; i < 32; ++j) {\n";
6329 pr " if (tok[j] == '\\0') {\n";
6330 pr " fprintf (stderr, \"%%s: failed to parse UUID from '%%s'\\n\", __func__, tok);\n";
6332 pr " } else if (tok[j] != '-')\n";
6333 pr " r->%s[i++] = tok[j];\n" name;
6336 pr " if (sscanf (tok, \"%%\"SCNu64, &r->%s) != 1) {\n" name;
6337 pr " fprintf (stderr, \"%%s: failed to parse size '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
6341 pr " if (sscanf (tok, \"%%\"SCNi64, &r->%s) != 1) {\n" name;
6342 pr " fprintf (stderr, \"%%s: failed to parse int '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
6346 pr " if (tok[0] == '\\0')\n";
6347 pr " r->%s = -1;\n" name;
6348 pr " else if (sscanf (tok, \"%%f\", &r->%s) != 1) {\n" name;
6349 pr " fprintf (stderr, \"%%s: failed to parse float '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
6352 | FBuffer | FInt32 | FUInt32 | FUInt64 | FChar ->
6353 assert false (* can never be an LVM column *)
6355 pr " tok = next;\n";
6358 pr " if (tok != NULL) {\n";
6359 pr " fprintf (stderr, \"%%s: failed: extra tokens at end of string\\n\", __func__);\n";
6366 pr "guestfs_int_lvm_%s_list *\n" typ;
6367 pr "parse_command_line_%ss (void)\n" typ;
6369 pr " char *out, *err;\n";
6370 pr " char *p, *pend;\n";
6372 pr " guestfs_int_lvm_%s_list *ret;\n" typ;
6373 pr " void *newp;\n";
6375 pr " ret = malloc (sizeof *ret);\n";
6376 pr " if (!ret) {\n";
6377 pr " reply_with_perror (\"malloc\");\n";
6378 pr " return NULL;\n";
6381 pr " ret->guestfs_int_lvm_%s_list_len = 0;\n" typ;
6382 pr " ret->guestfs_int_lvm_%s_list_val = NULL;\n" typ;
6384 pr " r = command (&out, &err,\n";
6385 pr " \"lvm\", \"%ss\",\n" typ;
6386 pr " \"-o\", lvm_%s_cols, \"--unbuffered\", \"--noheadings\",\n" typ;
6387 pr " \"--nosuffix\", \"--separator\", \",\", \"--units\", \"b\", NULL);\n";
6388 pr " if (r == -1) {\n";
6389 pr " reply_with_error (\"%%s\", err);\n";
6390 pr " free (out);\n";
6391 pr " free (err);\n";
6392 pr " free (ret);\n";
6393 pr " return NULL;\n";
6396 pr " free (err);\n";
6398 pr " /* Tokenize each line of the output. */\n";
6401 pr " while (p) {\n";
6402 pr " pend = strchr (p, '\\n'); /* Get the next line of output. */\n";
6403 pr " if (pend) {\n";
6404 pr " *pend = '\\0';\n";
6408 pr " while (*p && c_isspace (*p)) /* Skip any leading whitespace. */\n";
6411 pr " if (!*p) { /* Empty line? Skip it. */\n";
6416 pr " /* Allocate some space to store this next entry. */\n";
6417 pr " newp = realloc (ret->guestfs_int_lvm_%s_list_val,\n" typ;
6418 pr " sizeof (guestfs_int_lvm_%s) * (i+1));\n" typ;
6419 pr " if (newp == NULL) {\n";
6420 pr " reply_with_perror (\"realloc\");\n";
6421 pr " free (ret->guestfs_int_lvm_%s_list_val);\n" typ;
6422 pr " free (ret);\n";
6423 pr " free (out);\n";
6424 pr " return NULL;\n";
6426 pr " ret->guestfs_int_lvm_%s_list_val = newp;\n" typ;
6428 pr " /* Tokenize the next entry. */\n";
6429 pr " r = lvm_tokenize_%s (p, &ret->guestfs_int_lvm_%s_list_val[i]);\n" typ typ;
6430 pr " if (r == -1) {\n";
6431 pr " reply_with_error (\"failed to parse output of '%ss' command\");\n" typ;
6432 pr " free (ret->guestfs_int_lvm_%s_list_val);\n" typ;
6433 pr " free (ret);\n";
6434 pr " free (out);\n";
6435 pr " return NULL;\n";
6442 pr " ret->guestfs_int_lvm_%s_list_len = i;\n" typ;
6444 pr " free (out);\n";
6445 pr " return ret;\n";
6448 ) ["pv", lvm_pv_cols; "vg", lvm_vg_cols; "lv", lvm_lv_cols]
6450 (* Generate a list of function names, for debugging in the daemon.. *)
6451 and generate_daemon_names () =
6452 generate_header CStyle GPLv2plus;
6454 pr "#include <config.h>\n";
6456 pr "#include \"daemon.h\"\n";
6459 pr "/* This array is indexed by proc_nr. See guestfs_protocol.x. */\n";
6460 pr "const char *function_names[] = {\n";
6462 fun (name, _, proc_nr, _, _, _, _) -> pr " [%d] = \"%s\",\n" proc_nr name
6466 (* Generate the optional groups for the daemon to implement
6467 * guestfs_available.
6469 and generate_daemon_optgroups_c () =
6470 generate_header CStyle GPLv2plus;
6472 pr "#include <config.h>\n";
6474 pr "#include \"daemon.h\"\n";
6475 pr "#include \"optgroups.h\"\n";
6478 pr "struct optgroup optgroups[] = {\n";
6481 pr " { \"%s\", optgroup_%s_available },\n" group group
6483 pr " { NULL, NULL }\n";
6486 and generate_daemon_optgroups_h () =
6487 generate_header CStyle GPLv2plus;
6491 pr "extern int optgroup_%s_available (void);\n" group
6494 (* Generate the tests. *)
6495 and generate_tests () =
6496 generate_header CStyle GPLv2plus;
6503 #include <sys/types.h>
6506 #include \"guestfs.h\"
6507 #include \"guestfs-internal.h\"
6509 static guestfs_h *g;
6510 static int suppress_error = 0;
6512 static void print_error (guestfs_h *g, void *data, const char *msg)
6514 if (!suppress_error)
6515 fprintf (stderr, \"%%s\\n\", msg);
6518 /* FIXME: nearly identical code appears in fish.c */
6519 static void print_strings (char *const *argv)
6523 for (argc = 0; argv[argc] != NULL; ++argc)
6524 printf (\"\\t%%s\\n\", argv[argc]);
6528 static void print_table (char const *const *argv)
6532 for (i = 0; argv[i] != NULL; i += 2)
6533 printf (\"%%s: %%s\\n\", argv[i], argv[i+1]);
6539 (* Generate a list of commands which are not tested anywhere. *)
6540 pr "static void no_test_warnings (void)\n";
6543 let hash : (string, bool) Hashtbl.t = Hashtbl.create 13 in
6545 fun (_, _, _, _, tests, _, _) ->
6546 let tests = filter_map (
6548 | (_, (Always|If _|Unless _), test) -> Some test
6549 | (_, Disabled, _) -> None
6551 let seq = List.concat (List.map seq_of_test tests) in
6552 let cmds_tested = List.map List.hd seq in
6553 List.iter (fun cmd -> Hashtbl.replace hash cmd true) cmds_tested
6557 fun (name, _, _, _, _, _, _) ->
6558 if not (Hashtbl.mem hash name) then
6559 pr " fprintf (stderr, \"warning: \\\"guestfs_%s\\\" has no tests\\n\");\n" name
6565 (* Generate the actual tests. Note that we generate the tests
6566 * in reverse order, deliberately, so that (in general) the
6567 * newest tests run first. This makes it quicker and easier to
6572 fun (name, _, _, flags, tests, _, _) ->
6573 mapi (generate_one_test name flags) tests
6574 ) (List.rev all_functions) in
6575 let test_names = List.concat test_names in
6576 let nr_tests = List.length test_names in
6579 int main (int argc, char *argv[])
6582 unsigned long int n_failed = 0;
6583 const char *filename;
6585 int nr_tests, test_num = 0;
6587 setbuf (stdout, NULL);
6589 no_test_warnings ();
6591 g = guestfs_create ();
6593 printf (\"guestfs_create FAILED\\n\");
6594 exit (EXIT_FAILURE);
6597 guestfs_set_error_handler (g, print_error, NULL);
6599 guestfs_set_path (g, \"../appliance\");
6601 filename = \"test1.img\";
6602 fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
6605 exit (EXIT_FAILURE);
6607 if (lseek (fd, %d, SEEK_SET) == -1) {
6611 exit (EXIT_FAILURE);
6613 if (write (fd, &c, 1) == -1) {
6617 exit (EXIT_FAILURE);
6619 if (close (fd) == -1) {
6622 exit (EXIT_FAILURE);
6624 if (guestfs_add_drive (g, filename) == -1) {
6625 printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
6626 exit (EXIT_FAILURE);
6629 filename = \"test2.img\";
6630 fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
6633 exit (EXIT_FAILURE);
6635 if (lseek (fd, %d, SEEK_SET) == -1) {
6639 exit (EXIT_FAILURE);
6641 if (write (fd, &c, 1) == -1) {
6645 exit (EXIT_FAILURE);
6647 if (close (fd) == -1) {
6650 exit (EXIT_FAILURE);
6652 if (guestfs_add_drive (g, filename) == -1) {
6653 printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
6654 exit (EXIT_FAILURE);
6657 filename = \"test3.img\";
6658 fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
6661 exit (EXIT_FAILURE);
6663 if (lseek (fd, %d, SEEK_SET) == -1) {
6667 exit (EXIT_FAILURE);
6669 if (write (fd, &c, 1) == -1) {
6673 exit (EXIT_FAILURE);
6675 if (close (fd) == -1) {
6678 exit (EXIT_FAILURE);
6680 if (guestfs_add_drive (g, filename) == -1) {
6681 printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
6682 exit (EXIT_FAILURE);
6685 if (guestfs_add_drive_ro (g, \"../images/test.iso\") == -1) {
6686 printf (\"guestfs_add_drive_ro ../images/test.iso FAILED\\n\");
6687 exit (EXIT_FAILURE);
6690 /* Set a timeout in case qemu hangs during launch (RHBZ#505329). */
6693 if (guestfs_launch (g) == -1) {
6694 printf (\"guestfs_launch FAILED\\n\");
6695 exit (EXIT_FAILURE);
6698 /* Cancel previous alarm. */
6703 " (500 * 1024 * 1024) (50 * 1024 * 1024) (10 * 1024 * 1024) nr_tests;
6707 pr " test_num++;\n";
6708 pr " printf (\"%%3d/%%3d %s\\n\", test_num, nr_tests);\n" test_name;
6709 pr " if (%s () == -1) {\n" test_name;
6710 pr " printf (\"%s FAILED\\n\");\n" test_name;
6711 pr " n_failed++;\n";
6716 pr " guestfs_close (g);\n";
6717 pr " unlink (\"test1.img\");\n";
6718 pr " unlink (\"test2.img\");\n";
6719 pr " unlink (\"test3.img\");\n";
6722 pr " if (n_failed > 0) {\n";
6723 pr " printf (\"***** %%lu / %%d tests FAILED *****\\n\", n_failed, nr_tests);\n";
6724 pr " exit (EXIT_FAILURE);\n";
6728 pr " exit (EXIT_SUCCESS);\n";
6731 and generate_one_test name flags i (init, prereq, test) =
6732 let test_name = sprintf "test_%s_%d" name i in
6735 static int %s_skip (void)
6739 str = getenv (\"TEST_ONLY\");
6741 return strstr (str, \"%s\") == NULL;
6742 str = getenv (\"SKIP_%s\");
6743 if (str && STREQ (str, \"1\")) return 1;
6744 str = getenv (\"SKIP_TEST_%s\");
6745 if (str && STREQ (str, \"1\")) return 1;
6749 " test_name name (String.uppercase test_name) (String.uppercase name);
6752 | Disabled | Always -> ()
6753 | If code | Unless code ->
6754 pr "static int %s_prereq (void)\n" test_name;
6762 static int %s (void)
6765 printf (\" %%s skipped (reason: environment variable set)\\n\", \"%s\");
6769 " test_name test_name test_name;
6771 (* Optional functions should only be tested if the relevant
6772 * support is available in the daemon.
6778 pr " const char *groups[] = { \"%s\", NULL };\n" group;
6780 pr " suppress_error = 1;\n";
6781 pr " r = guestfs_available (g, (char **) groups);\n";
6782 pr " suppress_error = 0;\n";
6783 pr " if (r == -1) {\n";
6784 pr " printf (\" %%s skipped (reason: group %%s not available in daemon)\\n\", \"%s\", groups[0]);\n" test_name;
6793 pr " printf (\" %%s skipped (reason: test disabled in generator)\\n\", \"%s\");\n" test_name
6795 pr " if (! %s_prereq ()) {\n" test_name;
6796 pr " printf (\" %%s skipped (reason: test prerequisite)\\n\", \"%s\");\n" test_name;
6800 generate_one_test_body name i test_name init test;
6802 pr " if (%s_prereq ()) {\n" test_name;
6803 pr " printf (\" %%s skipped (reason: test prerequisite)\\n\", \"%s\");\n" test_name;
6807 generate_one_test_body name i test_name init test;
6809 generate_one_test_body name i test_name init test
6817 and generate_one_test_body name i test_name init test =
6819 | InitNone (* XXX at some point, InitNone and InitEmpty became
6820 * folded together as the same thing. Really we should
6821 * make InitNone do nothing at all, but the tests may
6822 * need to be checked to make sure this is OK.
6825 pr " /* InitNone|InitEmpty for %s */\n" test_name;
6826 List.iter (generate_test_command_call test_name)
6827 [["blockdev_setrw"; "/dev/sda"];
6831 pr " /* InitPartition for %s: create /dev/sda1 */\n" test_name;
6832 List.iter (generate_test_command_call test_name)
6833 [["blockdev_setrw"; "/dev/sda"];
6836 ["part_disk"; "/dev/sda"; "mbr"]]
6838 pr " /* InitBasicFS for %s: create ext2 on /dev/sda1 */\n" test_name;
6839 List.iter (generate_test_command_call test_name)
6840 [["blockdev_setrw"; "/dev/sda"];
6843 ["part_disk"; "/dev/sda"; "mbr"];
6844 ["mkfs"; "ext2"; "/dev/sda1"];
6845 ["mount_options"; ""; "/dev/sda1"; "/"]]
6846 | InitBasicFSonLVM ->
6847 pr " /* InitBasicFSonLVM for %s: create ext2 on /dev/VG/LV */\n"
6849 List.iter (generate_test_command_call test_name)
6850 [["blockdev_setrw"; "/dev/sda"];
6853 ["part_disk"; "/dev/sda"; "mbr"];
6854 ["pvcreate"; "/dev/sda1"];
6855 ["vgcreate"; "VG"; "/dev/sda1"];
6856 ["lvcreate"; "LV"; "VG"; "8"];
6857 ["mkfs"; "ext2"; "/dev/VG/LV"];
6858 ["mount_options"; ""; "/dev/VG/LV"; "/"]]
6860 pr " /* InitISOFS for %s */\n" test_name;
6861 List.iter (generate_test_command_call test_name)
6862 [["blockdev_setrw"; "/dev/sda"];
6865 ["mount_ro"; "/dev/sdd"; "/"]]
6868 let get_seq_last = function
6870 failwithf "%s: you cannot use [] (empty list) when expecting a command"
6873 let seq = List.rev seq in
6874 List.rev (List.tl seq), List.hd seq
6879 pr " /* TestRun for %s (%d) */\n" name i;
6880 List.iter (generate_test_command_call test_name) seq
6881 | TestOutput (seq, expected) ->
6882 pr " /* TestOutput for %s (%d) */\n" name i;
6883 pr " const char *expected = \"%s\";\n" (c_quote expected);
6884 let seq, last = get_seq_last seq in
6886 pr " if (STRNEQ (r, expected)) {\n";
6887 pr " fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r);\n" test_name;
6891 List.iter (generate_test_command_call test_name) seq;
6892 generate_test_command_call ~test test_name last
6893 | TestOutputList (seq, expected) ->
6894 pr " /* TestOutputList for %s (%d) */\n" name i;
6895 let seq, last = get_seq_last seq in
6899 pr " if (!r[%d]) {\n" i;
6900 pr " fprintf (stderr, \"%s: short list returned from command\\n\");\n" test_name;
6901 pr " print_strings (r);\n";
6905 pr " const char *expected = \"%s\";\n" (c_quote str);
6906 pr " if (STRNEQ (r[%d], expected)) {\n" i;
6907 pr " fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r[%d]);\n" test_name i;
6912 pr " if (r[%d] != NULL) {\n" (List.length expected);
6913 pr " fprintf (stderr, \"%s: extra elements returned from command\\n\");\n"
6915 pr " print_strings (r);\n";
6919 List.iter (generate_test_command_call test_name) seq;
6920 generate_test_command_call ~test test_name last
6921 | TestOutputListOfDevices (seq, expected) ->
6922 pr " /* TestOutputListOfDevices for %s (%d) */\n" name i;
6923 let seq, last = get_seq_last seq in
6927 pr " if (!r[%d]) {\n" i;
6928 pr " fprintf (stderr, \"%s: short list returned from command\\n\");\n" test_name;
6929 pr " print_strings (r);\n";
6933 pr " const char *expected = \"%s\";\n" (c_quote str);
6934 pr " r[%d][5] = 's';\n" i;
6935 pr " if (STRNEQ (r[%d], expected)) {\n" i;
6936 pr " fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r[%d]);\n" test_name i;
6941 pr " if (r[%d] != NULL) {\n" (List.length expected);
6942 pr " fprintf (stderr, \"%s: extra elements returned from command\\n\");\n"
6944 pr " print_strings (r);\n";
6948 List.iter (generate_test_command_call test_name) seq;
6949 generate_test_command_call ~test test_name last
6950 | TestOutputInt (seq, expected) ->
6951 pr " /* TestOutputInt for %s (%d) */\n" name i;
6952 let seq, last = get_seq_last seq in
6954 pr " if (r != %d) {\n" expected;
6955 pr " fprintf (stderr, \"%s: expected %d but got %%d\\n\","
6961 List.iter (generate_test_command_call test_name) seq;
6962 generate_test_command_call ~test test_name last
6963 | TestOutputIntOp (seq, op, expected) ->
6964 pr " /* TestOutputIntOp for %s (%d) */\n" name i;
6965 let seq, last = get_seq_last seq in
6967 pr " if (! (r %s %d)) {\n" op expected;
6968 pr " fprintf (stderr, \"%s: expected %s %d but got %%d\\n\","
6969 test_name op expected;
6974 List.iter (generate_test_command_call test_name) seq;
6975 generate_test_command_call ~test test_name last
6976 | TestOutputTrue seq ->
6977 pr " /* TestOutputTrue for %s (%d) */\n" name i;
6978 let seq, last = get_seq_last seq in
6981 pr " fprintf (stderr, \"%s: expected true, got false\\n\");\n"
6986 List.iter (generate_test_command_call test_name) seq;
6987 generate_test_command_call ~test test_name last
6988 | TestOutputFalse seq ->
6989 pr " /* TestOutputFalse for %s (%d) */\n" name i;
6990 let seq, last = get_seq_last seq in
6993 pr " fprintf (stderr, \"%s: expected false, got true\\n\");\n"
6998 List.iter (generate_test_command_call test_name) seq;
6999 generate_test_command_call ~test test_name last
7000 | TestOutputLength (seq, expected) ->
7001 pr " /* TestOutputLength for %s (%d) */\n" name i;
7002 let seq, last = get_seq_last seq in
7005 pr " for (j = 0; j < %d; ++j)\n" expected;
7006 pr " if (r[j] == NULL) {\n";
7007 pr " fprintf (stderr, \"%s: short list returned\\n\");\n"
7009 pr " print_strings (r);\n";
7012 pr " if (r[j] != NULL) {\n";
7013 pr " fprintf (stderr, \"%s: long list returned\\n\");\n"
7015 pr " print_strings (r);\n";
7019 List.iter (generate_test_command_call test_name) seq;
7020 generate_test_command_call ~test test_name last
7021 | TestOutputBuffer (seq, expected) ->
7022 pr " /* TestOutputBuffer for %s (%d) */\n" name i;
7023 pr " const char *expected = \"%s\";\n" (c_quote expected);
7024 let seq, last = get_seq_last seq in
7025 let len = String.length expected in
7027 pr " if (size != %d) {\n" len;
7028 pr " fprintf (stderr, \"%s: returned size of buffer wrong, expected %d but got %%zu\\n\", size);\n" test_name len;
7031 pr " if (STRNEQLEN (r, expected, size)) {\n";
7032 pr " fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r);\n" test_name;
7036 List.iter (generate_test_command_call test_name) seq;
7037 generate_test_command_call ~test test_name last
7038 | TestOutputStruct (seq, checks) ->
7039 pr " /* TestOutputStruct for %s (%d) */\n" name i;
7040 let seq, last = get_seq_last seq in
7044 | CompareWithInt (field, expected) ->
7045 pr " if (r->%s != %d) {\n" field expected;
7046 pr " fprintf (stderr, \"%s: %s was %%d, expected %d\\n\",\n"
7047 test_name field expected;
7048 pr " (int) r->%s);\n" field;
7051 | CompareWithIntOp (field, op, expected) ->
7052 pr " if (!(r->%s %s %d)) {\n" field op expected;
7053 pr " fprintf (stderr, \"%s: %s was %%d, expected %s %d\\n\",\n"
7054 test_name field op expected;
7055 pr " (int) r->%s);\n" field;
7058 | CompareWithString (field, expected) ->
7059 pr " if (STRNEQ (r->%s, \"%s\")) {\n" field expected;
7060 pr " fprintf (stderr, \"%s: %s was \"%%s\", expected \"%s\"\\n\",\n"
7061 test_name field expected;
7062 pr " r->%s);\n" field;
7065 | CompareFieldsIntEq (field1, field2) ->
7066 pr " if (r->%s != r->%s) {\n" field1 field2;
7067 pr " fprintf (stderr, \"%s: %s (%%d) <> %s (%%d)\\n\",\n"
7068 test_name field1 field2;
7069 pr " (int) r->%s, (int) r->%s);\n" field1 field2;
7072 | CompareFieldsStrEq (field1, field2) ->
7073 pr " if (STRNEQ (r->%s, r->%s)) {\n" field1 field2;
7074 pr " fprintf (stderr, \"%s: %s (\"%%s\") <> %s (\"%%s\")\\n\",\n"
7075 test_name field1 field2;
7076 pr " r->%s, r->%s);\n" field1 field2;
7081 List.iter (generate_test_command_call test_name) seq;
7082 generate_test_command_call ~test test_name last
7083 | TestLastFail seq ->
7084 pr " /* TestLastFail for %s (%d) */\n" name i;
7085 let seq, last = get_seq_last seq in
7086 List.iter (generate_test_command_call test_name) seq;
7087 generate_test_command_call test_name ~expect_error:true last
7089 (* Generate the code to run a command, leaving the result in 'r'.
7090 * If you expect to get an error then you should set expect_error:true.
7092 and generate_test_command_call ?(expect_error = false) ?test test_name cmd =
7094 | [] -> assert false
7096 (* Look up the command to find out what args/ret it has. *)
7099 let _, style, _, _, _, _, _ =
7100 List.find (fun (n, _, _, _, _, _, _) -> n = name) all_functions in
7103 failwithf "%s: in test, command %s was not found" test_name name in
7105 if List.length (snd style) <> List.length args then
7106 failwithf "%s: in test, wrong number of args given to %s"
7113 | OptString n, "NULL" -> ()
7116 | Dev_or_Path n, arg
7118 | OptString n, arg ->
7119 pr " const char *%s = \"%s\";\n" n (c_quote arg);
7123 | FileIn _, _ | FileOut _, _ -> ()
7124 | StringList n, "" | DeviceList n, "" ->
7125 pr " const char *const %s[1] = { NULL };\n" n
7126 | StringList n, arg | DeviceList n, arg ->
7127 let strs = string_split " " arg in
7130 pr " const char *%s_%d = \"%s\";\n" n i (c_quote str);
7132 pr " const char *const %s[] = {\n" n;
7134 fun i _ -> pr " %s_%d,\n" n i
7138 ) (List.combine (snd style) args);
7141 match fst style with
7142 | RErr | RInt _ | RBool _ -> pr " int r;\n"; "-1"
7143 | RInt64 _ -> pr " int64_t r;\n"; "-1"
7144 | RConstString _ | RConstOptString _ ->
7145 pr " const char *r;\n"; "NULL"
7146 | RString _ -> pr " char *r;\n"; "NULL"
7147 | RStringList _ | RHashtable _ ->
7151 | RStruct (_, typ) ->
7152 pr " struct guestfs_%s *r;\n" typ; "NULL"
7153 | RStructList (_, typ) ->
7154 pr " struct guestfs_%s_list *r;\n" typ; "NULL"
7157 pr " size_t size;\n";
7160 pr " suppress_error = %d;\n" (if expect_error then 1 else 0);
7161 pr " r = guestfs_%s (g" name;
7163 (* Generate the parameters. *)
7166 | OptString _, "NULL" -> pr ", NULL"
7168 | Device n, _ | Dev_or_Path n, _
7172 | FileIn _, arg | FileOut _, arg ->
7173 pr ", \"%s\"" (c_quote arg)
7174 | StringList n, _ | DeviceList n, _ ->
7175 pr ", (char **) %s" n
7178 try int_of_string arg
7179 with Failure "int_of_string" ->
7180 failwithf "%s: expecting an int, but got '%s'" test_name arg in
7184 try Int64.of_string arg
7185 with Failure "int_of_string" ->
7186 failwithf "%s: expecting an int64, but got '%s'" test_name arg in
7189 let b = bool_of_string arg in pr ", %d" (if b then 1 else 0)
7190 ) (List.combine (snd style) args);
7192 (match fst style with
7193 | RBufferOut _ -> pr ", &size"
7199 if not expect_error then
7200 pr " if (r == %s)\n" error_code
7202 pr " if (r != %s)\n" error_code;
7205 (* Insert the test code. *)
7211 (match fst style with
7212 | RErr | RInt _ | RInt64 _ | RBool _
7213 | RConstString _ | RConstOptString _ -> ()
7214 | RString _ | RBufferOut _ -> pr " free (r);\n"
7215 | RStringList _ | RHashtable _ ->
7216 pr " for (i = 0; r[i] != NULL; ++i)\n";
7217 pr " free (r[i]);\n";
7219 | RStruct (_, typ) ->
7220 pr " guestfs_free_%s (r);\n" typ
7221 | RStructList (_, typ) ->
7222 pr " guestfs_free_%s_list (r);\n" typ
7228 let str = replace_str str "\r" "\\r" in
7229 let str = replace_str str "\n" "\\n" in
7230 let str = replace_str str "\t" "\\t" in
7231 let str = replace_str str "\000" "\\0" in
7234 (* Generate a lot of different functions for guestfish. *)
7235 and generate_fish_cmds () =
7236 generate_header CStyle GPLv2plus;
7240 fun (_, _, _, flags, _, _, _) -> not (List.mem NotInFish flags)
7242 let all_functions_sorted =
7244 fun (_, _, _, flags, _, _, _) -> not (List.mem NotInFish flags)
7245 ) all_functions_sorted in
7247 pr "#include <config.h>\n";
7249 pr "#include <stdio.h>\n";
7250 pr "#include <stdlib.h>\n";
7251 pr "#include <string.h>\n";
7252 pr "#include <inttypes.h>\n";
7254 pr "#include <guestfs.h>\n";
7255 pr "#include \"c-ctype.h\"\n";
7256 pr "#include \"full-write.h\"\n";
7257 pr "#include \"xstrtol.h\"\n";
7258 pr "#include \"fish.h\"\n";
7261 (* list_commands function, which implements guestfish -h *)
7262 pr "void list_commands (void)\n";
7264 pr " printf (\" %%-16s %%s\\n\", _(\"Command\"), _(\"Description\"));\n";
7265 pr " list_builtin_commands ();\n";
7267 fun (name, _, _, flags, _, shortdesc, _) ->
7268 let name = replace_char name '_' '-' in
7269 pr " printf (\"%%-20s %%s\\n\", \"%s\", _(\"%s\"));\n"
7271 ) all_functions_sorted;
7272 pr " printf (\" %%s\\n\",";
7273 pr " _(\"Use -h <cmd> / help <cmd> to show detailed help for a command.\"));\n";
7277 (* display_command function, which implements guestfish -h cmd *)
7278 pr "void display_command (const char *cmd)\n";
7281 fun (name, style, _, flags, _, shortdesc, longdesc) ->
7282 let name2 = replace_char name '_' '-' in
7284 try find_map (function FishAlias n -> Some n | _ -> None) flags
7285 with Not_found -> name in
7286 let longdesc = replace_str longdesc "C<guestfs_" "C<" in
7288 match snd style with
7292 name2 (String.concat " " (List.map name_of_argt args)) in
7295 if List.mem ProtocolLimitWarning flags then
7296 ("\n\n" ^ protocol_limit_warning)
7299 (* For DangerWillRobinson commands, we should probably have
7300 * guestfish prompt before allowing you to use them (especially
7301 * in interactive mode). XXX
7305 if List.mem DangerWillRobinson flags then
7306 ("\n\n" ^ danger_will_robinson)
7311 match deprecation_notice flags with
7313 | Some txt -> "\n\n" ^ txt in
7315 let describe_alias =
7316 if name <> alias then
7317 sprintf "\n\nYou can use '%s' as an alias for this command." alias
7321 pr "STRCASEEQ (cmd, \"%s\")" name;
7322 if name <> name2 then
7323 pr " || STRCASEEQ (cmd, \"%s\")" name2;
7324 if name <> alias then
7325 pr " || STRCASEEQ (cmd, \"%s\")" alias;
7327 pr " pod2text (\"%s\", _(\"%s\"), %S);\n"
7329 ("=head1 SYNOPSIS\n\n " ^ synopsis ^ "\n\n" ^
7330 "=head1 DESCRIPTION\n\n" ^
7331 longdesc ^ warnings ^ describe_alias);
7334 pr " display_builtin_command (cmd);\n";
7338 let emit_print_list_function typ =
7339 pr "static void print_%s_list (struct guestfs_%s_list *%ss)\n"
7342 pr " unsigned int i;\n";
7344 pr " for (i = 0; i < %ss->len; ++i) {\n" typ;
7345 pr " printf (\"[%%d] = {\\n\", i);\n";
7346 pr " print_%s_indent (&%ss->val[i], \" \");\n" typ typ;
7347 pr " printf (\"}\\n\");\n";
7353 (* print_* functions *)
7357 List.exists (function (_, (FUUID|FBuffer)) -> true | _ -> false) cols in
7359 pr "static void print_%s_indent (struct guestfs_%s *%s, const char *indent)\n" typ typ typ;
7362 pr " unsigned int i;\n";
7368 pr " printf (\"%%s%s: %%s\\n\", indent, %s->%s);\n" name typ name
7370 pr " printf (\"%%s%s: \", indent);\n" name;
7371 pr " for (i = 0; i < 32; ++i)\n";
7372 pr " printf (\"%%c\", %s->%s[i]);\n" typ name;
7373 pr " printf (\"\\n\");\n"
7375 pr " printf (\"%%s%s: \", indent);\n" name;
7376 pr " for (i = 0; i < %s->%s_len; ++i)\n" typ name;
7377 pr " if (c_isprint (%s->%s[i]))\n" typ name;
7378 pr " printf (\"%%c\", %s->%s[i]);\n" typ name;
7380 pr " printf (\"\\\\x%%02x\", %s->%s[i]);\n" typ name;
7381 pr " printf (\"\\n\");\n"
7382 | name, (FUInt64|FBytes) ->
7383 pr " printf (\"%%s%s: %%\" PRIu64 \"\\n\", indent, %s->%s);\n"
7386 pr " printf (\"%%s%s: %%\" PRIi64 \"\\n\", indent, %s->%s);\n"
7389 pr " printf (\"%%s%s: %%\" PRIu32 \"\\n\", indent, %s->%s);\n"
7392 pr " printf (\"%%s%s: %%\" PRIi32 \"\\n\", indent, %s->%s);\n"
7395 pr " printf (\"%%s%s: %%c\\n\", indent, %s->%s);\n"
7397 | name, FOptPercent ->
7398 pr " if (%s->%s >= 0) printf (\"%%s%s: %%g %%%%\\n\", indent, %s->%s);\n"
7399 typ name name typ name;
7400 pr " else printf (\"%%s%s: \\n\", indent);\n" name
7406 (* Emit a print_TYPE_list function definition only if that function is used. *)
7409 | typ, (RStructListOnly | RStructAndList) ->
7410 (* generate the function for typ *)
7411 emit_print_list_function typ
7412 | typ, _ -> () (* empty *)
7413 ) (rstructs_used_by all_functions);
7415 (* Emit a print_TYPE function definition only if that function is used. *)
7418 | typ, (RStructOnly | RStructAndList) ->
7419 pr "static void print_%s (struct guestfs_%s *%s)\n" typ typ typ;
7421 pr " print_%s_indent (%s, \"\");\n" typ typ;
7424 | typ, _ -> () (* empty *)
7425 ) (rstructs_used_by all_functions);
7427 (* run_<action> actions *)
7429 fun (name, style, _, flags, _, _, _) ->
7430 pr "static int run_%s (const char *cmd, int argc, char *argv[])\n" name;
7432 (match fst style with
7435 | RBool _ -> pr " int r;\n"
7436 | RInt64 _ -> pr " int64_t r;\n"
7437 | RConstString _ | RConstOptString _ -> pr " const char *r;\n"
7438 | RString _ -> pr " char *r;\n"
7439 | RStringList _ | RHashtable _ -> pr " char **r;\n"
7440 | RStruct (_, typ) -> pr " struct guestfs_%s *r;\n" typ
7441 | RStructList (_, typ) -> pr " struct guestfs_%s_list *r;\n" typ
7444 pr " size_t size;\n";
7450 | OptString n -> pr " const char *%s;\n" n
7454 | FileOut n -> pr " char *%s;\n" n
7455 | StringList n | DeviceList n -> pr " char **%s;\n" n
7456 | Bool n -> pr " int %s;\n" n
7457 | Int n -> pr " int %s;\n" n
7458 | Int64 n -> pr " int64_t %s;\n" n
7461 (* Check and convert parameters. *)
7462 let argc_expected = List.length (snd style) in
7463 pr " if (argc != %d) {\n" argc_expected;
7464 pr " fprintf (stderr, _(\"%%s should have %%d parameter(s)\\n\"), cmd, %d);\n"
7466 pr " fprintf (stderr, _(\"type 'help %%s' for help on %%s\\n\"), cmd, cmd);\n";
7470 let parse_integer fn fntyp rtyp range name i =
7472 pr " strtol_error xerr;\n";
7473 pr " %s r;\n" fntyp;
7475 pr " xerr = %s (argv[%d], NULL, 0, &r, \"\");\n" fn i;
7476 pr " if (xerr != LONGINT_OK) {\n";
7477 pr " fprintf (stderr,\n";
7478 pr " _(\"%%s: %%s: invalid integer parameter (%%s returned %%d)\\n\"),\n";
7479 pr " cmd, \"%s\", \"%s\", xerr);\n" name fn;
7484 | Some (min, max, comment) ->
7485 pr " /* %s */\n" comment;
7486 pr " if (r < %s || r > %s) {\n" min max;
7487 pr " fprintf (stderr, _(\"%%s: %%s: integer out of range\\n\"), cmd, \"%s\");\n"
7491 pr " /* The check above should ensure this assignment does not overflow. */\n";
7493 pr " %s = r;\n" name;
7502 pr " %s = argv[%d];\n" name i
7504 | Dev_or_Path name ->
7505 pr " %s = resolve_win_path (argv[%d]);\n" name i;
7506 pr " if (%s == NULL) return -1;\n" name
7508 pr " %s = STRNEQ (argv[%d], \"\") ? argv[%d] : NULL;\n"
7511 pr " %s = file_in (argv[%d]);\n" name i;
7512 pr " if (%s == NULL) return -1;\n" name
7514 pr " %s = file_out (argv[%d]);\n" name i;
7515 pr " if (%s == NULL) return -1;\n" name
7516 | StringList name | DeviceList name ->
7517 pr " %s = parse_string_list (argv[%d]);\n" name i;
7518 pr " if (%s == NULL) return -1;\n" name;
7520 pr " %s = is_true (argv[%d]) ? 1 : 0;\n" name i
7523 let min = "(-(2LL<<30))"
7524 and max = "((2LL<<30)-1)"
7526 "The Int type in the generator is a signed 31 bit int." in
7527 Some (min, max, comment) in
7528 parse_integer "xstrtoll" "long long" "int" range name i
7530 parse_integer "xstrtoll" "long long" "int64_t" None name i
7533 (* Call C API function. *)
7535 try find_map (function FishAction n -> Some n | _ -> None) flags
7536 with Not_found -> sprintf "guestfs_%s" name in
7538 generate_c_call_args ~handle:"g" style;
7543 | Device name | String name
7544 | OptString name | Bool name
7545 | Int name | Int64 name -> ()
7546 | Pathname name | Dev_or_Path name | FileOut name ->
7547 pr " free (%s);\n" name
7549 pr " free_file_in (%s);\n" name
7550 | StringList name | DeviceList name ->
7551 pr " free_strings (%s);\n" name
7554 (* Any output flags? *)
7556 let flags = filter_map (
7557 function FishOutput flag -> Some flag | _ -> None
7563 failwithf "%s: more than one FishOutput flag is not allowed" name in
7565 (* Check return value for errors and display command results. *)
7566 (match fst style with
7567 | RErr -> pr " return r;\n"
7569 pr " if (r == -1) return -1;\n";
7570 (match fish_output with
7572 pr " printf (\"%%d\\n\", r);\n";
7573 | Some FishOutputOctal ->
7574 pr " printf (\"%%s%%o\\n\", r != 0 ? \"0\" : \"\", r);\n";
7575 | Some FishOutputHexadecimal ->
7576 pr " printf (\"%%s%%x\\n\", r != 0 ? \"0x\" : \"\", r);\n");
7579 pr " if (r == -1) return -1;\n";
7580 (match fish_output with
7582 pr " printf (\"%%\" PRIi64 \"\\n\", r);\n";
7583 | Some FishOutputOctal ->
7584 pr " printf (\"%%s%%\" PRIo64 \"\\n\", r != 0 ? \"0\" : \"\", r);\n";
7585 | Some FishOutputHexadecimal ->
7586 pr " printf (\"%%s%%\" PRIx64 \"\\n\", r != 0 ? \"0x\" : \"\", r);\n");
7589 pr " if (r == -1) return -1;\n";
7590 pr " if (r) printf (\"true\\n\"); else printf (\"false\\n\");\n";
7593 pr " if (r == NULL) return -1;\n";
7594 pr " printf (\"%%s\\n\", r);\n";
7596 | RConstOptString _ ->
7597 pr " printf (\"%%s\\n\", r ? : \"(null)\");\n";
7600 pr " if (r == NULL) return -1;\n";
7601 pr " printf (\"%%s\\n\", r);\n";
7605 pr " if (r == NULL) return -1;\n";
7606 pr " print_strings (r);\n";
7607 pr " free_strings (r);\n";
7609 | RStruct (_, typ) ->
7610 pr " if (r == NULL) return -1;\n";
7611 pr " print_%s (r);\n" typ;
7612 pr " guestfs_free_%s (r);\n" typ;
7614 | RStructList (_, typ) ->
7615 pr " if (r == NULL) return -1;\n";
7616 pr " print_%s_list (r);\n" typ;
7617 pr " guestfs_free_%s_list (r);\n" typ;
7620 pr " if (r == NULL) return -1;\n";
7621 pr " print_table (r);\n";
7622 pr " free_strings (r);\n";
7625 pr " if (r == NULL) return -1;\n";
7626 pr " if (full_write (1, r, size) != size) {\n";
7627 pr " perror (\"write\");\n";
7638 (* run_action function *)
7639 pr "int run_action (const char *cmd, int argc, char *argv[])\n";
7642 fun (name, _, _, flags, _, _, _) ->
7643 let name2 = replace_char name '_' '-' in
7645 try find_map (function FishAlias n -> Some n | _ -> None) flags
7646 with Not_found -> name in
7648 pr "STRCASEEQ (cmd, \"%s\")" name;
7649 if name <> name2 then
7650 pr " || STRCASEEQ (cmd, \"%s\")" name2;
7651 if name <> alias then
7652 pr " || STRCASEEQ (cmd, \"%s\")" alias;
7654 pr " return run_%s (cmd, argc, argv);\n" name;
7658 pr " fprintf (stderr, _(\"%%s: unknown command\\n\"), cmd);\n";
7659 pr " if (command_num == 1)\n";
7660 pr " extended_help_message ();\n";
7667 (* Readline completion for guestfish. *)
7668 and generate_fish_completion () =
7669 generate_header CStyle GPLv2plus;
7673 fun (_, _, _, flags, _, _, _) -> not (List.mem NotInFish flags)
7683 #ifdef HAVE_LIBREADLINE
7684 #include <readline/readline.h>
7689 #ifdef HAVE_LIBREADLINE
7691 static const char *const commands[] = {
7692 BUILTIN_COMMANDS_FOR_COMPLETION,
7695 (* Get the commands, including the aliases. They don't need to be
7696 * sorted - the generator() function just does a dumb linear search.
7700 fun (name, _, _, flags, _, _, _) ->
7701 let name2 = replace_char name '_' '-' in
7703 try find_map (function FishAlias n -> Some n | _ -> None) flags
7704 with Not_found -> name in
7706 if name <> alias then [name2; alias] else [name2]
7708 let commands = List.flatten commands in
7710 List.iter (pr " \"%s\",\n") commands;
7716 generator (const char *text, int state)
7718 static int index, len;
7723 len = strlen (text);
7726 rl_attempted_completion_over = 1;
7728 while ((name = commands[index]) != NULL) {
7730 if (STRCASEEQLEN (name, text, len))
7731 return strdup (name);
7737 #endif /* HAVE_LIBREADLINE */
7739 #ifdef HAVE_RL_COMPLETION_MATCHES
7740 #define RL_COMPLETION_MATCHES rl_completion_matches
7742 #ifdef HAVE_COMPLETION_MATCHES
7743 #define RL_COMPLETION_MATCHES completion_matches
7745 #endif /* else just fail if we don't have either symbol */
7748 do_completion (const char *text, int start, int end)
7750 char **matches = NULL;
7752 #ifdef HAVE_LIBREADLINE
7753 rl_completion_append_character = ' ';
7756 matches = RL_COMPLETION_MATCHES (text, generator);
7757 else if (complete_dest_paths)
7758 matches = RL_COMPLETION_MATCHES (text, complete_dest_paths_generator);
7765 (* Generate the POD documentation for guestfish. *)
7766 and generate_fish_actions_pod () =
7767 let all_functions_sorted =
7769 fun (_, _, _, flags, _, _, _) ->
7770 not (List.mem NotInFish flags || List.mem NotInDocs flags)
7771 ) all_functions_sorted in
7773 let rex = Str.regexp "C<guestfs_\\([^>]+\\)>" in
7776 fun (name, style, _, flags, _, _, longdesc) ->
7778 Str.global_substitute rex (
7781 try Str.matched_group 1 s
7783 failwithf "error substituting C<guestfs_...> in longdesc of function %s" name in
7784 "C<" ^ replace_char sub '_' '-' ^ ">"
7786 let name = replace_char name '_' '-' in
7788 try find_map (function FishAlias n -> Some n | _ -> None) flags
7789 with Not_found -> name in
7791 pr "=head2 %s" name;
7792 if name <> alias then
7799 | Pathname n | Device n | Dev_or_Path n | String n -> pr " %s" n
7800 | OptString n -> pr " %s" n
7801 | StringList n | DeviceList n -> pr " '%s ...'" n
7802 | Bool _ -> pr " true|false"
7803 | Int n -> pr " %s" n
7804 | Int64 n -> pr " %s" n
7805 | FileIn n | FileOut n -> pr " (%s|-)" n
7809 pr "%s\n\n" longdesc;
7811 if List.exists (function FileIn _ | FileOut _ -> true
7812 | _ -> false) (snd style) then
7813 pr "Use C<-> instead of a filename to read/write from stdin/stdout.\n\n";
7815 if List.mem ProtocolLimitWarning flags then
7816 pr "%s\n\n" protocol_limit_warning;
7818 if List.mem DangerWillRobinson flags then
7819 pr "%s\n\n" danger_will_robinson;
7821 match deprecation_notice flags with
7823 | Some txt -> pr "%s\n\n" txt
7824 ) all_functions_sorted
7826 (* Generate a C function prototype. *)
7827 and generate_prototype ?(extern = true) ?(static = false) ?(semicolon = true)
7828 ?(single_line = false) ?(newline = false) ?(in_daemon = false)
7830 ?handle name style =
7831 if extern then pr "extern ";
7832 if static then pr "static ";
7833 (match fst style with
7835 | RInt _ -> pr "int "
7836 | RInt64 _ -> pr "int64_t "
7837 | RBool _ -> pr "int "
7838 | RConstString _ | RConstOptString _ -> pr "const char *"
7839 | RString _ | RBufferOut _ -> pr "char *"
7840 | RStringList _ | RHashtable _ -> pr "char **"
7841 | RStruct (_, typ) ->
7842 if not in_daemon then pr "struct guestfs_%s *" typ
7843 else pr "guestfs_int_%s *" typ
7844 | RStructList (_, typ) ->
7845 if not in_daemon then pr "struct guestfs_%s_list *" typ
7846 else pr "guestfs_int_%s_list *" typ
7848 let is_RBufferOut = match fst style with RBufferOut _ -> true | _ -> false in
7849 pr "%s%s (" prefix name;
7850 if handle = None && List.length (snd style) = 0 && not is_RBufferOut then
7853 let comma = ref false in
7856 | Some handle -> pr "guestfs_h *%s" handle; comma := true
7860 if single_line then pr ", " else pr ",\n\t\t"
7867 | Device n | Dev_or_Path n
7871 pr "const char *%s" n
7872 | StringList n | DeviceList n ->
7874 pr "char *const *%s" n
7875 | Bool n -> next (); pr "int %s" n
7876 | Int n -> next (); pr "int %s" n
7877 | Int64 n -> next (); pr "int64_t %s" n
7880 if not in_daemon then (next (); pr "const char *%s" n)
7882 if is_RBufferOut then (next (); pr "size_t *size_r");
7885 if semicolon then pr ";";
7886 if newline then pr "\n"
7888 (* Generate C call arguments, eg "(handle, foo, bar)" *)
7889 and generate_c_call_args ?handle ?(decl = false) style =
7891 let comma = ref false in
7893 if !comma then pr ", ";
7898 | Some handle -> pr "%s" handle; comma := true
7903 pr "%s" (name_of_argt arg)
7905 (* For RBufferOut calls, add implicit &size parameter. *)
7907 match fst style with
7915 (* Generate the OCaml bindings interface. *)
7916 and generate_ocaml_mli () =
7917 generate_header OCamlStyle LGPLv2plus;
7920 (** For API documentation you should refer to the C API
7921 in the guestfs(3) manual page. The OCaml API uses almost
7922 exactly the same calls. *)
7925 (** A [guestfs_h] handle. *)
7927 exception Error of string
7928 (** This exception is raised when there is an error. *)
7930 exception Handle_closed of string
7931 (** This exception is raised if you use a {!Guestfs.t} handle
7932 after calling {!close} on it. The string is the name of
7935 val create : unit -> t
7936 (** Create a {!Guestfs.t} handle. *)
7938 val close : t -> unit
7939 (** Close the {!Guestfs.t} handle and free up all resources used
7942 Handles are closed by the garbage collector when they become
7943 unreferenced, but callers can call this in order to provide
7944 predictable cleanup. *)
7947 generate_ocaml_structure_decls ();
7951 fun (name, style, _, _, _, shortdesc, _) ->
7952 generate_ocaml_prototype name style;
7953 pr "(** %s *)\n" shortdesc;
7955 ) all_functions_sorted
7957 (* Generate the OCaml bindings implementation. *)
7958 and generate_ocaml_ml () =
7959 generate_header OCamlStyle LGPLv2plus;
7964 exception Error of string
7965 exception Handle_closed of string
7967 external create : unit -> t = \"ocaml_guestfs_create\"
7968 external close : t -> unit = \"ocaml_guestfs_close\"
7970 (* Give the exceptions names, so they can be raised from the C code. *)
7972 Callback.register_exception \"ocaml_guestfs_error\" (Error \"\");
7973 Callback.register_exception \"ocaml_guestfs_closed\" (Handle_closed \"\")
7977 generate_ocaml_structure_decls ();
7981 fun (name, style, _, _, _, shortdesc, _) ->
7982 generate_ocaml_prototype ~is_external:true name style;
7983 ) all_functions_sorted
7985 (* Generate the OCaml bindings C implementation. *)
7986 and generate_ocaml_c () =
7987 generate_header CStyle LGPLv2plus;
7994 #include <caml/config.h>
7995 #include <caml/alloc.h>
7996 #include <caml/callback.h>
7997 #include <caml/fail.h>
7998 #include <caml/memory.h>
7999 #include <caml/mlvalues.h>
8000 #include <caml/signals.h>
8002 #include <guestfs.h>
8004 #include \"guestfs_c.h\"
8006 /* Copy a hashtable of string pairs into an assoc-list. We return
8007 * the list in reverse order, but hashtables aren't supposed to be
8010 static CAMLprim value
8011 copy_table (char * const * argv)
8014 CAMLlocal5 (rv, pairv, kv, vv, cons);
8018 for (i = 0; argv[i] != NULL; i += 2) {
8019 kv = caml_copy_string (argv[i]);
8020 vv = caml_copy_string (argv[i+1]);
8021 pairv = caml_alloc (2, 0);
8022 Store_field (pairv, 0, kv);
8023 Store_field (pairv, 1, vv);
8024 cons = caml_alloc (2, 0);
8025 Store_field (cons, 1, rv);
8027 Store_field (cons, 0, pairv);
8035 (* Struct copy functions. *)
8037 let emit_ocaml_copy_list_function typ =
8038 pr "static CAMLprim value\n";
8039 pr "copy_%s_list (const struct guestfs_%s_list *%ss)\n" typ typ typ;
8041 pr " CAMLparam0 ();\n";
8042 pr " CAMLlocal2 (rv, v);\n";
8043 pr " unsigned int i;\n";
8045 pr " if (%ss->len == 0)\n" typ;
8046 pr " CAMLreturn (Atom (0));\n";
8048 pr " rv = caml_alloc (%ss->len, 0);\n" typ;
8049 pr " for (i = 0; i < %ss->len; ++i) {\n" typ;
8050 pr " v = copy_%s (&%ss->val[i]);\n" typ typ;
8051 pr " caml_modify (&Field (rv, i), v);\n";
8053 pr " CAMLreturn (rv);\n";
8061 let has_optpercent_col =
8062 List.exists (function (_, FOptPercent) -> true | _ -> false) cols in
8064 pr "static CAMLprim value\n";
8065 pr "copy_%s (const struct guestfs_%s *%s)\n" typ typ typ;
8067 pr " CAMLparam0 ();\n";
8068 if has_optpercent_col then
8069 pr " CAMLlocal3 (rv, v, v2);\n"
8071 pr " CAMLlocal2 (rv, v);\n";
8073 pr " rv = caml_alloc (%d, 0);\n" (List.length cols);
8078 pr " v = caml_copy_string (%s->%s);\n" typ name
8080 pr " v = caml_alloc_string (%s->%s_len);\n" typ name;
8081 pr " memcpy (String_val (v), %s->%s, %s->%s_len);\n"
8084 pr " v = caml_alloc_string (32);\n";
8085 pr " memcpy (String_val (v), %s->%s, 32);\n" typ name
8086 | name, (FBytes|FInt64|FUInt64) ->
8087 pr " v = caml_copy_int64 (%s->%s);\n" typ name
8088 | name, (FInt32|FUInt32) ->
8089 pr " v = caml_copy_int32 (%s->%s);\n" typ name
8090 | name, FOptPercent ->
8091 pr " if (%s->%s >= 0) { /* Some %s */\n" typ name name;
8092 pr " v2 = caml_copy_double (%s->%s);\n" typ name;
8093 pr " v = caml_alloc (1, 0);\n";
8094 pr " Store_field (v, 0, v2);\n";
8095 pr " } else /* None */\n";
8096 pr " v = Val_int (0);\n";
8098 pr " v = Val_int (%s->%s);\n" typ name
8100 pr " Store_field (rv, %d, v);\n" i
8102 pr " CAMLreturn (rv);\n";
8107 (* Emit a copy_TYPE_list function definition only if that function is used. *)
8110 | typ, (RStructListOnly | RStructAndList) ->
8111 (* generate the function for typ *)
8112 emit_ocaml_copy_list_function typ
8113 | typ, _ -> () (* empty *)
8114 ) (rstructs_used_by all_functions);
8118 fun (name, style, _, _, _, _, _) ->
8119 pr "/* Automatically generated wrapper for function\n";
8121 generate_ocaml_prototype name style;
8126 "gv" :: List.map (fun arg -> name_of_argt arg ^ "v") (snd style) in
8128 let needs_extra_vs =
8129 match fst style with RConstOptString _ -> true | _ -> false in
8131 pr "/* Emit prototype to appease gcc's -Wmissing-prototypes. */\n";
8132 pr "CAMLprim value ocaml_guestfs_%s (value %s" name (List.hd params);
8133 List.iter (pr ", value %s") (List.tl params); pr ");\n";
8136 pr "CAMLprim value\n";
8137 pr "ocaml_guestfs_%s (value %s" name (List.hd params);
8138 List.iter (pr ", value %s") (List.tl params);
8143 | [p1; p2; p3; p4; p5] ->
8144 pr " CAMLparam5 (%s);\n" (String.concat ", " params)
8145 | p1 :: p2 :: p3 :: p4 :: p5 :: rest ->
8146 pr " CAMLparam5 (%s);\n" (String.concat ", " [p1; p2; p3; p4; p5]);
8147 pr " CAMLxparam%d (%s);\n"
8148 (List.length rest) (String.concat ", " rest)
8150 pr " CAMLparam%d (%s);\n" (List.length ps) (String.concat ", " ps)
8152 if not needs_extra_vs then
8153 pr " CAMLlocal1 (rv);\n"
8155 pr " CAMLlocal3 (rv, v, v2);\n";
8158 pr " guestfs_h *g = Guestfs_val (gv);\n";
8159 pr " if (g == NULL)\n";
8160 pr " ocaml_guestfs_raise_closed (\"%s\");\n" name;
8166 | Device n | Dev_or_Path n
8170 pr " const char *%s = String_val (%sv);\n" n n
8172 pr " const char *%s =\n" n;
8173 pr " %sv != Val_int (0) ? String_val (Field (%sv, 0)) : NULL;\n"
8175 | StringList n | DeviceList n ->
8176 pr " char **%s = ocaml_guestfs_strings_val (g, %sv);\n" n n
8178 pr " int %s = Bool_val (%sv);\n" n n
8180 pr " int %s = Int_val (%sv);\n" n n
8182 pr " int64_t %s = Int64_val (%sv);\n" n n
8185 match fst style with
8186 | RErr -> pr " int r;\n"; "-1"
8187 | RInt _ -> pr " int r;\n"; "-1"
8188 | RInt64 _ -> pr " int64_t r;\n"; "-1"
8189 | RBool _ -> pr " int r;\n"; "-1"
8190 | RConstString _ | RConstOptString _ ->
8191 pr " const char *r;\n"; "NULL"
8192 | RString _ -> pr " char *r;\n"; "NULL"
8197 | RStruct (_, typ) ->
8198 pr " struct guestfs_%s *r;\n" typ; "NULL"
8199 | RStructList (_, typ) ->
8200 pr " struct guestfs_%s_list *r;\n" typ; "NULL"
8207 pr " size_t size;\n";
8211 pr " caml_enter_blocking_section ();\n";
8212 pr " r = guestfs_%s " name;
8213 generate_c_call_args ~handle:"g" style;
8215 pr " caml_leave_blocking_section ();\n";
8219 | StringList n | DeviceList n ->
8220 pr " ocaml_guestfs_free_strings (%s);\n" n;
8221 | Pathname _ | Device _ | Dev_or_Path _ | String _ | OptString _
8222 | Bool _ | Int _ | Int64 _
8223 | FileIn _ | FileOut _ -> ()
8226 pr " if (r == %s)\n" error_code;
8227 pr " ocaml_guestfs_raise_error (g, \"%s\");\n" name;
8230 (match fst style with
8231 | RErr -> pr " rv = Val_unit;\n"
8232 | RInt _ -> pr " rv = Val_int (r);\n"
8234 pr " rv = caml_copy_int64 (r);\n"
8235 | RBool _ -> pr " rv = Val_bool (r);\n"
8237 pr " rv = caml_copy_string (r);\n"
8238 | RConstOptString _ ->
8239 pr " if (r) { /* Some string */\n";
8240 pr " v = caml_alloc (1, 0);\n";
8241 pr " v2 = caml_copy_string (r);\n";
8242 pr " Store_field (v, 0, v2);\n";
8243 pr " } else /* None */\n";
8244 pr " v = Val_int (0);\n";
8246 pr " rv = caml_copy_string (r);\n";
8249 pr " rv = caml_copy_string_array ((const char **) r);\n";
8250 pr " for (i = 0; r[i] != NULL; ++i) free (r[i]);\n";
8252 | RStruct (_, typ) ->
8253 pr " rv = copy_%s (r);\n" typ;
8254 pr " guestfs_free_%s (r);\n" typ;
8255 | RStructList (_, typ) ->
8256 pr " rv = copy_%s_list (r);\n" typ;
8257 pr " guestfs_free_%s_list (r);\n" typ;
8259 pr " rv = copy_table (r);\n";
8260 pr " for (i = 0; r[i] != NULL; ++i) free (r[i]);\n";
8263 pr " rv = caml_alloc_string (size);\n";
8264 pr " memcpy (String_val (rv), r, size);\n";
8267 pr " CAMLreturn (rv);\n";
8271 if List.length params > 5 then (
8272 pr "/* Emit prototype to appease gcc's -Wmissing-prototypes. */\n";
8273 pr "CAMLprim value ";
8274 pr "ocaml_guestfs_%s_byte (value *argv, int argn);\n" name;
8275 pr "CAMLprim value\n";
8276 pr "ocaml_guestfs_%s_byte (value *argv, int argn)\n" name;
8278 pr " return ocaml_guestfs_%s (argv[0]" name;
8279 iteri (fun i _ -> pr ", argv[%d]" i) (List.tl params);
8284 ) all_functions_sorted
8286 and generate_ocaml_structure_decls () =
8289 pr "type %s = {\n" typ;
8292 | name, FString -> pr " %s : string;\n" name
8293 | name, FBuffer -> pr " %s : string;\n" name
8294 | name, FUUID -> pr " %s : string;\n" name
8295 | name, (FBytes|FInt64|FUInt64) -> pr " %s : int64;\n" name
8296 | name, (FInt32|FUInt32) -> pr " %s : int32;\n" name
8297 | name, FChar -> pr " %s : char;\n" name
8298 | name, FOptPercent -> pr " %s : float option;\n" name
8304 and generate_ocaml_prototype ?(is_external = false) name style =
8305 if is_external then pr "external " else pr "val ";
8306 pr "%s : t -> " name;
8309 | Pathname _ | Device _ | Dev_or_Path _ | String _ | FileIn _ | FileOut _ -> pr "string -> "
8310 | OptString _ -> pr "string option -> "
8311 | StringList _ | DeviceList _ -> pr "string array -> "
8312 | Bool _ -> pr "bool -> "
8313 | Int _ -> pr "int -> "
8314 | Int64 _ -> pr "int64 -> "
8316 (match fst style with
8317 | RErr -> pr "unit" (* all errors are turned into exceptions *)
8318 | RInt _ -> pr "int"
8319 | RInt64 _ -> pr "int64"
8320 | RBool _ -> pr "bool"
8321 | RConstString _ -> pr "string"
8322 | RConstOptString _ -> pr "string option"
8323 | RString _ | RBufferOut _ -> pr "string"
8324 | RStringList _ -> pr "string array"
8325 | RStruct (_, typ) -> pr "%s" typ
8326 | RStructList (_, typ) -> pr "%s array" typ
8327 | RHashtable _ -> pr "(string * string) list"
8329 if is_external then (
8331 if List.length (snd style) + 1 > 5 then
8332 pr "\"ocaml_guestfs_%s_byte\" " name;
8333 pr "\"ocaml_guestfs_%s\"" name
8337 (* Generate Perl xs code, a sort of crazy variation of C with macros. *)
8338 and generate_perl_xs () =
8339 generate_header CStyle LGPLv2plus;
8342 #include \"EXTERN.h\"
8346 #include <guestfs.h>
8349 #define PRId64 \"lld\"
8353 my_newSVll(long long val) {
8354 #ifdef USE_64_BIT_ALL
8355 return newSViv(val);
8359 len = snprintf(buf, 100, \"%%\" PRId64, val);
8360 return newSVpv(buf, len);
8365 #define PRIu64 \"llu\"
8369 my_newSVull(unsigned long long val) {
8370 #ifdef USE_64_BIT_ALL
8371 return newSVuv(val);
8375 len = snprintf(buf, 100, \"%%\" PRIu64, val);
8376 return newSVpv(buf, len);
8380 /* http://www.perlmonks.org/?node_id=680842 */
8382 XS_unpack_charPtrPtr (SV *arg) {
8387 if (!arg || !SvOK (arg) || !SvROK (arg) || SvTYPE (SvRV (arg)) != SVt_PVAV)
8388 croak (\"array reference expected\");
8390 av = (AV *)SvRV (arg);
8391 ret = malloc ((av_len (av) + 1 + 1) * sizeof (char *));
8393 croak (\"malloc failed\");
8395 for (i = 0; i <= av_len (av); i++) {
8396 SV **elem = av_fetch (av, i, 0);
8398 if (!elem || !*elem)
8399 croak (\"missing element in list\");
8401 ret[i] = SvPV_nolen (*elem);
8409 MODULE = Sys::Guestfs PACKAGE = Sys::Guestfs
8416 RETVAL = guestfs_create ();
8418 croak (\"could not create guestfs handle\");
8419 guestfs_set_error_handler (RETVAL, NULL, NULL);
8432 fun (name, style, _, _, _, _, _) ->
8433 (match fst style with
8434 | RErr -> pr "void\n"
8435 | RInt _ -> pr "SV *\n"
8436 | RInt64 _ -> pr "SV *\n"
8437 | RBool _ -> pr "SV *\n"
8438 | RConstString _ -> pr "SV *\n"
8439 | RConstOptString _ -> pr "SV *\n"
8440 | RString _ -> pr "SV *\n"
8441 | RBufferOut _ -> pr "SV *\n"
8443 | RStruct _ | RStructList _
8445 pr "void\n" (* all lists returned implictly on the stack *)
8447 (* Call and arguments. *)
8449 generate_c_call_args ~handle:"g" ~decl:true style;
8451 pr " guestfs_h *g;\n";
8455 | Pathname n | Device n | Dev_or_Path n | String n | FileIn n | FileOut n ->
8458 (* http://www.perlmonks.org/?node_id=554277
8459 * Note that the implicit handle argument means we have
8460 * to add 1 to the ST(x) operator.
8462 pr " char *%s = SvOK(ST(%d)) ? SvPV_nolen(ST(%d)) : NULL;\n" n (i+1) (i+1)
8463 | StringList n | DeviceList n -> pr " char **%s;\n" n
8464 | Bool n -> pr " int %s;\n" n
8465 | Int n -> pr " int %s;\n" n
8466 | Int64 n -> pr " int64_t %s;\n" n
8469 let do_cleanups () =
8472 | Pathname _ | Device _ | Dev_or_Path _ | String _ | OptString _
8473 | Bool _ | Int _ | Int64 _
8474 | FileIn _ | FileOut _ -> ()
8475 | StringList n | DeviceList n -> pr " free (%s);\n" n
8480 (match fst style with
8485 pr " r = guestfs_%s " name;
8486 generate_c_call_args ~handle:"g" style;
8489 pr " if (r == -1)\n";
8490 pr " croak (\"%%s\", guestfs_last_error (g));\n";
8496 pr " %s = guestfs_%s " n name;
8497 generate_c_call_args ~handle:"g" style;
8500 pr " if (%s == -1)\n" n;
8501 pr " croak (\"%%s\", guestfs_last_error (g));\n";
8502 pr " RETVAL = newSViv (%s);\n" n;
8507 pr " int64_t %s;\n" n;
8509 pr " %s = guestfs_%s " n name;
8510 generate_c_call_args ~handle:"g" style;
8513 pr " if (%s == -1)\n" n;
8514 pr " croak (\"%%s\", guestfs_last_error (g));\n";
8515 pr " RETVAL = my_newSVll (%s);\n" n;
8520 pr " const char *%s;\n" n;
8522 pr " %s = guestfs_%s " n name;
8523 generate_c_call_args ~handle:"g" style;
8526 pr " if (%s == NULL)\n" n;
8527 pr " croak (\"%%s\", guestfs_last_error (g));\n";
8528 pr " RETVAL = newSVpv (%s, 0);\n" n;
8531 | RConstOptString n ->
8533 pr " const char *%s;\n" n;
8535 pr " %s = guestfs_%s " n name;
8536 generate_c_call_args ~handle:"g" style;
8539 pr " if (%s == NULL)\n" n;
8540 pr " RETVAL = &PL_sv_undef;\n";
8542 pr " RETVAL = newSVpv (%s, 0);\n" n;
8547 pr " char *%s;\n" n;
8549 pr " %s = guestfs_%s " n name;
8550 generate_c_call_args ~handle:"g" style;
8553 pr " if (%s == NULL)\n" n;
8554 pr " croak (\"%%s\", guestfs_last_error (g));\n";
8555 pr " RETVAL = newSVpv (%s, 0);\n" n;
8556 pr " free (%s);\n" n;
8559 | RStringList n | RHashtable n ->
8561 pr " char **%s;\n" n;
8564 pr " %s = guestfs_%s " n name;
8565 generate_c_call_args ~handle:"g" style;
8568 pr " if (%s == NULL)\n" n;
8569 pr " croak (\"%%s\", guestfs_last_error (g));\n";
8570 pr " for (n = 0; %s[n] != NULL; ++n) /**/;\n" n;
8571 pr " EXTEND (SP, n);\n";
8572 pr " for (i = 0; i < n; ++i) {\n";
8573 pr " PUSHs (sv_2mortal (newSVpv (%s[i], 0)));\n" n;
8574 pr " free (%s[i]);\n" n;
8576 pr " free (%s);\n" n;
8577 | RStruct (n, typ) ->
8578 let cols = cols_of_struct typ in
8579 generate_perl_struct_code typ cols name style n do_cleanups
8580 | RStructList (n, typ) ->
8581 let cols = cols_of_struct typ in
8582 generate_perl_struct_list_code typ cols name style n do_cleanups
8585 pr " char *%s;\n" n;
8586 pr " size_t size;\n";
8588 pr " %s = guestfs_%s " n name;
8589 generate_c_call_args ~handle:"g" style;
8592 pr " if (%s == NULL)\n" n;
8593 pr " croak (\"%%s\", guestfs_last_error (g));\n";
8594 pr " RETVAL = newSVpvn (%s, size);\n" n;
8595 pr " free (%s);\n" n;
8603 and generate_perl_struct_list_code typ cols name style n do_cleanups =
8605 pr " struct guestfs_%s_list *%s;\n" typ n;
8609 pr " %s = guestfs_%s " n name;
8610 generate_c_call_args ~handle:"g" style;
8613 pr " if (%s == NULL)\n" n;
8614 pr " croak (\"%%s\", guestfs_last_error (g));\n";
8615 pr " EXTEND (SP, %s->len);\n" n;
8616 pr " for (i = 0; i < %s->len; ++i) {\n" n;
8617 pr " hv = newHV ();\n";
8621 pr " (void) hv_store (hv, \"%s\", %d, newSVpv (%s->val[i].%s, 0), 0);\n"
8622 name (String.length name) n name
8624 pr " (void) hv_store (hv, \"%s\", %d, newSVpv (%s->val[i].%s, 32), 0);\n"
8625 name (String.length name) n name
8627 pr " (void) hv_store (hv, \"%s\", %d, newSVpvn (%s->val[i].%s, %s->val[i].%s_len), 0);\n"
8628 name (String.length name) n name n name
8629 | name, (FBytes|FUInt64) ->
8630 pr " (void) hv_store (hv, \"%s\", %d, my_newSVull (%s->val[i].%s), 0);\n"
8631 name (String.length name) n name
8633 pr " (void) hv_store (hv, \"%s\", %d, my_newSVll (%s->val[i].%s), 0);\n"
8634 name (String.length name) n name
8635 | name, (FInt32|FUInt32) ->
8636 pr " (void) hv_store (hv, \"%s\", %d, newSVnv (%s->val[i].%s), 0);\n"
8637 name (String.length name) n name
8639 pr " (void) hv_store (hv, \"%s\", %d, newSVpv (&%s->val[i].%s, 1), 0);\n"
8640 name (String.length name) n name
8641 | name, FOptPercent ->
8642 pr " (void) hv_store (hv, \"%s\", %d, newSVnv (%s->val[i].%s), 0);\n"
8643 name (String.length name) n name
8645 pr " PUSHs (sv_2mortal (newRV ((SV *) hv)));\n";
8647 pr " guestfs_free_%s_list (%s);\n" typ n
8649 and generate_perl_struct_code typ cols name style n do_cleanups =
8651 pr " struct guestfs_%s *%s;\n" typ n;
8653 pr " %s = guestfs_%s " n name;
8654 generate_c_call_args ~handle:"g" style;
8657 pr " if (%s == NULL)\n" n;
8658 pr " croak (\"%%s\", guestfs_last_error (g));\n";
8659 pr " EXTEND (SP, 2 * %d);\n" (List.length cols);
8661 fun ((name, _) as col) ->
8662 pr " PUSHs (sv_2mortal (newSVpv (\"%s\", 0)));\n" name;
8666 pr " PUSHs (sv_2mortal (newSVpv (%s->%s, 0)));\n"
8669 pr " PUSHs (sv_2mortal (newSVpvn (%s->%s, %s->%s_len)));\n"
8672 pr " PUSHs (sv_2mortal (newSVpv (%s->%s, 32)));\n"
8674 | name, (FBytes|FUInt64) ->
8675 pr " PUSHs (sv_2mortal (my_newSVull (%s->%s)));\n"
8678 pr " PUSHs (sv_2mortal (my_newSVll (%s->%s)));\n"
8680 | name, (FInt32|FUInt32) ->
8681 pr " PUSHs (sv_2mortal (newSVnv (%s->%s)));\n"
8684 pr " PUSHs (sv_2mortal (newSVpv (&%s->%s, 1)));\n"
8686 | name, FOptPercent ->
8687 pr " PUSHs (sv_2mortal (newSVnv (%s->%s)));\n"
8690 pr " free (%s);\n" n
8692 (* Generate Sys/Guestfs.pm. *)
8693 and generate_perl_pm () =
8694 generate_header HashStyle LGPLv2plus;
8701 Sys::Guestfs - Perl bindings for libguestfs
8707 my $h = Sys::Guestfs->new ();
8708 $h->add_drive ('guest.img');
8710 $h->mount ('/dev/sda1', '/');
8711 $h->touch ('/hello');
8716 The C<Sys::Guestfs> module provides a Perl XS binding to the
8717 libguestfs API for examining and modifying virtual machine
8720 Amongst the things this is good for: making batch configuration
8721 changes to guests, getting disk used/free statistics (see also:
8722 virt-df), migrating between virtualization systems (see also:
8723 virt-p2v), performing partial backups, performing partial guest
8724 clones, cloning guests and changing registry/UUID/hostname info, and
8727 Libguestfs uses Linux kernel and qemu code, and can access any type of
8728 guest filesystem that Linux and qemu can, including but not limited
8729 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
8730 schemes, qcow, qcow2, vmdk.
8732 Libguestfs provides ways to enumerate guest storage (eg. partitions,
8733 LVs, what filesystem is in each LV, etc.). It can also run commands
8734 in the context of the guest. Also you can access filesystems over
8737 See also L<Sys::Guestfs::Lib(3)> for a set of useful library
8738 functions for using libguestfs from Perl, including integration
8743 All errors turn into calls to C<croak> (see L<Carp(3)>).
8751 package Sys::Guestfs;
8757 XSLoader::load ('Sys::Guestfs');
8759 =item $h = Sys::Guestfs->new ();
8761 Create a new guestfs handle.
8767 my $class = ref ($proto) || $proto;
8769 my $self = Sys::Guestfs::_create ();
8770 bless $self, $class;
8776 (* Actions. We only need to print documentation for these as
8777 * they are pulled in from the XS code automatically.
8780 fun (name, style, _, flags, _, _, longdesc) ->
8781 if not (List.mem NotInDocs flags) then (
8782 let longdesc = replace_str longdesc "C<guestfs_" "C<$h-E<gt>" in
8784 generate_perl_prototype name style;
8786 pr "%s\n\n" longdesc;
8787 if List.mem ProtocolLimitWarning flags then
8788 pr "%s\n\n" protocol_limit_warning;
8789 if List.mem DangerWillRobinson flags then
8790 pr "%s\n\n" danger_will_robinson;
8791 match deprecation_notice flags with
8793 | Some txt -> pr "%s\n\n" txt
8795 ) all_functions_sorted;
8807 Copyright (C) %s Red Hat Inc.
8811 Please see the file COPYING.LIB for the full license.
8817 L<http://libguestfs.org>,
8818 L<Sys::Guestfs::Lib(3)>.
8823 and generate_perl_prototype name style =
8824 (match fst style with
8832 | RBufferOut n -> pr "$%s = " n
8834 | RHashtable n -> pr "%%%s = " n
8836 | RStructList (n,_) -> pr "@%s = " n
8839 let comma = ref false in
8842 if !comma then pr ", ";
8845 | Pathname n | Device n | Dev_or_Path n | String n
8846 | OptString n | Bool n | Int n | Int64 n | FileIn n | FileOut n ->
8848 | StringList n | DeviceList n ->
8853 (* Generate Python C module. *)
8854 and generate_python_c () =
8855 generate_header CStyle LGPLv2plus;
8864 #include \"guestfs.h\"
8872 get_handle (PyObject *obj)
8875 assert (obj != Py_None);
8876 return ((Pyguestfs_Object *) obj)->g;
8880 put_handle (guestfs_h *g)
8884 PyCObject_FromVoidPtrAndDesc ((void *) g, (char *) \"guestfs_h\", NULL);
8887 /* This list should be freed (but not the strings) after use. */
8889 get_string_list (PyObject *obj)
8896 if (!PyList_Check (obj)) {
8897 PyErr_SetString (PyExc_RuntimeError, \"expecting a list parameter\");
8901 len = PyList_Size (obj);
8902 r = malloc (sizeof (char *) * (len+1));
8904 PyErr_SetString (PyExc_RuntimeError, \"get_string_list: out of memory\");
8908 for (i = 0; i < len; ++i)
8909 r[i] = PyString_AsString (PyList_GetItem (obj, i));
8916 put_string_list (char * const * const argv)
8921 for (argc = 0; argv[argc] != NULL; ++argc)
8924 list = PyList_New (argc);
8925 for (i = 0; i < argc; ++i)
8926 PyList_SetItem (list, i, PyString_FromString (argv[i]));
8932 put_table (char * const * const argv)
8934 PyObject *list, *item;
8937 for (argc = 0; argv[argc] != NULL; ++argc)
8940 list = PyList_New (argc >> 1);
8941 for (i = 0; i < argc; i += 2) {
8942 item = PyTuple_New (2);
8943 PyTuple_SetItem (item, 0, PyString_FromString (argv[i]));
8944 PyTuple_SetItem (item, 1, PyString_FromString (argv[i+1]));
8945 PyList_SetItem (list, i >> 1, item);
8952 free_strings (char **argv)
8956 for (argc = 0; argv[argc] != NULL; ++argc)
8962 py_guestfs_create (PyObject *self, PyObject *args)
8966 g = guestfs_create ();
8968 PyErr_SetString (PyExc_RuntimeError,
8969 \"guestfs.create: failed to allocate handle\");
8972 guestfs_set_error_handler (g, NULL, NULL);
8973 return put_handle (g);
8977 py_guestfs_close (PyObject *self, PyObject *args)
8982 if (!PyArg_ParseTuple (args, (char *) \"O:guestfs_close\", &py_g))
8984 g = get_handle (py_g);
8988 Py_INCREF (Py_None);
8994 let emit_put_list_function typ =
8995 pr "static PyObject *\n";
8996 pr "put_%s_list (struct guestfs_%s_list *%ss)\n" typ typ typ;
8998 pr " PyObject *list;\n";
9001 pr " list = PyList_New (%ss->len);\n" typ;
9002 pr " for (i = 0; i < %ss->len; ++i)\n" typ;
9003 pr " PyList_SetItem (list, i, put_%s (&%ss->val[i]));\n" typ typ;
9004 pr " return list;\n";
9009 (* Structures, turned into Python dictionaries. *)
9012 pr "static PyObject *\n";
9013 pr "put_%s (struct guestfs_%s *%s)\n" typ typ typ;
9015 pr " PyObject *dict;\n";
9017 pr " dict = PyDict_New ();\n";
9021 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
9022 pr " PyString_FromString (%s->%s));\n"
9025 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
9026 pr " PyString_FromStringAndSize (%s->%s, %s->%s_len));\n"
9029 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
9030 pr " PyString_FromStringAndSize (%s->%s, 32));\n"
9032 | name, (FBytes|FUInt64) ->
9033 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
9034 pr " PyLong_FromUnsignedLongLong (%s->%s));\n"
9037 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
9038 pr " PyLong_FromLongLong (%s->%s));\n"
9041 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
9042 pr " PyLong_FromUnsignedLong (%s->%s));\n"
9045 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
9046 pr " PyLong_FromLong (%s->%s));\n"
9048 | name, FOptPercent ->
9049 pr " if (%s->%s >= 0)\n" typ name;
9050 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
9051 pr " PyFloat_FromDouble ((double) %s->%s));\n"
9054 pr " Py_INCREF (Py_None);\n";
9055 pr " PyDict_SetItemString (dict, \"%s\", Py_None);\n" name;
9058 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
9059 pr " PyString_FromStringAndSize (&dirent->%s, 1));\n" name
9061 pr " return dict;\n";
9067 (* Emit a put_TYPE_list function definition only if that function is used. *)
9070 | typ, (RStructListOnly | RStructAndList) ->
9071 (* generate the function for typ *)
9072 emit_put_list_function typ
9073 | typ, _ -> () (* empty *)
9074 ) (rstructs_used_by all_functions);
9076 (* Python wrapper functions. *)
9078 fun (name, style, _, _, _, _, _) ->
9079 pr "static PyObject *\n";
9080 pr "py_guestfs_%s (PyObject *self, PyObject *args)\n" name;
9083 pr " PyObject *py_g;\n";
9084 pr " guestfs_h *g;\n";
9085 pr " PyObject *py_r;\n";
9088 match fst style with
9089 | RErr | RInt _ | RBool _ -> pr " int r;\n"; "-1"
9090 | RInt64 _ -> pr " int64_t r;\n"; "-1"
9091 | RConstString _ | RConstOptString _ ->
9092 pr " const char *r;\n"; "NULL"
9093 | RString _ -> pr " char *r;\n"; "NULL"
9094 | RStringList _ | RHashtable _ -> pr " char **r;\n"; "NULL"
9095 | RStruct (_, typ) -> pr " struct guestfs_%s *r;\n" typ; "NULL"
9096 | RStructList (_, typ) ->
9097 pr " struct guestfs_%s_list *r;\n" typ; "NULL"
9100 pr " size_t size;\n";
9105 | Pathname n | Device n | Dev_or_Path n | String n | FileIn n | FileOut n ->
9106 pr " const char *%s;\n" n
9107 | OptString n -> pr " const char *%s;\n" n
9108 | StringList n | DeviceList n ->
9109 pr " PyObject *py_%s;\n" n;
9110 pr " char **%s;\n" n
9111 | Bool n -> pr " int %s;\n" n
9112 | Int n -> pr " int %s;\n" n
9113 | Int64 n -> pr " long long %s;\n" n
9118 (* Convert the parameters. *)
9119 pr " if (!PyArg_ParseTuple (args, (char *) \"O";
9122 | Pathname _ | Device _ | Dev_or_Path _ | String _ | FileIn _ | FileOut _ -> pr "s"
9123 | OptString _ -> pr "z"
9124 | StringList _ | DeviceList _ -> pr "O"
9125 | Bool _ -> pr "i" (* XXX Python has booleans? *)
9127 | Int64 _ -> pr "L" (* XXX Whoever thought it was a good idea to
9128 * emulate C's int/long/long long in Python?
9131 pr ":guestfs_%s\",\n" name;
9135 | Pathname n | Device n | Dev_or_Path n | String n | FileIn n | FileOut n -> pr ", &%s" n
9136 | OptString n -> pr ", &%s" n
9137 | StringList n | DeviceList n -> pr ", &py_%s" n
9138 | Bool n -> pr ", &%s" n
9139 | Int n -> pr ", &%s" n
9140 | Int64 n -> pr ", &%s" n
9144 pr " return NULL;\n";
9146 pr " g = get_handle (py_g);\n";
9149 | Pathname _ | Device _ | Dev_or_Path _ | String _
9150 | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ | Int64 _ -> ()
9151 | StringList n | DeviceList n ->
9152 pr " %s = get_string_list (py_%s);\n" n n;
9153 pr " if (!%s) return NULL;\n" n
9158 pr " r = guestfs_%s " name;
9159 generate_c_call_args ~handle:"g" style;
9164 | Pathname _ | Device _ | Dev_or_Path _ | String _
9165 | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ | Int64 _ -> ()
9166 | StringList n | DeviceList n ->
9167 pr " free (%s);\n" n
9170 pr " if (r == %s) {\n" error_code;
9171 pr " PyErr_SetString (PyExc_RuntimeError, guestfs_last_error (g));\n";
9172 pr " return NULL;\n";
9176 (match fst style with
9178 pr " Py_INCREF (Py_None);\n";
9179 pr " py_r = Py_None;\n"
9181 | RBool _ -> pr " py_r = PyInt_FromLong ((long) r);\n"
9182 | RInt64 _ -> pr " py_r = PyLong_FromLongLong (r);\n"
9183 | RConstString _ -> pr " py_r = PyString_FromString (r);\n"
9184 | RConstOptString _ ->
9186 pr " py_r = PyString_FromString (r);\n";
9188 pr " Py_INCREF (Py_None);\n";
9189 pr " py_r = Py_None;\n";
9192 pr " py_r = PyString_FromString (r);\n";
9195 pr " py_r = put_string_list (r);\n";
9196 pr " free_strings (r);\n"
9197 | RStruct (_, typ) ->
9198 pr " py_r = put_%s (r);\n" typ;
9199 pr " guestfs_free_%s (r);\n" typ
9200 | RStructList (_, typ) ->
9201 pr " py_r = put_%s_list (r);\n" typ;
9202 pr " guestfs_free_%s_list (r);\n" typ
9204 pr " py_r = put_table (r);\n";
9205 pr " free_strings (r);\n"
9207 pr " py_r = PyString_FromStringAndSize (r, size);\n";
9211 pr " return py_r;\n";
9216 (* Table of functions. *)
9217 pr "static PyMethodDef methods[] = {\n";
9218 pr " { (char *) \"create\", py_guestfs_create, METH_VARARGS, NULL },\n";
9219 pr " { (char *) \"close\", py_guestfs_close, METH_VARARGS, NULL },\n";
9221 fun (name, _, _, _, _, _, _) ->
9222 pr " { (char *) \"%s\", py_guestfs_%s, METH_VARARGS, NULL },\n"
9225 pr " { NULL, NULL, 0, NULL }\n";
9229 (* Init function. *)
9232 initlibguestfsmod (void)
9234 static int initialized = 0;
9236 if (initialized) return;
9237 Py_InitModule ((char *) \"libguestfsmod\", methods);
9242 (* Generate Python module. *)
9243 and generate_python_py () =
9244 generate_header HashStyle LGPLv2plus;
9247 u\"\"\"Python bindings for libguestfs
9250 g = guestfs.GuestFS ()
9251 g.add_drive (\"guest.img\")
9253 parts = g.list_partitions ()
9255 The guestfs module provides a Python binding to the libguestfs API
9256 for examining and modifying virtual machine disk images.
9258 Amongst the things this is good for: making batch configuration
9259 changes to guests, getting disk used/free statistics (see also:
9260 virt-df), migrating between virtualization systems (see also:
9261 virt-p2v), performing partial backups, performing partial guest
9262 clones, cloning guests and changing registry/UUID/hostname info, and
9265 Libguestfs uses Linux kernel and qemu code, and can access any type of
9266 guest filesystem that Linux and qemu can, including but not limited
9267 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
9268 schemes, qcow, qcow2, vmdk.
9270 Libguestfs provides ways to enumerate guest storage (eg. partitions,
9271 LVs, what filesystem is in each LV, etc.). It can also run commands
9272 in the context of the guest. Also you can access filesystems over
9275 Errors which happen while using the API are turned into Python
9276 RuntimeError exceptions.
9278 To create a guestfs handle you usually have to perform the following
9281 # Create the handle, call add_drive at least once, and possibly
9282 # several times if the guest has multiple block devices:
9283 g = guestfs.GuestFS ()
9284 g.add_drive (\"guest.img\")
9286 # Launch the qemu subprocess and wait for it to become ready:
9289 # Now you can issue commands, for example:
9294 import libguestfsmod
9297 \"\"\"Instances of this class are libguestfs API handles.\"\"\"
9299 def __init__ (self):
9300 \"\"\"Create a new libguestfs handle.\"\"\"
9301 self._o = libguestfsmod.create ()
9304 libguestfsmod.close (self._o)
9309 fun (name, style, _, flags, _, _, longdesc) ->
9311 generate_py_call_args ~handle:"self" (snd style);
9314 if not (List.mem NotInDocs flags) then (
9315 let doc = replace_str longdesc "C<guestfs_" "C<g." in
9317 match fst style with
9318 | RErr | RInt _ | RInt64 _ | RBool _
9319 | RConstOptString _ | RConstString _
9320 | RString _ | RBufferOut _ -> doc
9322 doc ^ "\n\nThis function returns a list of strings."
9323 | RStruct (_, typ) ->
9324 doc ^ sprintf "\n\nThis function returns a dictionary, with keys matching the various fields in the guestfs_%s structure." typ
9325 | RStructList (_, typ) ->
9326 doc ^ sprintf "\n\nThis function returns a list of %ss. Each %s is represented as a dictionary." typ typ
9328 doc ^ "\n\nThis function returns a dictionary." in
9330 if List.mem ProtocolLimitWarning flags then
9331 doc ^ "\n\n" ^ protocol_limit_warning
9334 if List.mem DangerWillRobinson flags then
9335 doc ^ "\n\n" ^ danger_will_robinson
9338 match deprecation_notice flags with
9340 | Some txt -> doc ^ "\n\n" ^ txt in
9341 let doc = pod2text ~width:60 name doc in
9342 let doc = List.map (fun line -> replace_str line "\\" "\\\\") doc in
9343 let doc = String.concat "\n " doc in
9344 pr " u\"\"\"%s\"\"\"\n" doc;
9346 pr " return libguestfsmod.%s " name;
9347 generate_py_call_args ~handle:"self._o" (snd style);
9352 (* Generate Python call arguments, eg "(handle, foo, bar)" *)
9353 and generate_py_call_args ~handle args =
9355 List.iter (fun arg -> pr ", %s" (name_of_argt arg)) args;
9358 (* Useful if you need the longdesc POD text as plain text. Returns a
9361 * Because this is very slow (the slowest part of autogeneration),
9362 * we memoize the results.
9364 and pod2text ~width name longdesc =
9365 let key = width, name, longdesc in
9366 try Hashtbl.find pod2text_memo key
9368 let filename, chan = Filename.open_temp_file "gen" ".tmp" in
9369 fprintf chan "=head1 %s\n\n%s\n" name longdesc;
9371 let cmd = sprintf "pod2text -w %d %s" width (Filename.quote filename) in
9372 let chan = open_process_in cmd in
9373 let lines = ref [] in
9375 let line = input_line chan in
9376 if i = 1 then (* discard the first line of output *)
9379 let line = triml line in
9380 lines := line :: !lines;
9383 let lines = try loop 1 with End_of_file -> List.rev !lines in
9385 (match close_process_in chan with
9388 failwithf "pod2text: process exited with non-zero status (%d)" i
9389 | WSIGNALED i | WSTOPPED i ->
9390 failwithf "pod2text: process signalled or stopped by signal %d" i
9392 Hashtbl.add pod2text_memo key lines;
9393 pod2text_memo_updated ();
9396 (* Generate ruby bindings. *)
9397 and generate_ruby_c () =
9398 generate_header CStyle LGPLv2plus;
9406 #include \"guestfs.h\"
9408 #include \"extconf.h\"
9410 /* For Ruby < 1.9 */
9412 #define RARRAY_LEN(r) (RARRAY((r))->len)
9415 static VALUE m_guestfs; /* guestfs module */
9416 static VALUE c_guestfs; /* guestfs_h handle */
9417 static VALUE e_Error; /* used for all errors */
9419 static void ruby_guestfs_free (void *p)
9422 guestfs_close ((guestfs_h *) p);
9425 static VALUE ruby_guestfs_create (VALUE m)
9429 g = guestfs_create ();
9431 rb_raise (e_Error, \"failed to create guestfs handle\");
9433 /* Don't print error messages to stderr by default. */
9434 guestfs_set_error_handler (g, NULL, NULL);
9436 /* Wrap it, and make sure the close function is called when the
9439 return Data_Wrap_Struct (c_guestfs, NULL, ruby_guestfs_free, g);
9442 static VALUE ruby_guestfs_close (VALUE gv)
9445 Data_Get_Struct (gv, guestfs_h, g);
9447 ruby_guestfs_free (g);
9448 DATA_PTR (gv) = NULL;
9456 fun (name, style, _, _, _, _, _) ->
9457 pr "static VALUE ruby_guestfs_%s (VALUE gv" name;
9458 List.iter (fun arg -> pr ", VALUE %sv" (name_of_argt arg)) (snd style);
9461 pr " guestfs_h *g;\n";
9462 pr " Data_Get_Struct (gv, guestfs_h, g);\n";
9464 pr " rb_raise (rb_eArgError, \"%%s: used handle after closing it\", \"%s\");\n"
9470 | Pathname n | Device n | Dev_or_Path n | String n | FileIn n | FileOut n ->
9471 pr " Check_Type (%sv, T_STRING);\n" n;
9472 pr " const char *%s = StringValueCStr (%sv);\n" n n;
9474 pr " rb_raise (rb_eTypeError, \"expected string for parameter %%s of %%s\",\n";
9475 pr " \"%s\", \"%s\");\n" n name
9477 pr " const char *%s = !NIL_P (%sv) ? StringValueCStr (%sv) : NULL;\n" n n n
9478 | StringList n | DeviceList n ->
9479 pr " char **%s;\n" n;
9480 pr " Check_Type (%sv, T_ARRAY);\n" n;
9482 pr " int i, len;\n";
9483 pr " len = RARRAY_LEN (%sv);\n" n;
9484 pr " %s = guestfs_safe_malloc (g, sizeof (char *) * (len+1));\n"
9486 pr " for (i = 0; i < len; ++i) {\n";
9487 pr " VALUE v = rb_ary_entry (%sv, i);\n" n;
9488 pr " %s[i] = StringValueCStr (v);\n" n;
9490 pr " %s[len] = NULL;\n" n;
9493 pr " int %s = RTEST (%sv);\n" n n
9495 pr " int %s = NUM2INT (%sv);\n" n n
9497 pr " long long %s = NUM2LL (%sv);\n" n n
9502 match fst style with
9503 | RErr | RInt _ | RBool _ -> pr " int r;\n"; "-1"
9504 | RInt64 _ -> pr " int64_t r;\n"; "-1"
9505 | RConstString _ | RConstOptString _ ->
9506 pr " const char *r;\n"; "NULL"
9507 | RString _ -> pr " char *r;\n"; "NULL"
9508 | RStringList _ | RHashtable _ -> pr " char **r;\n"; "NULL"
9509 | RStruct (_, typ) -> pr " struct guestfs_%s *r;\n" typ; "NULL"
9510 | RStructList (_, typ) ->
9511 pr " struct guestfs_%s_list *r;\n" typ; "NULL"
9514 pr " size_t size;\n";
9518 pr " r = guestfs_%s " name;
9519 generate_c_call_args ~handle:"g" style;
9524 | Pathname _ | Device _ | Dev_or_Path _ | String _
9525 | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ | Int64 _ -> ()
9526 | StringList n | DeviceList n ->
9527 pr " free (%s);\n" n
9530 pr " if (r == %s)\n" error_code;
9531 pr " rb_raise (e_Error, \"%%s\", guestfs_last_error (g));\n";
9534 (match fst style with
9536 pr " return Qnil;\n"
9537 | RInt _ | RBool _ ->
9538 pr " return INT2NUM (r);\n"
9540 pr " return ULL2NUM (r);\n"
9542 pr " return rb_str_new2 (r);\n";
9543 | RConstOptString _ ->
9545 pr " return rb_str_new2 (r);\n";
9547 pr " return Qnil;\n";
9549 pr " VALUE rv = rb_str_new2 (r);\n";
9553 pr " int i, len = 0;\n";
9554 pr " for (i = 0; r[i] != NULL; ++i) len++;\n";
9555 pr " VALUE rv = rb_ary_new2 (len);\n";
9556 pr " for (i = 0; r[i] != NULL; ++i) {\n";
9557 pr " rb_ary_push (rv, rb_str_new2 (r[i]));\n";
9558 pr " free (r[i]);\n";
9562 | RStruct (_, typ) ->
9563 let cols = cols_of_struct typ in
9564 generate_ruby_struct_code typ cols
9565 | RStructList (_, typ) ->
9566 let cols = cols_of_struct typ in
9567 generate_ruby_struct_list_code typ cols
9569 pr " VALUE rv = rb_hash_new ();\n";
9571 pr " for (i = 0; r[i] != NULL; i+=2) {\n";
9572 pr " rb_hash_aset (rv, rb_str_new2 (r[i]), rb_str_new2 (r[i+1]));\n";
9573 pr " free (r[i]);\n";
9574 pr " free (r[i+1]);\n";
9579 pr " VALUE rv = rb_str_new (r, size);\n";
9589 /* Initialize the module. */
9590 void Init__guestfs ()
9592 m_guestfs = rb_define_module (\"Guestfs\");
9593 c_guestfs = rb_define_class_under (m_guestfs, \"Guestfs\", rb_cObject);
9594 e_Error = rb_define_class_under (m_guestfs, \"Error\", rb_eStandardError);
9596 rb_define_module_function (m_guestfs, \"create\", ruby_guestfs_create, 0);
9597 rb_define_method (c_guestfs, \"close\", ruby_guestfs_close, 0);
9600 (* Define the rest of the methods. *)
9602 fun (name, style, _, _, _, _, _) ->
9603 pr " rb_define_method (c_guestfs, \"%s\",\n" name;
9604 pr " ruby_guestfs_%s, %d);\n" name (List.length (snd style))
9609 (* Ruby code to return a struct. *)
9610 and generate_ruby_struct_code typ cols =
9611 pr " VALUE rv = rb_hash_new ();\n";
9615 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_str_new2 (r->%s));\n" name name
9617 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_str_new (r->%s, r->%s_len));\n" name name name
9619 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_str_new (r->%s, 32));\n" name name
9620 | name, (FBytes|FUInt64) ->
9621 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), ULL2NUM (r->%s));\n" name name
9623 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), LL2NUM (r->%s));\n" name name
9625 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), UINT2NUM (r->%s));\n" name name
9627 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), INT2NUM (r->%s));\n" name name
9628 | name, FOptPercent ->
9629 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_dbl2big (r->%s));\n" name name
9630 | name, FChar -> (* XXX wrong? *)
9631 pr " rb_hash_aset (rv, rb_str_new2 (\"%s\"), ULL2NUM (r->%s));\n" name name
9633 pr " guestfs_free_%s (r);\n" typ;
9636 (* Ruby code to return a struct list. *)
9637 and generate_ruby_struct_list_code typ cols =
9638 pr " VALUE rv = rb_ary_new2 (r->len);\n";
9640 pr " for (i = 0; i < r->len; ++i) {\n";
9641 pr " VALUE hv = rb_hash_new ();\n";
9645 pr " rb_hash_aset (hv, rb_str_new2 (\"%s\"), rb_str_new2 (r->val[i].%s));\n" name name
9647 pr " rb_hash_aset (hv, rb_str_new2 (\"%s\"), rb_str_new (r->val[i].%s, r->val[i].%s_len));\n" name name name
9649 pr " rb_hash_aset (hv, rb_str_new2 (\"%s\"), rb_str_new (r->val[i].%s, 32));\n" name name
9650 | name, (FBytes|FUInt64) ->
9651 pr " rb_hash_aset (hv, rb_str_new2 (\"%s\"), ULL2NUM (r->val[i].%s));\n" name name
9653 pr " rb_hash_aset (hv, rb_str_new2 (\"%s\"), LL2NUM (r->val[i].%s));\n" name name
9655 pr " rb_hash_aset (hv, rb_str_new2 (\"%s\"), UINT2NUM (r->val[i].%s));\n" name name
9657 pr " rb_hash_aset (hv, rb_str_new2 (\"%s\"), INT2NUM (r->val[i].%s));\n" name name
9658 | name, FOptPercent ->
9659 pr " rb_hash_aset (hv, rb_str_new2 (\"%s\"), rb_dbl2big (r->val[i].%s));\n" name name
9660 | name, FChar -> (* XXX wrong? *)
9661 pr " rb_hash_aset (hv, rb_str_new2 (\"%s\"), ULL2NUM (r->val[i].%s));\n" name name
9663 pr " rb_ary_push (rv, hv);\n";
9665 pr " guestfs_free_%s_list (r);\n" typ;
9668 (* Generate Java bindings GuestFS.java file. *)
9669 and generate_java_java () =
9670 generate_header CStyle LGPLv2plus;
9673 package com.redhat.et.libguestfs;
9675 import java.util.HashMap;
9676 import com.redhat.et.libguestfs.LibGuestFSException;
9677 import com.redhat.et.libguestfs.PV;
9678 import com.redhat.et.libguestfs.VG;
9679 import com.redhat.et.libguestfs.LV;
9680 import com.redhat.et.libguestfs.Stat;
9681 import com.redhat.et.libguestfs.StatVFS;
9682 import com.redhat.et.libguestfs.IntBool;
9683 import com.redhat.et.libguestfs.Dirent;
9686 * The GuestFS object is a libguestfs handle.
9690 public class GuestFS {
9691 // Load the native code.
9693 System.loadLibrary (\"guestfs_jni\");
9697 * The native guestfs_h pointer.
9702 * Create a libguestfs handle.
9704 * @throws LibGuestFSException
9706 public GuestFS () throws LibGuestFSException
9710 private native long _create () throws LibGuestFSException;
9713 * Close a libguestfs handle.
9715 * You can also leave handles to be collected by the garbage
9716 * collector, but this method ensures that the resources used
9717 * by the handle are freed up immediately. If you call any
9718 * other methods after closing the handle, you will get an
9721 * @throws LibGuestFSException
9723 public void close () throws LibGuestFSException
9729 private native void _close (long g) throws LibGuestFSException;
9731 public void finalize () throws LibGuestFSException
9739 fun (name, style, _, flags, _, shortdesc, longdesc) ->
9740 if not (List.mem NotInDocs flags); then (
9741 let doc = replace_str longdesc "C<guestfs_" "C<g." in
9743 if List.mem ProtocolLimitWarning flags then
9744 doc ^ "\n\n" ^ protocol_limit_warning
9747 if List.mem DangerWillRobinson flags then
9748 doc ^ "\n\n" ^ danger_will_robinson
9751 match deprecation_notice flags with
9753 | Some txt -> doc ^ "\n\n" ^ txt in
9754 let doc = pod2text ~width:60 name doc in
9755 let doc = List.map ( (* RHBZ#501883 *)
9758 | nonempty -> nonempty
9760 let doc = String.concat "\n * " doc in
9763 pr " * %s\n" shortdesc;
9766 pr " * @throws LibGuestFSException\n";
9770 generate_java_prototype ~public:true ~semicolon:false name style;
9773 pr " if (g == 0)\n";
9774 pr " throw new LibGuestFSException (\"%s: handle is closed\");\n"
9777 if fst style <> RErr then pr "return ";
9779 generate_java_call_args ~handle:"g" (snd style);
9783 generate_java_prototype ~privat:true ~native:true name style;
9790 (* Generate Java call arguments, eg "(handle, foo, bar)" *)
9791 and generate_java_call_args ~handle args =
9793 List.iter (fun arg -> pr ", %s" (name_of_argt arg)) args;
9796 and generate_java_prototype ?(public=false) ?(privat=false) ?(native=false)
9797 ?(semicolon=true) name style =
9798 if privat then pr "private ";
9799 if public then pr "public ";
9800 if native then pr "native ";
9803 (match fst style with
9804 | RErr -> pr "void ";
9805 | RInt _ -> pr "int ";
9806 | RInt64 _ -> pr "long ";
9807 | RBool _ -> pr "boolean ";
9808 | RConstString _ | RConstOptString _ | RString _
9809 | RBufferOut _ -> pr "String ";
9810 | RStringList _ -> pr "String[] ";
9811 | RStruct (_, typ) ->
9812 let name = java_name_of_struct typ in
9814 | RStructList (_, typ) ->
9815 let name = java_name_of_struct typ in
9817 | RHashtable _ -> pr "HashMap<String,String> ";
9820 if native then pr "_%s " name else pr "%s " name;
9822 let needs_comma = ref false in
9831 if !needs_comma then pr ", ";
9832 needs_comma := true;
9836 | Device n | Dev_or_Path n
9842 | StringList n | DeviceList n ->
9853 pr " throws LibGuestFSException";
9854 if semicolon then pr ";"
9856 and generate_java_struct jtyp cols () =
9857 generate_header CStyle LGPLv2plus;
9860 package com.redhat.et.libguestfs;
9863 * Libguestfs %s structure.
9875 | name, FBuffer -> pr " public String %s;\n" name
9876 | name, (FBytes|FUInt64|FInt64) -> pr " public long %s;\n" name
9877 | name, (FUInt32|FInt32) -> pr " public int %s;\n" name
9878 | name, FChar -> pr " public char %s;\n" name
9879 | name, FOptPercent ->
9880 pr " /* The next field is [0..100] or -1 meaning 'not present': */\n";
9881 pr " public float %s;\n" name
9886 and generate_java_c () =
9887 generate_header CStyle LGPLv2plus;
9894 #include \"com_redhat_et_libguestfs_GuestFS.h\"
9895 #include \"guestfs.h\"
9897 /* Note that this function returns. The exception is not thrown
9898 * until after the wrapper function returns.
9901 throw_exception (JNIEnv *env, const char *msg)
9904 cl = (*env)->FindClass (env,
9905 \"com/redhat/et/libguestfs/LibGuestFSException\");
9906 (*env)->ThrowNew (env, cl, msg);
9909 JNIEXPORT jlong JNICALL
9910 Java_com_redhat_et_libguestfs_GuestFS__1create
9911 (JNIEnv *env, jobject obj)
9915 g = guestfs_create ();
9917 throw_exception (env, \"GuestFS.create: failed to allocate handle\");
9920 guestfs_set_error_handler (g, NULL, NULL);
9921 return (jlong) (long) g;
9924 JNIEXPORT void JNICALL
9925 Java_com_redhat_et_libguestfs_GuestFS__1close
9926 (JNIEnv *env, jobject obj, jlong jg)
9928 guestfs_h *g = (guestfs_h *) (long) jg;
9935 fun (name, style, _, _, _, _, _) ->
9937 (match fst style with
9938 | RErr -> pr "void ";
9939 | RInt _ -> pr "jint ";
9940 | RInt64 _ -> pr "jlong ";
9941 | RBool _ -> pr "jboolean ";
9942 | RConstString _ | RConstOptString _ | RString _
9943 | RBufferOut _ -> pr "jstring ";
9944 | RStruct _ | RHashtable _ ->
9946 | RStringList _ | RStructList _ ->
9950 pr "Java_com_redhat_et_libguestfs_GuestFS_";
9951 pr "%s" (replace_str ("_" ^ name) "_" "_1");
9953 pr " (JNIEnv *env, jobject obj, jlong jg";
9957 | Device n | Dev_or_Path n
9962 pr ", jstring j%s" n
9963 | StringList n | DeviceList n ->
9964 pr ", jobjectArray j%s" n
9966 pr ", jboolean j%s" n
9974 pr " guestfs_h *g = (guestfs_h *) (long) jg;\n";
9975 let error_code, no_ret =
9976 match fst style with
9977 | RErr -> pr " int r;\n"; "-1", ""
9979 | RInt _ -> pr " int r;\n"; "-1", "0"
9980 | RInt64 _ -> pr " int64_t r;\n"; "-1", "0"
9981 | RConstString _ -> pr " const char *r;\n"; "NULL", "NULL"
9982 | RConstOptString _ -> pr " const char *r;\n"; "NULL", "NULL"
9984 pr " jstring jr;\n";
9985 pr " char *r;\n"; "NULL", "NULL"
9987 pr " jobjectArray jr;\n";
9990 pr " jstring jstr;\n";
9991 pr " char **r;\n"; "NULL", "NULL"
9992 | RStruct (_, typ) ->
9993 pr " jobject jr;\n";
9995 pr " jfieldID fl;\n";
9996 pr " struct guestfs_%s *r;\n" typ; "NULL", "NULL"
9997 | RStructList (_, typ) ->
9998 pr " jobjectArray jr;\n";
10000 pr " jfieldID fl;\n";
10001 pr " jobject jfl;\n";
10002 pr " struct guestfs_%s_list *r;\n" typ; "NULL", "NULL"
10003 | RHashtable _ -> pr " char **r;\n"; "NULL", "NULL"
10005 pr " jstring jr;\n";
10007 pr " size_t size;\n";
10012 | Device n | Dev_or_Path n
10017 pr " const char *%s;\n" n
10018 | StringList n | DeviceList n ->
10019 pr " int %s_len;\n" n;
10020 pr " const char **%s;\n" n
10025 pr " int64_t %s;\n" n
10029 (match fst style with
10030 | RStringList _ | RStructList _ -> true
10031 | RErr | RBool _ | RInt _ | RInt64 _ | RConstString _
10032 | RConstOptString _
10033 | RString _ | RBufferOut _ | RStruct _ | RHashtable _ -> false) ||
10034 List.exists (function
10035 | StringList _ -> true
10036 | DeviceList _ -> true
10037 | _ -> false) (snd style) in
10043 (* Get the parameters. *)
10047 | Device n | Dev_or_Path n
10051 pr " %s = (*env)->GetStringUTFChars (env, j%s, NULL);\n" n n
10053 (* This is completely undocumented, but Java null becomes
10054 * a NULL parameter.
10056 pr " %s = j%s ? (*env)->GetStringUTFChars (env, j%s, NULL) : NULL;\n" n n n
10057 | StringList n | DeviceList n ->
10058 pr " %s_len = (*env)->GetArrayLength (env, j%s);\n" n n;
10059 pr " %s = guestfs_safe_malloc (g, sizeof (char *) * (%s_len+1));\n" n n;
10060 pr " for (i = 0; i < %s_len; ++i) {\n" n;
10061 pr " jobject o = (*env)->GetObjectArrayElement (env, j%s, i);\n"
10063 pr " %s[i] = (*env)->GetStringUTFChars (env, o, NULL);\n" n;
10065 pr " %s[%s_len] = NULL;\n" n n;
10069 pr " %s = j%s;\n" n n
10072 (* Make the call. *)
10073 pr " r = guestfs_%s " name;
10074 generate_c_call_args ~handle:"g" style;
10077 (* Release the parameters. *)
10081 | Device n | Dev_or_Path n
10085 pr " (*env)->ReleaseStringUTFChars (env, j%s, %s);\n" n n
10087 pr " if (j%s)\n" n;
10088 pr " (*env)->ReleaseStringUTFChars (env, j%s, %s);\n" n n
10089 | StringList n | DeviceList n ->
10090 pr " for (i = 0; i < %s_len; ++i) {\n" n;
10091 pr " jobject o = (*env)->GetObjectArrayElement (env, j%s, i);\n"
10093 pr " (*env)->ReleaseStringUTFChars (env, o, %s[i]);\n" n;
10095 pr " free (%s);\n" n
10101 (* Check for errors. *)
10102 pr " if (r == %s) {\n" error_code;
10103 pr " throw_exception (env, guestfs_last_error (g));\n";
10104 pr " return %s;\n" no_ret;
10107 (* Return value. *)
10108 (match fst style with
10110 | RInt _ -> pr " return (jint) r;\n"
10111 | RBool _ -> pr " return (jboolean) r;\n"
10112 | RInt64 _ -> pr " return (jlong) r;\n"
10113 | RConstString _ -> pr " return (*env)->NewStringUTF (env, r);\n"
10114 | RConstOptString _ ->
10115 pr " return (*env)->NewStringUTF (env, r); /* XXX r NULL? */\n"
10117 pr " jr = (*env)->NewStringUTF (env, r);\n";
10121 pr " for (r_len = 0; r[r_len] != NULL; ++r_len) ;\n";
10122 pr " cl = (*env)->FindClass (env, \"java/lang/String\");\n";
10123 pr " jstr = (*env)->NewStringUTF (env, \"\");\n";
10124 pr " jr = (*env)->NewObjectArray (env, r_len, cl, jstr);\n";
10125 pr " for (i = 0; i < r_len; ++i) {\n";
10126 pr " jstr = (*env)->NewStringUTF (env, r[i]);\n";
10127 pr " (*env)->SetObjectArrayElement (env, jr, i, jstr);\n";
10128 pr " free (r[i]);\n";
10132 | RStruct (_, typ) ->
10133 let jtyp = java_name_of_struct typ in
10134 let cols = cols_of_struct typ in
10135 generate_java_struct_return typ jtyp cols
10136 | RStructList (_, typ) ->
10137 let jtyp = java_name_of_struct typ in
10138 let cols = cols_of_struct typ in
10139 generate_java_struct_list_return typ jtyp cols
10142 pr " throw_exception (env, \"%s: internal error: please let us know how to make a Java HashMap from JNI bindings!\");\n" name;
10143 pr " return NULL;\n"
10145 pr " jr = (*env)->NewStringUTF (env, r); /* XXX size */\n";
10154 and generate_java_struct_return typ jtyp cols =
10155 pr " cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/%s\");\n" jtyp;
10156 pr " jr = (*env)->AllocObject (env, cl);\n";
10160 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
10161 pr " (*env)->SetObjectField (env, jr, fl, (*env)->NewStringUTF (env, r->%s));\n" name;
10164 pr " char s[33];\n";
10165 pr " memcpy (s, r->%s, 32);\n" name;
10166 pr " s[32] = 0;\n";
10167 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
10168 pr " (*env)->SetObjectField (env, jr, fl, (*env)->NewStringUTF (env, s));\n";
10172 pr " int len = r->%s_len;\n" name;
10173 pr " char s[len+1];\n";
10174 pr " memcpy (s, r->%s, len);\n" name;
10175 pr " s[len] = 0;\n";
10176 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
10177 pr " (*env)->SetObjectField (env, jr, fl, (*env)->NewStringUTF (env, s));\n";
10179 | name, (FBytes|FUInt64|FInt64) ->
10180 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"J\");\n" name;
10181 pr " (*env)->SetLongField (env, jr, fl, r->%s);\n" name;
10182 | name, (FUInt32|FInt32) ->
10183 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"I\");\n" name;
10184 pr " (*env)->SetLongField (env, jr, fl, r->%s);\n" name;
10185 | name, FOptPercent ->
10186 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"F\");\n" name;
10187 pr " (*env)->SetFloatField (env, jr, fl, r->%s);\n" name;
10189 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"C\");\n" name;
10190 pr " (*env)->SetLongField (env, jr, fl, r->%s);\n" name;
10195 and generate_java_struct_list_return typ jtyp cols =
10196 pr " cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/%s\");\n" jtyp;
10197 pr " jr = (*env)->NewObjectArray (env, r->len, cl, NULL);\n";
10198 pr " for (i = 0; i < r->len; ++i) {\n";
10199 pr " jfl = (*env)->AllocObject (env, cl);\n";
10203 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
10204 pr " (*env)->SetObjectField (env, jfl, fl, (*env)->NewStringUTF (env, r->val[i].%s));\n" name;
10207 pr " char s[33];\n";
10208 pr " memcpy (s, r->val[i].%s, 32);\n" name;
10209 pr " s[32] = 0;\n";
10210 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
10211 pr " (*env)->SetObjectField (env, jfl, fl, (*env)->NewStringUTF (env, s));\n";
10215 pr " int len = r->val[i].%s_len;\n" name;
10216 pr " char s[len+1];\n";
10217 pr " memcpy (s, r->val[i].%s, len);\n" name;
10218 pr " s[len] = 0;\n";
10219 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
10220 pr " (*env)->SetObjectField (env, jfl, fl, (*env)->NewStringUTF (env, s));\n";
10222 | name, (FBytes|FUInt64|FInt64) ->
10223 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"J\");\n" name;
10224 pr " (*env)->SetLongField (env, jfl, fl, r->val[i].%s);\n" name;
10225 | name, (FUInt32|FInt32) ->
10226 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"I\");\n" name;
10227 pr " (*env)->SetLongField (env, jfl, fl, r->val[i].%s);\n" name;
10228 | name, FOptPercent ->
10229 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"F\");\n" name;
10230 pr " (*env)->SetFloatField (env, jfl, fl, r->val[i].%s);\n" name;
10232 pr " fl = (*env)->GetFieldID (env, cl, \"%s\", \"C\");\n" name;
10233 pr " (*env)->SetLongField (env, jfl, fl, r->val[i].%s);\n" name;
10235 pr " (*env)->SetObjectArrayElement (env, jfl, i, jfl);\n";
10237 pr " guestfs_free_%s_list (r);\n" typ;
10240 and generate_java_makefile_inc () =
10241 generate_header HashStyle GPLv2plus;
10243 pr "java_built_sources = \\\n";
10246 pr "\tcom/redhat/et/libguestfs/%s.java \\\n" jtyp;
10248 pr "\tcom/redhat/et/libguestfs/GuestFS.java\n"
10250 and generate_haskell_hs () =
10251 generate_header HaskellStyle LGPLv2plus;
10253 (* XXX We only know how to generate partial FFI for Haskell
10254 * at the moment. Please help out!
10256 let can_generate style =
10260 | RInt64 _, _ -> true
10262 | RConstString _, _
10263 | RConstOptString _, _
10269 | RBufferOut _, _ -> false in
10272 {-# INCLUDE <guestfs.h> #-}
10273 {-# LANGUAGE ForeignFunctionInterface #-}
10278 (* List out the names of the actions we want to export. *)
10280 fun (name, style, _, _, _, _, _) ->
10281 if can_generate style then pr ",\n %s" name
10287 -- Unfortunately some symbols duplicate ones already present
10288 -- in Prelude. We don't know which, so we hard-code a list
10290 import Prelude hiding (truncate)
10294 import Foreign.C.Types
10296 import Control.Exception
10297 import Data.Typeable
10299 data GuestfsS = GuestfsS -- represents the opaque C struct
10300 type GuestfsP = Ptr GuestfsS -- guestfs_h *
10301 type GuestfsH = ForeignPtr GuestfsS -- guestfs_h * with attached finalizer
10303 -- XXX define properly later XXX
10307 data IntBool = IntBool
10309 data StatVFS = StatVFS
10310 data Hashtable = Hashtable
10312 foreign import ccall unsafe \"guestfs_create\" c_create
10314 foreign import ccall unsafe \"&guestfs_close\" c_close
10315 :: FunPtr (GuestfsP -> IO ())
10316 foreign import ccall unsafe \"guestfs_set_error_handler\" c_set_error_handler
10317 :: GuestfsP -> Ptr CInt -> Ptr CInt -> IO ()
10319 create :: IO GuestfsH
10322 c_set_error_handler p nullPtr nullPtr
10323 h <- newForeignPtr c_close p
10326 foreign import ccall unsafe \"guestfs_last_error\" c_last_error
10327 :: GuestfsP -> IO CString
10329 -- last_error :: GuestfsH -> IO (Maybe String)
10330 -- last_error h = do
10331 -- str <- withForeignPtr h (\\p -> c_last_error p)
10332 -- maybePeek peekCString str
10334 last_error :: GuestfsH -> IO (String)
10336 str <- withForeignPtr h (\\p -> c_last_error p)
10337 if (str == nullPtr)
10338 then return \"no error\"
10339 else peekCString str
10343 (* Generate wrappers for each foreign function. *)
10345 fun (name, style, _, _, _, _, _) ->
10346 if can_generate style then (
10347 pr "foreign import ccall unsafe \"guestfs_%s\" c_%s\n" name name;
10349 generate_haskell_prototype ~handle:"GuestfsP" style;
10353 generate_haskell_prototype ~handle:"GuestfsH" ~hs:true style;
10355 pr "%s %s = do\n" name
10356 (String.concat " " ("h" :: List.map name_of_argt (snd style)));
10358 (* Convert pointer arguments using with* functions. *)
10363 | Pathname n | Device n | Dev_or_Path n | String n -> pr "withCString %s $ \\%s -> " n n
10364 | OptString n -> pr "maybeWith withCString %s $ \\%s -> " n n
10365 | StringList n | DeviceList n -> pr "withMany withCString %s $ \\%s -> withArray0 nullPtr %s $ \\%s -> " n n n n
10366 | Bool _ | Int _ | Int64 _ -> ()
10368 (* Convert integer arguments. *)
10372 | Bool n -> sprintf "(fromBool %s)" n
10373 | Int n -> sprintf "(fromIntegral %s)" n
10374 | Int64 n -> sprintf "(fromIntegral %s)" n
10375 | FileIn n | FileOut n
10376 | Pathname n | Device n | Dev_or_Path n | String n | OptString n | StringList n | DeviceList n -> n
10378 pr "withForeignPtr h (\\p -> c_%s %s)\n" name
10379 (String.concat " " ("p" :: args));
10380 (match fst style with
10381 | RErr | RInt _ | RInt64 _ | RBool _ ->
10382 pr " if (r == -1)\n";
10384 pr " err <- last_error h\n";
10386 | RConstString _ | RConstOptString _ | RString _
10387 | RStringList _ | RStruct _
10388 | RStructList _ | RHashtable _ | RBufferOut _ ->
10389 pr " if (r == nullPtr)\n";
10391 pr " err <- last_error h\n";
10394 (match fst style with
10396 pr " else return ()\n"
10398 pr " else return (fromIntegral r)\n"
10400 pr " else return (fromIntegral r)\n"
10402 pr " else return (toBool r)\n"
10404 | RConstOptString _
10411 pr " else return ()\n" (* XXXXXXXXXXXXXXXXXXXX *)
10417 and generate_haskell_prototype ~handle ?(hs = false) style =
10418 pr "%s -> " handle;
10419 let string = if hs then "String" else "CString" in
10420 let int = if hs then "Int" else "CInt" in
10421 let bool = if hs then "Bool" else "CInt" in
10422 let int64 = if hs then "Integer" else "Int64" in
10426 | Pathname _ | Device _ | Dev_or_Path _ | String _ -> pr "%s" string
10427 | OptString _ -> if hs then pr "Maybe String" else pr "CString"
10428 | StringList _ | DeviceList _ -> if hs then pr "[String]" else pr "Ptr CString"
10429 | Bool _ -> pr "%s" bool
10430 | Int _ -> pr "%s" int
10431 | Int64 _ -> pr "%s" int
10432 | FileIn _ -> pr "%s" string
10433 | FileOut _ -> pr "%s" string
10438 (match fst style with
10439 | RErr -> if not hs then pr "CInt"
10440 | RInt _ -> pr "%s" int
10441 | RInt64 _ -> pr "%s" int64
10442 | RBool _ -> pr "%s" bool
10443 | RConstString _ -> pr "%s" string
10444 | RConstOptString _ -> pr "Maybe %s" string
10445 | RString _ -> pr "%s" string
10446 | RStringList _ -> pr "[%s]" string
10447 | RStruct (_, typ) ->
10448 let name = java_name_of_struct typ in
10450 | RStructList (_, typ) ->
10451 let name = java_name_of_struct typ in
10453 | RHashtable _ -> pr "Hashtable"
10454 | RBufferOut _ -> pr "%s" string
10458 and generate_csharp () =
10459 generate_header CPlusPlusStyle LGPLv2plus;
10461 (* XXX Make this configurable by the C# assembly users. *)
10462 let library = "libguestfs.so.0" in
10465 // These C# bindings are highly experimental at present.
10467 // Firstly they only work on Linux (ie. Mono). In order to get them
10468 // to work on Windows (ie. .Net) you would need to port the library
10469 // itself to Windows first.
10471 // The second issue is that some calls are known to be incorrect and
10472 // can cause Mono to segfault. Particularly: calls which pass or
10473 // return string[], or return any structure value. This is because
10474 // we haven't worked out the correct way to do this from C#.
10476 // The third issue is that when compiling you get a lot of warnings.
10477 // We are not sure whether the warnings are important or not.
10479 // Fourthly we do not routinely build or test these bindings as part
10480 // of the make && make check cycle, which means that regressions might
10483 // Suggestions and patches are welcome.
10487 // gmcs Libguestfs.cs
10488 // mono Libguestfs.exe
10490 // (You'll probably want to add a Test class / static main function
10491 // otherwise this won't do anything useful).
10495 using System.Runtime.InteropServices;
10496 using System.Runtime.Serialization;
10497 using System.Collections;
10501 class Error : System.ApplicationException
10503 public Error (string message) : base (message) {}
10504 protected Error (SerializationInfo info, StreamingContext context) {}
10511 [DllImport (\"%s\")]
10512 static extern IntPtr guestfs_create ();
10516 _handle = guestfs_create ();
10517 if (_handle == IntPtr.Zero)
10518 throw new Error (\"could not create guestfs handle\");
10521 [DllImport (\"%s\")]
10522 static extern void guestfs_close (IntPtr h);
10526 guestfs_close (_handle);
10529 [DllImport (\"%s\")]
10530 static extern string guestfs_last_error (IntPtr h);
10532 " library library library;
10534 (* Generate C# structure bindings. We prefix struct names with
10535 * underscore because C# cannot have conflicting struct names and
10536 * method names (eg. "class stat" and "stat").
10540 pr " [StructLayout (LayoutKind.Sequential)]\n";
10541 pr " public class _%s {\n" typ;
10544 | name, FChar -> pr " char %s;\n" name
10545 | name, FString -> pr " string %s;\n" name
10547 pr " uint %s_len;\n" name;
10548 pr " string %s;\n" name
10550 pr " [MarshalAs (UnmanagedType.ByValTStr, SizeConst=16)]\n";
10551 pr " string %s;\n" name
10552 | name, FUInt32 -> pr " uint %s;\n" name
10553 | name, FInt32 -> pr " int %s;\n" name
10554 | name, (FUInt64|FBytes) -> pr " ulong %s;\n" name
10555 | name, FInt64 -> pr " long %s;\n" name
10556 | name, FOptPercent -> pr " float %s; /* [0..100] or -1 */\n" name
10562 (* Generate C# function bindings. *)
10564 fun (name, style, _, _, _, shortdesc, _) ->
10565 let rec csharp_return_type () =
10566 match fst style with
10568 | RBool n -> "bool"
10570 | RInt64 n -> "long"
10572 | RConstOptString n
10574 | RBufferOut n -> "string"
10575 | RStruct (_,n) -> "_" ^ n
10576 | RHashtable n -> "Hashtable"
10577 | RStringList n -> "string[]"
10578 | RStructList (_,n) -> sprintf "_%s[]" n
10580 and c_return_type () =
10581 match fst style with
10585 | RInt64 _ -> "long"
10587 | RConstOptString _
10589 | RBufferOut _ -> "string"
10590 | RStruct (_,n) -> "_" ^ n
10592 | RStringList _ -> "string[]"
10593 | RStructList (_,n) -> sprintf "_%s[]" n
10595 and c_error_comparison () =
10596 match fst style with
10600 | RInt64 _ -> "== -1"
10602 | RConstOptString _
10608 | RStructList (_,_) -> "== null"
10610 and generate_extern_prototype () =
10611 pr " static extern %s guestfs_%s (IntPtr h"
10612 (c_return_type ()) name;
10615 | Pathname n | Device n | Dev_or_Path n | String n | OptString n
10616 | FileIn n | FileOut n ->
10617 pr ", [In] string %s" n
10618 | StringList n | DeviceList n ->
10619 pr ", [In] string[] %s" n
10629 and generate_public_prototype () =
10630 pr " public %s %s (" (csharp_return_type ()) name;
10631 let comma = ref false in
10633 if !comma then pr ", ";
10638 | Pathname n | Device n | Dev_or_Path n | String n | OptString n
10639 | FileIn n | FileOut n ->
10640 next (); pr "string %s" n
10641 | StringList n | DeviceList n ->
10642 next (); pr "string[] %s" n
10644 next (); pr "bool %s" n
10646 next (); pr "int %s" n
10648 next (); pr "long %s" n
10652 and generate_call () =
10653 pr "guestfs_%s (_handle" name;
10654 List.iter (fun arg -> pr ", %s" (name_of_argt arg)) (snd style);
10658 pr " [DllImport (\"%s\")]\n" library;
10659 generate_extern_prototype ();
10661 pr " /// <summary>\n";
10662 pr " /// %s\n" shortdesc;
10663 pr " /// </summary>\n";
10664 generate_public_prototype ();
10666 pr " %s r;\n" (c_return_type ());
10669 pr " if (r %s)\n" (c_error_comparison ());
10670 pr " throw new Error (guestfs_last_error (_handle));\n";
10671 (match fst style with
10674 pr " return r != 0 ? true : false;\n"
10676 pr " Hashtable rr = new Hashtable ();\n";
10677 pr " for (int i = 0; i < r.Length; i += 2)\n";
10678 pr " rr.Add (r[i], r[i+1]);\n";
10680 | RInt _ | RInt64 _ | RConstString _ | RConstOptString _
10681 | RString _ | RBufferOut _ | RStruct _ | RStringList _
10687 ) all_functions_sorted;
10693 and generate_bindtests () =
10694 generate_header CStyle LGPLv2plus;
10698 #include <stdlib.h>
10699 #include <inttypes.h>
10700 #include <string.h>
10702 #include \"guestfs.h\"
10703 #include \"guestfs-internal.h\"
10704 #include \"guestfs-internal-actions.h\"
10705 #include \"guestfs_protocol.h\"
10707 #define error guestfs_error
10708 #define safe_calloc guestfs_safe_calloc
10709 #define safe_malloc guestfs_safe_malloc
10712 print_strings (char *const *argv)
10717 for (argc = 0; argv[argc] != NULL; ++argc) {
10718 if (argc > 0) printf (\", \");
10719 printf (\"\\\"%%s\\\"\", argv[argc]);
10724 /* The test0 function prints its parameters to stdout. */
10728 match test_functions with
10729 | [] -> assert false
10730 | test0 :: tests -> test0, tests in
10733 let (name, style, _, _, _, _, _) = test0 in
10734 generate_prototype ~extern:false ~semicolon:false ~newline:true
10735 ~handle:"g" ~prefix:"guestfs__" name style;
10740 | Device n | Dev_or_Path n
10743 | FileOut n -> pr " printf (\"%%s\\n\", %s);\n" n
10744 | OptString n -> pr " printf (\"%%s\\n\", %s ? %s : \"null\");\n" n n
10745 | StringList n | DeviceList n -> pr " print_strings (%s);\n" n
10746 | Bool n -> pr " printf (\"%%s\\n\", %s ? \"true\" : \"false\");\n" n
10747 | Int n -> pr " printf (\"%%d\\n\", %s);\n" n
10748 | Int64 n -> pr " printf (\"%%\" PRIi64 \"\\n\", %s);\n" n
10750 pr " /* Java changes stdout line buffering so we need this: */\n";
10751 pr " fflush (stdout);\n";
10757 fun (name, style, _, _, _, _, _) ->
10758 if String.sub name (String.length name - 3) 3 <> "err" then (
10759 pr "/* Test normal return. */\n";
10760 generate_prototype ~extern:false ~semicolon:false ~newline:true
10761 ~handle:"g" ~prefix:"guestfs__" name style;
10763 (match fst style with
10768 pr " sscanf (val, \"%%d\", &r);\n";
10771 pr " int64_t r;\n";
10772 pr " sscanf (val, \"%%\" SCNi64, &r);\n";
10775 pr " return STREQ (val, \"true\");\n"
10777 | RConstOptString _ ->
10778 (* Can't return the input string here. Return a static
10779 * string so we ensure we get a segfault if the caller
10780 * tries to free it.
10782 pr " return \"static string\";\n"
10784 pr " return strdup (val);\n"
10786 pr " char **strs;\n";
10788 pr " sscanf (val, \"%%d\", &n);\n";
10789 pr " strs = safe_malloc (g, (n+1) * sizeof (char *));\n";
10790 pr " for (i = 0; i < n; ++i) {\n";
10791 pr " strs[i] = safe_malloc (g, 16);\n";
10792 pr " snprintf (strs[i], 16, \"%%d\", i);\n";
10794 pr " strs[n] = NULL;\n";
10795 pr " return strs;\n"
10796 | RStruct (_, typ) ->
10797 pr " struct guestfs_%s *r;\n" typ;
10798 pr " r = safe_calloc (g, sizeof *r, 1);\n";
10800 | RStructList (_, typ) ->
10801 pr " struct guestfs_%s_list *r;\n" typ;
10802 pr " r = safe_calloc (g, sizeof *r, 1);\n";
10803 pr " sscanf (val, \"%%d\", &r->len);\n";
10804 pr " r->val = safe_calloc (g, r->len, sizeof *r->val);\n";
10807 pr " char **strs;\n";
10809 pr " sscanf (val, \"%%d\", &n);\n";
10810 pr " strs = safe_malloc (g, (n*2+1) * sizeof (*strs));\n";
10811 pr " for (i = 0; i < n; ++i) {\n";
10812 pr " strs[i*2] = safe_malloc (g, 16);\n";
10813 pr " strs[i*2+1] = safe_malloc (g, 16);\n";
10814 pr " snprintf (strs[i*2], 16, \"%%d\", i);\n";
10815 pr " snprintf (strs[i*2+1], 16, \"%%d\", i);\n";
10817 pr " strs[n*2] = NULL;\n";
10818 pr " return strs;\n"
10820 pr " return strdup (val);\n"
10825 pr "/* Test error return. */\n";
10826 generate_prototype ~extern:false ~semicolon:false ~newline:true
10827 ~handle:"g" ~prefix:"guestfs__" name style;
10829 pr " error (g, \"error\");\n";
10830 (match fst style with
10831 | RErr | RInt _ | RInt64 _ | RBool _ ->
10833 | RConstString _ | RConstOptString _
10834 | RString _ | RStringList _ | RStruct _
10838 pr " return NULL;\n"
10845 and generate_ocaml_bindtests () =
10846 generate_header OCamlStyle GPLv2plus;
10850 let g = Guestfs.create () in
10854 String.concat " " (
10857 | CallString s -> "\"" ^ s ^ "\""
10858 | CallOptString None -> "None"
10859 | CallOptString (Some s) -> sprintf "(Some \"%s\")" s
10860 | CallStringList xs ->
10861 "[|" ^ String.concat ";" (List.map (sprintf "\"%s\"") xs) ^ "|]"
10862 | CallInt i when i >= 0 -> string_of_int i
10863 | CallInt i (* when i < 0 *) -> "(" ^ string_of_int i ^ ")"
10864 | CallInt64 i when i >= 0L -> Int64.to_string i ^ "L"
10865 | CallInt64 i (* when i < 0L *) -> "(" ^ Int64.to_string i ^ "L)"
10866 | CallBool b -> string_of_bool b
10871 generate_lang_bindtests (
10872 fun f args -> pr " Guestfs.%s g %s;\n" f (mkargs args)
10875 pr "print_endline \"EOF\"\n"
10877 and generate_perl_bindtests () =
10878 pr "#!/usr/bin/perl -w\n";
10879 generate_header HashStyle GPLv2plus;
10886 my $g = Sys::Guestfs->new ();
10890 String.concat ", " (
10893 | CallString s -> "\"" ^ s ^ "\""
10894 | CallOptString None -> "undef"
10895 | CallOptString (Some s) -> sprintf "\"%s\"" s
10896 | CallStringList xs ->
10897 "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
10898 | CallInt i -> string_of_int i
10899 | CallInt64 i -> Int64.to_string i
10900 | CallBool b -> if b then "1" else "0"
10905 generate_lang_bindtests (
10906 fun f args -> pr "$g->%s (%s);\n" f (mkargs args)
10909 pr "print \"EOF\\n\"\n"
10911 and generate_python_bindtests () =
10912 generate_header HashStyle GPLv2plus;
10917 g = guestfs.GuestFS ()
10921 String.concat ", " (
10924 | CallString s -> "\"" ^ s ^ "\""
10925 | CallOptString None -> "None"
10926 | CallOptString (Some s) -> sprintf "\"%s\"" s
10927 | CallStringList xs ->
10928 "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
10929 | CallInt i -> string_of_int i
10930 | CallInt64 i -> Int64.to_string i
10931 | CallBool b -> if b then "1" else "0"
10936 generate_lang_bindtests (
10937 fun f args -> pr "g.%s (%s)\n" f (mkargs args)
10940 pr "print \"EOF\"\n"
10942 and generate_ruby_bindtests () =
10943 generate_header HashStyle GPLv2plus;
10948 g = Guestfs::create()
10952 String.concat ", " (
10955 | CallString s -> "\"" ^ s ^ "\""
10956 | CallOptString None -> "nil"
10957 | CallOptString (Some s) -> sprintf "\"%s\"" s
10958 | CallStringList xs ->
10959 "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
10960 | CallInt i -> string_of_int i
10961 | CallInt64 i -> Int64.to_string i
10962 | CallBool b -> string_of_bool b
10967 generate_lang_bindtests (
10968 fun f args -> pr "g.%s(%s)\n" f (mkargs args)
10971 pr "print \"EOF\\n\"\n"
10973 and generate_java_bindtests () =
10974 generate_header CStyle GPLv2plus;
10977 import com.redhat.et.libguestfs.*;
10979 public class Bindtests {
10980 public static void main (String[] argv)
10983 GuestFS g = new GuestFS ();
10987 String.concat ", " (
10990 | CallString s -> "\"" ^ s ^ "\""
10991 | CallOptString None -> "null"
10992 | CallOptString (Some s) -> sprintf "\"%s\"" s
10993 | CallStringList xs ->
10995 String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "}"
10996 | CallInt i -> string_of_int i
10997 | CallInt64 i -> Int64.to_string i
10998 | CallBool b -> string_of_bool b
11003 generate_lang_bindtests (
11004 fun f args -> pr " g.%s (%s);\n" f (mkargs args)
11008 System.out.println (\"EOF\");
11010 catch (Exception exn) {
11011 System.err.println (exn);
11018 and generate_haskell_bindtests () =
11019 generate_header HaskellStyle GPLv2plus;
11022 module Bindtests where
11023 import qualified Guestfs
11026 g <- Guestfs.create
11030 String.concat " " (
11033 | CallString s -> "\"" ^ s ^ "\""
11034 | CallOptString None -> "Nothing"
11035 | CallOptString (Some s) -> sprintf "(Just \"%s\")" s
11036 | CallStringList xs ->
11037 "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
11038 | CallInt i when i < 0 -> "(" ^ string_of_int i ^ ")"
11039 | CallInt i -> string_of_int i
11040 | CallInt64 i when i < 0L -> "(" ^ Int64.to_string i ^ ")"
11041 | CallInt64 i -> Int64.to_string i
11042 | CallBool true -> "True"
11043 | CallBool false -> "False"
11048 generate_lang_bindtests (
11049 fun f args -> pr " Guestfs.%s g %s\n" f (mkargs args)
11052 pr " putStrLn \"EOF\"\n"
11054 (* Language-independent bindings tests - we do it this way to
11055 * ensure there is parity in testing bindings across all languages.
11057 and generate_lang_bindtests call =
11058 call "test0" [CallString "abc"; CallOptString (Some "def");
11059 CallStringList []; CallBool false;
11060 CallInt 0; CallInt64 0L; CallString "123"; CallString "456"];
11061 call "test0" [CallString "abc"; CallOptString None;
11062 CallStringList []; CallBool false;
11063 CallInt 0; CallInt64 0L; CallString "123"; CallString "456"];
11064 call "test0" [CallString ""; CallOptString (Some "def");
11065 CallStringList []; CallBool false;
11066 CallInt 0; CallInt64 0L; CallString "123"; CallString "456"];
11067 call "test0" [CallString ""; CallOptString (Some "");
11068 CallStringList []; CallBool false;
11069 CallInt 0; CallInt64 0L; CallString "123"; CallString "456"];
11070 call "test0" [CallString "abc"; CallOptString (Some "def");
11071 CallStringList ["1"]; CallBool false;
11072 CallInt 0; CallInt64 0L; CallString "123"; CallString "456"];
11073 call "test0" [CallString "abc"; CallOptString (Some "def");
11074 CallStringList ["1"; "2"]; CallBool false;
11075 CallInt 0; CallInt64 0L; CallString "123"; CallString "456"];
11076 call "test0" [CallString "abc"; CallOptString (Some "def");
11077 CallStringList ["1"]; CallBool true;
11078 CallInt 0; CallInt64 0L; CallString "123"; CallString "456"];
11079 call "test0" [CallString "abc"; CallOptString (Some "def");
11080 CallStringList ["1"]; CallBool false;
11081 CallInt (-1); CallInt64 (-1L); CallString "123"; CallString "456"];
11082 call "test0" [CallString "abc"; CallOptString (Some "def");
11083 CallStringList ["1"]; CallBool false;
11084 CallInt (-2); CallInt64 (-2L); CallString "123"; CallString "456"];
11085 call "test0" [CallString "abc"; CallOptString (Some "def");
11086 CallStringList ["1"]; CallBool false;
11087 CallInt 1; CallInt64 1L; CallString "123"; CallString "456"];
11088 call "test0" [CallString "abc"; CallOptString (Some "def");
11089 CallStringList ["1"]; CallBool false;
11090 CallInt 2; CallInt64 2L; CallString "123"; CallString "456"];
11091 call "test0" [CallString "abc"; CallOptString (Some "def");
11092 CallStringList ["1"]; CallBool false;
11093 CallInt 4095; CallInt64 4095L; CallString "123"; CallString "456"];
11094 call "test0" [CallString "abc"; CallOptString (Some "def");
11095 CallStringList ["1"]; CallBool false;
11096 CallInt 0; CallInt64 0L; CallString ""; CallString ""]
11098 (* XXX Add here tests of the return and error functions. *)
11100 (* Code to generator bindings for virt-inspector. Currently only
11101 * implemented for OCaml code (for virt-p2v 2.0).
11103 let rng_input = "inspector/virt-inspector.rng"
11105 (* Read the input file and parse it into internal structures. This is
11106 * by no means a complete RELAX NG parser, but is just enough to be
11107 * able to parse the specific input file.
11110 | Element of string * rng list (* <element name=name/> *)
11111 | Attribute of string * rng list (* <attribute name=name/> *)
11112 | Interleave of rng list (* <interleave/> *)
11113 | ZeroOrMore of rng (* <zeroOrMore/> *)
11114 | OneOrMore of rng (* <oneOrMore/> *)
11115 | Optional of rng (* <optional/> *)
11116 | Choice of string list (* <choice><value/>*</choice> *)
11117 | Value of string (* <value>str</value> *)
11118 | Text (* <text/> *)
11120 let rec string_of_rng = function
11121 | Element (name, xs) ->
11122 "Element (\"" ^ name ^ "\", (" ^ string_of_rng_list xs ^ "))"
11123 | Attribute (name, xs) ->
11124 "Attribute (\"" ^ name ^ "\", (" ^ string_of_rng_list xs ^ "))"
11125 | Interleave xs -> "Interleave (" ^ string_of_rng_list xs ^ ")"
11126 | ZeroOrMore rng -> "ZeroOrMore (" ^ string_of_rng rng ^ ")"
11127 | OneOrMore rng -> "OneOrMore (" ^ string_of_rng rng ^ ")"
11128 | Optional rng -> "Optional (" ^ string_of_rng rng ^ ")"
11129 | Choice values -> "Choice [" ^ String.concat ", " values ^ "]"
11130 | Value value -> "Value \"" ^ value ^ "\""
11133 and string_of_rng_list xs =
11134 String.concat ", " (List.map string_of_rng xs)
11136 let rec parse_rng ?defines context = function
11138 | Xml.Element ("element", ["name", name], children) :: rest ->
11139 Element (name, parse_rng ?defines context children)
11140 :: parse_rng ?defines context rest
11141 | Xml.Element ("attribute", ["name", name], children) :: rest ->
11142 Attribute (name, parse_rng ?defines context children)
11143 :: parse_rng ?defines context rest
11144 | Xml.Element ("interleave", [], children) :: rest ->
11145 Interleave (parse_rng ?defines context children)
11146 :: parse_rng ?defines context rest
11147 | Xml.Element ("zeroOrMore", [], [child]) :: rest ->
11148 let rng = parse_rng ?defines context [child] in
11150 | [child] -> ZeroOrMore child :: parse_rng ?defines context rest
11152 failwithf "%s: <zeroOrMore> contains more than one child element"
11155 | Xml.Element ("oneOrMore", [], [child]) :: rest ->
11156 let rng = parse_rng ?defines context [child] in
11158 | [child] -> OneOrMore child :: parse_rng ?defines context rest
11160 failwithf "%s: <oneOrMore> contains more than one child element"
11163 | Xml.Element ("optional", [], [child]) :: rest ->
11164 let rng = parse_rng ?defines context [child] in
11166 | [child] -> Optional child :: parse_rng ?defines context rest
11168 failwithf "%s: <optional> contains more than one child element"
11171 | Xml.Element ("choice", [], children) :: rest ->
11172 let values = List.map (
11173 function Xml.Element ("value", [], [Xml.PCData value]) -> value
11175 failwithf "%s: can't handle anything except <value> in <choice>"
11179 :: parse_rng ?defines context rest
11180 | Xml.Element ("value", [], [Xml.PCData value]) :: rest ->
11181 Value value :: parse_rng ?defines context rest
11182 | Xml.Element ("text", [], []) :: rest ->
11183 Text :: parse_rng ?defines context rest
11184 | Xml.Element ("ref", ["name", name], []) :: rest ->
11185 (* Look up the reference. Because of limitations in this parser,
11186 * we can't handle arbitrarily nested <ref> yet. You can only
11187 * use <ref> from inside <start>.
11189 (match defines with
11191 failwithf "%s: contains <ref>, but no refs are defined yet" context
11193 let rng = StringMap.find name map in
11194 rng @ parse_rng ?defines context rest
11197 failwithf "%s: can't handle '%s' in schema" context (Xml.to_string x)
11200 let xml = Xml.parse_file rng_input in
11202 | Xml.Element ("grammar", _,
11203 Xml.Element ("start", _, gram) :: defines) ->
11204 (* The <define/> elements are referenced in the <start> section,
11205 * so build a map of those first.
11207 let defines = List.fold_left (
11209 function Xml.Element ("define", ["name", name], defn) ->
11210 StringMap.add name defn map
11212 failwithf "%s: expected <define name=name/>" rng_input
11213 ) StringMap.empty defines in
11214 let defines = StringMap.mapi parse_rng defines in
11216 (* Parse the <start> clause, passing the defines. *)
11217 parse_rng ~defines "<start>" gram
11219 failwithf "%s: input is not <grammar><start/><define>*</grammar>"
11222 let name_of_field = function
11223 | Element (name, _) | Attribute (name, _)
11224 | ZeroOrMore (Element (name, _))
11225 | OneOrMore (Element (name, _))
11226 | Optional (Element (name, _)) -> name
11227 | Optional (Attribute (name, _)) -> name
11228 | Text -> (* an unnamed field in an element *)
11231 failwithf "name_of_field failed at: %s" (string_of_rng rng)
11233 (* At the moment this function only generates OCaml types. However we
11234 * should parameterize it later so it can generate types/structs in a
11235 * variety of languages.
11237 let generate_types xs =
11238 (* A simple type is one that can be printed out directly, eg.
11239 * "string option". A complex type is one which has a name and has
11240 * to be defined via another toplevel definition, eg. a struct.
11242 * generate_type generates code for either simple or complex types.
11243 * In the simple case, it returns the string ("string option"). In
11244 * the complex case, it returns the name ("mountpoint"). In the
11245 * complex case it has to print out the definition before returning,
11246 * so it should only be called when we are at the beginning of a
11247 * new line (BOL context).
11249 let rec generate_type = function
11250 | Text -> (* string *)
11252 | Choice values -> (* [`val1|`val2|...] *)
11253 "[" ^ String.concat "|" (List.map ((^)"`") values) ^ "]", true
11254 | ZeroOrMore rng -> (* <rng> list *)
11255 let t, is_simple = generate_type rng in
11256 t ^ " list (* 0 or more *)", is_simple
11257 | OneOrMore rng -> (* <rng> list *)
11258 let t, is_simple = generate_type rng in
11259 t ^ " list (* 1 or more *)", is_simple
11260 (* virt-inspector hack: bool *)
11261 | Optional (Attribute (name, [Value "1"])) ->
11263 | Optional rng -> (* <rng> list *)
11264 let t, is_simple = generate_type rng in
11265 t ^ " option", is_simple
11266 (* type name = { fields ... } *)
11267 | Element (name, fields) when is_attrs_interleave fields ->
11268 generate_type_struct name (get_attrs_interleave fields)
11269 | Element (name, [field]) (* type name = field *)
11270 | Attribute (name, [field]) ->
11271 let t, is_simple = generate_type field in
11272 if is_simple then (t, true)
11274 pr "type %s = %s\n" name t;
11277 | Element (name, fields) -> (* type name = { fields ... } *)
11278 generate_type_struct name fields
11280 failwithf "generate_type failed at: %s" (string_of_rng rng)
11282 and is_attrs_interleave = function
11283 | [Interleave _] -> true
11284 | Attribute _ :: fields -> is_attrs_interleave fields
11285 | Optional (Attribute _) :: fields -> is_attrs_interleave fields
11288 and get_attrs_interleave = function
11289 | [Interleave fields] -> fields
11290 | ((Attribute _) as field) :: fields
11291 | ((Optional (Attribute _)) as field) :: fields ->
11292 field :: get_attrs_interleave fields
11293 | _ -> assert false
11295 and generate_types xs =
11296 List.iter (fun x -> ignore (generate_type x)) xs
11298 and generate_type_struct name fields =
11299 (* Calculate the types of the fields first. We have to do this
11300 * before printing anything so we are still in BOL context.
11302 let types = List.map fst (List.map generate_type fields) in
11304 (* Special case of a struct containing just a string and another
11305 * field. Turn it into an assoc list.
11308 | ["string"; other] ->
11309 let fname1, fname2 =
11311 | [f1; f2] -> name_of_field f1, name_of_field f2
11312 | _ -> assert false in
11313 pr "type %s = string * %s (* %s -> %s *)\n" name other fname1 fname2;
11317 pr "type %s = {\n" name;
11319 fun (field, ftype) ->
11320 let fname = name_of_field field in
11321 pr " %s_%s : %s;\n" name fname ftype
11322 ) (List.combine fields types);
11324 (* Return the name of this type, and
11325 * false because it's not a simple type.
11332 let generate_parsers xs =
11333 (* As for generate_type above, generate_parser makes a parser for
11334 * some type, and returns the name of the parser it has generated.
11335 * Because it (may) need to print something, it should always be
11336 * called in BOL context.
11338 let rec generate_parser = function
11339 | Text -> (* string *)
11340 "string_child_or_empty"
11341 | Choice values -> (* [`val1|`val2|...] *)
11342 sprintf "(fun x -> match Xml.pcdata (first_child x) with %s | str -> failwith (\"unexpected field value: \" ^ str))"
11344 (List.map (fun v -> sprintf "%S -> `%s" v v) values))
11345 | ZeroOrMore rng -> (* <rng> list *)
11346 let pa = generate_parser rng in
11347 sprintf "(fun x -> List.map %s (Xml.children x))" pa
11348 | OneOrMore rng -> (* <rng> list *)
11349 let pa = generate_parser rng in
11350 sprintf "(fun x -> List.map %s (Xml.children x))" pa
11351 (* virt-inspector hack: bool *)
11352 | Optional (Attribute (name, [Value "1"])) ->
11353 sprintf "(fun x -> try ignore (Xml.attrib x %S); true with Xml.No_attribute _ -> false)" name
11354 | Optional rng -> (* <rng> list *)
11355 let pa = generate_parser rng in
11356 sprintf "(function None -> None | Some x -> Some (%s x))" pa
11357 (* type name = { fields ... } *)
11358 | Element (name, fields) when is_attrs_interleave fields ->
11359 generate_parser_struct name (get_attrs_interleave fields)
11360 | Element (name, [field]) -> (* type name = field *)
11361 let pa = generate_parser field in
11362 let parser_name = sprintf "parse_%s_%d" name (unique ()) in
11363 pr "let %s =\n" parser_name;
11365 pr "let parse_%s = %s\n" name parser_name;
11367 | Attribute (name, [field]) ->
11368 let pa = generate_parser field in
11369 let parser_name = sprintf "parse_%s_%d" name (unique ()) in
11370 pr "let %s =\n" parser_name;
11372 pr "let parse_%s = %s\n" name parser_name;
11374 | Element (name, fields) -> (* type name = { fields ... } *)
11375 generate_parser_struct name ([], fields)
11377 failwithf "generate_parser failed at: %s" (string_of_rng rng)
11379 and is_attrs_interleave = function
11380 | [Interleave _] -> true
11381 | Attribute _ :: fields -> is_attrs_interleave fields
11382 | Optional (Attribute _) :: fields -> is_attrs_interleave fields
11385 and get_attrs_interleave = function
11386 | [Interleave fields] -> [], fields
11387 | ((Attribute _) as field) :: fields
11388 | ((Optional (Attribute _)) as field) :: fields ->
11389 let attrs, interleaves = get_attrs_interleave fields in
11390 (field :: attrs), interleaves
11391 | _ -> assert false
11393 and generate_parsers xs =
11394 List.iter (fun x -> ignore (generate_parser x)) xs
11396 and generate_parser_struct name (attrs, interleaves) =
11397 (* Generate parsers for the fields first. We have to do this
11398 * before printing anything so we are still in BOL context.
11400 let fields = attrs @ interleaves in
11401 let pas = List.map generate_parser fields in
11403 (* Generate an intermediate tuple from all the fields first.
11404 * If the type is just a string + another field, then we will
11405 * return this directly, otherwise it is turned into a record.
11407 * RELAX NG note: This code treats <interleave> and plain lists of
11408 * fields the same. In other words, it doesn't bother enforcing
11409 * any ordering of fields in the XML.
11411 pr "let parse_%s x =\n" name;
11412 pr " let t = (\n ";
11413 let comma = ref false in
11416 if !comma then pr ",\n ";
11419 | Optional (Attribute (fname, [field])), pa ->
11421 | Optional (Element (fname, [field])), pa ->
11422 pr "%s (optional_child %S x)" pa fname
11423 | Attribute (fname, [Text]), _ ->
11424 pr "attribute %S x" fname
11425 | (ZeroOrMore _ | OneOrMore _), pa ->
11430 let fname = name_of_field field in
11431 pr "%s (child %S x)" pa fname
11432 ) (List.combine fields pas);
11436 | [Element (_, [Text]) | Attribute (_, [Text]); _] ->
11440 pr " (Obj.magic t : %s)\n" name
11444 | (Optional (Attribute (fname, [field])), pa) ->
11445 pr " %s_%s =\n" name fname;
11447 | (Optional (Element (fname, [field])), pa) ->
11448 pr " %s_%s =\n" name fname;
11449 pr " (let x = optional_child %S x in\n" fname;
11452 let fname = name_of_field field in
11453 pr " %s_%s =\n" name fname;
11454 pr " (let x = child %S x in\n" fname;
11456 ) (List.combine fields pas);
11460 sprintf "parse_%s" name
11463 generate_parsers xs
11465 (* Generate ocaml/guestfs_inspector.mli. *)
11466 let generate_ocaml_inspector_mli () =
11467 generate_header ~extra_inputs:[rng_input] OCamlStyle LGPLv2plus;
11470 (** This is an OCaml language binding to the external [virt-inspector]
11473 For more information, please read the man page [virt-inspector(1)].
11478 generate_types grammar;
11479 pr "(** The nested information returned from the {!inspect} function. *)\n";
11483 val inspect : ?connect:string -> ?xml:string -> string list -> operatingsystems
11484 (** To inspect a libvirt domain called [name], pass a singleton
11485 list: [inspect [name]]. When using libvirt only, you may
11486 optionally pass a libvirt URI using [inspect ~connect:uri ...].
11488 To inspect a disk image or images, pass a list of the filenames
11489 of the disk images: [inspect filenames]
11491 This function inspects the given guest or disk images and
11492 returns a list of operating system(s) found and a large amount
11493 of information about them. In the vast majority of cases,
11494 a virtual machine only contains a single operating system.
11496 If the optional [~xml] parameter is given, then this function
11497 skips running the external virt-inspector program and just
11498 parses the given XML directly (which is expected to be XML
11499 produced from a previous run of virt-inspector). The list of
11500 names and connect URI are ignored in this case.
11502 This function can throw a wide variety of exceptions, for example
11503 if the external virt-inspector program cannot be found, or if
11504 it doesn't generate valid XML.
11508 (* Generate ocaml/guestfs_inspector.ml. *)
11509 let generate_ocaml_inspector_ml () =
11510 generate_header ~extra_inputs:[rng_input] OCamlStyle LGPLv2plus;
11515 generate_types grammar;
11519 (* Misc functions which are used by the parser code below. *)
11520 let first_child = function
11521 | Xml.Element (_, _, c::_) -> c
11522 | Xml.Element (name, _, []) ->
11523 failwith (\"expected <\" ^ name ^ \"/> to have a child node\")
11524 | Xml.PCData str ->
11525 failwith (\"expected XML tag, but read PCDATA '\" ^ str ^ \"' instead\")
11527 let string_child_or_empty = function
11528 | Xml.Element (_, _, [Xml.PCData s]) -> s
11529 | Xml.Element (_, _, []) -> \"\"
11530 | Xml.Element (x, _, _) ->
11531 failwith (\"expected XML tag with a single PCDATA child, but got \" ^
11533 | Xml.PCData str ->
11534 failwith (\"expected XML tag, but read PCDATA '\" ^ str ^ \"' instead\")
11536 let optional_child name xml =
11537 let children = Xml.children xml in
11539 Some (List.find (function
11540 | Xml.Element (n, _, _) when n = name -> true
11541 | _ -> false) children)
11545 let child name xml =
11546 match optional_child name xml with
11549 failwith (\"mandatory field <\" ^ name ^ \"/> missing in XML output\")
11551 let attribute name xml =
11552 try Xml.attrib xml name
11553 with Xml.No_attribute _ ->
11554 failwith (\"mandatory attribute \" ^ name ^ \" missing in XML output\")
11558 generate_parsers grammar;
11562 (* Run external virt-inspector, then use parser to parse the XML. *)
11563 let inspect ?connect ?xml names =
11567 if names = [] then invalid_arg \"inspect: no names given\";
11568 let cmd = [ \"virt-inspector\"; \"--xml\" ] @
11569 (match connect with None -> [] | Some uri -> [ \"--connect\"; uri ]) @
11571 let cmd = List.map Filename.quote cmd in
11572 let cmd = String.concat \" \" cmd in
11573 let chan = open_process_in cmd in
11574 let xml = Xml.parse_in chan in
11575 (match close_process_in chan with
11577 | WEXITED _ -> failwith \"external virt-inspector command failed\"
11578 | WSIGNALED i | WSTOPPED i ->
11579 failwith (\"external virt-inspector command died or stopped on sig \" ^
11584 Xml.parse_string doc in
11585 parse_operatingsystems xml
11588 (* This is used to generate the src/MAX_PROC_NR file which
11589 * contains the maximum procedure number, a surrogate for the
11590 * ABI version number. See src/Makefile.am for the details.
11592 and generate_max_proc_nr () =
11593 let proc_nrs = List.map (
11594 fun (_, _, proc_nr, _, _, _, _) -> proc_nr
11595 ) daemon_functions in
11597 let max_proc_nr = List.fold_left max 0 proc_nrs in
11599 pr "%d\n" max_proc_nr
11601 let output_to filename k =
11602 let filename_new = filename ^ ".new" in
11603 chan := open_out filename_new;
11606 chan := Pervasives.stdout;
11608 (* Is the new file different from the current file? *)
11609 if Sys.file_exists filename && files_equal filename filename_new then
11610 unlink filename_new (* same, so skip it *)
11612 (* different, overwrite old one *)
11613 (try chmod filename 0o644 with Unix_error _ -> ());
11614 rename filename_new filename;
11615 chmod filename 0o444;
11616 printf "written %s\n%!" filename;
11619 let perror msg = function
11620 | Unix_error (err, _, _) ->
11621 eprintf "%s: %s\n" msg (error_message err)
11623 eprintf "%s: %s\n" msg (Printexc.to_string exn)
11625 (* Main program. *)
11628 try openfile "HACKING" [O_RDWR] 0
11630 | Unix_error (ENOENT, _, _) ->
11632 You are probably running this from the wrong directory.
11633 Run it from the top source directory using the command
11638 perror "open: HACKING" exn;
11641 (* Acquire a lock so parallel builds won't try to run the generator
11642 * twice at the same time. Subsequent builds will wait for the first
11643 * one to finish. Note the lock is released implicitly when the
11646 (try lockf lock_fd F_LOCK 1
11648 perror "lock: HACKING" exn;
11651 check_functions ();
11653 output_to "src/guestfs_protocol.x" generate_xdr;
11654 output_to "src/guestfs-structs.h" generate_structs_h;
11655 output_to "src/guestfs-actions.h" generate_actions_h;
11656 output_to "src/guestfs-internal-actions.h" generate_internal_actions_h;
11657 output_to "src/guestfs-actions.c" generate_client_actions;
11658 output_to "src/guestfs-bindtests.c" generate_bindtests;
11659 output_to "src/guestfs-structs.pod" generate_structs_pod;
11660 output_to "src/guestfs-actions.pod" generate_actions_pod;
11661 output_to "src/guestfs-availability.pod" generate_availability_pod;
11662 output_to "src/MAX_PROC_NR" generate_max_proc_nr;
11663 output_to "src/libguestfs.syms" generate_linker_script;
11664 output_to "daemon/actions.h" generate_daemon_actions_h;
11665 output_to "daemon/stubs.c" generate_daemon_actions;
11666 output_to "daemon/names.c" generate_daemon_names;
11667 output_to "daemon/optgroups.c" generate_daemon_optgroups_c;
11668 output_to "daemon/optgroups.h" generate_daemon_optgroups_h;
11669 output_to "capitests/tests.c" generate_tests;
11670 output_to "fish/cmds.c" generate_fish_cmds;
11671 output_to "fish/completion.c" generate_fish_completion;
11672 output_to "fish/guestfish-actions.pod" generate_fish_actions_pod;
11673 output_to "ocaml/guestfs.mli" generate_ocaml_mli;
11674 output_to "ocaml/guestfs.ml" generate_ocaml_ml;
11675 output_to "ocaml/guestfs_c_actions.c" generate_ocaml_c;
11676 output_to "ocaml/bindtests.ml" generate_ocaml_bindtests;
11677 output_to "ocaml/guestfs_inspector.mli" generate_ocaml_inspector_mli;
11678 output_to "ocaml/guestfs_inspector.ml" generate_ocaml_inspector_ml;
11679 output_to "perl/Guestfs.xs" generate_perl_xs;
11680 output_to "perl/lib/Sys/Guestfs.pm" generate_perl_pm;
11681 output_to "perl/bindtests.pl" generate_perl_bindtests;
11682 output_to "python/guestfs-py.c" generate_python_c;
11683 output_to "python/guestfs.py" generate_python_py;
11684 output_to "python/bindtests.py" generate_python_bindtests;
11685 output_to "ruby/ext/guestfs/_guestfs.c" generate_ruby_c;
11686 output_to "ruby/bindtests.rb" generate_ruby_bindtests;
11687 output_to "java/com/redhat/et/libguestfs/GuestFS.java" generate_java_java;
11691 let cols = cols_of_struct typ in
11692 let filename = sprintf "java/com/redhat/et/libguestfs/%s.java" jtyp in
11693 output_to filename (generate_java_struct jtyp cols);
11696 output_to "java/Makefile.inc" generate_java_makefile_inc;
11697 output_to "java/com_redhat_et_libguestfs_GuestFS.c" generate_java_c;
11698 output_to "java/Bindtests.java" generate_java_bindtests;
11699 output_to "haskell/Guestfs.hs" generate_haskell_hs;
11700 output_to "haskell/Bindtests.hs" generate_haskell_bindtests;
11701 output_to "csharp/Libguestfs.cs" generate_csharp;
11703 (* Always generate this file last, and unconditionally. It's used
11704 * by the Makefile to know when we must re-run the generator.
11706 let chan = open_out "src/stamp-generator" in
11707 fprintf chan "1\n";
11710 printf "generated %d lines of code\n" !lines