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.
167 (* Opaque buffer which can contain arbitrary 8 bit data.
168 * In the C API, this is expressed as <const char *, size_t> pair.
169 * Most other languages have a string type which can contain
170 * ASCII NUL. We use whatever type is appropriate for each
172 * Buffers are limited by the total message size. To transfer
173 * large blocks of data, use FileIn/FileOut parameters instead.
174 * To return an arbitrary buffer, use RBufferOut.
177 (* Key material / passphrase. Eventually we should treat this
178 * as sensitive and mlock it into physical RAM. However this
179 * is highly complex because of all the places that XDR-encoded
180 * strings can end up. So currently the only difference from
181 * 'String' is the way that guestfish requests these parameters
187 | ProtocolLimitWarning (* display warning about protocol size limits *)
188 | DangerWillRobinson (* flags particularly dangerous commands *)
189 | FishAlias of string (* provide an alias for this cmd in guestfish *)
190 | FishOutput of fish_output_t (* how to display output in guestfish *)
191 | NotInFish (* do not export via guestfish *)
192 | NotInDocs (* do not add this function to documentation *)
193 | DeprecatedBy of string (* function is deprecated, use .. instead *)
194 | Optional of string (* function is part of an optional group *)
197 | FishOutputOctal (* for int return, print in octal *)
198 | FishOutputHexadecimal (* for int return, print in hex *)
200 (* You can supply zero or as many tests as you want per API call.
202 * Note that the test environment has 3 block devices, of size 500MB,
203 * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and
204 * a fourth ISO block device with some known files on it (/dev/sdd).
206 * Note for partitioning purposes, the 500MB device has 1015 cylinders.
207 * Number of cylinders was 63 for IDE emulated disks with precisely
208 * the same size. How exactly this is calculated is a mystery.
210 * The ISO block device (/dev/sdd) comes from images/test.iso.
212 * To be able to run the tests in a reasonable amount of time,
213 * the virtual machine and block devices are reused between tests.
214 * So don't try testing kill_subprocess :-x
216 * Between each test we blockdev-setrw, umount-all, lvm-remove-all.
218 * Don't assume anything about the previous contents of the block
219 * devices. Use 'Init*' to create some initial scenarios.
221 * You can add a prerequisite clause to any individual test. This
222 * is a run-time check, which, if it fails, causes the test to be
223 * skipped. Useful if testing a command which might not work on
224 * all variations of libguestfs builds. A test that has prerequisite
225 * of 'Always' is run unconditionally.
227 * In addition, packagers can skip individual tests by setting the
228 * environment variables: eg:
229 * SKIP_TEST_<CMD>_<NUM>=1 SKIP_TEST_COMMAND_3=1 (skips test #3 of command)
230 * SKIP_TEST_<CMD>=1 SKIP_TEST_ZEROFREE=1 (skips all zerofree tests)
232 type tests = (test_init * test_prereq * test) list
234 (* Run the command sequence and just expect nothing to fail. *)
237 (* Run the command sequence and expect the output of the final
238 * command to be the string.
240 | TestOutput of seq * string
242 (* Run the command sequence and expect the output of the final
243 * command to be the list of strings.
245 | TestOutputList of seq * string list
247 (* Run the command sequence and expect the output of the final
248 * command to be the list of block devices (could be either
249 * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
250 * character of each string).
252 | TestOutputListOfDevices of seq * string list
254 (* Run the command sequence and expect the output of the final
255 * command to be the integer.
257 | TestOutputInt of seq * int
259 (* Run the command sequence and expect the output of the final
260 * command to be <op> <int>, eg. ">=", "1".
262 | TestOutputIntOp of seq * string * int
264 (* Run the command sequence and expect the output of the final
265 * command to be a true value (!= 0 or != NULL).
267 | TestOutputTrue of seq
269 (* Run the command sequence and expect the output of the final
270 * command to be a false value (== 0 or == NULL, but not an error).
272 | TestOutputFalse of seq
274 (* Run the command sequence and expect the output of the final
275 * command to be a list of the given length (but don't care about
278 | TestOutputLength of seq * int
280 (* Run the command sequence and expect the output of the final
281 * command to be a buffer (RBufferOut), ie. string + size.
283 | TestOutputBuffer of seq * string
285 (* Run the command sequence and expect the output of the final
286 * command to be a structure.
288 | TestOutputStruct of seq * test_field_compare list
290 (* Run the command sequence and expect the final command (only)
293 | TestLastFail of seq
295 and test_field_compare =
296 | CompareWithInt of string * int
297 | CompareWithIntOp of string * string * int
298 | CompareWithString of string * string
299 | CompareFieldsIntEq of string * string
300 | CompareFieldsStrEq of string * string
302 (* Test prerequisites. *)
304 (* Test always runs. *)
307 (* Test is currently disabled - eg. it fails, or it tests some
308 * unimplemented feature.
312 (* 'string' is some C code (a function body) that should return
313 * true or false. The test will run if the code returns true.
317 (* As for 'If' but the test runs _unless_ the code returns true. *)
320 (* Run the test only if 'string' is available in the daemon. *)
321 | IfAvailable of string
323 (* Some initial scenarios for testing. *)
325 (* Do nothing, block devices could contain random stuff including
326 * LVM PVs, and some filesystems might be mounted. This is usually
331 (* Block devices are empty and no filesystems are mounted. *)
334 (* /dev/sda contains a single partition /dev/sda1, with random
335 * content. /dev/sdb and /dev/sdc may have random content.
340 (* /dev/sda contains a single partition /dev/sda1, which is formatted
341 * as ext2, empty [except for lost+found] and mounted on /.
342 * /dev/sdb and /dev/sdc may have random content.
348 * /dev/sda1 (is a PV):
349 * /dev/VG/LV (size 8MB):
350 * formatted as ext2, empty [except for lost+found], mounted on /
351 * /dev/sdb and /dev/sdc may have random content.
355 (* /dev/sdd (the ISO, see images/ directory in source)
360 (* Sequence of commands for testing. *)
362 and cmd = string list
364 (* Note about long descriptions: When referring to another
365 * action, use the format C<guestfs_other> (ie. the full name of
366 * the C function). This will be replaced as appropriate in other
369 * Apart from that, long descriptions are just perldoc paragraphs.
372 (* Generate a random UUID (used in tests). *)
374 let chan = open_process_in "uuidgen" in
375 let uuid = input_line chan in
376 (match close_process_in chan with
379 failwith "uuidgen: process exited with non-zero status"
380 | WSIGNALED _ | WSTOPPED _ ->
381 failwith "uuidgen: process signalled or stopped by signal"
385 (* These test functions are used in the language binding tests. *)
387 let test_all_args = [
390 StringList "strlist";
399 let test_all_rets = [
400 (* except for RErr, which is tested thoroughly elsewhere *)
401 "test0rint", RInt "valout";
402 "test0rint64", RInt64 "valout";
403 "test0rbool", RBool "valout";
404 "test0rconststring", RConstString "valout";
405 "test0rconstoptstring", RConstOptString "valout";
406 "test0rstring", RString "valout";
407 "test0rstringlist", RStringList "valout";
408 "test0rstruct", RStruct ("valout", "lvm_pv");
409 "test0rstructlist", RStructList ("valout", "lvm_pv");
410 "test0rhashtable", RHashtable "valout";
413 let test_functions = [
414 ("test0", (RErr, test_all_args), -1, [NotInFish; NotInDocs],
416 "internal test function - do not use",
418 This is an internal test function which is used to test whether
419 the automatically generated bindings can handle every possible
420 parameter type correctly.
422 It echos the contents of each parameter to stdout.
424 You probably don't want to call this function.");
428 [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs],
430 "internal test function - do not use",
432 This is an internal test function which is used to test whether
433 the automatically generated bindings can handle every possible
434 return type correctly.
436 It converts string C<val> to the return type.
438 You probably don't want to call this function.");
439 (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs],
441 "internal test function - do not use",
443 This is an internal test function which is used to test whether
444 the automatically generated bindings can handle every possible
445 return type correctly.
447 This function always returns an error.
449 You probably don't want to call this function.")]
453 (* non_daemon_functions are any functions which don't get processed
454 * in the daemon, eg. functions for setting and getting local
455 * configuration values.
458 let non_daemon_functions = test_functions @ [
459 ("launch", (RErr, []), -1, [FishAlias "run"],
461 "launch the qemu subprocess",
463 Internally libguestfs is implemented by running a virtual machine
466 You should call this after configuring the handle
467 (eg. adding drives) but before performing any actions.");
469 ("wait_ready", (RErr, []), -1, [NotInFish],
471 "wait until the qemu subprocess launches (no op)",
473 This function is a no op.
475 In versions of the API E<lt> 1.0.71 you had to call this function
476 just after calling C<guestfs_launch> to wait for the launch
477 to complete. However this is no longer necessary because
478 C<guestfs_launch> now does the waiting.
480 If you see any calls to this function in code then you can just
481 remove them, unless you want to retain compatibility with older
482 versions of the API.");
484 ("kill_subprocess", (RErr, []), -1, [],
486 "kill the qemu subprocess",
488 This kills the qemu subprocess. You should never need to call this.");
490 ("add_drive", (RErr, [String "filename"]), -1, [FishAlias "add"],
492 "add an image to examine or modify",
494 This function adds a virtual machine disk image C<filename> to the
495 guest. The first time you call this function, the disk appears as IDE
496 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
499 You don't necessarily need to be root when using libguestfs. However
500 you obviously do need sufficient permissions to access the filename
501 for whatever operations you want to perform (ie. read access if you
502 just want to read the image or write access if you want to modify the
505 This is equivalent to the qemu parameter
506 C<-drive file=filename,cache=off,if=...>.
508 C<cache=off> is omitted in cases where it is not supported by
509 the underlying filesystem.
511 C<if=...> is set at compile time by the configuration option
512 C<./configure --with-drive-if=...>. In the rare case where you
513 might need to change this at run time, use C<guestfs_add_drive_with_if>
514 or C<guestfs_add_drive_ro_with_if>.
516 Note that this call checks for the existence of C<filename>. This
517 stops you from specifying other types of drive which are supported
518 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
519 the general C<guestfs_config> call instead.");
521 ("add_cdrom", (RErr, [String "filename"]), -1, [FishAlias "cdrom"],
523 "add a CD-ROM disk image to examine",
525 This function adds a virtual CD-ROM disk image to the guest.
527 This is equivalent to the qemu parameter C<-cdrom filename>.
535 This call checks for the existence of C<filename>. This
536 stops you from specifying other types of drive which are supported
537 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
538 the general C<guestfs_config> call instead.
542 If you just want to add an ISO file (often you use this as an
543 efficient way to transfer large files into the guest), then you
544 should probably use C<guestfs_add_drive_ro> instead.
548 ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"],
550 "add a drive in snapshot mode (read-only)",
552 This adds a drive in snapshot mode, making it effectively
555 Note that writes to the device are allowed, and will be seen for
556 the duration of the guestfs handle, but they are written
557 to a temporary file which is discarded as soon as the guestfs
558 handle is closed. We don't currently have any method to enable
559 changes to be committed, although qemu can support this.
561 This is equivalent to the qemu parameter
562 C<-drive file=filename,snapshot=on,if=...>.
564 C<if=...> is set at compile time by the configuration option
565 C<./configure --with-drive-if=...>. In the rare case where you
566 might need to change this at run time, use C<guestfs_add_drive_with_if>
567 or C<guestfs_add_drive_ro_with_if>.
569 Note that this call checks for the existence of C<filename>. This
570 stops you from specifying other types of drive which are supported
571 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
572 the general C<guestfs_config> call instead.");
574 ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"]), -1, [],
576 "add qemu parameters",
578 This can be used to add arbitrary qemu command line parameters
579 of the form C<-param value>. Actually it's not quite arbitrary - we
580 prevent you from setting some parameters which would interfere with
581 parameters that we use.
583 The first character of C<param> string must be a C<-> (dash).
585 C<value> can be NULL.");
587 ("set_qemu", (RErr, [OptString "qemu"]), -1, [FishAlias "qemu"],
589 "set the qemu binary",
591 Set the qemu binary that we will use.
593 The default is chosen when the library was compiled by the
596 You can also override this by setting the C<LIBGUESTFS_QEMU>
597 environment variable.
599 Setting C<qemu> to C<NULL> restores the default qemu binary.
601 Note that you should call this function as early as possible
602 after creating the handle. This is because some pre-launch
603 operations depend on testing qemu features (by running C<qemu -help>).
604 If the qemu binary changes, we don't retest features, and
605 so you might see inconsistent results. Using the environment
606 variable C<LIBGUESTFS_QEMU> is safest of all since that picks
607 the qemu binary at the same time as the handle is created.");
609 ("get_qemu", (RConstString "qemu", []), -1, [],
610 [InitNone, Always, TestRun (
612 "get the qemu binary",
614 Return the current qemu binary.
616 This is always non-NULL. If it wasn't set already, then this will
617 return the default qemu binary name.");
619 ("set_path", (RErr, [OptString "searchpath"]), -1, [FishAlias "path"],
621 "set the search path",
623 Set the path that libguestfs searches for kernel and initrd.img.
625 The default is C<$libdir/guestfs> unless overridden by setting
626 C<LIBGUESTFS_PATH> environment variable.
628 Setting C<path> to C<NULL> restores the default path.");
630 ("get_path", (RConstString "path", []), -1, [],
631 [InitNone, Always, TestRun (
633 "get the search path",
635 Return the current search path.
637 This is always non-NULL. If it wasn't set already, then this will
638 return the default path.");
640 ("set_append", (RErr, [OptString "append"]), -1, [FishAlias "append"],
642 "add options to kernel command line",
644 This function is used to add additional options to the
645 guest kernel command line.
647 The default is C<NULL> unless overridden by setting
648 C<LIBGUESTFS_APPEND> environment variable.
650 Setting C<append> to C<NULL> means I<no> additional options
651 are passed (libguestfs always adds a few of its own).");
653 ("get_append", (RConstOptString "append", []), -1, [],
654 (* This cannot be tested with the current framework. The
655 * function can return NULL in normal operations, which the
656 * test framework interprets as an error.
659 "get the additional kernel options",
661 Return the additional kernel options which are added to the
662 guest kernel command line.
664 If C<NULL> then no options are added.");
666 ("set_autosync", (RErr, [Bool "autosync"]), -1, [FishAlias "autosync"],
670 If C<autosync> is true, this enables autosync. Libguestfs will make a
671 best effort attempt to run C<guestfs_umount_all> followed by
672 C<guestfs_sync> when the handle is closed
673 (also if the program exits without closing handles).
675 This is disabled by default (except in guestfish where it is
676 enabled by default).");
678 ("get_autosync", (RBool "autosync", []), -1, [],
679 [InitNone, Always, TestRun (
680 [["get_autosync"]])],
683 Get the autosync flag.");
685 ("set_verbose", (RErr, [Bool "verbose"]), -1, [FishAlias "verbose"],
689 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
691 Verbose messages are disabled unless the environment variable
692 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
694 ("get_verbose", (RBool "verbose", []), -1, [],
698 This returns the verbose messages flag.");
700 ("is_ready", (RBool "ready", []), -1, [],
701 [InitNone, Always, TestOutputTrue (
703 "is ready to accept commands",
705 This returns true iff this handle is ready to accept commands
706 (in the C<READY> state).
708 For more information on states, see L<guestfs(3)>.");
710 ("is_config", (RBool "config", []), -1, [],
711 [InitNone, Always, TestOutputFalse (
713 "is in configuration state",
715 This returns true iff this handle is being configured
716 (in the C<CONFIG> state).
718 For more information on states, see L<guestfs(3)>.");
720 ("is_launching", (RBool "launching", []), -1, [],
721 [InitNone, Always, TestOutputFalse (
722 [["is_launching"]])],
723 "is launching subprocess",
725 This returns true iff this handle is launching the subprocess
726 (in the C<LAUNCHING> state).
728 For more information on states, see L<guestfs(3)>.");
730 ("is_busy", (RBool "busy", []), -1, [],
731 [InitNone, Always, TestOutputFalse (
733 "is busy processing a command",
735 This returns true iff this handle is busy processing a command
736 (in the C<BUSY> state).
738 For more information on states, see L<guestfs(3)>.");
740 ("get_state", (RInt "state", []), -1, [],
742 "get the current state",
744 This returns the current state as an opaque integer. This is
745 only useful for printing debug and internal error messages.
747 For more information on states, see L<guestfs(3)>.");
749 ("set_memsize", (RErr, [Int "memsize"]), -1, [FishAlias "memsize"],
750 [InitNone, Always, TestOutputInt (
751 [["set_memsize"; "500"];
752 ["get_memsize"]], 500)],
753 "set memory allocated to the qemu subprocess",
755 This sets the memory size in megabytes allocated to the
756 qemu subprocess. This only has any effect if called before
759 You can also change this by setting the environment
760 variable C<LIBGUESTFS_MEMSIZE> before the handle is
763 For more information on the architecture of libguestfs,
764 see L<guestfs(3)>.");
766 ("get_memsize", (RInt "memsize", []), -1, [],
767 [InitNone, Always, TestOutputIntOp (
768 [["get_memsize"]], ">=", 256)],
769 "get memory allocated to the qemu subprocess",
771 This gets the memory size in megabytes allocated to the
774 If C<guestfs_set_memsize> was not called
775 on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
776 then this returns the compiled-in default value for memsize.
778 For more information on the architecture of libguestfs,
779 see L<guestfs(3)>.");
781 ("get_pid", (RInt "pid", []), -1, [FishAlias "pid"],
782 [InitNone, Always, TestOutputIntOp (
783 [["get_pid"]], ">=", 1)],
784 "get PID of qemu subprocess",
786 Return the process ID of the qemu subprocess. If there is no
787 qemu subprocess, then this will return an error.
789 This is an internal call used for debugging and testing.");
791 ("version", (RStruct ("version", "version"), []), -1, [],
792 [InitNone, Always, TestOutputStruct (
793 [["version"]], [CompareWithInt ("major", 1)])],
794 "get the library version number",
796 Return the libguestfs version number that the program is linked
799 Note that because of dynamic linking this is not necessarily
800 the version of libguestfs that you compiled against. You can
801 compile the program, and then at runtime dynamically link
802 against a completely different C<libguestfs.so> library.
804 This call was added in version C<1.0.58>. In previous
805 versions of libguestfs there was no way to get the version
806 number. From C code you can use dynamic linker functions
807 to find out if this symbol exists (if it doesn't, then
808 it's an earlier version).
810 The call returns a structure with four elements. The first
811 three (C<major>, C<minor> and C<release>) are numbers and
812 correspond to the usual version triplet. The fourth element
813 (C<extra>) is a string and is normally empty, but may be
814 used for distro-specific information.
816 To construct the original version string:
817 C<$major.$minor.$release$extra>
819 See also: L<guestfs(3)/LIBGUESTFS VERSION NUMBERS>.
821 I<Note:> Don't use this call to test for availability
822 of features. In enterprise distributions we backport
823 features from later versions into earlier versions,
824 making this an unreliable way to test for features.
825 Use C<guestfs_available> instead.");
827 ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"],
828 [InitNone, Always, TestOutputTrue (
829 [["set_selinux"; "true"];
831 "set SELinux enabled or disabled at appliance boot",
833 This sets the selinux flag that is passed to the appliance
834 at boot time. The default is C<selinux=0> (disabled).
836 Note that if SELinux is enabled, it is always in
837 Permissive mode (C<enforcing=0>).
839 For more information on the architecture of libguestfs,
840 see L<guestfs(3)>.");
842 ("get_selinux", (RBool "selinux", []), -1, [],
844 "get SELinux enabled flag",
846 This returns the current setting of the selinux flag which
847 is passed to the appliance at boot time. See C<guestfs_set_selinux>.
849 For more information on the architecture of libguestfs,
850 see L<guestfs(3)>.");
852 ("set_trace", (RErr, [Bool "trace"]), -1, [FishAlias "trace"],
853 [InitNone, Always, TestOutputFalse (
854 [["set_trace"; "false"];
856 "enable or disable command traces",
858 If the command trace flag is set to 1, then commands are
859 printed on stderr before they are executed in a format
860 which is very similar to the one used by guestfish. In
861 other words, you can run a program with this enabled, and
862 you will get out a script which you can feed to guestfish
863 to perform the same set of actions.
865 If you want to trace C API calls into libguestfs (and
866 other libraries) then possibly a better way is to use
867 the external ltrace(1) command.
869 Command traces are disabled unless the environment variable
870 C<LIBGUESTFS_TRACE> is defined and set to C<1>.");
872 ("get_trace", (RBool "trace", []), -1, [],
874 "get command trace enabled flag",
876 Return the command trace flag.");
878 ("set_direct", (RErr, [Bool "direct"]), -1, [FishAlias "direct"],
879 [InitNone, Always, TestOutputFalse (
880 [["set_direct"; "false"];
882 "enable or disable direct appliance mode",
884 If the direct appliance mode flag is enabled, then stdin and
885 stdout are passed directly through to the appliance once it
888 One consequence of this is that log messages aren't caught
889 by the library and handled by C<guestfs_set_log_message_callback>,
890 but go straight to stdout.
892 You probably don't want to use this unless you know what you
895 The default is disabled.");
897 ("get_direct", (RBool "direct", []), -1, [],
899 "get direct appliance mode flag",
901 Return the direct appliance mode flag.");
903 ("set_recovery_proc", (RErr, [Bool "recoveryproc"]), -1, [FishAlias "recovery-proc"],
904 [InitNone, Always, TestOutputTrue (
905 [["set_recovery_proc"; "true"];
906 ["get_recovery_proc"]])],
907 "enable or disable the recovery process",
909 If this is called with the parameter C<false> then
910 C<guestfs_launch> does not create a recovery process. The
911 purpose of the recovery process is to stop runaway qemu
912 processes in the case where the main program aborts abruptly.
914 This only has any effect if called before C<guestfs_launch>,
915 and the default is true.
917 About the only time when you would want to disable this is
918 if the main process will fork itself into the background
919 (\"daemonize\" itself). In this case the recovery process
920 thinks that the main program has disappeared and so kills
921 qemu, which is not very helpful.");
923 ("get_recovery_proc", (RBool "recoveryproc", []), -1, [],
925 "get recovery process enabled flag",
927 Return the recovery process enabled flag.");
929 ("add_drive_with_if", (RErr, [String "filename"; String "iface"]), -1, [],
931 "add a drive specifying the QEMU block emulation to use",
933 This is the same as C<guestfs_add_drive> but it allows you
934 to specify the QEMU interface emulation to use at run time.");
936 ("add_drive_ro_with_if", (RErr, [String "filename"; String "iface"]), -1, [],
938 "add a drive read-only specifying the QEMU block emulation to use",
940 This is the same as C<guestfs_add_drive_ro> but it allows you
941 to specify the QEMU interface emulation to use at run time.");
943 ("file_architecture", (RString "arch", [Pathname "filename"]), -1, [],
944 [InitISOFS, Always, TestOutput (
945 [["file_architecture"; "/bin-i586-dynamic"]], "i386");
946 InitISOFS, Always, TestOutput (
947 [["file_architecture"; "/bin-sparc-dynamic"]], "sparc");
948 InitISOFS, Always, TestOutput (
949 [["file_architecture"; "/bin-win32.exe"]], "i386");
950 InitISOFS, Always, TestOutput (
951 [["file_architecture"; "/bin-win64.exe"]], "x86_64");
952 InitISOFS, Always, TestOutput (
953 [["file_architecture"; "/bin-x86_64-dynamic"]], "x86_64");
954 InitISOFS, Always, TestOutput (
955 [["file_architecture"; "/lib-i586.so"]], "i386");
956 InitISOFS, Always, TestOutput (
957 [["file_architecture"; "/lib-sparc.so"]], "sparc");
958 InitISOFS, Always, TestOutput (
959 [["file_architecture"; "/lib-win32.dll"]], "i386");
960 InitISOFS, Always, TestOutput (
961 [["file_architecture"; "/lib-win64.dll"]], "x86_64");
962 InitISOFS, Always, TestOutput (
963 [["file_architecture"; "/lib-x86_64.so"]], "x86_64");
964 InitISOFS, Always, TestOutput (
965 [["file_architecture"; "/initrd-x86_64.img"]], "x86_64");
966 InitISOFS, Always, TestOutput (
967 [["file_architecture"; "/initrd-x86_64.img.gz"]], "x86_64");],
968 "detect the architecture of a binary file",
970 This detects the architecture of the binary C<filename>,
971 and returns it if known.
973 Currently defined architectures are:
979 This string is returned for all 32 bit i386, i486, i586, i686 binaries
980 irrespective of the precise processor requirements of the binary.
992 64 bit SPARC V9 and above.
1008 Libguestfs may return other architecture strings in future.
1010 The function works on at least the following types of files:
1016 many types of Un*x and Linux binary
1020 many types of Un*x and Linux shared library
1024 Windows Win32 and Win64 binaries
1028 Windows Win32 and Win64 DLLs
1030 Win32 binaries and DLLs return C<i386>.
1032 Win64 binaries and DLLs return C<x86_64>.
1036 Linux kernel modules
1040 Linux new-style initrd images
1044 some non-x86 Linux vmlinuz kernels
1048 What it can't do currently:
1054 static libraries (libfoo.a)
1058 Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
1062 x86 Linux vmlinuz kernels
1064 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32- and
1065 compressed code, and are horribly hard to unpack. If you want to find
1066 the architecture of a kernel, use the architecture of the associated
1067 initrd or kernel module(s) instead.
1073 (* daemon_functions are any functions which cause some action
1074 * to take place in the daemon.
1077 let daemon_functions = [
1078 ("mount", (RErr, [Device "device"; String "mountpoint"]), 1, [],
1079 [InitEmpty, Always, TestOutput (
1080 [["part_disk"; "/dev/sda"; "mbr"];
1081 ["mkfs"; "ext2"; "/dev/sda1"];
1082 ["mount"; "/dev/sda1"; "/"];
1083 ["write"; "/new"; "new file contents"];
1084 ["cat"; "/new"]], "new file contents")],
1085 "mount a guest disk at a position in the filesystem",
1087 Mount a guest disk at a position in the filesystem. Block devices
1088 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1089 the guest. If those block devices contain partitions, they will have
1090 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
1093 The rules are the same as for L<mount(2)>: A filesystem must
1094 first be mounted on C</> before others can be mounted. Other
1095 filesystems can only be mounted on directories which already
1098 The mounted filesystem is writable, if we have sufficient permissions
1099 on the underlying device.
1102 When you use this call, the filesystem options C<sync> and C<noatime>
1103 are set implicitly. This was originally done because we thought it
1104 would improve reliability, but it turns out that I<-o sync> has a
1105 very large negative performance impact and negligible effect on
1106 reliability. Therefore we recommend that you avoid using
1107 C<guestfs_mount> in any code that needs performance, and instead
1108 use C<guestfs_mount_options> (use an empty string for the first
1109 parameter if you don't want any options).");
1111 ("sync", (RErr, []), 2, [],
1112 [ InitEmpty, Always, TestRun [["sync"]]],
1113 "sync disks, writes are flushed through to the disk image",
1115 This syncs the disk, so that any writes are flushed through to the
1116 underlying disk image.
1118 You should always call this if you have modified a disk image, before
1119 closing the handle.");
1121 ("touch", (RErr, [Pathname "path"]), 3, [],
1122 [InitBasicFS, Always, TestOutputTrue (
1124 ["exists"; "/new"]])],
1125 "update file timestamps or create a new file",
1127 Touch acts like the L<touch(1)> command. It can be used to
1128 update the timestamps on a file, or, if the file does not exist,
1129 to create a new zero-length file.
1131 This command only works on regular files, and will fail on other
1132 file types such as directories, symbolic links, block special etc.");
1134 ("cat", (RString "content", [Pathname "path"]), 4, [ProtocolLimitWarning],
1135 [InitISOFS, Always, TestOutput (
1136 [["cat"; "/known-2"]], "abcdef\n")],
1137 "list the contents of a file",
1139 Return the contents of the file named C<path>.
1141 Note that this function cannot correctly handle binary files
1142 (specifically, files containing C<\\0> character which is treated
1143 as end of string). For those you need to use the C<guestfs_read_file>
1144 or C<guestfs_download> functions which have a more complex interface.");
1146 ("ll", (RString "listing", [Pathname "directory"]), 5, [],
1147 [], (* XXX Tricky to test because it depends on the exact format
1148 * of the 'ls -l' command, which changes between F10 and F11.
1150 "list the files in a directory (long format)",
1152 List the files in C<directory> (relative to the root directory,
1153 there is no cwd) in the format of 'ls -la'.
1155 This command is mostly useful for interactive sessions. It
1156 is I<not> intended that you try to parse the output string.");
1158 ("ls", (RStringList "listing", [Pathname "directory"]), 6, [],
1159 [InitBasicFS, Always, TestOutputList (
1161 ["touch"; "/newer"];
1162 ["touch"; "/newest"];
1163 ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])],
1164 "list the files in a directory",
1166 List the files in C<directory> (relative to the root directory,
1167 there is no cwd). The '.' and '..' entries are not returned, but
1168 hidden files are shown.
1170 This command is mostly useful for interactive sessions. Programs
1171 should probably use C<guestfs_readdir> instead.");
1173 ("list_devices", (RStringList "devices", []), 7, [],
1174 [InitEmpty, Always, TestOutputListOfDevices (
1175 [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
1176 "list the block devices",
1178 List all the block devices.
1180 The full block device names are returned, eg. C</dev/sda>");
1182 ("list_partitions", (RStringList "partitions", []), 8, [],
1183 [InitBasicFS, Always, TestOutputListOfDevices (
1184 [["list_partitions"]], ["/dev/sda1"]);
1185 InitEmpty, Always, TestOutputListOfDevices (
1186 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1187 ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1188 "list the partitions",
1190 List all the partitions detected on all block devices.
1192 The full partition device names are returned, eg. C</dev/sda1>
1194 This does not return logical volumes. For that you will need to
1195 call C<guestfs_lvs>.");
1197 ("pvs", (RStringList "physvols", []), 9, [Optional "lvm2"],
1198 [InitBasicFSonLVM, Always, TestOutputListOfDevices (
1199 [["pvs"]], ["/dev/sda1"]);
1200 InitEmpty, Always, TestOutputListOfDevices (
1201 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1202 ["pvcreate"; "/dev/sda1"];
1203 ["pvcreate"; "/dev/sda2"];
1204 ["pvcreate"; "/dev/sda3"];
1205 ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1206 "list the LVM physical volumes (PVs)",
1208 List all the physical volumes detected. This is the equivalent
1209 of the L<pvs(8)> command.
1211 This returns a list of just the device names that contain
1212 PVs (eg. C</dev/sda2>).
1214 See also C<guestfs_pvs_full>.");
1216 ("vgs", (RStringList "volgroups", []), 10, [Optional "lvm2"],
1217 [InitBasicFSonLVM, Always, TestOutputList (
1219 InitEmpty, Always, TestOutputList (
1220 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1221 ["pvcreate"; "/dev/sda1"];
1222 ["pvcreate"; "/dev/sda2"];
1223 ["pvcreate"; "/dev/sda3"];
1224 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1225 ["vgcreate"; "VG2"; "/dev/sda3"];
1226 ["vgs"]], ["VG1"; "VG2"])],
1227 "list the LVM volume groups (VGs)",
1229 List all the volumes groups detected. This is the equivalent
1230 of the L<vgs(8)> command.
1232 This returns a list of just the volume group names that were
1233 detected (eg. C<VolGroup00>).
1235 See also C<guestfs_vgs_full>.");
1237 ("lvs", (RStringList "logvols", []), 11, [Optional "lvm2"],
1238 [InitBasicFSonLVM, Always, TestOutputList (
1239 [["lvs"]], ["/dev/VG/LV"]);
1240 InitEmpty, Always, TestOutputList (
1241 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1242 ["pvcreate"; "/dev/sda1"];
1243 ["pvcreate"; "/dev/sda2"];
1244 ["pvcreate"; "/dev/sda3"];
1245 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1246 ["vgcreate"; "VG2"; "/dev/sda3"];
1247 ["lvcreate"; "LV1"; "VG1"; "50"];
1248 ["lvcreate"; "LV2"; "VG1"; "50"];
1249 ["lvcreate"; "LV3"; "VG2"; "50"];
1250 ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
1251 "list the LVM logical volumes (LVs)",
1253 List all the logical volumes detected. This is the equivalent
1254 of the L<lvs(8)> command.
1256 This returns a list of the logical volume device names
1257 (eg. C</dev/VolGroup00/LogVol00>).
1259 See also C<guestfs_lvs_full>.");
1261 ("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 12, [Optional "lvm2"],
1262 [], (* XXX how to test? *)
1263 "list the LVM physical volumes (PVs)",
1265 List all the physical volumes detected. This is the equivalent
1266 of the L<pvs(8)> command. The \"full\" version includes all fields.");
1268 ("vgs_full", (RStructList ("volgroups", "lvm_vg"), []), 13, [Optional "lvm2"],
1269 [], (* XXX how to test? *)
1270 "list the LVM volume groups (VGs)",
1272 List all the volumes groups detected. This is the equivalent
1273 of the L<vgs(8)> command. The \"full\" version includes all fields.");
1275 ("lvs_full", (RStructList ("logvols", "lvm_lv"), []), 14, [Optional "lvm2"],
1276 [], (* XXX how to test? *)
1277 "list the LVM logical volumes (LVs)",
1279 List all the logical volumes detected. This is the equivalent
1280 of the L<lvs(8)> command. The \"full\" version includes all fields.");
1282 ("read_lines", (RStringList "lines", [Pathname "path"]), 15, [],
1283 [InitISOFS, Always, TestOutputList (
1284 [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]);
1285 InitISOFS, Always, TestOutputList (
1286 [["read_lines"; "/empty"]], [])],
1287 "read file as lines",
1289 Return the contents of the file named C<path>.
1291 The file contents are returned as a list of lines. Trailing
1292 C<LF> and C<CRLF> character sequences are I<not> returned.
1294 Note that this function cannot correctly handle binary files
1295 (specifically, files containing C<\\0> character which is treated
1296 as end of line). For those you need to use the C<guestfs_read_file>
1297 function which has a more complex interface.");
1299 ("aug_init", (RErr, [Pathname "root"; Int "flags"]), 16, [Optional "augeas"],
1300 [], (* XXX Augeas code needs tests. *)
1301 "create a new Augeas handle",
1303 Create a new Augeas handle for editing configuration files.
1304 If there was any previous Augeas handle associated with this
1305 guestfs session, then it is closed.
1307 You must call this before using any other C<guestfs_aug_*>
1310 C<root> is the filesystem root. C<root> must not be NULL,
1313 The flags are the same as the flags defined in
1314 E<lt>augeas.hE<gt>, the logical I<or> of the following
1319 =item C<AUG_SAVE_BACKUP> = 1
1321 Keep the original file with a C<.augsave> extension.
1323 =item C<AUG_SAVE_NEWFILE> = 2
1325 Save changes into a file with extension C<.augnew>, and
1326 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
1328 =item C<AUG_TYPE_CHECK> = 4
1330 Typecheck lenses (can be expensive).
1332 =item C<AUG_NO_STDINC> = 8
1334 Do not use standard load path for modules.
1336 =item C<AUG_SAVE_NOOP> = 16
1338 Make save a no-op, just record what would have been changed.
1340 =item C<AUG_NO_LOAD> = 32
1342 Do not load the tree in C<guestfs_aug_init>.
1346 To close the handle, you can call C<guestfs_aug_close>.
1348 To find out more about Augeas, see L<http://augeas.net/>.");
1350 ("aug_close", (RErr, []), 26, [Optional "augeas"],
1351 [], (* XXX Augeas code needs tests. *)
1352 "close the current Augeas handle",
1354 Close the current Augeas handle and free up any resources
1355 used by it. After calling this, you have to call
1356 C<guestfs_aug_init> again before you can use any other
1357 Augeas functions.");
1359 ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [Optional "augeas"],
1360 [], (* XXX Augeas code needs tests. *)
1361 "define an Augeas variable",
1363 Defines an Augeas variable C<name> whose value is the result
1364 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
1367 On success this returns the number of nodes in C<expr>, or
1368 C<0> if C<expr> evaluates to something which is not a nodeset.");
1370 ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"]), 18, [Optional "augeas"],
1371 [], (* XXX Augeas code needs tests. *)
1372 "define an Augeas node",
1374 Defines a variable C<name> whose value is the result of
1377 If C<expr> evaluates to an empty nodeset, a node is created,
1378 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
1379 C<name> will be the nodeset containing that single node.
1381 On success this returns a pair containing the
1382 number of nodes in the nodeset, and a boolean flag
1383 if a node was created.");
1385 ("aug_get", (RString "val", [String "augpath"]), 19, [Optional "augeas"],
1386 [], (* XXX Augeas code needs tests. *)
1387 "look up the value of an Augeas path",
1389 Look up the value associated with C<path>. If C<path>
1390 matches exactly one node, the C<value> is returned.");
1392 ("aug_set", (RErr, [String "augpath"; String "val"]), 20, [Optional "augeas"],
1393 [], (* XXX Augeas code needs tests. *)
1394 "set Augeas path to value",
1396 Set the value associated with C<path> to C<val>.
1398 In the Augeas API, it is possible to clear a node by setting
1399 the value to NULL. Due to an oversight in the libguestfs API
1400 you cannot do that with this call. Instead you must use the
1401 C<guestfs_aug_clear> call.");
1403 ("aug_insert", (RErr, [String "augpath"; String "label"; Bool "before"]), 21, [Optional "augeas"],
1404 [], (* XXX Augeas code needs tests. *)
1405 "insert a sibling Augeas node",
1407 Create a new sibling C<label> for C<path>, inserting it into
1408 the tree before or after C<path> (depending on the boolean
1411 C<path> must match exactly one existing node in the tree, and
1412 C<label> must be a label, ie. not contain C</>, C<*> or end
1413 with a bracketed index C<[N]>.");
1415 ("aug_rm", (RInt "nrnodes", [String "augpath"]), 22, [Optional "augeas"],
1416 [], (* XXX Augeas code needs tests. *)
1417 "remove an Augeas path",
1419 Remove C<path> and all of its children.
1421 On success this returns the number of entries which were removed.");
1423 ("aug_mv", (RErr, [String "src"; String "dest"]), 23, [Optional "augeas"],
1424 [], (* XXX Augeas code needs tests. *)
1427 Move the node C<src> to C<dest>. C<src> must match exactly
1428 one node. C<dest> is overwritten if it exists.");
1430 ("aug_match", (RStringList "matches", [String "augpath"]), 24, [Optional "augeas"],
1431 [], (* XXX Augeas code needs tests. *)
1432 "return Augeas nodes which match augpath",
1434 Returns a list of paths which match the path expression C<path>.
1435 The returned paths are sufficiently qualified so that they match
1436 exactly one node in the current tree.");
1438 ("aug_save", (RErr, []), 25, [Optional "augeas"],
1439 [], (* XXX Augeas code needs tests. *)
1440 "write all pending Augeas changes to disk",
1442 This writes all pending changes to disk.
1444 The flags which were passed to C<guestfs_aug_init> affect exactly
1445 how files are saved.");
1447 ("aug_load", (RErr, []), 27, [Optional "augeas"],
1448 [], (* XXX Augeas code needs tests. *)
1449 "load files into the tree",
1451 Load files into the tree.
1453 See C<aug_load> in the Augeas documentation for the full gory
1456 ("aug_ls", (RStringList "matches", [String "augpath"]), 28, [Optional "augeas"],
1457 [], (* XXX Augeas code needs tests. *)
1458 "list Augeas nodes under augpath",
1460 This is just a shortcut for listing C<guestfs_aug_match>
1461 C<path/*> and sorting the resulting nodes into alphabetical order.");
1463 ("rm", (RErr, [Pathname "path"]), 29, [],
1464 [InitBasicFS, Always, TestRun
1467 InitBasicFS, Always, TestLastFail
1469 InitBasicFS, Always, TestLastFail
1474 Remove the single file C<path>.");
1476 ("rmdir", (RErr, [Pathname "path"]), 30, [],
1477 [InitBasicFS, Always, TestRun
1480 InitBasicFS, Always, TestLastFail
1481 [["rmdir"; "/new"]];
1482 InitBasicFS, Always, TestLastFail
1484 ["rmdir"; "/new"]]],
1485 "remove a directory",
1487 Remove the single directory C<path>.");
1489 ("rm_rf", (RErr, [Pathname "path"]), 31, [],
1490 [InitBasicFS, Always, TestOutputFalse
1492 ["mkdir"; "/new/foo"];
1493 ["touch"; "/new/foo/bar"];
1495 ["exists"; "/new"]]],
1496 "remove a file or directory recursively",
1498 Remove the file or directory C<path>, recursively removing the
1499 contents if its a directory. This is like the C<rm -rf> shell
1502 ("mkdir", (RErr, [Pathname "path"]), 32, [],
1503 [InitBasicFS, Always, TestOutputTrue
1505 ["is_dir"; "/new"]];
1506 InitBasicFS, Always, TestLastFail
1507 [["mkdir"; "/new/foo/bar"]]],
1508 "create a directory",
1510 Create a directory named C<path>.");
1512 ("mkdir_p", (RErr, [Pathname "path"]), 33, [],
1513 [InitBasicFS, Always, TestOutputTrue
1514 [["mkdir_p"; "/new/foo/bar"];
1515 ["is_dir"; "/new/foo/bar"]];
1516 InitBasicFS, Always, TestOutputTrue
1517 [["mkdir_p"; "/new/foo/bar"];
1518 ["is_dir"; "/new/foo"]];
1519 InitBasicFS, Always, TestOutputTrue
1520 [["mkdir_p"; "/new/foo/bar"];
1521 ["is_dir"; "/new"]];
1522 (* Regression tests for RHBZ#503133: *)
1523 InitBasicFS, Always, TestRun
1525 ["mkdir_p"; "/new"]];
1526 InitBasicFS, Always, TestLastFail
1528 ["mkdir_p"; "/new"]]],
1529 "create a directory and parents",
1531 Create a directory named C<path>, creating any parent directories
1532 as necessary. This is like the C<mkdir -p> shell command.");
1534 ("chmod", (RErr, [Int "mode"; Pathname "path"]), 34, [],
1535 [], (* XXX Need stat command to test *)
1538 Change the mode (permissions) of C<path> to C<mode>. Only
1539 numeric modes are supported.
1541 I<Note>: When using this command from guestfish, C<mode>
1542 by default would be decimal, unless you prefix it with
1543 C<0> to get octal, ie. use C<0700> not C<700>.
1545 The mode actually set is affected by the umask.");
1547 ("chown", (RErr, [Int "owner"; Int "group"; Pathname "path"]), 35, [],
1548 [], (* XXX Need stat command to test *)
1549 "change file owner and group",
1551 Change the file owner to C<owner> and group to C<group>.
1553 Only numeric uid and gid are supported. If you want to use
1554 names, you will need to locate and parse the password file
1555 yourself (Augeas support makes this relatively easy).");
1557 ("exists", (RBool "existsflag", [Pathname "path"]), 36, [],
1558 [InitISOFS, Always, TestOutputTrue (
1559 [["exists"; "/empty"]]);
1560 InitISOFS, Always, TestOutputTrue (
1561 [["exists"; "/directory"]])],
1562 "test if file or directory exists",
1564 This returns C<true> if and only if there is a file, directory
1565 (or anything) with the given C<path> name.
1567 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
1569 ("is_file", (RBool "fileflag", [Pathname "path"]), 37, [],
1570 [InitISOFS, Always, TestOutputTrue (
1571 [["is_file"; "/known-1"]]);
1572 InitISOFS, Always, TestOutputFalse (
1573 [["is_file"; "/directory"]])],
1574 "test if file exists",
1576 This returns C<true> if and only if there is a file
1577 with the given C<path> name. Note that it returns false for
1578 other objects like directories.
1580 See also C<guestfs_stat>.");
1582 ("is_dir", (RBool "dirflag", [Pathname "path"]), 38, [],
1583 [InitISOFS, Always, TestOutputFalse (
1584 [["is_dir"; "/known-3"]]);
1585 InitISOFS, Always, TestOutputTrue (
1586 [["is_dir"; "/directory"]])],
1587 "test if file exists",
1589 This returns C<true> if and only if there is a directory
1590 with the given C<path> name. Note that it returns false for
1591 other objects like files.
1593 See also C<guestfs_stat>.");
1595 ("pvcreate", (RErr, [Device "device"]), 39, [Optional "lvm2"],
1596 [InitEmpty, Always, TestOutputListOfDevices (
1597 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1598 ["pvcreate"; "/dev/sda1"];
1599 ["pvcreate"; "/dev/sda2"];
1600 ["pvcreate"; "/dev/sda3"];
1601 ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1602 "create an LVM physical volume",
1604 This creates an LVM physical volume on the named C<device>,
1605 where C<device> should usually be a partition name such
1608 ("vgcreate", (RErr, [String "volgroup"; DeviceList "physvols"]), 40, [Optional "lvm2"],
1609 [InitEmpty, Always, TestOutputList (
1610 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1611 ["pvcreate"; "/dev/sda1"];
1612 ["pvcreate"; "/dev/sda2"];
1613 ["pvcreate"; "/dev/sda3"];
1614 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1615 ["vgcreate"; "VG2"; "/dev/sda3"];
1616 ["vgs"]], ["VG1"; "VG2"])],
1617 "create an LVM volume group",
1619 This creates an LVM volume group called C<volgroup>
1620 from the non-empty list of physical volumes C<physvols>.");
1622 ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"]), 41, [Optional "lvm2"],
1623 [InitEmpty, Always, TestOutputList (
1624 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1625 ["pvcreate"; "/dev/sda1"];
1626 ["pvcreate"; "/dev/sda2"];
1627 ["pvcreate"; "/dev/sda3"];
1628 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1629 ["vgcreate"; "VG2"; "/dev/sda3"];
1630 ["lvcreate"; "LV1"; "VG1"; "50"];
1631 ["lvcreate"; "LV2"; "VG1"; "50"];
1632 ["lvcreate"; "LV3"; "VG2"; "50"];
1633 ["lvcreate"; "LV4"; "VG2"; "50"];
1634 ["lvcreate"; "LV5"; "VG2"; "50"];
1636 ["/dev/VG1/LV1"; "/dev/VG1/LV2";
1637 "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
1638 "create an LVM logical volume",
1640 This creates an LVM logical volume called C<logvol>
1641 on the volume group C<volgroup>, with C<size> megabytes.");
1643 ("mkfs", (RErr, [String "fstype"; Device "device"]), 42, [],
1644 [InitEmpty, Always, TestOutput (
1645 [["part_disk"; "/dev/sda"; "mbr"];
1646 ["mkfs"; "ext2"; "/dev/sda1"];
1647 ["mount_options"; ""; "/dev/sda1"; "/"];
1648 ["write"; "/new"; "new file contents"];
1649 ["cat"; "/new"]], "new file contents")],
1650 "make a filesystem",
1652 This creates a filesystem on C<device> (usually a partition
1653 or LVM logical volume). The filesystem type is C<fstype>, for
1656 ("sfdisk", (RErr, [Device "device";
1657 Int "cyls"; Int "heads"; Int "sectors";
1658 StringList "lines"]), 43, [DangerWillRobinson],
1660 "create partitions on a block device",
1662 This is a direct interface to the L<sfdisk(8)> program for creating
1663 partitions on block devices.
1665 C<device> should be a block device, for example C</dev/sda>.
1667 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1668 and sectors on the device, which are passed directly to sfdisk as
1669 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
1670 of these, then the corresponding parameter is omitted. Usually for
1671 'large' disks, you can just pass C<0> for these, but for small
1672 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1673 out the right geometry and you will need to tell it.
1675 C<lines> is a list of lines that we feed to C<sfdisk>. For more
1676 information refer to the L<sfdisk(8)> manpage.
1678 To create a single partition occupying the whole disk, you would
1679 pass C<lines> as a single element list, when the single element being
1680 the string C<,> (comma).
1682 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>,
1683 C<guestfs_part_init>");
1685 ("write_file", (RErr, [Pathname "path"; String "content"; Int "size"]), 44, [ProtocolLimitWarning; DeprecatedBy "write"],
1686 (* Regression test for RHBZ#597135. *)
1687 [InitBasicFS, Always, TestLastFail
1688 [["write_file"; "/new"; "abc"; "10000"]]],
1691 This call creates a file called C<path>. The contents of the
1692 file is the string C<content> (which can contain any 8 bit data),
1693 with length C<size>.
1695 As a special case, if C<size> is C<0>
1696 then the length is calculated using C<strlen> (so in this case
1697 the content cannot contain embedded ASCII NULs).
1699 I<NB.> Owing to a bug, writing content containing ASCII NUL
1700 characters does I<not> work, even if the length is specified.");
1702 ("umount", (RErr, [String "pathordevice"]), 45, [FishAlias "unmount"],
1703 [InitEmpty, Always, TestOutputListOfDevices (
1704 [["part_disk"; "/dev/sda"; "mbr"];
1705 ["mkfs"; "ext2"; "/dev/sda1"];
1706 ["mount_options"; ""; "/dev/sda1"; "/"];
1707 ["mounts"]], ["/dev/sda1"]);
1708 InitEmpty, Always, TestOutputList (
1709 [["part_disk"; "/dev/sda"; "mbr"];
1710 ["mkfs"; "ext2"; "/dev/sda1"];
1711 ["mount_options"; ""; "/dev/sda1"; "/"];
1714 "unmount a filesystem",
1716 This unmounts the given filesystem. The filesystem may be
1717 specified either by its mountpoint (path) or the device which
1718 contains the filesystem.");
1720 ("mounts", (RStringList "devices", []), 46, [],
1721 [InitBasicFS, Always, TestOutputListOfDevices (
1722 [["mounts"]], ["/dev/sda1"])],
1723 "show mounted filesystems",
1725 This returns the list of currently mounted filesystems. It returns
1726 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1728 Some internal mounts are not shown.
1730 See also: C<guestfs_mountpoints>");
1732 ("umount_all", (RErr, []), 47, [FishAlias "unmount-all"],
1733 [InitBasicFS, Always, TestOutputList (
1736 (* check that umount_all can unmount nested mounts correctly: *)
1737 InitEmpty, Always, TestOutputList (
1738 [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1739 ["mkfs"; "ext2"; "/dev/sda1"];
1740 ["mkfs"; "ext2"; "/dev/sda2"];
1741 ["mkfs"; "ext2"; "/dev/sda3"];
1742 ["mount_options"; ""; "/dev/sda1"; "/"];
1744 ["mount_options"; ""; "/dev/sda2"; "/mp1"];
1745 ["mkdir"; "/mp1/mp2"];
1746 ["mount_options"; ""; "/dev/sda3"; "/mp1/mp2"];
1747 ["mkdir"; "/mp1/mp2/mp3"];
1750 "unmount all filesystems",
1752 This unmounts all mounted filesystems.
1754 Some internal mounts are not unmounted by this call.");
1756 ("lvm_remove_all", (RErr, []), 48, [DangerWillRobinson; Optional "lvm2"],
1758 "remove all LVM LVs, VGs and PVs",
1760 This command removes all LVM logical volumes, volume groups
1761 and physical volumes.");
1763 ("file", (RString "description", [Dev_or_Path "path"]), 49, [],
1764 [InitISOFS, Always, TestOutput (
1765 [["file"; "/empty"]], "empty");
1766 InitISOFS, Always, TestOutput (
1767 [["file"; "/known-1"]], "ASCII text");
1768 InitISOFS, Always, TestLastFail (
1769 [["file"; "/notexists"]]);
1770 InitISOFS, Always, TestOutput (
1771 [["file"; "/abssymlink"]], "symbolic link");
1772 InitISOFS, Always, TestOutput (
1773 [["file"; "/directory"]], "directory")],
1774 "determine file type",
1776 This call uses the standard L<file(1)> command to determine
1777 the type or contents of the file.
1779 This call will also transparently look inside various types
1782 The exact command which runs is C<file -zb path>. Note in
1783 particular that the filename is not prepended to the output
1786 This command can also be used on C</dev/> devices
1787 (and partitions, LV names). You can for example use this
1788 to determine if a device contains a filesystem, although
1789 it's usually better to use C<guestfs_vfs_type>.
1791 If the C<path> does not begin with C</dev/> then
1792 this command only works for the content of regular files.
1793 For other file types (directory, symbolic link etc) it
1794 will just return the string C<directory> etc.");
1796 ("command", (RString "output", [StringList "arguments"]), 50, [ProtocolLimitWarning],
1797 [InitBasicFS, Always, TestOutput (
1798 [["upload"; "test-command"; "/test-command"];
1799 ["chmod"; "0o755"; "/test-command"];
1800 ["command"; "/test-command 1"]], "Result1");
1801 InitBasicFS, Always, TestOutput (
1802 [["upload"; "test-command"; "/test-command"];
1803 ["chmod"; "0o755"; "/test-command"];
1804 ["command"; "/test-command 2"]], "Result2\n");
1805 InitBasicFS, Always, TestOutput (
1806 [["upload"; "test-command"; "/test-command"];
1807 ["chmod"; "0o755"; "/test-command"];
1808 ["command"; "/test-command 3"]], "\nResult3");
1809 InitBasicFS, Always, TestOutput (
1810 [["upload"; "test-command"; "/test-command"];
1811 ["chmod"; "0o755"; "/test-command"];
1812 ["command"; "/test-command 4"]], "\nResult4\n");
1813 InitBasicFS, Always, TestOutput (
1814 [["upload"; "test-command"; "/test-command"];
1815 ["chmod"; "0o755"; "/test-command"];
1816 ["command"; "/test-command 5"]], "\nResult5\n\n");
1817 InitBasicFS, Always, TestOutput (
1818 [["upload"; "test-command"; "/test-command"];
1819 ["chmod"; "0o755"; "/test-command"];
1820 ["command"; "/test-command 6"]], "\n\nResult6\n\n");
1821 InitBasicFS, Always, TestOutput (
1822 [["upload"; "test-command"; "/test-command"];
1823 ["chmod"; "0o755"; "/test-command"];
1824 ["command"; "/test-command 7"]], "");
1825 InitBasicFS, Always, TestOutput (
1826 [["upload"; "test-command"; "/test-command"];
1827 ["chmod"; "0o755"; "/test-command"];
1828 ["command"; "/test-command 8"]], "\n");
1829 InitBasicFS, Always, TestOutput (
1830 [["upload"; "test-command"; "/test-command"];
1831 ["chmod"; "0o755"; "/test-command"];
1832 ["command"; "/test-command 9"]], "\n\n");
1833 InitBasicFS, Always, TestOutput (
1834 [["upload"; "test-command"; "/test-command"];
1835 ["chmod"; "0o755"; "/test-command"];
1836 ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n");
1837 InitBasicFS, Always, TestOutput (
1838 [["upload"; "test-command"; "/test-command"];
1839 ["chmod"; "0o755"; "/test-command"];
1840 ["command"; "/test-command 11"]], "Result11-1\nResult11-2");
1841 InitBasicFS, Always, TestLastFail (
1842 [["upload"; "test-command"; "/test-command"];
1843 ["chmod"; "0o755"; "/test-command"];
1844 ["command"; "/test-command"]])],
1845 "run a command from the guest filesystem",
1847 This call runs a command from the guest filesystem. The
1848 filesystem must be mounted, and must contain a compatible
1849 operating system (ie. something Linux, with the same
1850 or compatible processor architecture).
1852 The single parameter is an argv-style list of arguments.
1853 The first element is the name of the program to run.
1854 Subsequent elements are parameters. The list must be
1855 non-empty (ie. must contain a program name). Note that
1856 the command runs directly, and is I<not> invoked via
1857 the shell (see C<guestfs_sh>).
1859 The return value is anything printed to I<stdout> by
1862 If the command returns a non-zero exit status, then
1863 this function returns an error message. The error message
1864 string is the content of I<stderr> from the command.
1866 The C<$PATH> environment variable will contain at least
1867 C</usr/bin> and C</bin>. If you require a program from
1868 another location, you should provide the full path in the
1871 Shared libraries and data files required by the program
1872 must be available on filesystems which are mounted in the
1873 correct places. It is the caller's responsibility to ensure
1874 all filesystems that are needed are mounted at the right
1877 ("command_lines", (RStringList "lines", [StringList "arguments"]), 51, [ProtocolLimitWarning],
1878 [InitBasicFS, Always, TestOutputList (
1879 [["upload"; "test-command"; "/test-command"];
1880 ["chmod"; "0o755"; "/test-command"];
1881 ["command_lines"; "/test-command 1"]], ["Result1"]);
1882 InitBasicFS, Always, TestOutputList (
1883 [["upload"; "test-command"; "/test-command"];
1884 ["chmod"; "0o755"; "/test-command"];
1885 ["command_lines"; "/test-command 2"]], ["Result2"]);
1886 InitBasicFS, Always, TestOutputList (
1887 [["upload"; "test-command"; "/test-command"];
1888 ["chmod"; "0o755"; "/test-command"];
1889 ["command_lines"; "/test-command 3"]], ["";"Result3"]);
1890 InitBasicFS, Always, TestOutputList (
1891 [["upload"; "test-command"; "/test-command"];
1892 ["chmod"; "0o755"; "/test-command"];
1893 ["command_lines"; "/test-command 4"]], ["";"Result4"]);
1894 InitBasicFS, Always, TestOutputList (
1895 [["upload"; "test-command"; "/test-command"];
1896 ["chmod"; "0o755"; "/test-command"];
1897 ["command_lines"; "/test-command 5"]], ["";"Result5";""]);
1898 InitBasicFS, Always, TestOutputList (
1899 [["upload"; "test-command"; "/test-command"];
1900 ["chmod"; "0o755"; "/test-command"];
1901 ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]);
1902 InitBasicFS, Always, TestOutputList (
1903 [["upload"; "test-command"; "/test-command"];
1904 ["chmod"; "0o755"; "/test-command"];
1905 ["command_lines"; "/test-command 7"]], []);
1906 InitBasicFS, Always, TestOutputList (
1907 [["upload"; "test-command"; "/test-command"];
1908 ["chmod"; "0o755"; "/test-command"];
1909 ["command_lines"; "/test-command 8"]], [""]);
1910 InitBasicFS, Always, TestOutputList (
1911 [["upload"; "test-command"; "/test-command"];
1912 ["chmod"; "0o755"; "/test-command"];
1913 ["command_lines"; "/test-command 9"]], ["";""]);
1914 InitBasicFS, Always, TestOutputList (
1915 [["upload"; "test-command"; "/test-command"];
1916 ["chmod"; "0o755"; "/test-command"];
1917 ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]);
1918 InitBasicFS, Always, TestOutputList (
1919 [["upload"; "test-command"; "/test-command"];
1920 ["chmod"; "0o755"; "/test-command"];
1921 ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])],
1922 "run a command, returning lines",
1924 This is the same as C<guestfs_command>, but splits the
1925 result into a list of lines.
1927 See also: C<guestfs_sh_lines>");
1929 ("stat", (RStruct ("statbuf", "stat"), [Pathname "path"]), 52, [],
1930 [InitISOFS, Always, TestOutputStruct (
1931 [["stat"; "/empty"]], [CompareWithInt ("size", 0)])],
1932 "get file information",
1934 Returns file information for the given C<path>.
1936 This is the same as the C<stat(2)> system call.");
1938 ("lstat", (RStruct ("statbuf", "stat"), [Pathname "path"]), 53, [],
1939 [InitISOFS, Always, TestOutputStruct (
1940 [["lstat"; "/empty"]], [CompareWithInt ("size", 0)])],
1941 "get file information for a symbolic link",
1943 Returns file information for the given C<path>.
1945 This is the same as C<guestfs_stat> except that if C<path>
1946 is a symbolic link, then the link is stat-ed, not the file it
1949 This is the same as the C<lstat(2)> system call.");
1951 ("statvfs", (RStruct ("statbuf", "statvfs"), [Pathname "path"]), 54, [],
1952 [InitISOFS, Always, TestOutputStruct (
1953 [["statvfs"; "/"]], [CompareWithInt ("namemax", 255)])],
1954 "get file system statistics",
1956 Returns file system statistics for any mounted file system.
1957 C<path> should be a file or directory in the mounted file system
1958 (typically it is the mount point itself, but it doesn't need to be).
1960 This is the same as the C<statvfs(2)> system call.");
1962 ("tune2fs_l", (RHashtable "superblock", [Device "device"]), 55, [],
1964 "get ext2/ext3/ext4 superblock details",
1966 This returns the contents of the ext2, ext3 or ext4 filesystem
1967 superblock on C<device>.
1969 It is the same as running C<tune2fs -l device>. See L<tune2fs(8)>
1970 manpage for more details. The list of fields returned isn't
1971 clearly defined, and depends on both the version of C<tune2fs>
1972 that libguestfs was built against, and the filesystem itself.");
1974 ("blockdev_setro", (RErr, [Device "device"]), 56, [],
1975 [InitEmpty, Always, TestOutputTrue (
1976 [["blockdev_setro"; "/dev/sda"];
1977 ["blockdev_getro"; "/dev/sda"]])],
1978 "set block device to read-only",
1980 Sets the block device named C<device> to read-only.
1982 This uses the L<blockdev(8)> command.");
1984 ("blockdev_setrw", (RErr, [Device "device"]), 57, [],
1985 [InitEmpty, Always, TestOutputFalse (
1986 [["blockdev_setrw"; "/dev/sda"];
1987 ["blockdev_getro"; "/dev/sda"]])],
1988 "set block device to read-write",
1990 Sets the block device named C<device> to read-write.
1992 This uses the L<blockdev(8)> command.");
1994 ("blockdev_getro", (RBool "ro", [Device "device"]), 58, [],
1995 [InitEmpty, Always, TestOutputTrue (
1996 [["blockdev_setro"; "/dev/sda"];
1997 ["blockdev_getro"; "/dev/sda"]])],
1998 "is block device set to read-only",
2000 Returns a boolean indicating if the block device is read-only
2001 (true if read-only, false if not).
2003 This uses the L<blockdev(8)> command.");
2005 ("blockdev_getss", (RInt "sectorsize", [Device "device"]), 59, [],
2006 [InitEmpty, Always, TestOutputInt (
2007 [["blockdev_getss"; "/dev/sda"]], 512)],
2008 "get sectorsize of block device",
2010 This returns the size of sectors on a block device.
2011 Usually 512, but can be larger for modern devices.
2013 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
2016 This uses the L<blockdev(8)> command.");
2018 ("blockdev_getbsz", (RInt "blocksize", [Device "device"]), 60, [],
2019 [InitEmpty, Always, TestOutputInt (
2020 [["blockdev_getbsz"; "/dev/sda"]], 4096)],
2021 "get blocksize of block device",
2023 This returns the block size of a device.
2025 (Note this is different from both I<size in blocks> and
2026 I<filesystem block size>).
2028 This uses the L<blockdev(8)> command.");
2030 ("blockdev_setbsz", (RErr, [Device "device"; Int "blocksize"]), 61, [],
2032 "set blocksize of block device",
2034 This sets the block size of a device.
2036 (Note this is different from both I<size in blocks> and
2037 I<filesystem block size>).
2039 This uses the L<blockdev(8)> command.");
2041 ("blockdev_getsz", (RInt64 "sizeinsectors", [Device "device"]), 62, [],
2042 [InitEmpty, Always, TestOutputInt (
2043 [["blockdev_getsz"; "/dev/sda"]], 1024000)],
2044 "get total size of device in 512-byte sectors",
2046 This returns the size of the device in units of 512-byte sectors
2047 (even if the sectorsize isn't 512 bytes ... weird).
2049 See also C<guestfs_blockdev_getss> for the real sector size of
2050 the device, and C<guestfs_blockdev_getsize64> for the more
2051 useful I<size in bytes>.
2053 This uses the L<blockdev(8)> command.");
2055 ("blockdev_getsize64", (RInt64 "sizeinbytes", [Device "device"]), 63, [],
2056 [InitEmpty, Always, TestOutputInt (
2057 [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
2058 "get total size of device in bytes",
2060 This returns the size of the device in bytes.
2062 See also C<guestfs_blockdev_getsz>.
2064 This uses the L<blockdev(8)> command.");
2066 ("blockdev_flushbufs", (RErr, [Device "device"]), 64, [],
2067 [InitEmpty, Always, TestRun
2068 [["blockdev_flushbufs"; "/dev/sda"]]],
2069 "flush device buffers",
2071 This tells the kernel to flush internal buffers associated
2074 This uses the L<blockdev(8)> command.");
2076 ("blockdev_rereadpt", (RErr, [Device "device"]), 65, [],
2077 [InitEmpty, Always, TestRun
2078 [["blockdev_rereadpt"; "/dev/sda"]]],
2079 "reread partition table",
2081 Reread the partition table on C<device>.
2083 This uses the L<blockdev(8)> command.");
2085 ("upload", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"]), 66, [],
2086 [InitBasicFS, Always, TestOutput (
2087 (* Pick a file from cwd which isn't likely to change. *)
2088 [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
2089 ["checksum"; "md5"; "/COPYING.LIB"]],
2090 Digest.to_hex (Digest.file "COPYING.LIB"))],
2091 "upload a file from the local machine",
2093 Upload local file C<filename> to C<remotefilename> on the
2096 C<filename> can also be a named pipe.
2098 See also C<guestfs_download>.");
2100 ("download", (RErr, [Dev_or_Path "remotefilename"; FileOut "filename"]), 67, [],
2101 [InitBasicFS, Always, TestOutput (
2102 (* Pick a file from cwd which isn't likely to change. *)
2103 [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
2104 ["download"; "/COPYING.LIB"; "testdownload.tmp"];
2105 ["upload"; "testdownload.tmp"; "/upload"];
2106 ["checksum"; "md5"; "/upload"]],
2107 Digest.to_hex (Digest.file "COPYING.LIB"))],
2108 "download a file to the local machine",
2110 Download file C<remotefilename> and save it as C<filename>
2111 on the local machine.
2113 C<filename> can also be a named pipe.
2115 See also C<guestfs_upload>, C<guestfs_cat>.");
2117 ("checksum", (RString "checksum", [String "csumtype"; Pathname "path"]), 68, [],
2118 [InitISOFS, Always, TestOutput (
2119 [["checksum"; "crc"; "/known-3"]], "2891671662");
2120 InitISOFS, Always, TestLastFail (
2121 [["checksum"; "crc"; "/notexists"]]);
2122 InitISOFS, Always, TestOutput (
2123 [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c");
2124 InitISOFS, Always, TestOutput (
2125 [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15");
2126 InitISOFS, Always, TestOutput (
2127 [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741");
2128 InitISOFS, Always, TestOutput (
2129 [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30");
2130 InitISOFS, Always, TestOutput (
2131 [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640");
2132 InitISOFS, Always, TestOutput (
2133 [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6");
2134 (* Test for RHBZ#579608, absolute symbolic links. *)
2135 InitISOFS, Always, TestOutput (
2136 [["checksum"; "sha512"; "/abssymlink"]], "5f57d0639bc95081c53afc63a449403883818edc64da48930ad6b1a4fb49be90404686877743fbcd7c99811f3def7df7bc22635c885c6a8cf79c806b43451c1a")],
2137 "compute MD5, SHAx or CRC checksum of file",
2139 This call computes the MD5, SHAx or CRC checksum of the
2142 The type of checksum to compute is given by the C<csumtype>
2143 parameter which must have one of the following values:
2149 Compute the cyclic redundancy check (CRC) specified by POSIX
2150 for the C<cksum> command.
2154 Compute the MD5 hash (using the C<md5sum> program).
2158 Compute the SHA1 hash (using the C<sha1sum> program).
2162 Compute the SHA224 hash (using the C<sha224sum> program).
2166 Compute the SHA256 hash (using the C<sha256sum> program).
2170 Compute the SHA384 hash (using the C<sha384sum> program).
2174 Compute the SHA512 hash (using the C<sha512sum> program).
2178 The checksum is returned as a printable string.
2180 To get the checksum for a device, use C<guestfs_checksum_device>.
2182 To get the checksums for many files, use C<guestfs_checksums_out>.");
2184 ("tar_in", (RErr, [FileIn "tarfile"; Pathname "directory"]), 69, [],
2185 [InitBasicFS, Always, TestOutput (
2186 [["tar_in"; "../images/helloworld.tar"; "/"];
2187 ["cat"; "/hello"]], "hello\n")],
2188 "unpack tarfile to directory",
2190 This command uploads and unpacks local file C<tarfile> (an
2191 I<uncompressed> tar file) into C<directory>.
2193 To upload a compressed tarball, use C<guestfs_tgz_in>
2194 or C<guestfs_txz_in>.");
2196 ("tar_out", (RErr, [String "directory"; FileOut "tarfile"]), 70, [],
2198 "pack directory into tarfile",
2200 This command packs the contents of C<directory> and downloads
2201 it to local file C<tarfile>.
2203 To download a compressed tarball, use C<guestfs_tgz_out>
2204 or C<guestfs_txz_out>.");
2206 ("tgz_in", (RErr, [FileIn "tarball"; Pathname "directory"]), 71, [],
2207 [InitBasicFS, Always, TestOutput (
2208 [["tgz_in"; "../images/helloworld.tar.gz"; "/"];
2209 ["cat"; "/hello"]], "hello\n")],
2210 "unpack compressed tarball to directory",
2212 This command uploads and unpacks local file C<tarball> (a
2213 I<gzip compressed> tar file) into C<directory>.
2215 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
2217 ("tgz_out", (RErr, [Pathname "directory"; FileOut "tarball"]), 72, [],
2219 "pack directory into compressed tarball",
2221 This command packs the contents of C<directory> and downloads
2222 it to local file C<tarball>.
2224 To download an uncompressed tarball, use C<guestfs_tar_out>.");
2226 ("mount_ro", (RErr, [Device "device"; String "mountpoint"]), 73, [],
2227 [InitBasicFS, Always, TestLastFail (
2229 ["mount_ro"; "/dev/sda1"; "/"];
2230 ["touch"; "/new"]]);
2231 InitBasicFS, Always, TestOutput (
2232 [["write"; "/new"; "data"];
2234 ["mount_ro"; "/dev/sda1"; "/"];
2235 ["cat"; "/new"]], "data")],
2236 "mount a guest disk, read-only",
2238 This is the same as the C<guestfs_mount> command, but it
2239 mounts the filesystem with the read-only (I<-o ro>) flag.");
2241 ("mount_options", (RErr, [String "options"; Device "device"; String "mountpoint"]), 74, [],
2243 "mount a guest disk with mount options",
2245 This is the same as the C<guestfs_mount> command, but it
2246 allows you to set the mount options as for the
2247 L<mount(8)> I<-o> flag.
2249 If the C<options> parameter is an empty string, then
2250 no options are passed (all options default to whatever
2251 the filesystem uses).");
2253 ("mount_vfs", (RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"]), 75, [],
2255 "mount a guest disk with mount options and vfstype",
2257 This is the same as the C<guestfs_mount> command, but it
2258 allows you to set both the mount options and the vfstype
2259 as for the L<mount(8)> I<-o> and I<-t> flags.");
2261 ("debug", (RString "result", [String "subcmd"; StringList "extraargs"]), 76, [],
2263 "debugging and internals",
2265 The C<guestfs_debug> command exposes some internals of
2266 C<guestfsd> (the guestfs daemon) that runs inside the
2269 There is no comprehensive help for this command. You have
2270 to look at the file C<daemon/debug.c> in the libguestfs source
2271 to find out what you can do.");
2273 ("lvremove", (RErr, [Device "device"]), 77, [Optional "lvm2"],
2274 [InitEmpty, Always, TestOutputList (
2275 [["part_disk"; "/dev/sda"; "mbr"];
2276 ["pvcreate"; "/dev/sda1"];
2277 ["vgcreate"; "VG"; "/dev/sda1"];
2278 ["lvcreate"; "LV1"; "VG"; "50"];
2279 ["lvcreate"; "LV2"; "VG"; "50"];
2280 ["lvremove"; "/dev/VG/LV1"];
2281 ["lvs"]], ["/dev/VG/LV2"]);
2282 InitEmpty, Always, TestOutputList (
2283 [["part_disk"; "/dev/sda"; "mbr"];
2284 ["pvcreate"; "/dev/sda1"];
2285 ["vgcreate"; "VG"; "/dev/sda1"];
2286 ["lvcreate"; "LV1"; "VG"; "50"];
2287 ["lvcreate"; "LV2"; "VG"; "50"];
2288 ["lvremove"; "/dev/VG"];
2290 InitEmpty, Always, TestOutputList (
2291 [["part_disk"; "/dev/sda"; "mbr"];
2292 ["pvcreate"; "/dev/sda1"];
2293 ["vgcreate"; "VG"; "/dev/sda1"];
2294 ["lvcreate"; "LV1"; "VG"; "50"];
2295 ["lvcreate"; "LV2"; "VG"; "50"];
2296 ["lvremove"; "/dev/VG"];
2298 "remove an LVM logical volume",
2300 Remove an LVM logical volume C<device>, where C<device> is
2301 the path to the LV, such as C</dev/VG/LV>.
2303 You can also remove all LVs in a volume group by specifying
2304 the VG name, C</dev/VG>.");
2306 ("vgremove", (RErr, [String "vgname"]), 78, [Optional "lvm2"],
2307 [InitEmpty, Always, TestOutputList (
2308 [["part_disk"; "/dev/sda"; "mbr"];
2309 ["pvcreate"; "/dev/sda1"];
2310 ["vgcreate"; "VG"; "/dev/sda1"];
2311 ["lvcreate"; "LV1"; "VG"; "50"];
2312 ["lvcreate"; "LV2"; "VG"; "50"];
2315 InitEmpty, Always, TestOutputList (
2316 [["part_disk"; "/dev/sda"; "mbr"];
2317 ["pvcreate"; "/dev/sda1"];
2318 ["vgcreate"; "VG"; "/dev/sda1"];
2319 ["lvcreate"; "LV1"; "VG"; "50"];
2320 ["lvcreate"; "LV2"; "VG"; "50"];
2323 "remove an LVM volume group",
2325 Remove an LVM volume group C<vgname>, (for example C<VG>).
2327 This also forcibly removes all logical volumes in the volume
2330 ("pvremove", (RErr, [Device "device"]), 79, [Optional "lvm2"],
2331 [InitEmpty, Always, TestOutputListOfDevices (
2332 [["part_disk"; "/dev/sda"; "mbr"];
2333 ["pvcreate"; "/dev/sda1"];
2334 ["vgcreate"; "VG"; "/dev/sda1"];
2335 ["lvcreate"; "LV1"; "VG"; "50"];
2336 ["lvcreate"; "LV2"; "VG"; "50"];
2338 ["pvremove"; "/dev/sda1"];
2340 InitEmpty, Always, TestOutputListOfDevices (
2341 [["part_disk"; "/dev/sda"; "mbr"];
2342 ["pvcreate"; "/dev/sda1"];
2343 ["vgcreate"; "VG"; "/dev/sda1"];
2344 ["lvcreate"; "LV1"; "VG"; "50"];
2345 ["lvcreate"; "LV2"; "VG"; "50"];
2347 ["pvremove"; "/dev/sda1"];
2349 InitEmpty, Always, TestOutputListOfDevices (
2350 [["part_disk"; "/dev/sda"; "mbr"];
2351 ["pvcreate"; "/dev/sda1"];
2352 ["vgcreate"; "VG"; "/dev/sda1"];
2353 ["lvcreate"; "LV1"; "VG"; "50"];
2354 ["lvcreate"; "LV2"; "VG"; "50"];
2356 ["pvremove"; "/dev/sda1"];
2358 "remove an LVM physical volume",
2360 This wipes a physical volume C<device> so that LVM will no longer
2363 The implementation uses the C<pvremove> command which refuses to
2364 wipe physical volumes that contain any volume groups, so you have
2365 to remove those first.");
2367 ("set_e2label", (RErr, [Device "device"; String "label"]), 80, [],
2368 [InitBasicFS, Always, TestOutput (
2369 [["set_e2label"; "/dev/sda1"; "testlabel"];
2370 ["get_e2label"; "/dev/sda1"]], "testlabel")],
2371 "set the ext2/3/4 filesystem label",
2373 This sets the ext2/3/4 filesystem label of the filesystem on
2374 C<device> to C<label>. Filesystem labels are limited to
2377 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
2378 to return the existing label on a filesystem.");
2380 ("get_e2label", (RString "label", [Device "device"]), 81, [DeprecatedBy "vfs_label"],
2382 "get the ext2/3/4 filesystem label",
2384 This returns the ext2/3/4 filesystem label of the filesystem on
2387 ("set_e2uuid", (RErr, [Device "device"; String "uuid"]), 82, [],
2388 (let uuid = uuidgen () in
2389 [InitBasicFS, Always, TestOutput (
2390 [["set_e2uuid"; "/dev/sda1"; uuid];
2391 ["get_e2uuid"; "/dev/sda1"]], uuid);
2392 InitBasicFS, Always, TestOutput (
2393 [["set_e2uuid"; "/dev/sda1"; "clear"];
2394 ["get_e2uuid"; "/dev/sda1"]], "");
2395 (* We can't predict what UUIDs will be, so just check the commands run. *)
2396 InitBasicFS, Always, TestRun (
2397 [["set_e2uuid"; "/dev/sda1"; "random"]]);
2398 InitBasicFS, Always, TestRun (
2399 [["set_e2uuid"; "/dev/sda1"; "time"]])]),
2400 "set the ext2/3/4 filesystem UUID",
2402 This sets the ext2/3/4 filesystem UUID of the filesystem on
2403 C<device> to C<uuid>. The format of the UUID and alternatives
2404 such as C<clear>, C<random> and C<time> are described in the
2405 L<tune2fs(8)> manpage.
2407 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
2408 to return the existing UUID of a filesystem.");
2410 ("get_e2uuid", (RString "uuid", [Device "device"]), 83, [DeprecatedBy "vfs_uuid"],
2411 (* Regression test for RHBZ#597112. *)
2412 (let uuid = uuidgen () in
2413 [InitBasicFS, Always, TestOutput (
2414 [["mke2journal"; "1024"; "/dev/sdb"];
2415 ["set_e2uuid"; "/dev/sdb"; uuid];
2416 ["get_e2uuid"; "/dev/sdb"]], uuid)]),
2417 "get the ext2/3/4 filesystem UUID",
2419 This returns the ext2/3/4 filesystem UUID of the filesystem on
2422 ("fsck", (RInt "status", [String "fstype"; Device "device"]), 84, [FishOutput FishOutputHexadecimal],
2423 [InitBasicFS, Always, TestOutputInt (
2424 [["umount"; "/dev/sda1"];
2425 ["fsck"; "ext2"; "/dev/sda1"]], 0);
2426 InitBasicFS, Always, TestOutputInt (
2427 [["umount"; "/dev/sda1"];
2428 ["zero"; "/dev/sda1"];
2429 ["fsck"; "ext2"; "/dev/sda1"]], 8)],
2430 "run the filesystem checker",
2432 This runs the filesystem checker (fsck) on C<device> which
2433 should have filesystem type C<fstype>.
2435 The returned integer is the status. See L<fsck(8)> for the
2436 list of status codes from C<fsck>.
2444 Multiple status codes can be summed together.
2448 A non-zero return code can mean \"success\", for example if
2449 errors have been corrected on the filesystem.
2453 Checking or repairing NTFS volumes is not supported
2458 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
2460 ("zero", (RErr, [Device "device"]), 85, [],
2461 [InitBasicFS, Always, TestOutput (
2462 [["umount"; "/dev/sda1"];
2463 ["zero"; "/dev/sda1"];
2464 ["file"; "/dev/sda1"]], "data")],
2465 "write zeroes to the device",
2467 This command writes zeroes over the first few blocks of C<device>.
2469 How many blocks are zeroed isn't specified (but it's I<not> enough
2470 to securely wipe the device). It should be sufficient to remove
2471 any partition tables, filesystem superblocks and so on.
2473 See also: C<guestfs_zero_device>, C<guestfs_scrub_device>.");
2475 ("grub_install", (RErr, [Pathname "root"; Device "device"]), 86, [],
2477 * https://bugzilla.redhat.com/show_bug.cgi?id=484986
2478 * https://bugzilla.redhat.com/show_bug.cgi?id=479760
2480 [InitBasicFS, Always, TestOutputTrue (
2481 [["mkdir_p"; "/boot/grub"];
2482 ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
2483 ["grub_install"; "/"; "/dev/vda"];
2484 ["is_dir"; "/boot"]])],
2487 This command installs GRUB (the Grand Unified Bootloader) on
2488 C<device>, with the root directory being C<root>.
2490 Note: If grub-install reports the error
2491 \"No suitable drive was found in the generated device map.\"
2492 it may be that you need to create a C</boot/grub/device.map>
2493 file first that contains the mapping between grub device names
2494 and Linux device names. It is usually sufficient to create
2499 replacing C</dev/vda> with the name of the installation device.");
2501 ("cp", (RErr, [Pathname "src"; Pathname "dest"]), 87, [],
2502 [InitBasicFS, Always, TestOutput (
2503 [["write"; "/old"; "file content"];
2504 ["cp"; "/old"; "/new"];
2505 ["cat"; "/new"]], "file content");
2506 InitBasicFS, Always, TestOutputTrue (
2507 [["write"; "/old"; "file content"];
2508 ["cp"; "/old"; "/new"];
2509 ["is_file"; "/old"]]);
2510 InitBasicFS, Always, TestOutput (
2511 [["write"; "/old"; "file content"];
2513 ["cp"; "/old"; "/dir/new"];
2514 ["cat"; "/dir/new"]], "file content")],
2517 This copies a file from C<src> to C<dest> where C<dest> is
2518 either a destination filename or destination directory.");
2520 ("cp_a", (RErr, [Pathname "src"; Pathname "dest"]), 88, [],
2521 [InitBasicFS, Always, TestOutput (
2522 [["mkdir"; "/olddir"];
2523 ["mkdir"; "/newdir"];
2524 ["write"; "/olddir/file"; "file content"];
2525 ["cp_a"; "/olddir"; "/newdir"];
2526 ["cat"; "/newdir/olddir/file"]], "file content")],
2527 "copy a file or directory recursively",
2529 This copies a file or directory from C<src> to C<dest>
2530 recursively using the C<cp -a> command.");
2532 ("mv", (RErr, [Pathname "src"; Pathname "dest"]), 89, [],
2533 [InitBasicFS, Always, TestOutput (
2534 [["write"; "/old"; "file content"];
2535 ["mv"; "/old"; "/new"];
2536 ["cat"; "/new"]], "file content");
2537 InitBasicFS, Always, TestOutputFalse (
2538 [["write"; "/old"; "file content"];
2539 ["mv"; "/old"; "/new"];
2540 ["is_file"; "/old"]])],
2543 This moves a file from C<src> to C<dest> where C<dest> is
2544 either a destination filename or destination directory.");
2546 ("drop_caches", (RErr, [Int "whattodrop"]), 90, [],
2547 [InitEmpty, Always, TestRun (
2548 [["drop_caches"; "3"]])],
2549 "drop kernel page cache, dentries and inodes",
2551 This instructs the guest kernel to drop its page cache,
2552 and/or dentries and inode caches. The parameter C<whattodrop>
2553 tells the kernel what precisely to drop, see
2554 L<http://linux-mm.org/Drop_Caches>
2556 Setting C<whattodrop> to 3 should drop everything.
2558 This automatically calls L<sync(2)> before the operation,
2559 so that the maximum guest memory is freed.");
2561 ("dmesg", (RString "kmsgs", []), 91, [],
2562 [InitEmpty, Always, TestRun (
2564 "return kernel messages",
2566 This returns the kernel messages (C<dmesg> output) from
2567 the guest kernel. This is sometimes useful for extended
2568 debugging of problems.
2570 Another way to get the same information is to enable
2571 verbose messages with C<guestfs_set_verbose> or by setting
2572 the environment variable C<LIBGUESTFS_DEBUG=1> before
2573 running the program.");
2575 ("ping_daemon", (RErr, []), 92, [],
2576 [InitEmpty, Always, TestRun (
2577 [["ping_daemon"]])],
2578 "ping the guest daemon",
2580 This is a test probe into the guestfs daemon running inside
2581 the qemu subprocess. Calling this function checks that the
2582 daemon responds to the ping message, without affecting the daemon
2583 or attached block device(s) in any other way.");
2585 ("equal", (RBool "equality", [Pathname "file1"; Pathname "file2"]), 93, [],
2586 [InitBasicFS, Always, TestOutputTrue (
2587 [["write"; "/file1"; "contents of a file"];
2588 ["cp"; "/file1"; "/file2"];
2589 ["equal"; "/file1"; "/file2"]]);
2590 InitBasicFS, Always, TestOutputFalse (
2591 [["write"; "/file1"; "contents of a file"];
2592 ["write"; "/file2"; "contents of another file"];
2593 ["equal"; "/file1"; "/file2"]]);
2594 InitBasicFS, Always, TestLastFail (
2595 [["equal"; "/file1"; "/file2"]])],
2596 "test if two files have equal contents",
2598 This compares the two files C<file1> and C<file2> and returns
2599 true if their content is exactly equal, or false otherwise.
2601 The external L<cmp(1)> program is used for the comparison.");
2603 ("strings", (RStringList "stringsout", [Pathname "path"]), 94, [ProtocolLimitWarning],
2604 [InitISOFS, Always, TestOutputList (
2605 [["strings"; "/known-5"]], ["abcdefghi"; "jklmnopqr"]);
2606 InitISOFS, Always, TestOutputList (
2607 [["strings"; "/empty"]], []);
2608 (* Test for RHBZ#579608, absolute symbolic links. *)
2609 InitISOFS, Always, TestRun (
2610 [["strings"; "/abssymlink"]])],
2611 "print the printable strings in a file",
2613 This runs the L<strings(1)> command on a file and returns
2614 the list of printable strings found.");
2616 ("strings_e", (RStringList "stringsout", [String "encoding"; Pathname "path"]), 95, [ProtocolLimitWarning],
2617 [InitISOFS, Always, TestOutputList (
2618 [["strings_e"; "b"; "/known-5"]], []);
2619 InitBasicFS, Always, TestOutputList (
2620 [["write"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"];
2621 ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2622 "print the printable strings in a file",
2624 This is like the C<guestfs_strings> command, but allows you to
2625 specify the encoding of strings that are looked for in
2626 the source file C<path>.
2628 Allowed encodings are:
2634 Single 7-bit-byte characters like ASCII and the ASCII-compatible
2635 parts of ISO-8859-X (this is what C<guestfs_strings> uses).
2639 Single 8-bit-byte characters.
2643 16-bit big endian strings such as those encoded in
2644 UTF-16BE or UCS-2BE.
2646 =item l (lower case letter L)
2648 16-bit little endian such as UTF-16LE and UCS-2LE.
2649 This is useful for examining binaries in Windows guests.
2653 32-bit big endian such as UCS-4BE.
2657 32-bit little endian such as UCS-4LE.
2661 The returned strings are transcoded to UTF-8.");
2663 ("hexdump", (RString "dump", [Pathname "path"]), 96, [ProtocolLimitWarning],
2664 [InitISOFS, Always, TestOutput (
2665 [["hexdump"; "/known-4"]], "00000000 61 62 63 0a 64 65 66 0a 67 68 69 |abc.def.ghi|\n0000000b\n");
2666 (* Test for RHBZ#501888c2 regression which caused large hexdump
2667 * commands to segfault.
2669 InitISOFS, Always, TestRun (
2670 [["hexdump"; "/100krandom"]]);
2671 (* Test for RHBZ#579608, absolute symbolic links. *)
2672 InitISOFS, Always, TestRun (
2673 [["hexdump"; "/abssymlink"]])],
2674 "dump a file in hexadecimal",
2676 This runs C<hexdump -C> on the given C<path>. The result is
2677 the human-readable, canonical hex dump of the file.");
2679 ("zerofree", (RErr, [Device "device"]), 97, [Optional "zerofree"],
2680 [InitNone, Always, TestOutput (
2681 [["part_disk"; "/dev/sda"; "mbr"];
2682 ["mkfs"; "ext3"; "/dev/sda1"];
2683 ["mount_options"; ""; "/dev/sda1"; "/"];
2684 ["write"; "/new"; "test file"];
2685 ["umount"; "/dev/sda1"];
2686 ["zerofree"; "/dev/sda1"];
2687 ["mount_options"; ""; "/dev/sda1"; "/"];
2688 ["cat"; "/new"]], "test file")],
2689 "zero unused inodes and disk blocks on ext2/3 filesystem",
2691 This runs the I<zerofree> program on C<device>. This program
2692 claims to zero unused inodes and disk blocks on an ext2/3
2693 filesystem, thus making it possible to compress the filesystem
2696 You should B<not> run this program if the filesystem is
2699 It is possible that using this program can damage the filesystem
2700 or data on the filesystem.");
2702 ("pvresize", (RErr, [Device "device"]), 98, [Optional "lvm2"],
2704 "resize an LVM physical volume",
2706 This resizes (expands or shrinks) an existing LVM physical
2707 volume to match the new size of the underlying device.");
2709 ("sfdisk_N", (RErr, [Device "device"; Int "partnum";
2710 Int "cyls"; Int "heads"; Int "sectors";
2711 String "line"]), 99, [DangerWillRobinson],
2713 "modify a single partition on a block device",
2715 This runs L<sfdisk(8)> option to modify just the single
2716 partition C<n> (note: C<n> counts from 1).
2718 For other parameters, see C<guestfs_sfdisk>. You should usually
2719 pass C<0> for the cyls/heads/sectors parameters.
2721 See also: C<guestfs_part_add>");
2723 ("sfdisk_l", (RString "partitions", [Device "device"]), 100, [],
2725 "display the partition table",
2727 This displays the partition table on C<device>, in the
2728 human-readable output of the L<sfdisk(8)> command. It is
2729 not intended to be parsed.
2731 See also: C<guestfs_part_list>");
2733 ("sfdisk_kernel_geometry", (RString "partitions", [Device "device"]), 101, [],
2735 "display the kernel geometry",
2737 This displays the kernel's idea of the geometry of C<device>.
2739 The result is in human-readable format, and not designed to
2742 ("sfdisk_disk_geometry", (RString "partitions", [Device "device"]), 102, [],
2744 "display the disk geometry from the partition table",
2746 This displays the disk geometry of C<device> read from the
2747 partition table. Especially in the case where the underlying
2748 block device has been resized, this can be different from the
2749 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2751 The result is in human-readable format, and not designed to
2754 ("vg_activate_all", (RErr, [Bool "activate"]), 103, [Optional "lvm2"],
2756 "activate or deactivate all volume groups",
2758 This command activates or (if C<activate> is false) deactivates
2759 all logical volumes in all volume groups.
2760 If activated, then they are made known to the
2761 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2762 then those devices disappear.
2764 This command is the same as running C<vgchange -a y|n>");
2766 ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"]), 104, [Optional "lvm2"],
2768 "activate or deactivate some volume groups",
2770 This command activates or (if C<activate> is false) deactivates
2771 all logical volumes in the listed volume groups C<volgroups>.
2772 If activated, then they are made known to the
2773 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2774 then those devices disappear.
2776 This command is the same as running C<vgchange -a y|n volgroups...>
2778 Note that if C<volgroups> is an empty list then B<all> volume groups
2779 are activated or deactivated.");
2781 ("lvresize", (RErr, [Device "device"; Int "mbytes"]), 105, [Optional "lvm2"],
2782 [InitNone, Always, TestOutput (
2783 [["part_disk"; "/dev/sda"; "mbr"];
2784 ["pvcreate"; "/dev/sda1"];
2785 ["vgcreate"; "VG"; "/dev/sda1"];
2786 ["lvcreate"; "LV"; "VG"; "10"];
2787 ["mkfs"; "ext2"; "/dev/VG/LV"];
2788 ["mount_options"; ""; "/dev/VG/LV"; "/"];
2789 ["write"; "/new"; "test content"];
2791 ["lvresize"; "/dev/VG/LV"; "20"];
2792 ["e2fsck_f"; "/dev/VG/LV"];
2793 ["resize2fs"; "/dev/VG/LV"];
2794 ["mount_options"; ""; "/dev/VG/LV"; "/"];
2795 ["cat"; "/new"]], "test content");
2796 InitNone, Always, TestRun (
2797 (* Make an LV smaller to test RHBZ#587484. *)
2798 [["part_disk"; "/dev/sda"; "mbr"];
2799 ["pvcreate"; "/dev/sda1"];
2800 ["vgcreate"; "VG"; "/dev/sda1"];
2801 ["lvcreate"; "LV"; "VG"; "20"];
2802 ["lvresize"; "/dev/VG/LV"; "10"]])],
2803 "resize an LVM logical volume",
2805 This resizes (expands or shrinks) an existing LVM logical
2806 volume to C<mbytes>. When reducing, data in the reduced part
2809 ("resize2fs", (RErr, [Device "device"]), 106, [],
2810 [], (* lvresize tests this *)
2811 "resize an ext2, ext3 or ext4 filesystem",
2813 This resizes an ext2, ext3 or ext4 filesystem to match the size of
2814 the underlying device.
2816 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2817 on the C<device> before calling this command. For unknown reasons
2818 C<resize2fs> sometimes gives an error about this and sometimes not.
2819 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2820 calling this function.");
2822 ("find", (RStringList "names", [Pathname "directory"]), 107, [ProtocolLimitWarning],
2823 [InitBasicFS, Always, TestOutputList (
2824 [["find"; "/"]], ["lost+found"]);
2825 InitBasicFS, Always, TestOutputList (
2829 ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2830 InitBasicFS, Always, TestOutputList (
2831 [["mkdir_p"; "/a/b/c"];
2832 ["touch"; "/a/b/c/d"];
2833 ["find"; "/a/b/"]], ["c"; "c/d"])],
2834 "find all files and directories",
2836 This command lists out all files and directories, recursively,
2837 starting at C<directory>. It is essentially equivalent to
2838 running the shell command C<find directory -print> but some
2839 post-processing happens on the output, described below.
2841 This returns a list of strings I<without any prefix>. Thus
2842 if the directory structure was:
2848 then the returned list from C<guestfs_find> C</tmp> would be
2856 If C<directory> is not a directory, then this command returns
2859 The returned list is sorted.
2861 See also C<guestfs_find0>.");
2863 ("e2fsck_f", (RErr, [Device "device"]), 108, [],
2864 [], (* lvresize tests this *)
2865 "check an ext2/ext3 filesystem",
2867 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2868 filesystem checker on C<device>, noninteractively (C<-p>),
2869 even if the filesystem appears to be clean (C<-f>).
2871 This command is only needed because of C<guestfs_resize2fs>
2872 (q.v.). Normally you should use C<guestfs_fsck>.");
2874 ("sleep", (RErr, [Int "secs"]), 109, [],
2875 [InitNone, Always, TestRun (
2877 "sleep for some seconds",
2879 Sleep for C<secs> seconds.");
2881 ("ntfs_3g_probe", (RInt "status", [Bool "rw"; Device "device"]), 110, [Optional "ntfs3g"],
2882 [InitNone, Always, TestOutputInt (
2883 [["part_disk"; "/dev/sda"; "mbr"];
2884 ["mkfs"; "ntfs"; "/dev/sda1"];
2885 ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2886 InitNone, Always, TestOutputInt (
2887 [["part_disk"; "/dev/sda"; "mbr"];
2888 ["mkfs"; "ext2"; "/dev/sda1"];
2889 ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2890 "probe NTFS volume",
2892 This command runs the L<ntfs-3g.probe(8)> command which probes
2893 an NTFS C<device> for mountability. (Not all NTFS volumes can
2894 be mounted read-write, and some cannot be mounted at all).
2896 C<rw> is a boolean flag. Set it to true if you want to test
2897 if the volume can be mounted read-write. Set it to false if
2898 you want to test if the volume can be mounted read-only.
2900 The return value is an integer which C<0> if the operation
2901 would succeed, or some non-zero value documented in the
2902 L<ntfs-3g.probe(8)> manual page.");
2904 ("sh", (RString "output", [String "command"]), 111, [],
2905 [], (* XXX needs tests *)
2906 "run a command via the shell",
2908 This call runs a command from the guest filesystem via the
2911 This is like C<guestfs_command>, but passes the command to:
2913 /bin/sh -c \"command\"
2915 Depending on the guest's shell, this usually results in
2916 wildcards being expanded, shell expressions being interpolated
2919 All the provisos about C<guestfs_command> apply to this call.");
2921 ("sh_lines", (RStringList "lines", [String "command"]), 112, [],
2922 [], (* XXX needs tests *)
2923 "run a command via the shell returning lines",
2925 This is the same as C<guestfs_sh>, but splits the result
2926 into a list of lines.
2928 See also: C<guestfs_command_lines>");
2930 ("glob_expand", (RStringList "paths", [Pathname "pattern"]), 113, [],
2931 (* Use Pathname here, and hence ABS_PATH (pattern,... in generated
2932 * code in stubs.c, since all valid glob patterns must start with "/".
2933 * There is no concept of "cwd" in libguestfs, hence no "."-relative names.
2935 [InitBasicFS, Always, TestOutputList (
2936 [["mkdir_p"; "/a/b/c"];
2937 ["touch"; "/a/b/c/d"];
2938 ["touch"; "/a/b/c/e"];
2939 ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2940 InitBasicFS, Always, TestOutputList (
2941 [["mkdir_p"; "/a/b/c"];
2942 ["touch"; "/a/b/c/d"];
2943 ["touch"; "/a/b/c/e"];
2944 ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2945 InitBasicFS, Always, TestOutputList (
2946 [["mkdir_p"; "/a/b/c"];
2947 ["touch"; "/a/b/c/d"];
2948 ["touch"; "/a/b/c/e"];
2949 ["glob_expand"; "/a/*/x/*"]], [])],
2950 "expand a wildcard path",
2952 This command searches for all the pathnames matching
2953 C<pattern> according to the wildcard expansion rules
2956 If no paths match, then this returns an empty list
2957 (note: not an error).
2959 It is just a wrapper around the C L<glob(3)> function
2960 with flags C<GLOB_MARK|GLOB_BRACE>.
2961 See that manual page for more details.");
2963 ("scrub_device", (RErr, [Device "device"]), 114, [DangerWillRobinson; Optional "scrub"],
2964 [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *)
2965 [["scrub_device"; "/dev/sdc"]])],
2966 "scrub (securely wipe) a device",
2968 This command writes patterns over C<device> to make data retrieval
2971 It is an interface to the L<scrub(1)> program. See that
2972 manual page for more details.");
2974 ("scrub_file", (RErr, [Pathname "file"]), 115, [Optional "scrub"],
2975 [InitBasicFS, Always, TestRun (
2976 [["write"; "/file"; "content"];
2977 ["scrub_file"; "/file"]])],
2978 "scrub (securely wipe) a file",
2980 This command writes patterns over a file to make data retrieval
2983 The file is I<removed> after scrubbing.
2985 It is an interface to the L<scrub(1)> program. See that
2986 manual page for more details.");
2988 ("scrub_freespace", (RErr, [Pathname "dir"]), 116, [Optional "scrub"],
2989 [], (* XXX needs testing *)
2990 "scrub (securely wipe) free space",
2992 This command creates the directory C<dir> and then fills it
2993 with files until the filesystem is full, and scrubs the files
2994 as for C<guestfs_scrub_file>, and deletes them.
2995 The intention is to scrub any free space on the partition
2998 It is an interface to the L<scrub(1)> program. See that
2999 manual page for more details.");
3001 ("mkdtemp", (RString "dir", [Pathname "template"]), 117, [],
3002 [InitBasicFS, Always, TestRun (
3004 ["mkdtemp"; "/tmp/tmpXXXXXX"]])],
3005 "create a temporary directory",
3007 This command creates a temporary directory. The
3008 C<template> parameter should be a full pathname for the
3009 temporary directory name with the final six characters being
3012 For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
3013 the second one being suitable for Windows filesystems.
3015 The name of the temporary directory that was created
3018 The temporary directory is created with mode 0700
3019 and is owned by root.
3021 The caller is responsible for deleting the temporary
3022 directory and its contents after use.
3024 See also: L<mkdtemp(3)>");
3026 ("wc_l", (RInt "lines", [Pathname "path"]), 118, [],
3027 [InitISOFS, Always, TestOutputInt (
3028 [["wc_l"; "/10klines"]], 10000);
3029 (* Test for RHBZ#579608, absolute symbolic links. *)
3030 InitISOFS, Always, TestOutputInt (
3031 [["wc_l"; "/abssymlink"]], 10000)],
3032 "count lines in a file",
3034 This command counts the lines in a file, using the
3035 C<wc -l> external command.");
3037 ("wc_w", (RInt "words", [Pathname "path"]), 119, [],
3038 [InitISOFS, Always, TestOutputInt (
3039 [["wc_w"; "/10klines"]], 10000)],
3040 "count words in a file",
3042 This command counts the words in a file, using the
3043 C<wc -w> external command.");
3045 ("wc_c", (RInt "chars", [Pathname "path"]), 120, [],
3046 [InitISOFS, Always, TestOutputInt (
3047 [["wc_c"; "/100kallspaces"]], 102400)],
3048 "count characters in a file",
3050 This command counts the characters in a file, using the
3051 C<wc -c> external command.");
3053 ("head", (RStringList "lines", [Pathname "path"]), 121, [ProtocolLimitWarning],
3054 [InitISOFS, Always, TestOutputList (
3055 [["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"]);
3056 (* Test for RHBZ#579608, absolute symbolic links. *)
3057 InitISOFS, Always, TestOutputList (
3058 [["head"; "/abssymlink"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])],
3059 "return first 10 lines of a file",
3061 This command returns up to the first 10 lines of a file as
3062 a list of strings.");
3064 ("head_n", (RStringList "lines", [Int "nrlines"; Pathname "path"]), 122, [ProtocolLimitWarning],
3065 [InitISOFS, Always, TestOutputList (
3066 [["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3067 InitISOFS, Always, TestOutputList (
3068 [["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3069 InitISOFS, Always, TestOutputList (
3070 [["head_n"; "0"; "/10klines"]], [])],
3071 "return first N lines of a file",
3073 If the parameter C<nrlines> is a positive number, this returns the first
3074 C<nrlines> lines of the file C<path>.
3076 If the parameter C<nrlines> is a negative number, this returns lines
3077 from the file C<path>, excluding the last C<nrlines> lines.
3079 If the parameter C<nrlines> is zero, this returns an empty list.");
3081 ("tail", (RStringList "lines", [Pathname "path"]), 123, [ProtocolLimitWarning],
3082 [InitISOFS, Always, TestOutputList (
3083 [["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])],
3084 "return last 10 lines of a file",
3086 This command returns up to the last 10 lines of a file as
3087 a list of strings.");
3089 ("tail_n", (RStringList "lines", [Int "nrlines"; Pathname "path"]), 124, [ProtocolLimitWarning],
3090 [InitISOFS, Always, TestOutputList (
3091 [["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
3092 InitISOFS, Always, TestOutputList (
3093 [["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
3094 InitISOFS, Always, TestOutputList (
3095 [["tail_n"; "0"; "/10klines"]], [])],
3096 "return last N lines of a file",
3098 If the parameter C<nrlines> is a positive number, this returns the last
3099 C<nrlines> lines of the file C<path>.
3101 If the parameter C<nrlines> is a negative number, this returns lines
3102 from the file C<path>, starting with the C<-nrlines>th line.
3104 If the parameter C<nrlines> is zero, this returns an empty list.");
3106 ("df", (RString "output", []), 125, [],
3107 [], (* XXX Tricky to test because it depends on the exact format
3108 * of the 'df' command and other imponderables.
3110 "report file system disk space usage",
3112 This command runs the C<df> command to report disk space used.
3114 This command is mostly useful for interactive sessions. It
3115 is I<not> intended that you try to parse the output string.
3116 Use C<statvfs> from programs.");
3118 ("df_h", (RString "output", []), 126, [],
3119 [], (* XXX Tricky to test because it depends on the exact format
3120 * of the 'df' command and other imponderables.
3122 "report file system disk space usage (human readable)",
3124 This command runs the C<df -h> command to report disk space used
3125 in human-readable format.
3127 This command is mostly useful for interactive sessions. It
3128 is I<not> intended that you try to parse the output string.
3129 Use C<statvfs> from programs.");
3131 ("du", (RInt64 "sizekb", [Pathname "path"]), 127, [],
3132 [InitISOFS, Always, TestOutputInt (
3133 [["du"; "/directory"]], 2 (* ISO fs blocksize is 2K *))],
3134 "estimate file space usage",
3136 This command runs the C<du -s> command to estimate file space
3139 C<path> can be a file or a directory. If C<path> is a directory
3140 then the estimate includes the contents of the directory and all
3141 subdirectories (recursively).
3143 The result is the estimated size in I<kilobytes>
3144 (ie. units of 1024 bytes).");
3146 ("initrd_list", (RStringList "filenames", [Pathname "path"]), 128, [],
3147 [InitISOFS, Always, TestOutputList (
3148 [["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3";"known-4"; "known-5"])],
3149 "list files in an initrd",
3151 This command lists out files contained in an initrd.
3153 The files are listed without any initial C</> character. The
3154 files are listed in the order they appear (not necessarily
3155 alphabetical). Directory names are listed as separate items.
3157 Old Linux kernels (2.4 and earlier) used a compressed ext2
3158 filesystem as initrd. We I<only> support the newer initramfs
3159 format (compressed cpio files).");
3161 ("mount_loop", (RErr, [Pathname "file"; Pathname "mountpoint"]), 129, [],
3163 "mount a file using the loop device",
3165 This command lets you mount C<file> (a filesystem image
3166 in a file) on a mount point. It is entirely equivalent to
3167 the command C<mount -o loop file mountpoint>.");
3169 ("mkswap", (RErr, [Device "device"]), 130, [],
3170 [InitEmpty, Always, TestRun (
3171 [["part_disk"; "/dev/sda"; "mbr"];
3172 ["mkswap"; "/dev/sda1"]])],
3173 "create a swap partition",
3175 Create a swap partition on C<device>.");
3177 ("mkswap_L", (RErr, [String "label"; Device "device"]), 131, [],
3178 [InitEmpty, Always, TestRun (
3179 [["part_disk"; "/dev/sda"; "mbr"];
3180 ["mkswap_L"; "hello"; "/dev/sda1"]])],
3181 "create a swap partition with a label",
3183 Create a swap partition on C<device> with label C<label>.
3185 Note that you cannot attach a swap label to a block device
3186 (eg. C</dev/sda>), just to a partition. This appears to be
3187 a limitation of the kernel or swap tools.");
3189 ("mkswap_U", (RErr, [String "uuid"; Device "device"]), 132, [Optional "linuxfsuuid"],
3190 (let uuid = uuidgen () in
3191 [InitEmpty, Always, TestRun (
3192 [["part_disk"; "/dev/sda"; "mbr"];
3193 ["mkswap_U"; uuid; "/dev/sda1"]])]),
3194 "create a swap partition with an explicit UUID",
3196 Create a swap partition on C<device> with UUID C<uuid>.");
3198 ("mknod", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"]), 133, [Optional "mknod"],
3199 [InitBasicFS, Always, TestOutputStruct (
3200 [["mknod"; "0o10777"; "0"; "0"; "/node"];
3201 (* NB: default umask 022 means 0777 -> 0755 in these tests *)
3202 ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)]);
3203 InitBasicFS, Always, TestOutputStruct (
3204 [["mknod"; "0o60777"; "66"; "99"; "/node"];
3205 ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
3206 "make block, character or FIFO devices",
3208 This call creates block or character special devices, or
3209 named pipes (FIFOs).
3211 The C<mode> parameter should be the mode, using the standard
3212 constants. C<devmajor> and C<devminor> are the
3213 device major and minor numbers, only used when creating block
3214 and character special devices.
3216 Note that, just like L<mknod(2)>, the mode must be bitwise
3217 OR'd with S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call
3218 just creates a regular file). These constants are
3219 available in the standard Linux header files, or you can use
3220 C<guestfs_mknod_b>, C<guestfs_mknod_c> or C<guestfs_mkfifo>
3221 which are wrappers around this command which bitwise OR
3222 in the appropriate constant for you.
3224 The mode actually set is affected by the umask.");
3226 ("mkfifo", (RErr, [Int "mode"; Pathname "path"]), 134, [Optional "mknod"],
3227 [InitBasicFS, Always, TestOutputStruct (
3228 [["mkfifo"; "0o777"; "/node"];
3229 ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)])],
3230 "make FIFO (named pipe)",
3232 This call creates a FIFO (named pipe) called C<path> with
3233 mode C<mode>. It is just a convenient wrapper around
3236 The mode actually set is affected by the umask.");
3238 ("mknod_b", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"]), 135, [Optional "mknod"],
3239 [InitBasicFS, Always, TestOutputStruct (
3240 [["mknod_b"; "0o777"; "99"; "66"; "/node"];
3241 ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
3242 "make block device node",
3244 This call creates a block device node called C<path> with
3245 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3246 It is just a convenient wrapper around C<guestfs_mknod>.
3248 The mode actually set is affected by the umask.");
3250 ("mknod_c", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"]), 136, [Optional "mknod"],
3251 [InitBasicFS, Always, TestOutputStruct (
3252 [["mknod_c"; "0o777"; "99"; "66"; "/node"];
3253 ["stat"; "/node"]], [CompareWithInt ("mode", 0o20755)])],
3254 "make char device node",
3256 This call creates a char device node called C<path> with
3257 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3258 It is just a convenient wrapper around C<guestfs_mknod>.
3260 The mode actually set is affected by the umask.");
3262 ("umask", (RInt "oldmask", [Int "mask"]), 137, [FishOutput FishOutputOctal],
3263 [InitEmpty, Always, TestOutputInt (
3264 [["umask"; "0o22"]], 0o22)],
3265 "set file mode creation mask (umask)",
3267 This function sets the mask used for creating new files and
3268 device nodes to C<mask & 0777>.
3270 Typical umask values would be C<022> which creates new files
3271 with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and
3272 C<002> which creates new files with permissions like
3273 \"-rw-rw-r--\" or \"-rwxrwxr-x\".
3275 The default umask is C<022>. This is important because it
3276 means that directories and device nodes will be created with
3277 C<0644> or C<0755> mode even if you specify C<0777>.
3279 See also C<guestfs_get_umask>,
3280 L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
3282 This call returns the previous umask.");
3284 ("readdir", (RStructList ("entries", "dirent"), [Pathname "dir"]), 138, [],
3286 "read directories entries",
3288 This returns the list of directory entries in directory C<dir>.
3290 All entries in the directory are returned, including C<.> and
3291 C<..>. The entries are I<not> sorted, but returned in the same
3292 order as the underlying filesystem.
3294 Also this call returns basic file type information about each
3295 file. The C<ftyp> field will contain one of the following characters:
3333 The L<readdir(3)> call returned a C<d_type> field with an
3338 This function is primarily intended for use by programs. To
3339 get a simple list of names, use C<guestfs_ls>. To get a printable
3340 directory for human consumption, use C<guestfs_ll>.");
3342 ("sfdiskM", (RErr, [Device "device"; StringList "lines"]), 139, [DangerWillRobinson],
3344 "create partitions on a block device",
3346 This is a simplified interface to the C<guestfs_sfdisk>
3347 command, where partition sizes are specified in megabytes
3348 only (rounded to the nearest cylinder) and you don't need
3349 to specify the cyls, heads and sectors parameters which
3350 were rarely if ever used anyway.
3352 See also: C<guestfs_sfdisk>, the L<sfdisk(8)> manpage
3353 and C<guestfs_part_disk>");
3355 ("zfile", (RString "description", [String "meth"; Pathname "path"]), 140, [DeprecatedBy "file"],
3357 "determine file type inside a compressed file",
3359 This command runs C<file> after first decompressing C<path>
3362 C<method> must be one of C<gzip>, C<compress> or C<bzip2>.
3364 Since 1.0.63, use C<guestfs_file> instead which can now
3365 process compressed files.");
3367 ("getxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"]), 141, [Optional "linuxxattrs"],
3369 "list extended attributes of a file or directory",
3371 This call lists the extended attributes of the file or directory
3374 At the system call level, this is a combination of the
3375 L<listxattr(2)> and L<getxattr(2)> calls.
3377 See also: C<guestfs_lgetxattrs>, L<attr(5)>.");
3379 ("lgetxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"]), 142, [Optional "linuxxattrs"],
3381 "list extended attributes of a file or directory",
3383 This is the same as C<guestfs_getxattrs>, but if C<path>
3384 is a symbolic link, then it returns the extended attributes
3385 of the link itself.");
3387 ("setxattr", (RErr, [String "xattr";
3388 String "val"; Int "vallen"; (* will be BufferIn *)
3389 Pathname "path"]), 143, [Optional "linuxxattrs"],
3391 "set extended attribute of a file or directory",
3393 This call sets the extended attribute named C<xattr>
3394 of the file C<path> to the value C<val> (of length C<vallen>).
3395 The value is arbitrary 8 bit data.
3397 See also: C<guestfs_lsetxattr>, L<attr(5)>.");
3399 ("lsetxattr", (RErr, [String "xattr";
3400 String "val"; Int "vallen"; (* will be BufferIn *)
3401 Pathname "path"]), 144, [Optional "linuxxattrs"],
3403 "set extended attribute of a file or directory",
3405 This is the same as C<guestfs_setxattr>, but if C<path>
3406 is a symbolic link, then it sets an extended attribute
3407 of the link itself.");
3409 ("removexattr", (RErr, [String "xattr"; Pathname "path"]), 145, [Optional "linuxxattrs"],
3411 "remove extended attribute of a file or directory",
3413 This call removes the extended attribute named C<xattr>
3414 of the file C<path>.
3416 See also: C<guestfs_lremovexattr>, L<attr(5)>.");
3418 ("lremovexattr", (RErr, [String "xattr"; Pathname "path"]), 146, [Optional "linuxxattrs"],
3420 "remove extended attribute of a file or directory",
3422 This is the same as C<guestfs_removexattr>, but if C<path>
3423 is a symbolic link, then it removes an extended attribute
3424 of the link itself.");
3426 ("mountpoints", (RHashtable "mps", []), 147, [],
3430 This call is similar to C<guestfs_mounts>. That call returns
3431 a list of devices. This one returns a hash table (map) of
3432 device name to directory where the device is mounted.");
3434 ("mkmountpoint", (RErr, [String "exemptpath"]), 148, [],
3435 (* This is a special case: while you would expect a parameter
3436 * of type "Pathname", that doesn't work, because it implies
3437 * NEED_ROOT in the generated calling code in stubs.c, and
3438 * this function cannot use NEED_ROOT.
3441 "create a mountpoint",
3443 C<guestfs_mkmountpoint> and C<guestfs_rmmountpoint> are
3444 specialized calls that can be used to create extra mountpoints
3445 before mounting the first filesystem.
3447 These calls are I<only> necessary in some very limited circumstances,
3448 mainly the case where you want to mount a mix of unrelated and/or
3449 read-only filesystems together.
3451 For example, live CDs often contain a \"Russian doll\" nest of
3452 filesystems, an ISO outer layer, with a squashfs image inside, with
3453 an ext2/3 image inside that. You can unpack this as follows
3456 add-ro Fedora-11-i686-Live.iso
3459 mkmountpoint /squash
3462 mount-loop /cd/LiveOS/squashfs.img /squash
3463 mount-loop /squash/LiveOS/ext3fs.img /ext3
3465 The inner filesystem is now unpacked under the /ext3 mountpoint.");
3467 ("rmmountpoint", (RErr, [String "exemptpath"]), 149, [],
3469 "remove a mountpoint",
3471 This calls removes a mountpoint that was previously created
3472 with C<guestfs_mkmountpoint>. See C<guestfs_mkmountpoint>
3473 for full details.");
3475 ("read_file", (RBufferOut "content", [Pathname "path"]), 150, [ProtocolLimitWarning],
3476 [InitISOFS, Always, TestOutputBuffer (
3477 [["read_file"; "/known-4"]], "abc\ndef\nghi");
3478 (* Test various near large, large and too large files (RHBZ#589039). *)
3479 InitBasicFS, Always, TestLastFail (
3481 ["truncate_size"; "/a"; "4194303"]; (* GUESTFS_MESSAGE_MAX - 1 *)
3482 ["read_file"; "/a"]]);
3483 InitBasicFS, Always, TestLastFail (
3485 ["truncate_size"; "/a"; "4194304"]; (* GUESTFS_MESSAGE_MAX *)
3486 ["read_file"; "/a"]]);
3487 InitBasicFS, Always, TestLastFail (
3489 ["truncate_size"; "/a"; "41943040"]; (* GUESTFS_MESSAGE_MAX * 10 *)
3490 ["read_file"; "/a"]])],
3493 This calls returns the contents of the file C<path> as a
3496 Unlike C<guestfs_cat>, this function can correctly
3497 handle files that contain embedded ASCII NUL characters.
3498 However unlike C<guestfs_download>, this function is limited
3499 in the total size of file that can be handled.");
3501 ("grep", (RStringList "lines", [String "regex"; Pathname "path"]), 151, [ProtocolLimitWarning],
3502 [InitISOFS, Always, TestOutputList (
3503 [["grep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"]);
3504 InitISOFS, Always, TestOutputList (
3505 [["grep"; "nomatch"; "/test-grep.txt"]], []);
3506 (* Test for RHBZ#579608, absolute symbolic links. *)
3507 InitISOFS, Always, TestOutputList (
3508 [["grep"; "nomatch"; "/abssymlink"]], [])],
3509 "return lines matching a pattern",
3511 This calls the external C<grep> program and returns the
3514 ("egrep", (RStringList "lines", [String "regex"; Pathname "path"]), 152, [ProtocolLimitWarning],
3515 [InitISOFS, Always, TestOutputList (
3516 [["egrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3517 "return lines matching a pattern",
3519 This calls the external C<egrep> program and returns the
3522 ("fgrep", (RStringList "lines", [String "pattern"; Pathname "path"]), 153, [ProtocolLimitWarning],
3523 [InitISOFS, Always, TestOutputList (
3524 [["fgrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3525 "return lines matching a pattern",
3527 This calls the external C<fgrep> program and returns the
3530 ("grepi", (RStringList "lines", [String "regex"; Pathname "path"]), 154, [ProtocolLimitWarning],
3531 [InitISOFS, Always, TestOutputList (
3532 [["grepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3533 "return lines matching a pattern",
3535 This calls the external C<grep -i> program and returns the
3538 ("egrepi", (RStringList "lines", [String "regex"; Pathname "path"]), 155, [ProtocolLimitWarning],
3539 [InitISOFS, Always, TestOutputList (
3540 [["egrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3541 "return lines matching a pattern",
3543 This calls the external C<egrep -i> program and returns the
3546 ("fgrepi", (RStringList "lines", [String "pattern"; Pathname "path"]), 156, [ProtocolLimitWarning],
3547 [InitISOFS, Always, TestOutputList (
3548 [["fgrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3549 "return lines matching a pattern",
3551 This calls the external C<fgrep -i> program and returns the
3554 ("zgrep", (RStringList "lines", [String "regex"; Pathname "path"]), 157, [ProtocolLimitWarning],
3555 [InitISOFS, Always, TestOutputList (
3556 [["zgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3557 "return lines matching a pattern",
3559 This calls the external C<zgrep> program and returns the
3562 ("zegrep", (RStringList "lines", [String "regex"; Pathname "path"]), 158, [ProtocolLimitWarning],
3563 [InitISOFS, Always, TestOutputList (
3564 [["zegrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3565 "return lines matching a pattern",
3567 This calls the external C<zegrep> program and returns the
3570 ("zfgrep", (RStringList "lines", [String "pattern"; Pathname "path"]), 159, [ProtocolLimitWarning],
3571 [InitISOFS, Always, TestOutputList (
3572 [["zfgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3573 "return lines matching a pattern",
3575 This calls the external C<zfgrep> program and returns the
3578 ("zgrepi", (RStringList "lines", [String "regex"; Pathname "path"]), 160, [ProtocolLimitWarning],
3579 [InitISOFS, Always, TestOutputList (
3580 [["zgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3581 "return lines matching a pattern",
3583 This calls the external C<zgrep -i> program and returns the
3586 ("zegrepi", (RStringList "lines", [String "regex"; Pathname "path"]), 161, [ProtocolLimitWarning],
3587 [InitISOFS, Always, TestOutputList (
3588 [["zegrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3589 "return lines matching a pattern",
3591 This calls the external C<zegrep -i> program and returns the
3594 ("zfgrepi", (RStringList "lines", [String "pattern"; Pathname "path"]), 162, [ProtocolLimitWarning],
3595 [InitISOFS, Always, TestOutputList (
3596 [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3597 "return lines matching a pattern",
3599 This calls the external C<zfgrep -i> program and returns the
3602 ("realpath", (RString "rpath", [Pathname "path"]), 163, [Optional "realpath"],
3603 [InitISOFS, Always, TestOutput (
3604 [["realpath"; "/../directory"]], "/directory")],
3605 "canonicalized absolute pathname",
3607 Return the canonicalized absolute pathname of C<path>. The
3608 returned path has no C<.>, C<..> or symbolic link path elements.");
3610 ("ln", (RErr, [String "target"; Pathname "linkname"]), 164, [],
3611 [InitBasicFS, Always, TestOutputStruct (
3614 ["stat"; "/b"]], [CompareWithInt ("nlink", 2)])],
3615 "create a hard link",
3617 This command creates a hard link using the C<ln> command.");
3619 ("ln_f", (RErr, [String "target"; Pathname "linkname"]), 165, [],
3620 [InitBasicFS, Always, TestOutputStruct (
3623 ["ln_f"; "/a"; "/b"];
3624 ["stat"; "/b"]], [CompareWithInt ("nlink", 2)])],
3625 "create a hard link",
3627 This command creates a hard link using the C<ln -f> command.
3628 The C<-f> option removes the link (C<linkname>) if it exists already.");
3630 ("ln_s", (RErr, [String "target"; Pathname "linkname"]), 166, [],
3631 [InitBasicFS, Always, TestOutputStruct (
3633 ["ln_s"; "a"; "/b"];
3634 ["lstat"; "/b"]], [CompareWithInt ("mode", 0o120777)])],
3635 "create a symbolic link",
3637 This command creates a symbolic link using the C<ln -s> command.");
3639 ("ln_sf", (RErr, [String "target"; Pathname "linkname"]), 167, [],
3640 [InitBasicFS, Always, TestOutput (
3641 [["mkdir_p"; "/a/b"];
3642 ["touch"; "/a/b/c"];
3643 ["ln_sf"; "../d"; "/a/b/c"];
3644 ["readlink"; "/a/b/c"]], "../d")],
3645 "create a symbolic link",
3647 This command creates a symbolic link using the C<ln -sf> command,
3648 The C<-f> option removes the link (C<linkname>) if it exists already.");
3650 ("readlink", (RString "link", [Pathname "path"]), 168, [],
3651 [] (* XXX tested above *),
3652 "read the target of a symbolic link",
3654 This command reads the target of a symbolic link.");
3656 ("fallocate", (RErr, [Pathname "path"; Int "len"]), 169, [DeprecatedBy "fallocate64"],
3657 [InitBasicFS, Always, TestOutputStruct (
3658 [["fallocate"; "/a"; "1000000"];
3659 ["stat"; "/a"]], [CompareWithInt ("size", 1_000_000)])],
3660 "preallocate a file in the guest filesystem",
3662 This command preallocates a file (containing zero bytes) named
3663 C<path> of size C<len> bytes. If the file exists already, it
3666 Do not confuse this with the guestfish-specific
3667 C<alloc> command which allocates a file in the host and
3668 attaches it as a device.");
3670 ("swapon_device", (RErr, [Device "device"]), 170, [],
3671 [InitPartition, Always, TestRun (
3672 [["mkswap"; "/dev/sda1"];
3673 ["swapon_device"; "/dev/sda1"];
3674 ["swapoff_device"; "/dev/sda1"]])],
3675 "enable swap on device",
3677 This command enables the libguestfs appliance to use the
3678 swap device or partition named C<device>. The increased
3679 memory is made available for all commands, for example
3680 those run using C<guestfs_command> or C<guestfs_sh>.
3682 Note that you should not swap to existing guest swap
3683 partitions unless you know what you are doing. They may
3684 contain hibernation information, or other information that
3685 the guest doesn't want you to trash. You also risk leaking
3686 information about the host to the guest this way. Instead,
3687 attach a new host device to the guest and swap on that.");
3689 ("swapoff_device", (RErr, [Device "device"]), 171, [],
3690 [], (* XXX tested by swapon_device *)
3691 "disable swap on device",
3693 This command disables the libguestfs appliance swap
3694 device or partition named C<device>.
3695 See C<guestfs_swapon_device>.");
3697 ("swapon_file", (RErr, [Pathname "file"]), 172, [],
3698 [InitBasicFS, Always, TestRun (
3699 [["fallocate"; "/swap"; "8388608"];
3700 ["mkswap_file"; "/swap"];
3701 ["swapon_file"; "/swap"];
3702 ["swapoff_file"; "/swap"]])],
3703 "enable swap on file",
3705 This command enables swap to a file.
3706 See C<guestfs_swapon_device> for other notes.");
3708 ("swapoff_file", (RErr, [Pathname "file"]), 173, [],
3709 [], (* XXX tested by swapon_file *)
3710 "disable swap on file",
3712 This command disables the libguestfs appliance swap on file.");
3714 ("swapon_label", (RErr, [String "label"]), 174, [],
3715 [InitEmpty, Always, TestRun (
3716 [["part_disk"; "/dev/sdb"; "mbr"];
3717 ["mkswap_L"; "swapit"; "/dev/sdb1"];
3718 ["swapon_label"; "swapit"];
3719 ["swapoff_label"; "swapit"];
3720 ["zero"; "/dev/sdb"];
3721 ["blockdev_rereadpt"; "/dev/sdb"]])],
3722 "enable swap on labeled swap partition",
3724 This command enables swap to a labeled swap partition.
3725 See C<guestfs_swapon_device> for other notes.");
3727 ("swapoff_label", (RErr, [String "label"]), 175, [],
3728 [], (* XXX tested by swapon_label *)
3729 "disable swap on labeled swap partition",
3731 This command disables the libguestfs appliance swap on
3732 labeled swap partition.");
3734 ("swapon_uuid", (RErr, [String "uuid"]), 176, [Optional "linuxfsuuid"],
3735 (let uuid = uuidgen () in
3736 [InitEmpty, Always, TestRun (
3737 [["mkswap_U"; uuid; "/dev/sdb"];
3738 ["swapon_uuid"; uuid];