2 * Copyright (C) 2009-2010 Red Hat Inc.
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 (* Please read generator/README first. *)
21 (* Note about long descriptions: When referring to another
22 * action, use the format C<guestfs_other> (ie. the full name of
23 * the C function). This will be replaced as appropriate in other
26 * Apart from that, long descriptions are just perldoc paragraphs.
32 (* These test functions are used in the language binding tests. *)
47 (* except for RErr, which is tested thoroughly elsewhere *)
48 "test0rint", RInt "valout";
49 "test0rint64", RInt64 "valout";
50 "test0rbool", RBool "valout";
51 "test0rconststring", RConstString "valout";
52 "test0rconstoptstring", RConstOptString "valout";
53 "test0rstring", RString "valout";
54 "test0rstringlist", RStringList "valout";
55 "test0rstruct", RStruct ("valout", "lvm_pv");
56 "test0rstructlist", RStructList ("valout", "lvm_pv");
57 "test0rhashtable", RHashtable "valout";
60 let test_functions = [
61 ("test0", (RErr, test_all_args, []), -1, [NotInFish; NotInDocs],
63 "internal test function - do not use",
65 This is an internal test function which is used to test whether
66 the automatically generated bindings can handle every possible
67 parameter type correctly.
69 It echos the contents of each parameter to stdout.
71 You probably don't want to call this function.");
75 [(name, (ret, [String "val"], []), -1, [NotInFish; NotInDocs],
77 "internal test function - do not use",
79 This is an internal test function which is used to test whether
80 the automatically generated bindings can handle every possible
81 return type correctly.
83 It converts string C<val> to the return type.
85 You probably don't want to call this function.");
86 (name ^ "err", (ret, [], []), -1, [NotInFish; NotInDocs],
88 "internal test function - do not use",
90 This is an internal test function which is used to test whether
91 the automatically generated bindings can handle every possible
92 return type correctly.
94 This function always returns an error.
96 You probably don't want to call this function.")]
100 (* non_daemon_functions are any functions which don't get processed
101 * in the daemon, eg. functions for setting and getting local
102 * configuration values.
105 let non_daemon_functions = test_functions @ [
106 ("launch", (RErr, [], []), -1, [FishAlias "run"],
108 "launch the qemu subprocess",
110 Internally libguestfs is implemented by running a virtual machine
113 You should call this after configuring the handle
114 (eg. adding drives) but before performing any actions.");
116 ("wait_ready", (RErr, [], []), -1, [NotInFish],
118 "wait until the qemu subprocess launches (no op)",
120 This function is a no op.
122 In versions of the API E<lt> 1.0.71 you had to call this function
123 just after calling C<guestfs_launch> to wait for the launch
124 to complete. However this is no longer necessary because
125 C<guestfs_launch> now does the waiting.
127 If you see any calls to this function in code then you can just
128 remove them, unless you want to retain compatibility with older
129 versions of the API.");
131 ("kill_subprocess", (RErr, [], []), -1, [],
133 "kill the qemu subprocess",
135 This kills the qemu subprocess. You should never need to call this.");
137 ("add_drive", (RErr, [String "filename"], []), -1, [],
139 "add an image to examine or modify",
141 This function is the equivalent of calling C<guestfs_add_drive_opts>
142 with no optional parameters, so the disk is added writable, with
143 the format being detected automatically.
145 Automatic detection of the format opens you up to a potential
146 security hole when dealing with untrusted raw-format images.
147 See CVE-2010-3851 and RHBZ#642934. Specifying the format closes
148 this security hole. Therefore you should think about replacing
149 calls to this function with calls to C<guestfs_add_drive_opts>,
150 and specifying the format.");
152 ("add_cdrom", (RErr, [String "filename"], []), -1, [DeprecatedBy "add_drive_opts"],
154 "add a CD-ROM disk image to examine",
156 This function adds a virtual CD-ROM disk image to the guest.
158 This is equivalent to the qemu parameter C<-cdrom filename>.
166 This call checks for the existence of C<filename>. This
167 stops you from specifying other types of drive which are supported
168 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
169 the general C<guestfs_config> call instead.
173 If you just want to add an ISO file (often you use this as an
174 efficient way to transfer large files into the guest), then you
175 should probably use C<guestfs_add_drive_ro> instead.
179 ("add_drive_ro", (RErr, [String "filename"], []), -1, [FishAlias "add-ro"],
181 "add a drive in snapshot mode (read-only)",
183 This function is the equivalent of calling C<guestfs_add_drive_opts>
184 with the optional parameter C<GUESTFS_ADD_DRIVE_OPTS_READONLY> set to 1,
185 so the disk is added read-only, with the format being detected
188 ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"], []), -1, [],
190 "add qemu parameters",
192 This can be used to add arbitrary qemu command line parameters
193 of the form C<-param value>. Actually it's not quite arbitrary - we
194 prevent you from setting some parameters which would interfere with
195 parameters that we use.
197 The first character of C<param> string must be a C<-> (dash).
199 C<value> can be NULL.");
201 ("set_qemu", (RErr, [OptString "qemu"], []), -1, [FishAlias "qemu"],
203 "set the qemu binary",
205 Set the qemu binary that we will use.
207 The default is chosen when the library was compiled by the
210 You can also override this by setting the C<LIBGUESTFS_QEMU>
211 environment variable.
213 Setting C<qemu> to C<NULL> restores the default qemu binary.
215 Note that you should call this function as early as possible
216 after creating the handle. This is because some pre-launch
217 operations depend on testing qemu features (by running C<qemu -help>).
218 If the qemu binary changes, we don't retest features, and
219 so you might see inconsistent results. Using the environment
220 variable C<LIBGUESTFS_QEMU> is safest of all since that picks
221 the qemu binary at the same time as the handle is created.");
223 ("get_qemu", (RConstString "qemu", [], []), -1, [],
224 [InitNone, Always, TestRun (
226 "get the qemu binary",
228 Return the current qemu binary.
230 This is always non-NULL. If it wasn't set already, then this will
231 return the default qemu binary name.");
233 ("set_path", (RErr, [OptString "searchpath"], []), -1, [FishAlias "path"],
235 "set the search path",
237 Set the path that libguestfs searches for kernel and initrd.img.
239 The default is C<$libdir/guestfs> unless overridden by setting
240 C<LIBGUESTFS_PATH> environment variable.
242 Setting C<path> to C<NULL> restores the default path.");
244 ("get_path", (RConstString "path", [], []), -1, [],
245 [InitNone, Always, TestRun (
247 "get the search path",
249 Return the current search path.
251 This is always non-NULL. If it wasn't set already, then this will
252 return the default path.");
254 ("set_append", (RErr, [OptString "append"], []), -1, [FishAlias "append"],
256 "add options to kernel command line",
258 This function is used to add additional options to the
259 guest kernel command line.
261 The default is C<NULL> unless overridden by setting
262 C<LIBGUESTFS_APPEND> environment variable.
264 Setting C<append> to C<NULL> means I<no> additional options
265 are passed (libguestfs always adds a few of its own).");
267 ("get_append", (RConstOptString "append", [], []), -1, [],
268 (* This cannot be tested with the current framework. The
269 * function can return NULL in normal operations, which the
270 * test framework interprets as an error.
273 "get the additional kernel options",
275 Return the additional kernel options which are added to the
276 guest kernel command line.
278 If C<NULL> then no options are added.");
280 ("set_autosync", (RErr, [Bool "autosync"], []), -1, [FishAlias "autosync"],
284 If C<autosync> is true, this enables autosync. Libguestfs will make a
285 best effort attempt to run C<guestfs_umount_all> followed by
286 C<guestfs_sync> when the handle is closed
287 (also if the program exits without closing handles).
289 This is enabled by default (since libguestfs 1.5.24, previously it was
290 disabled by default).");
292 ("get_autosync", (RBool "autosync", [], []), -1, [],
293 [InitNone, Always, TestOutputTrue (
294 [["get_autosync"]])],
297 Get the autosync flag.");
299 ("set_verbose", (RErr, [Bool "verbose"], []), -1, [FishAlias "verbose"],
303 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
305 Verbose messages are disabled unless the environment variable
306 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
308 ("get_verbose", (RBool "verbose", [], []), -1, [],
312 This returns the verbose messages flag.");
314 ("is_ready", (RBool "ready", [], []), -1, [],
315 [InitNone, Always, TestOutputTrue (
317 "is ready to accept commands",
319 This returns true iff this handle is ready to accept commands
320 (in the C<READY> state).
322 For more information on states, see L<guestfs(3)>.");
324 ("is_config", (RBool "config", [], []), -1, [],
325 [InitNone, Always, TestOutputFalse (
327 "is in configuration state",
329 This returns true iff this handle is being configured
330 (in the C<CONFIG> state).
332 For more information on states, see L<guestfs(3)>.");
334 ("is_launching", (RBool "launching", [], []), -1, [],
335 [InitNone, Always, TestOutputFalse (
336 [["is_launching"]])],
337 "is launching subprocess",
339 This returns true iff this handle is launching the subprocess
340 (in the C<LAUNCHING> state).
342 For more information on states, see L<guestfs(3)>.");
344 ("is_busy", (RBool "busy", [], []), -1, [],
345 [InitNone, Always, TestOutputFalse (
347 "is busy processing a command",
349 This returns true iff this handle is busy processing a command
350 (in the C<BUSY> state).
352 For more information on states, see L<guestfs(3)>.");
354 ("get_state", (RInt "state", [], []), -1, [],
356 "get the current state",
358 This returns the current state as an opaque integer. This is
359 only useful for printing debug and internal error messages.
361 For more information on states, see L<guestfs(3)>.");
363 ("set_memsize", (RErr, [Int "memsize"], []), -1, [FishAlias "memsize"],
364 [InitNone, Always, TestOutputInt (
365 [["set_memsize"; "500"];
366 ["get_memsize"]], 500)],
367 "set memory allocated to the qemu subprocess",
369 This sets the memory size in megabytes allocated to the
370 qemu subprocess. This only has any effect if called before
373 You can also change this by setting the environment
374 variable C<LIBGUESTFS_MEMSIZE> before the handle is
377 For more information on the architecture of libguestfs,
378 see L<guestfs(3)>.");
380 ("get_memsize", (RInt "memsize", [], []), -1, [],
381 [InitNone, Always, TestOutputIntOp (
382 [["get_memsize"]], ">=", 256)],
383 "get memory allocated to the qemu subprocess",
385 This gets the memory size in megabytes allocated to the
388 If C<guestfs_set_memsize> was not called
389 on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
390 then this returns the compiled-in default value for memsize.
392 For more information on the architecture of libguestfs,
393 see L<guestfs(3)>.");
395 ("get_pid", (RInt "pid", [], []), -1, [FishAlias "pid"],
396 [InitNone, Always, TestOutputIntOp (
397 [["get_pid"]], ">=", 1)],
398 "get PID of qemu subprocess",
400 Return the process ID of the qemu subprocess. If there is no
401 qemu subprocess, then this will return an error.
403 This is an internal call used for debugging and testing.");
405 ("version", (RStruct ("version", "version"), [], []), -1, [],
406 [InitNone, Always, TestOutputStruct (
407 [["version"]], [CompareWithInt ("major", 1)])],
408 "get the library version number",
410 Return the libguestfs version number that the program is linked
413 Note that because of dynamic linking this is not necessarily
414 the version of libguestfs that you compiled against. You can
415 compile the program, and then at runtime dynamically link
416 against a completely different C<libguestfs.so> library.
418 This call was added in version C<1.0.58>. In previous
419 versions of libguestfs there was no way to get the version
420 number. From C code you can use dynamic linker functions
421 to find out if this symbol exists (if it doesn't, then
422 it's an earlier version).
424 The call returns a structure with four elements. The first
425 three (C<major>, C<minor> and C<release>) are numbers and
426 correspond to the usual version triplet. The fourth element
427 (C<extra>) is a string and is normally empty, but may be
428 used for distro-specific information.
430 To construct the original version string:
431 C<$major.$minor.$release$extra>
433 See also: L<guestfs(3)/LIBGUESTFS VERSION NUMBERS>.
435 I<Note:> Don't use this call to test for availability
436 of features. In enterprise distributions we backport
437 features from later versions into earlier versions,
438 making this an unreliable way to test for features.
439 Use C<guestfs_available> instead.");
441 ("set_selinux", (RErr, [Bool "selinux"], []), -1, [FishAlias "selinux"],
442 [InitNone, Always, TestOutputTrue (
443 [["set_selinux"; "true"];
445 "set SELinux enabled or disabled at appliance boot",
447 This sets the selinux flag that is passed to the appliance
448 at boot time. The default is C<selinux=0> (disabled).
450 Note that if SELinux is enabled, it is always in
451 Permissive mode (C<enforcing=0>).
453 For more information on the architecture of libguestfs,
454 see L<guestfs(3)>.");
456 ("get_selinux", (RBool "selinux", [], []), -1, [],
458 "get SELinux enabled flag",
460 This returns the current setting of the selinux flag which
461 is passed to the appliance at boot time. See C<guestfs_set_selinux>.
463 For more information on the architecture of libguestfs,
464 see L<guestfs(3)>.");
466 ("set_trace", (RErr, [Bool "trace"], []), -1, [FishAlias "trace"],
467 [InitNone, Always, TestOutputFalse (
468 [["set_trace"; "false"];
470 "enable or disable command traces",
472 If the command trace flag is set to 1, then commands are
473 printed on stderr before they are executed in a format
474 which is very similar to the one used by guestfish. In
475 other words, you can run a program with this enabled, and
476 you will get out a script which you can feed to guestfish
477 to perform the same set of actions.
479 If you want to trace C API calls into libguestfs (and
480 other libraries) then possibly a better way is to use
481 the external ltrace(1) command.
483 Command traces are disabled unless the environment variable
484 C<LIBGUESTFS_TRACE> is defined and set to C<1>.");
486 ("get_trace", (RBool "trace", [], []), -1, [],
488 "get command trace enabled flag",
490 Return the command trace flag.");
492 ("set_direct", (RErr, [Bool "direct"], []), -1, [FishAlias "direct"],
493 [InitNone, Always, TestOutputFalse (
494 [["set_direct"; "false"];
496 "enable or disable direct appliance mode",
498 If the direct appliance mode flag is enabled, then stdin and
499 stdout are passed directly through to the appliance once it
502 One consequence of this is that log messages aren't caught
503 by the library and handled by C<guestfs_set_log_message_callback>,
504 but go straight to stdout.
506 You probably don't want to use this unless you know what you
509 The default is disabled.");
511 ("get_direct", (RBool "direct", [], []), -1, [],
513 "get direct appliance mode flag",
515 Return the direct appliance mode flag.");
517 ("set_recovery_proc", (RErr, [Bool "recoveryproc"], []), -1, [FishAlias "recovery-proc"],
518 [InitNone, Always, TestOutputTrue (
519 [["set_recovery_proc"; "true"];
520 ["get_recovery_proc"]])],
521 "enable or disable the recovery process",
523 If this is called with the parameter C<false> then
524 C<guestfs_launch> does not create a recovery process. The
525 purpose of the recovery process is to stop runaway qemu
526 processes in the case where the main program aborts abruptly.
528 This only has any effect if called before C<guestfs_launch>,
529 and the default is true.
531 About the only time when you would want to disable this is
532 if the main process will fork itself into the background
533 (\"daemonize\" itself). In this case the recovery process
534 thinks that the main program has disappeared and so kills
535 qemu, which is not very helpful.");
537 ("get_recovery_proc", (RBool "recoveryproc", [], []), -1, [],
539 "get recovery process enabled flag",
541 Return the recovery process enabled flag.");
543 ("add_drive_with_if", (RErr, [String "filename"; String "iface"], []), -1, [DeprecatedBy "add_drive_opts"],
545 "add a drive specifying the QEMU block emulation to use",
547 This is the same as C<guestfs_add_drive> but it allows you
548 to specify the QEMU interface emulation to use at run time.");
550 ("add_drive_ro_with_if", (RErr, [String "filename"; String "iface"], []), -1, [DeprecatedBy "add_drive_opts"],
552 "add a drive read-only specifying the QEMU block emulation to use",
554 This is the same as C<guestfs_add_drive_ro> but it allows you
555 to specify the QEMU interface emulation to use at run time.");
557 ("file_architecture", (RString "arch", [Pathname "filename"], []), -1, [],
558 [InitISOFS, Always, TestOutput (
559 [["file_architecture"; "/bin-i586-dynamic"]], "i386");
560 InitISOFS, Always, TestOutput (
561 [["file_architecture"; "/bin-sparc-dynamic"]], "sparc");
562 InitISOFS, Always, TestOutput (
563 [["file_architecture"; "/bin-win32.exe"]], "i386");
564 InitISOFS, Always, TestOutput (
565 [["file_architecture"; "/bin-win64.exe"]], "x86_64");
566 InitISOFS, Always, TestOutput (
567 [["file_architecture"; "/bin-x86_64-dynamic"]], "x86_64");
568 InitISOFS, Always, TestOutput (
569 [["file_architecture"; "/lib-i586.so"]], "i386");
570 InitISOFS, Always, TestOutput (
571 [["file_architecture"; "/lib-sparc.so"]], "sparc");
572 InitISOFS, Always, TestOutput (
573 [["file_architecture"; "/lib-win32.dll"]], "i386");
574 InitISOFS, Always, TestOutput (
575 [["file_architecture"; "/lib-win64.dll"]], "x86_64");
576 InitISOFS, Always, TestOutput (
577 [["file_architecture"; "/lib-x86_64.so"]], "x86_64");
578 InitISOFS, Always, TestOutput (
579 [["file_architecture"; "/initrd-x86_64.img"]], "x86_64");
580 InitISOFS, Always, TestOutput (
581 [["file_architecture"; "/initrd-x86_64.img.gz"]], "x86_64");],
582 "detect the architecture of a binary file",
584 This detects the architecture of the binary C<filename>,
585 and returns it if known.
587 Currently defined architectures are:
593 This string is returned for all 32 bit i386, i486, i586, i686 binaries
594 irrespective of the precise processor requirements of the binary.
606 64 bit SPARC V9 and above.
622 Libguestfs may return other architecture strings in future.
624 The function works on at least the following types of files:
630 many types of Un*x and Linux binary
634 many types of Un*x and Linux shared library
638 Windows Win32 and Win64 binaries
642 Windows Win32 and Win64 DLLs
644 Win32 binaries and DLLs return C<i386>.
646 Win64 binaries and DLLs return C<x86_64>.
654 Linux new-style initrd images
658 some non-x86 Linux vmlinuz kernels
662 What it can't do currently:
668 static libraries (libfoo.a)
672 Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
676 x86 Linux vmlinuz kernels
678 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32- and
679 compressed code, and are horribly hard to unpack. If you want to find
680 the architecture of a kernel, use the architecture of the associated
681 initrd or kernel module(s) instead.
685 ("inspect_os", (RStringList "roots", [], []), -1, [],
687 "inspect disk and return list of operating systems found",
689 This function uses other libguestfs functions and certain
690 heuristics to inspect the disk(s) (usually disks belonging to
691 a virtual machine), looking for operating systems.
693 The list returned is empty if no operating systems were found.
695 If one operating system was found, then this returns a list with
696 a single element, which is the name of the root filesystem of
697 this operating system. It is also possible for this function
698 to return a list containing more than one element, indicating
699 a dual-boot or multi-boot virtual machine, with each element being
700 the root filesystem of one of the operating systems.
702 You can pass the root string(s) returned to other
703 C<guestfs_inspect_get_*> functions in order to query further
704 information about each operating system, such as the name
707 This function uses other libguestfs features such as
708 C<guestfs_mount_ro> and C<guestfs_umount_all> in order to mount
709 and unmount filesystems and look at the contents. This should
710 be called with no disks currently mounted. The function may also
711 use Augeas, so any existing Augeas handle will be closed.
713 This function cannot decrypt encrypted disks. The caller
714 must do that first (supplying the necessary keys) if the
717 Please read L<guestfs(3)/INSPECTION> for more details.
719 See also C<guestfs_list_filesystems>.");
721 ("inspect_get_type", (RString "name", [Device "root"], []), -1, [],
723 "get type of inspected operating system",
725 This function should only be called with a root device string
726 as returned by C<guestfs_inspect_os>.
728 This returns the type of the inspected operating system.
729 Currently defined types are:
735 Any Linux-based operating system.
739 Any Microsoft Windows operating system.
743 The operating system type could not be determined.
747 Future versions of libguestfs may return other strings here.
748 The caller should be prepared to handle any string.
750 Please read L<guestfs(3)/INSPECTION> for more details.");
752 ("inspect_get_arch", (RString "arch", [Device "root"], []), -1, [],
754 "get architecture of inspected operating system",
756 This function should only be called with a root device string
757 as returned by C<guestfs_inspect_os>.
759 This returns the architecture of the inspected operating system.
760 The possible return values are listed under
761 C<guestfs_file_architecture>.
763 If the architecture could not be determined, then the
764 string C<unknown> is returned.
766 Please read L<guestfs(3)/INSPECTION> for more details.");
768 ("inspect_get_distro", (RString "distro", [Device "root"], []), -1, [],
770 "get distro of inspected operating system",
772 This function should only be called with a root device string
773 as returned by C<guestfs_inspect_os>.
775 This returns the distro (distribution) of the inspected operating
778 Currently defined distros are:
788 Debian or a Debian-derived distro such as Ubuntu.
806 =item \"redhat-based\"
808 Some Red Hat-derived distro.
812 Red Hat Enterprise Linux and some derivatives.
816 Windows does not have distributions. This string is
817 returned if the OS type is Windows.
825 The distro could not be determined.
829 Future versions of libguestfs may return other strings here.
830 The caller should be prepared to handle any string.
832 Please read L<guestfs(3)/INSPECTION> for more details.");
834 ("inspect_get_major_version", (RInt "major", [Device "root"], []), -1, [],
836 "get major version of inspected operating system",
838 This function should only be called with a root device string
839 as returned by C<guestfs_inspect_os>.
841 This returns the major version number of the inspected operating
844 Windows uses a consistent versioning scheme which is I<not>
845 reflected in the popular public names used by the operating system.
846 Notably the operating system known as \"Windows 7\" is really
847 version 6.1 (ie. major = 6, minor = 1). You can find out the
848 real versions corresponding to releases of Windows by consulting
851 If the version could not be determined, then C<0> is returned.
853 Please read L<guestfs(3)/INSPECTION> for more details.");
855 ("inspect_get_minor_version", (RInt "minor", [Device "root"], []), -1, [],
857 "get minor version of inspected operating system",
859 This function should only be called with a root device string
860 as returned by C<guestfs_inspect_os>.
862 This returns the minor version number of the inspected operating
865 If the version could not be determined, then C<0> is returned.
867 Please read L<guestfs(3)/INSPECTION> for more details.
868 See also C<guestfs_inspect_get_major_version>.");
870 ("inspect_get_product_name", (RString "product", [Device "root"], []), -1, [],
872 "get product name of inspected operating system",
874 This function should only be called with a root device string
875 as returned by C<guestfs_inspect_os>.
877 This returns the product name of the inspected operating
878 system. The product name is generally some freeform string
879 which can be displayed to the user, but should not be
882 If the product name could not be determined, then the
883 string C<unknown> is returned.
885 Please read L<guestfs(3)/INSPECTION> for more details.");
887 ("inspect_get_mountpoints", (RHashtable "mountpoints", [Device "root"], []), -1, [],
889 "get mountpoints of inspected operating system",
891 This function should only be called with a root device string
892 as returned by C<guestfs_inspect_os>.
894 This returns a hash of where we think the filesystems
895 associated with this operating system should be mounted.
896 Callers should note that this is at best an educated guess
897 made by reading configuration files such as C</etc/fstab>.
899 Each element in the returned hashtable has a key which
900 is the path of the mountpoint (eg. C</boot>) and a value
901 which is the filesystem that would be mounted there
904 Non-mounted devices such as swap devices are I<not>
905 returned in this list.
907 Please read L<guestfs(3)/INSPECTION> for more details.
908 See also C<guestfs_inspect_get_filesystems>.");
910 ("inspect_get_filesystems", (RStringList "filesystems", [Device "root"], []), -1, [],
912 "get filesystems associated with inspected operating system",
914 This function should only be called with a root device string
915 as returned by C<guestfs_inspect_os>.
917 This returns a list of all the filesystems that we think
918 are associated with this operating system. This includes
919 the root filesystem, other ordinary filesystems, and
920 non-mounted devices like swap partitions.
922 In the case of a multi-boot virtual machine, it is possible
923 for a filesystem to be shared between operating systems.
925 Please read L<guestfs(3)/INSPECTION> for more details.
926 See also C<guestfs_inspect_get_mountpoints>.");
928 ("set_network", (RErr, [Bool "network"], []), -1, [FishAlias "network"],
930 "set enable network flag",
932 If C<network> is true, then the network is enabled in the
933 libguestfs appliance. The default is false.
935 This affects whether commands are able to access the network
936 (see L<guestfs(3)/RUNNING COMMANDS>).
938 You must call this before calling C<guestfs_launch>, otherwise
941 ("get_network", (RBool "network", [], []), -1, [],
943 "get enable network flag",
945 This returns the enable network flag.");
947 ("list_filesystems", (RHashtable "fses", [], []), -1, [],
951 This inspection command looks for filesystems on partitions,
952 block devices and logical volumes, returning a list of devices
953 containing filesystems and their type.
955 The return value is a hash, where the keys are the devices
956 containing filesystems, and the values are the filesystem types.
959 \"/dev/sda1\" => \"ntfs\"
960 \"/dev/sda2\" => \"ext2\"
961 \"/dev/vg_guest/lv_root\" => \"ext4\"
962 \"/dev/vg_guest/lv_swap\" => \"swap\"
964 The value can have the special value \"unknown\", meaning the
965 content of the device is undetermined or empty.
966 \"swap\" means a Linux swap partition.
968 This command runs other libguestfs commands, which might include
969 C<guestfs_mount> and C<guestfs_umount>, and therefore you should
970 use this soon after launch and only when nothing is mounted.
972 Not all of the filesystems returned will be mountable. In
973 particular, swap partitions are returned in the list. Also
974 this command does not check that each filesystem
975 found is valid and mountable, and some filesystems might
976 be mountable but require special options. Filesystems may
977 not all belong to a single logical operating system
978 (use C<guestfs_inspect_os> to look for OSes).");
980 ("add_drive_opts", (RErr, [String "filename"], [Bool "readonly"; String "format"; String "iface"]), -1, [FishAlias "add"],
982 "add an image to examine or modify",
984 This function adds a virtual machine disk image C<filename> to
985 libguestfs. The first time you call this function, the disk
986 appears as C</dev/sda>, the second time as C</dev/sdb>, and
989 You don't necessarily need to be root when using libguestfs. However
990 you obviously do need sufficient permissions to access the filename
991 for whatever operations you want to perform (ie. read access if you
992 just want to read the image or write access if you want to modify the
995 This call checks that C<filename> exists.
997 The optional arguments are:
1003 If true then the image is treated as read-only. Writes are still
1004 allowed, but they are stored in a temporary snapshot overlay which
1005 is discarded at the end. The disk that you add is not modified.
1009 This forces the image format. If you omit this (or use C<guestfs_add_drive>
1010 or C<guestfs_add_drive_ro>) then the format is automatically detected.
1011 Possible formats include C<raw> and C<qcow2>.
1013 Automatic detection of the format opens you up to a potential
1014 security hole when dealing with untrusted raw-format images.
1015 See CVE-2010-3851 and RHBZ#642934. Specifying the format closes
1020 This rarely-used option lets you emulate the behaviour of the
1021 deprecated C<guestfs_add_drive_with_if> call (q.v.)
1025 ("inspect_get_windows_systemroot", (RString "systemroot", [Device "root"], []), -1, [],
1027 "get Windows systemroot of inspected operating system",
1029 This function should only be called with a root device string
1030 as returned by C<guestfs_inspect_os>.
1032 This returns the Windows systemroot of the inspected guest.
1033 The systemroot is a directory path such as C</WINDOWS>.
1035 This call assumes that the guest is Windows and that the
1036 systemroot could be determined by inspection. If this is not
1037 the case then an error is returned.
1039 Please read L<guestfs(3)/INSPECTION> for more details.");
1041 ("inspect_get_roots", (RStringList "roots", [], []), -1, [],
1043 "return list of operating systems found by last inspection",
1045 This function is a convenient way to get the list of root
1046 devices, as returned from a previous call to C<guestfs_inspect_os>,
1047 but without redoing the whole inspection process.
1049 This returns an empty list if either no root devices were
1050 found or the caller has not called C<guestfs_inspect_os>.
1052 Please read L<guestfs(3)/INSPECTION> for more details.");
1054 ("debug_cmdline", (RStringList "cmdline", [], []), -1, [NotInDocs],
1056 "debug the QEMU command line (internal use only)",
1058 This returns the internal QEMU command line. 'debug' commands are
1059 not part of the formal API and can be removed or changed at any time.");
1061 ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"]), -1, [FishAlias "domain"],
1063 "add the disk(s) from a named libvirt domain",
1065 This function adds the disk(s) attached to the named libvirt
1066 domain C<dom>. It works by connecting to libvirt, requesting
1067 the domain and domain XML from libvirt, parsing it for disks,
1068 and calling C<guestfs_add_drive_opts> on each one.
1070 The number of disks added is returned. This operation is atomic:
1071 if an error is returned, then no disks are added.
1073 This function does some minimal checks to make sure the libvirt
1074 domain is not running (unless C<readonly> is true). In a future
1075 version we will try to acquire the libvirt lock on each disk.
1077 Disks must be accessible locally. This often means that adding disks
1078 from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
1079 will fail unless those disks are accessible via the same device path
1082 The optional C<libvirturi> parameter sets the libvirt URI
1083 (see L<http://libvirt.org/uri.html>). If this is not set then
1084 we connect to the default libvirt URI (or one set through an
1085 environment variable, see the libvirt documentation for full
1086 details). If you are using the C API directly then it is more
1087 flexible to create the libvirt connection object yourself, get
1088 the domain object, and call C<guestfs_add_libvirt_dom>.
1090 The other optional parameters are passed directly through to
1091 C<guestfs_add_drive_opts>.");
1094 This interface is not quite baked yet. -- RWMJ 2010-11-11
1095 ("add_libvirt_dom", (RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"]), -1, [NotInFish],
1097 "add the disk(s) from a libvirt domain",
1099 This function adds the disk(s) attached to the libvirt domain C<dom>.
1100 It works by requesting the domain XML from libvirt, parsing it for
1101 disks, and calling C<guestfs_add_drive_opts> on each one.
1103 In the C API we declare C<void *dom>, but really it has type
1104 C<virDomainPtr dom>. This is so we don't need E<lt>libvirt.hE<gt>.
1106 The number of disks added is returned. This operation is atomic:
1107 if an error is returned, then no disks are added.
1109 This function does some minimal checks to make sure the libvirt
1110 domain is not running (unless C<readonly> is true). In a future
1111 version we will try to acquire the libvirt lock on each disk.
1113 Disks must be accessible locally. This often means that adding disks
1114 from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
1115 will fail unless those disks are accessible via the same device path
1118 The optional parameters are passed directly through to
1119 C<guestfs_add_drive_opts>.");
1124 (* daemon_functions are any functions which cause some action
1125 * to take place in the daemon.
1128 let daemon_functions = [
1129 ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [],
1130 [InitEmpty, Always, TestOutput (
1131 [["part_disk"; "/dev/sda"; "mbr"];
1132 ["mkfs"; "ext2"; "/dev/sda1"];
1133 ["mount"; "/dev/sda1"; "/"];
1134 ["write"; "/new"; "new file contents"];
1135 ["cat"; "/new"]], "new file contents")],
1136 "mount a guest disk at a position in the filesystem",
1138 Mount a guest disk at a position in the filesystem. Block devices
1139 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1140 the guest. If those block devices contain partitions, they will have
1141 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
1144 The rules are the same as for L<mount(2)>: A filesystem must
1145 first be mounted on C</> before others can be mounted. Other
1146 filesystems can only be mounted on directories which already
1149 The mounted filesystem is writable, if we have sufficient permissions
1150 on the underlying device.
1153 When you use this call, the filesystem options C<sync> and C<noatime>
1154 are set implicitly. This was originally done because we thought it
1155 would improve reliability, but it turns out that I<-o sync> has a
1156 very large negative performance impact and negligible effect on
1157 reliability. Therefore we recommend that you avoid using
1158 C<guestfs_mount> in any code that needs performance, and instead
1159 use C<guestfs_mount_options> (use an empty string for the first
1160 parameter if you don't want any options).");
1162 ("sync", (RErr, [], []), 2, [],
1163 [ InitEmpty, Always, TestRun [["sync"]]],
1164 "sync disks, writes are flushed through to the disk image",
1166 This syncs the disk, so that any writes are flushed through to the
1167 underlying disk image.
1169 You should always call this if you have modified a disk image, before
1170 closing the handle.");
1172 ("touch", (RErr, [Pathname "path"], []), 3, [],
1173 [InitBasicFS, Always, TestOutputTrue (
1175 ["exists"; "/new"]])],
1176 "update file timestamps or create a new file",
1178 Touch acts like the L<touch(1)> command. It can be used to
1179 update the timestamps on a file, or, if the file does not exist,
1180 to create a new zero-length file.
1182 This command only works on regular files, and will fail on other
1183 file types such as directories, symbolic links, block special etc.");
1185 ("cat", (RString "content", [Pathname "path"], []), 4, [ProtocolLimitWarning],
1186 [InitISOFS, Always, TestOutput (
1187 [["cat"; "/known-2"]], "abcdef\n")],
1188 "list the contents of a file",
1190 Return the contents of the file named C<path>.
1192 Note that this function cannot correctly handle binary files
1193 (specifically, files containing C<\\0> character which is treated
1194 as end of string). For those you need to use the C<guestfs_read_file>
1195 or C<guestfs_download> functions which have a more complex interface.");
1197 ("ll", (RString "listing", [Pathname "directory"], []), 5, [],
1198 [], (* XXX Tricky to test because it depends on the exact format
1199 * of the 'ls -l' command, which changes between F10 and F11.
1201 "list the files in a directory (long format)",
1203 List the files in C<directory> (relative to the root directory,
1204 there is no cwd) in the format of 'ls -la'.
1206 This command is mostly useful for interactive sessions. It
1207 is I<not> intended that you try to parse the output string.");
1209 ("ls", (RStringList "listing", [Pathname "directory"], []), 6, [],
1210 [InitBasicFS, Always, TestOutputList (
1212 ["touch"; "/newer"];
1213 ["touch"; "/newest"];
1214 ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])],
1215 "list the files in a directory",
1217 List the files in C<directory> (relative to the root directory,
1218 there is no cwd). The '.' and '..' entries are not returned, but
1219 hidden files are shown.
1221 This command is mostly useful for interactive sessions. Programs
1222 should probably use C<guestfs_readdir> instead.");
1224 ("list_devices", (RStringList "devices", [], []), 7, [],
1225 [InitEmpty, Always, TestOutputListOfDevices (
1226 [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
1227 "list the block devices",
1229 List all the block devices.
1231 The full block device names are returned, eg. C</dev/sda>.
1233 See also C<guestfs_list_filesystems>.");
1235 ("list_partitions", (RStringList "partitions", [], []), 8, [],
1236 [InitBasicFS, Always, TestOutputListOfDevices (
1237 [["list_partitions"]], ["/dev/sda1"]);
1238 InitEmpty, Always, TestOutputListOfDevices (
1239 [["part_init"; "/dev/sda"; "mbr"];
1240 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1241 ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1242 ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1243 ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1244 "list the partitions",
1246 List all the partitions detected on all block devices.
1248 The full partition device names are returned, eg. C</dev/sda1>
1250 This does not return logical volumes. For that you will need to
1251 call C<guestfs_lvs>.
1253 See also C<guestfs_list_filesystems>.");
1255 ("pvs", (RStringList "physvols", [], []), 9, [Optional "lvm2"],
1256 [InitBasicFSonLVM, Always, TestOutputListOfDevices (
1257 [["pvs"]], ["/dev/sda1"]);
1258 InitEmpty, Always, TestOutputListOfDevices (
1259 [["part_init"; "/dev/sda"; "mbr"];
1260 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1261 ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1262 ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1263 ["pvcreate"; "/dev/sda1"];
1264 ["pvcreate"; "/dev/sda2"];
1265 ["pvcreate"; "/dev/sda3"];
1266 ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1267 "list the LVM physical volumes (PVs)",
1269 List all the physical volumes detected. This is the equivalent
1270 of the L<pvs(8)> command.
1272 This returns a list of just the device names that contain
1273 PVs (eg. C</dev/sda2>).
1275 See also C<guestfs_pvs_full>.");
1277 ("vgs", (RStringList "volgroups", [], []), 10, [Optional "lvm2"],
1278 [InitBasicFSonLVM, Always, TestOutputList (
1280 InitEmpty, Always, TestOutputList (
1281 [["part_init"; "/dev/sda"; "mbr"];
1282 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1283 ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1284 ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1285 ["pvcreate"; "/dev/sda1"];
1286 ["pvcreate"; "/dev/sda2"];
1287 ["pvcreate"; "/dev/sda3"];
1288 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1289 ["vgcreate"; "VG2"; "/dev/sda3"];
1290 ["vgs"]], ["VG1"; "VG2"])],
1291 "list the LVM volume groups (VGs)",
1293 List all the volumes groups detected. This is the equivalent
1294 of the L<vgs(8)> command.
1296 This returns a list of just the volume group names that were
1297 detected (eg. C<VolGroup00>).
1299 See also C<guestfs_vgs_full>.");
1301 ("lvs", (RStringList "logvols", [], []), 11, [Optional "lvm2"],
1302 [InitBasicFSonLVM, Always, TestOutputList (
1303 [["lvs"]], ["/dev/VG/LV"]);
1304 InitEmpty, Always, TestOutputList (
1305 [["part_init"; "/dev/sda"; "mbr"];
1306 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1307 ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1308 ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1309 ["pvcreate"; "/dev/sda1"];
1310 ["pvcreate"; "/dev/sda2"];
1311 ["pvcreate"; "/dev/sda3"];
1312 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1313 ["vgcreate"; "VG2"; "/dev/sda3"];
1314 ["lvcreate"; "LV1"; "VG1"; "50"];
1315 ["lvcreate"; "LV2"; "VG1"; "50"];
1316 ["lvcreate"; "LV3"; "VG2"; "50"];
1317 ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
1318 "list the LVM logical volumes (LVs)",
1320 List all the logical volumes detected. This is the equivalent
1321 of the L<lvs(8)> command.
1323 This returns a list of the logical volume device names
1324 (eg. C</dev/VolGroup00/LogVol00>).
1326 See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>.");
1328 ("pvs_full", (RStructList ("physvols", "lvm_pv"), [], []), 12, [Optional "lvm2"],
1329 [], (* XXX how to test? *)
1330 "list the LVM physical volumes (PVs)",
1332 List all the physical volumes detected. This is the equivalent
1333 of the L<pvs(8)> command. The \"full\" version includes all fields.");
1335 ("vgs_full", (RStructList ("volgroups", "lvm_vg"), [], []), 13, [Optional "lvm2"],
1336 [], (* XXX how to test? *)
1337 "list the LVM volume groups (VGs)",
1339 List all the volumes groups detected. This is the equivalent
1340 of the L<vgs(8)> command. The \"full\" version includes all fields.");
1342 ("lvs_full", (RStructList ("logvols", "lvm_lv"), [], []), 14, [Optional "lvm2"],
1343 [], (* XXX how to test? *)
1344 "list the LVM logical volumes (LVs)",
1346 List all the logical volumes detected. This is the equivalent
1347 of the L<lvs(8)> command. The \"full\" version includes all fields.");
1349 ("read_lines", (RStringList "lines", [Pathname "path"], []), 15, [],
1350 [InitISOFS, Always, TestOutputList (
1351 [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]);
1352 InitISOFS, Always, TestOutputList (
1353 [["read_lines"; "/empty"]], [])],
1354 "read file as lines",
1356 Return the contents of the file named C<path>.
1358 The file contents are returned as a list of lines. Trailing
1359 C<LF> and C<CRLF> character sequences are I<not> returned.
1361 Note that this function cannot correctly handle binary files
1362 (specifically, files containing C<\\0> character which is treated
1363 as end of line). For those you need to use the C<guestfs_read_file>
1364 function which has a more complex interface.");
1366 ("aug_init", (RErr, [Pathname "root"; Int "flags"], []), 16, [Optional "augeas"],
1367 [], (* XXX Augeas code needs tests. *)
1368 "create a new Augeas handle",
1370 Create a new Augeas handle for editing configuration files.
1371 If there was any previous Augeas handle associated with this
1372 guestfs session, then it is closed.
1374 You must call this before using any other C<guestfs_aug_*>
1377 C<root> is the filesystem root. C<root> must not be NULL,
1380 The flags are the same as the flags defined in
1381 E<lt>augeas.hE<gt>, the logical I<or> of the following
1386 =item C<AUG_SAVE_BACKUP> = 1
1388 Keep the original file with a C<.augsave> extension.
1390 =item C<AUG_SAVE_NEWFILE> = 2
1392 Save changes into a file with extension C<.augnew>, and
1393 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
1395 =item C<AUG_TYPE_CHECK> = 4
1397 Typecheck lenses (can be expensive).
1399 =item C<AUG_NO_STDINC> = 8
1401 Do not use standard load path for modules.
1403 =item C<AUG_SAVE_NOOP> = 16
1405 Make save a no-op, just record what would have been changed.
1407 =item C<AUG_NO_LOAD> = 32
1409 Do not load the tree in C<guestfs_aug_init>.
1413 To close the handle, you can call C<guestfs_aug_close>.
1415 To find out more about Augeas, see L<http://augeas.net/>.");
1417 ("aug_close", (RErr, [], []), 26, [Optional "augeas"],
1418 [], (* XXX Augeas code needs tests. *)
1419 "close the current Augeas handle",
1421 Close the current Augeas handle and free up any resources
1422 used by it. After calling this, you have to call
1423 C<guestfs_aug_init> again before you can use any other
1424 Augeas functions.");
1426 ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"], []), 17, [Optional "augeas"],
1427 [], (* XXX Augeas code needs tests. *)
1428 "define an Augeas variable",
1430 Defines an Augeas variable C<name> whose value is the result
1431 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
1434 On success this returns the number of nodes in C<expr>, or
1435 C<0> if C<expr> evaluates to something which is not a nodeset.");
1437 ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"], []), 18, [Optional "augeas"],
1438 [], (* XXX Augeas code needs tests. *)
1439 "define an Augeas node",
1441 Defines a variable C<name> whose value is the result of
1444 If C<expr> evaluates to an empty nodeset, a node is created,
1445 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
1446 C<name> will be the nodeset containing that single node.
1448 On success this returns a pair containing the
1449 number of nodes in the nodeset, and a boolean flag
1450 if a node was created.");
1452 ("aug_get", (RString "val", [String "augpath"], []), 19, [Optional "augeas"],
1453 [], (* XXX Augeas code needs tests. *)
1454 "look up the value of an Augeas path",
1456 Look up the value associated with C<path>. If C<path>
1457 matches exactly one node, the C<value> is returned.");
1459 ("aug_set", (RErr, [String "augpath"; String "val"], []), 20, [Optional "augeas"],
1460 [], (* XXX Augeas code needs tests. *)
1461 "set Augeas path to value",
1463 Set the value associated with C<path> to C<val>.
1465 In the Augeas API, it is possible to clear a node by setting
1466 the value to NULL. Due to an oversight in the libguestfs API
1467 you cannot do that with this call. Instead you must use the
1468 C<guestfs_aug_clear> call.");
1470 ("aug_insert", (RErr, [String "augpath"; String "label"; Bool "before"], []), 21, [Optional "augeas"],
1471 [], (* XXX Augeas code needs tests. *)
1472 "insert a sibling Augeas node",
1474 Create a new sibling C<label> for C<path>, inserting it into
1475 the tree before or after C<path> (depending on the boolean
1478 C<path> must match exactly one existing node in the tree, and
1479 C<label> must be a label, ie. not contain C</>, C<*> or end
1480 with a bracketed index C<[N]>.");
1482 ("aug_rm", (RInt "nrnodes", [String "augpath"], []), 22, [Optional "augeas"],
1483 [], (* XXX Augeas code needs tests. *)
1484 "remove an Augeas path",
1486 Remove C<path> and all of its children.
1488 On success this returns the number of entries which were removed.");
1490 ("aug_mv", (RErr, [String "src"; String "dest"], []), 23, [Optional "augeas"],
1491 [], (* XXX Augeas code needs tests. *)
1494 Move the node C<src> to C<dest>. C<src> must match exactly
1495 one node. C<dest> is overwritten if it exists.");
1497 ("aug_match", (RStringList "matches", [String "augpath"], []), 24, [Optional "augeas"],
1498 [], (* XXX Augeas code needs tests. *)
1499 "return Augeas nodes which match augpath",
1501 Returns a list of paths which match the path expression C<path>.
1502 The returned paths are sufficiently qualified so that they match
1503 exactly one node in the current tree.");
1505 ("aug_save", (RErr, [], []), 25, [Optional "augeas"],
1506 [], (* XXX Augeas code needs tests. *)
1507 "write all pending Augeas changes to disk",
1509 This writes all pending changes to disk.
1511 The flags which were passed to C<guestfs_aug_init> affect exactly
1512 how files are saved.");
1514 ("aug_load", (RErr, [], []), 27, [Optional "augeas"],
1515 [], (* XXX Augeas code needs tests. *)
1516 "load files into the tree",
1518 Load files into the tree.
1520 See C<aug_load> in the Augeas documentation for the full gory
1523 ("aug_ls", (RStringList "matches", [String "augpath"], []), 28, [Optional "augeas"],
1524 [], (* XXX Augeas code needs tests. *)
1525 "list Augeas nodes under augpath",
1527 This is just a shortcut for listing C<guestfs_aug_match>
1528 C<path/*> and sorting the resulting nodes into alphabetical order.");
1530 ("rm", (RErr, [Pathname "path"], []), 29, [],
1531 [InitBasicFS, Always, TestRun
1534 InitBasicFS, Always, TestLastFail
1536 InitBasicFS, Always, TestLastFail
1541 Remove the single file C<path>.");
1543 ("rmdir", (RErr, [Pathname "path"], []), 30, [],
1544 [InitBasicFS, Always, TestRun
1547 InitBasicFS, Always, TestLastFail
1548 [["rmdir"; "/new"]];
1549 InitBasicFS, Always, TestLastFail
1551 ["rmdir"; "/new"]]],
1552 "remove a directory",
1554 Remove the single directory C<path>.");
1556 ("rm_rf", (RErr, [Pathname "path"], []), 31, [],
1557 [InitBasicFS, Always, TestOutputFalse
1559 ["mkdir"; "/new/foo"];
1560 ["touch"; "/new/foo/bar"];
1562 ["exists"; "/new"]]],
1563 "remove a file or directory recursively",
1565 Remove the file or directory C<path>, recursively removing the
1566 contents if its a directory. This is like the C<rm -rf> shell
1569 ("mkdir", (RErr, [Pathname "path"], []), 32, [],
1570 [InitBasicFS, Always, TestOutputTrue
1572 ["is_dir"; "/new"]];
1573 InitBasicFS, Always, TestLastFail
1574 [["mkdir"; "/new/foo/bar"]]],
1575 "create a directory",
1577 Create a directory named C<path>.");
1579 ("mkdir_p", (RErr, [Pathname "path"], []), 33, [],
1580 [InitBasicFS, Always, TestOutputTrue
1581 [["mkdir_p"; "/new/foo/bar"];
1582 ["is_dir"; "/new/foo/bar"]];
1583 InitBasicFS, Always, TestOutputTrue
1584 [["mkdir_p"; "/new/foo/bar"];
1585 ["is_dir"; "/new/foo"]];
1586 InitBasicFS, Always, TestOutputTrue
1587 [["mkdir_p"; "/new/foo/bar"];
1588 ["is_dir"; "/new"]];
1589 (* Regression tests for RHBZ#503133: *)
1590 InitBasicFS, Always, TestRun
1592 ["mkdir_p"; "/new"]];
1593 InitBasicFS, Always, TestLastFail
1595 ["mkdir_p"; "/new"]]],
1596 "create a directory and parents",
1598 Create a directory named C<path>, creating any parent directories
1599 as necessary. This is like the C<mkdir -p> shell command.");
1601 ("chmod", (RErr, [Int "mode"; Pathname "path"], []), 34, [],
1602 [], (* XXX Need stat command to test *)
1605 Change the mode (permissions) of C<path> to C<mode>. Only
1606 numeric modes are supported.
1608 I<Note>: When using this command from guestfish, C<mode>
1609 by default would be decimal, unless you prefix it with
1610 C<0> to get octal, ie. use C<0700> not C<700>.
1612 The mode actually set is affected by the umask.");
1614 ("chown", (RErr, [Int "owner"; Int "group"; Pathname "path"], []), 35, [],
1615 [], (* XXX Need stat command to test *)
1616 "change file owner and group",
1618 Change the file owner to C<owner> and group to C<group>.
1620 Only numeric uid and gid are supported. If you want to use
1621 names, you will need to locate and parse the password file
1622 yourself (Augeas support makes this relatively easy).");
1624 ("exists", (RBool "existsflag", [Pathname "path"], []), 36, [],
1625 [InitISOFS, Always, TestOutputTrue (
1626 [["exists"; "/empty"]]);
1627 InitISOFS, Always, TestOutputTrue (
1628 [["exists"; "/directory"]])],
1629 "test if file or directory exists",
1631 This returns C<true> if and only if there is a file, directory
1632 (or anything) with the given C<path> name.
1634 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
1636 ("is_file", (RBool "fileflag", [Pathname "path"], []), 37, [],
1637 [InitISOFS, Always, TestOutputTrue (
1638 [["is_file"; "/known-1"]]);
1639 InitISOFS, Always, TestOutputFalse (
1640 [["is_file"; "/directory"]])],
1641 "test if a regular file",
1643 This returns C<true> if and only if there is a regular file
1644 with the given C<path> name. Note that it returns false for
1645 other objects like directories.
1647 See also C<guestfs_stat>.");
1649 ("is_dir", (RBool "dirflag", [Pathname "path"], []), 38, [],
1650 [InitISOFS, Always, TestOutputFalse (
1651 [["is_dir"; "/known-3"]]);
1652 InitISOFS, Always, TestOutputTrue (
1653 [["is_dir"; "/directory"]])],
1654 "test if a directory",
1656 This returns C<true> if and only if there is a directory
1657 with the given C<path> name. Note that it returns false for
1658 other objects like files.
1660 See also C<guestfs_stat>.");
1662 ("pvcreate", (RErr, [Device "device"], []), 39, [Optional "lvm2"],
1663 [InitEmpty, Always, TestOutputListOfDevices (
1664 [["part_init"; "/dev/sda"; "mbr"];
1665 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1666 ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1667 ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1668 ["pvcreate"; "/dev/sda1"];
1669 ["pvcreate"; "/dev/sda2"];
1670 ["pvcreate"; "/dev/sda3"];
1671 ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1672 "create an LVM physical volume",
1674 This creates an LVM physical volume on the named C<device>,
1675 where C<device> should usually be a partition name such
1678 ("vgcreate", (RErr, [String "volgroup"; DeviceList "physvols"], []), 40, [Optional "lvm2"],
1679 [InitEmpty, Always, TestOutputList (
1680 [["part_init"; "/dev/sda"; "mbr"];
1681 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1682 ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1683 ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1684 ["pvcreate"; "/dev/sda1"];
1685 ["pvcreate"; "/dev/sda2"];
1686 ["pvcreate"; "/dev/sda3"];
1687 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1688 ["vgcreate"; "VG2"; "/dev/sda3"];
1689 ["vgs"]], ["VG1"; "VG2"])],
1690 "create an LVM volume group",
1692 This creates an LVM volume group called C<volgroup>
1693 from the non-empty list of physical volumes C<physvols>.");
1695 ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"], []), 41, [Optional "lvm2"],
1696 [InitEmpty, Always, TestOutputList (
1697 [["part_init"; "/dev/sda"; "mbr"];
1698 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1699 ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1700 ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1701 ["pvcreate"; "/dev/sda1"];
1702 ["pvcreate"; "/dev/sda2"];
1703 ["pvcreate"; "/dev/sda3"];
1704 ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1705 ["vgcreate"; "VG2"; "/dev/sda3"];
1706 ["lvcreate"; "LV1"; "VG1"; "50"];
1707 ["lvcreate"; "LV2"; "VG1"; "50"];
1708 ["lvcreate"; "LV3"; "VG2"; "50"];
1709 ["lvcreate"; "LV4"; "VG2"; "50"];
1710 ["lvcreate"; "LV5"; "VG2"; "50"];
1712 ["/dev/VG1/LV1"; "/dev/VG1/LV2";
1713 "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
1714 "create an LVM logical volume",
1716 This creates an LVM logical volume called C<logvol>
1717 on the volume group C<volgroup>, with C<size> megabytes.");
1719 ("mkfs", (RErr, [String "fstype"; Device "device"], []), 42, [],
1720 [InitEmpty, Always, TestOutput (
1721 [["part_disk"; "/dev/sda"; "mbr"];
1722 ["mkfs"; "ext2"; "/dev/sda1"];
1723 ["mount_options"; ""; "/dev/sda1"; "/"];
1724 ["write"; "/new"; "new file contents"];
1725 ["cat"; "/new"]], "new file contents")],
1726 "make a filesystem",
1728 This creates a filesystem on C<device> (usually a partition
1729 or LVM logical volume). The filesystem type is C<fstype>, for
1732 ("sfdisk", (RErr, [Device "device";
1733 Int "cyls"; Int "heads"; Int "sectors";
1734 StringList "lines"], []), 43, [DangerWillRobinson],
1736 "create partitions on a block device",
1738 This is a direct interface to the L<sfdisk(8)> program for creating
1739 partitions on block devices.
1741 C<device> should be a block device, for example C</dev/sda>.
1743 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1744 and sectors on the device, which are passed directly to sfdisk as
1745 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
1746 of these, then the corresponding parameter is omitted. Usually for
1747 'large' disks, you can just pass C<0> for these, but for small
1748 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1749 out the right geometry and you will need to tell it.
1751 C<lines> is a list of lines that we feed to C<sfdisk>. For more
1752 information refer to the L<sfdisk(8)> manpage.
1754 To create a single partition occupying the whole disk, you would
1755 pass C<lines> as a single element list, when the single element being
1756 the string C<,> (comma).
1758 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>,
1759 C<guestfs_part_init>");
1761 ("write_file", (RErr, [Pathname "path"; String "content"; Int "size"], []), 44, [ProtocolLimitWarning; DeprecatedBy "write"],
1762 (* Regression test for RHBZ#597135. *)
1763 [InitBasicFS, Always, TestLastFail
1764 [["write_file"; "/new"; "abc"; "10000"]]],
1767 This call creates a file called C<path>. The contents of the
1768 file is the string C<content> (which can contain any 8 bit data),
1769 with length C<size>.
1771 As a special case, if C<size> is C<0>
1772 then the length is calculated using C<strlen> (so in this case
1773 the content cannot contain embedded ASCII NULs).
1775 I<NB.> Owing to a bug, writing content containing ASCII NUL
1776 characters does I<not> work, even if the length is specified.");
1778 ("umount", (RErr, [String "pathordevice"], []), 45, [FishAlias "unmount"],
1779 [InitEmpty, Always, TestOutputListOfDevices (
1780 [["part_disk"; "/dev/sda"; "mbr"];
1781 ["mkfs"; "ext2"; "/dev/sda1"];
1782 ["mount_options"; ""; "/dev/sda1"; "/"];
1783 ["mounts"]], ["/dev/sda1"]);
1784 InitEmpty, Always, TestOutputList (
1785 [["part_disk"; "/dev/sda"; "mbr"];
1786 ["mkfs"; "ext2"; "/dev/sda1"];
1787 ["mount_options"; ""; "/dev/sda1"; "/"];
1790 "unmount a filesystem",
1792 This unmounts the given filesystem. The filesystem may be
1793 specified either by its mountpoint (path) or the device which
1794 contains the filesystem.");
1796 ("mounts", (RStringList "devices", [], []), 46, [],
1797 [InitBasicFS, Always, TestOutputListOfDevices (
1798 [["mounts"]], ["/dev/sda1"])],
1799 "show mounted filesystems",
1801 This returns the list of currently mounted filesystems. It returns
1802 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1804 Some internal mounts are not shown.
1806 See also: C<guestfs_mountpoints>");
1808 ("umount_all", (RErr, [], []), 47, [FishAlias "unmount-all"],
1809 [InitBasicFS, Always, TestOutputList (
1812 (* check that umount_all can unmount nested mounts correctly: *)
1813 InitEmpty, Always, TestOutputList (
1814 [["part_init"; "/dev/sda"; "mbr"];
1815 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1816 ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1817 ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1818 ["mkfs"; "ext2"; "/dev/sda1"];
1819 ["mkfs"; "ext2"; "/dev/sda2"];
1820 ["mkfs"; "ext2"; "/dev/sda3"];
1821 ["mount_options"; ""; "/dev/sda1"; "/"];
1823 ["mount_options"; ""; "/dev/sda2"; "/mp1"];
1824 ["mkdir"; "/mp1/mp2"];
1825 ["mount_options"; ""; "/dev/sda3"; "/mp1/mp2"];
1826 ["mkdir"; "/mp1/mp2/mp3"];
1829 "unmount all filesystems",
1831 This unmounts all mounted filesystems.
1833 Some internal mounts are not unmounted by this call.");
1835 ("lvm_remove_all", (RErr, [], []), 48, [DangerWillRobinson; Optional "lvm2"],
1837 "remove all LVM LVs, VGs and PVs",
1839 This command removes all LVM logical volumes, volume groups
1840 and physical volumes.");
1842 ("file", (RString "description", [Dev_or_Path "path"], []), 49, [],
1843 [InitISOFS, Always, TestOutput (
1844 [["file"; "/empty"]], "empty");
1845 InitISOFS, Always, TestOutput (
1846 [["file"; "/known-1"]], "ASCII text");
1847 InitISOFS, Always, TestLastFail (
1848 [["file"; "/notexists"]]);
1849 InitISOFS, Always, TestOutput (
1850 [["file"; "/abssymlink"]], "symbolic link");
1851 InitISOFS, Always, TestOutput (
1852 [["file"; "/directory"]], "directory")],
1853 "determine file type",
1855 This call uses the standard L<file(1)> command to determine
1856 the type or contents of the file.
1858 This call will also transparently look inside various types
1861 The exact command which runs is C<file -zb path>. Note in
1862 particular that the filename is not prepended to the output
1865 This command can also be used on C</dev/> devices
1866 (and partitions, LV names). You can for example use this
1867 to determine if a device contains a filesystem, although
1868 it's usually better to use C<guestfs_vfs_type>.
1870 If the C<path> does not begin with C</dev/> then
1871 this command only works for the content of regular files.
1872 For other file types (directory, symbolic link etc) it
1873 will just return the string C<directory> etc.");
1875 ("command", (RString "output", [StringList "arguments"], []), 50, [ProtocolLimitWarning],
1876 [InitBasicFS, Always, TestOutput (
1877 [["upload"; "test-command"; "/test-command"];
1878 ["chmod"; "0o755"; "/test-command"];
1879 ["command"; "/test-command 1"]], "Result1");
1880 InitBasicFS, Always, TestOutput (
1881 [["upload"; "test-command"; "/test-command"];
1882 ["chmod"; "0o755"; "/test-command"];
1883 ["command"; "/test-command 2"]], "Result2\n");
1884 InitBasicFS, Always, TestOutput (
1885 [["upload"; "test-command"; "/test-command"];
1886 ["chmod"; "0o755"; "/test-command"];
1887 ["command"; "/test-command 3"]], "\nResult3");
1888 InitBasicFS, Always, TestOutput (
1889 [["upload"; "test-command"; "/test-command"];
1890 ["chmod"; "0o755"; "/test-command"];
1891 ["command"; "/test-command 4"]], "\nResult4\n");
1892 InitBasicFS, Always, TestOutput (
1893 [["upload"; "test-command"; "/test-command"];
1894 ["chmod"; "0o755"; "/test-command"];
1895 ["command"; "/test-command 5"]], "\nResult5\n\n");
1896 InitBasicFS, Always, TestOutput (
1897 [["upload"; "test-command"; "/test-command"];
1898 ["chmod"; "0o755"; "/test-command"];
1899 ["command"; "/test-command 6"]], "\n\nResult6\n\n");
1900 InitBasicFS, Always, TestOutput (
1901 [["upload"; "test-command"; "/test-command"];
1902 ["chmod"; "0o755"; "/test-command"];
1903 ["command"; "/test-command 7"]], "");
1904 InitBasicFS, Always, TestOutput (
1905 [["upload"; "test-command"; "/test-command"];
1906 ["chmod"; "0o755"; "/test-command"];
1907 ["command"; "/test-command 8"]], "\n");
1908 InitBasicFS, Always, TestOutput (
1909 [["upload"; "test-command"; "/test-command"];
1910 ["chmod"; "0o755"; "/test-command"];
1911 ["command"; "/test-command 9"]], "\n\n");
1912 InitBasicFS, Always, TestOutput (
1913 [["upload"; "test-command"; "/test-command"];
1914 ["chmod"; "0o755"; "/test-command"];
1915 ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n");
1916 InitBasicFS, Always, TestOutput (
1917 [["upload"; "test-command"; "/test-command"];
1918 ["chmod"; "0o755"; "/test-command"];
1919 ["command"; "/test-command 11"]], "Result11-1\nResult11-2");
1920 InitBasicFS, Always, TestLastFail (
1921 [["upload"; "test-command"; "/test-command"];
1922 ["chmod"; "0o755"; "/test-command"];
1923 ["command"; "/test-command"]])],
1924 "run a command from the guest filesystem",
1926 This call runs a command from the guest filesystem. The
1927 filesystem must be mounted, and must contain a compatible
1928 operating system (ie. something Linux, with the same
1929 or compatible processor architecture).
1931 The single parameter is an argv-style list of arguments.
1932 The first element is the name of the program to run.
1933 Subsequent elements are parameters. The list must be
1934 non-empty (ie. must contain a program name). Note that
1935 the command runs directly, and is I<not> invoked via
1936 the shell (see C<guestfs_sh>).
1938 The return value is anything printed to I<stdout> by
1941 If the command returns a non-zero exit status, then
1942 this function returns an error message. The error message
1943 string is the content of I<stderr> from the command.
1945 The C<$PATH> environment variable will contain at least
1946 C</usr/bin> and C</bin>. If you require a program from
1947 another location, you should provide the full path in the
1950 Shared libraries and data files required by the program
1951 must be available on filesystems which are mounted in the
1952 correct places. It is the caller's responsibility to ensure
1953 all filesystems that are needed are mounted at the right
1956 ("command_lines", (RStringList "lines", [StringList "arguments"], []), 51, [ProtocolLimitWarning],
1957 [InitBasicFS, Always, TestOutputList (
1958 [["upload"; "test-command"; "/test-command"];
1959 ["chmod"; "0o755"; "/test-command"];
1960 ["command_lines"; "/test-command 1"]], ["Result1"]);
1961 InitBasicFS, Always, TestOutputList (
1962 [["upload"; "test-command"; "/test-command"];
1963 ["chmod"; "0o755"; "/test-command"];
1964 ["command_lines"; "/test-command 2"]], ["Result2"]);
1965 InitBasicFS, Always, TestOutputList (
1966 [["upload"; "test-command"; "/test-command"];
1967 ["chmod"; "0o755"; "/test-command"];
1968 ["command_lines"; "/test-command 3"]], ["";"Result3"]);
1969 InitBasicFS, Always, TestOutputList (
1970 [["upload"; "test-command"; "/test-command"];
1971 ["chmod"; "0o755"; "/test-command"];
1972 ["command_lines"; "/test-command 4"]], ["";"Result4"]);
1973 InitBasicFS, Always, TestOutputList (
1974 [["upload"; "test-command"; "/test-command"];
1975 ["chmod"; "0o755"; "/test-command"];
1976 ["command_lines"; "/test-command 5"]], ["";"Result5";""]);
1977 InitBasicFS, Always, TestOutputList (
1978 [["upload"; "test-command"; "/test-command"];
1979 ["chmod"; "0o755"; "/test-command"];
1980 ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]);
1981 InitBasicFS, Always, TestOutputList (
1982 [["upload"; "test-command"; "/test-command"];
1983 ["chmod"; "0o755"; "/test-command"];
1984 ["command_lines"; "/test-command 7"]], []);
1985 InitBasicFS, Always, TestOutputList (
1986 [["upload"; "test-command"; "/test-command"];
1987 ["chmod"; "0o755"; "/test-command"];
1988 ["command_lines"; "/test-command 8"]], [""]);
1989 InitBasicFS, Always, TestOutputList (
1990 [["upload"; "test-command"; "/test-command"];
1991 ["chmod"; "0o755"; "/test-command"];
1992 ["command_lines"; "/test-command 9"]], ["";""]);
1993 InitBasicFS, Always, TestOutputList (
1994 [["upload"; "test-command"; "/test-command"];
1995 ["chmod"; "0o755"; "/test-command"];
1996 ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]);
1997 InitBasicFS, Always, TestOutputList (
1998 [["upload"; "test-command"; "/test-command"];
1999 ["chmod"; "0o755"; "/test-command"];
2000 ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])],
2001 "run a command, returning lines",
2003 This is the same as C<guestfs_command>, but splits the
2004 result into a list of lines.
2006 See also: C<guestfs_sh_lines>");
2008 ("stat", (RStruct ("statbuf", "stat"), [Pathname "path"], []), 52, [],
2009 [InitISOFS, Always, TestOutputStruct (
2010 [["stat"; "/empty"]], [CompareWithInt ("size", 0)])],
2011 "get file information",
2013 Returns file information for the given C<path>.
2015 This is the same as the C<stat(2)> system call.");
2017 ("lstat", (RStruct ("statbuf", "stat"), [Pathname "path"], []), 53, [],
2018 [InitISOFS, Always, TestOutputStruct (
2019 [["lstat"; "/empty"]], [CompareWithInt ("size", 0)])],
2020 "get file information for a symbolic link",
2022 Returns file information for the given C<path>.
2024 This is the same as C<guestfs_stat> except that if C<path>
2025 is a symbolic link, then the link is stat-ed, not the file it
2028 This is the same as the C<lstat(2)> system call.");
2030 ("statvfs", (RStruct ("statbuf", "statvfs"), [Pathname "path"], []), 54, [],
2031 [InitISOFS, Always, TestOutputStruct (
2032 [["statvfs"; "/"]], [CompareWithInt ("namemax", 255)])],
2033 "get file system statistics",
2035 Returns file system statistics for any mounted file system.
2036 C<path> should be a file or directory in the mounted file system
2037 (typically it is the mount point itself, but it doesn't need to be).
2039 This is the same as the C<statvfs(2)> system call.");
2041 ("tune2fs_l", (RHashtable "superblock", [Device "device"], []), 55, [],
2043 "get ext2/ext3/ext4 superblock details",
2045 This returns the contents of the ext2, ext3 or ext4 filesystem
2046 superblock on C<device>.
2048 It is the same as running C<tune2fs -l device>. See L<tune2fs(8)>
2049 manpage for more details. The list of fields returned isn't
2050 clearly defined, and depends on both the version of C<tune2fs>
2051 that libguestfs was built against, and the filesystem itself.");
2053 ("blockdev_setro", (RErr, [Device "device"], []), 56, [],
2054 [InitEmpty, Always, TestOutputTrue (
2055 [["blockdev_setro"; "/dev/sda"];
2056 ["blockdev_getro"; "/dev/sda"]])],
2057 "set block device to read-only",
2059 Sets the block device named C<device> to read-only.
2061 This uses the L<blockdev(8)> command.");
2063 ("blockdev_setrw", (RErr, [Device "device"], []), 57, [],
2064 [InitEmpty, Always, TestOutputFalse (
2065 [["blockdev_setrw"; "/dev/sda"];
2066 ["blockdev_getro"; "/dev/sda"]])],
2067 "set block device to read-write",
2069 Sets the block device named C<device> to read-write.
2071 This uses the L<blockdev(8)> command.");
2073 ("blockdev_getro", (RBool "ro", [Device "device"], []), 58, [],
2074 [InitEmpty, Always, TestOutputTrue (
2075 [["blockdev_setro"; "/dev/sda"];
2076 ["blockdev_getro"; "/dev/sda"]])],
2077 "is block device set to read-only",
2079 Returns a boolean indicating if the block device is read-only
2080 (true if read-only, false if not).
2082 This uses the L<blockdev(8)> command.");
2084 ("blockdev_getss", (RInt "sectorsize", [Device "device"], []), 59, [],
2085 [InitEmpty, Always, TestOutputInt (
2086 [["blockdev_getss"; "/dev/sda"]], 512)],
2087 "get sectorsize of block device",
2089 This returns the size of sectors on a block device.
2090 Usually 512, but can be larger for modern devices.
2092 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
2095 This uses the L<blockdev(8)> command.");
2097 ("blockdev_getbsz", (RInt "blocksize", [Device "device"], []), 60, [],
2098 [InitEmpty, Always, TestOutputInt (
2099 [["blockdev_getbsz"; "/dev/sda"]], 4096)],
2100 "get blocksize of block device",
2102 This returns the block size of a device.
2104 (Note this is different from both I<size in blocks> and
2105 I<filesystem block size>).
2107 This uses the L<blockdev(8)> command.");
2109 ("blockdev_setbsz", (RErr, [Device "device"; Int "blocksize"], []), 61, [],
2111 "set blocksize of block device",
2113 This sets the block size of a device.
2115 (Note this is different from both I<size in blocks> and
2116 I<filesystem block size>).
2118 This uses the L<blockdev(8)> command.");
2120 ("blockdev_getsz", (RInt64 "sizeinsectors", [Device "device"], []), 62, [],
2121 [InitEmpty, Always, TestOutputInt (
2122 [["blockdev_getsz"; "/dev/sda"]], 1024000)],
2123 "get total size of device in 512-byte sectors",
2125 This returns the size of the device in units of 512-byte sectors
2126 (even if the sectorsize isn't 512 bytes ... weird).
2128 See also C<guestfs_blockdev_getss> for the real sector size of
2129 the device, and C<guestfs_blockdev_getsize64> for the more
2130 useful I<size in bytes>.
2132 This uses the L<blockdev(8)> command.");
2134 ("blockdev_getsize64", (RInt64 "sizeinbytes", [Device "device"], []), 63, [],
2135 [InitEmpty, Always, TestOutputInt (
2136 [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
2137 "get total size of device in bytes",
2139 This returns the size of the device in bytes.
2141 See also C<guestfs_blockdev_getsz>.
2143 This uses the L<blockdev(8)> command.");
2145 ("blockdev_flushbufs", (RErr, [Device "device"], []), 64, [],
2146 [InitEmpty, Always, TestRun
2147 [["blockdev_flushbufs"; "/dev/sda"]]],
2148 "flush device buffers",
2150 This tells the kernel to flush internal buffers associated
2153 This uses the L<blockdev(8)> command.");
2155 ("blockdev_rereadpt", (RErr, [Device "device"], []), 65, [],
2156 [InitEmpty, Always, TestRun
2157 [["blockdev_rereadpt"; "/dev/sda"]]],
2158 "reread partition table",
2160 Reread the partition table on C<device>.
2162 This uses the L<blockdev(8)> command.");
2164 ("upload", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"], []), 66, [],
2165 [InitBasicFS, Always, TestOutput (
2166 (* Pick a file from cwd which isn't likely to change. *)
2167 [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
2168 ["checksum"; "md5"; "/COPYING.LIB"]],
2169 Digest.to_hex (Digest.file "COPYING.LIB"))],
2170 "upload a file from the local machine",
2172 Upload local file C<filename> to C<remotefilename> on the
2175 C<filename> can also be a named pipe.
2177 See also C<guestfs_download>.");
2179 ("download", (RErr, [Dev_or_Path "remotefilename"; FileOut "filename"], []), 67, [Progress],
2180 [InitBasicFS, Always, TestOutput (
2181 (* Pick a file from cwd which isn't likely to change. *)
2182 [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
2183 ["download"; "/COPYING.LIB"; "testdownload.tmp"];
2184 ["upload"; "testdownload.tmp"; "/upload"];
2185 ["checksum"; "md5"; "/upload"]],
2186 Digest.to_hex (Digest.file "COPYING.LIB"))],
2187 "download a file to the local machine",
2189 Download file C<remotefilename> and save it as C<filename>
2190 on the local machine.
2192 C<filename> can also be a named pipe.
2194 See also C<guestfs_upload>, C<guestfs_cat>.");
2196 ("checksum", (RString "checksum", [String "csumtype"; Pathname "path"], []), 68, [],
2197 [InitISOFS, Always, TestOutput (
2198 [["checksum"; "crc"; "/known-3"]], "2891671662");
2199 InitISOFS, Always, TestLastFail (
2200 [["checksum"; "crc"; "/notexists"]]);
2201 InitISOFS, Always, TestOutput (
2202 [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c");
2203 InitISOFS, Always, TestOutput (
2204 [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15");
2205 InitISOFS, Always, TestOutput (
2206 [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741");
2207 InitISOFS, Always, TestOutput (
2208 [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30");
2209 InitISOFS, Always, TestOutput (
2210 [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640");
2211 InitISOFS, Always, TestOutput (
2212 [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6");
2213 (* Test for RHBZ#579608, absolute symbolic links. *)
2214 InitISOFS, Always, TestOutput (
2215 [["checksum"; "sha512"; "/abssymlink"]], "5f57d0639bc95081c53afc63a449403883818edc64da48930ad6b1a4fb49be90404686877743fbcd7c99811f3def7df7bc22635c885c6a8cf79c806b43451c1a")],
2216 "compute MD5, SHAx or CRC checksum of file",
2218 This call computes the MD5, SHAx or CRC checksum of the
2221 The type of checksum to compute is given by the C<csumtype>
2222 parameter which must have one of the following values:
2228 Compute the cyclic redundancy check (CRC) specified by POSIX
2229 for the C<cksum> command.
2233 Compute the MD5 hash (using the C<md5sum> program).
2237 Compute the SHA1 hash (using the C<sha1sum> program).
2241 Compute the SHA224 hash (using the C<sha224sum> program).
2245 Compute the SHA256 hash (using the C<sha256sum> program).
2249 Compute the SHA384 hash (using the C<sha384sum> program).
2253 Compute the SHA512 hash (using the C<sha512sum> program).
2257 The checksum is returned as a printable string.
2259 To get the checksum for a device, use C<guestfs_checksum_device>.
2261 To get the checksums for many files, use C<guestfs_checksums_out>.");
2263 ("tar_in", (RErr, [FileIn "tarfile"; Pathname "directory"], []), 69, [],
2264 [InitBasicFS, Always, TestOutput (
2265 [["tar_in"; "../images/helloworld.tar"; "/"];
2266 ["cat"; "/hello"]], "hello\n")],
2267 "unpack tarfile to directory",
2269 This command uploads and unpacks local file C<tarfile> (an
2270 I<uncompressed> tar file) into C<directory>.
2272 To upload a compressed tarball, use C<guestfs_tgz_in>
2273 or C<guestfs_txz_in>.");
2275 ("tar_out", (RErr, [String "directory"; FileOut "tarfile"], []), 70, [],
2277 "pack directory into tarfile",
2279 This command packs the contents of C<directory> and downloads
2280 it to local file C<tarfile>.
2282 To download a compressed tarball, use C<guestfs_tgz_out>
2283 or C<guestfs_txz_out>.");
2285 ("tgz_in", (RErr, [FileIn "tarball"; Pathname "directory"], []), 71, [],
2286 [InitBasicFS, Always, TestOutput (
2287 [["tgz_in"; "../images/helloworld.tar.gz"; "/"];
2288 ["cat"; "/hello"]], "hello\n")],
2289 "unpack compressed tarball to directory",
2291 This command uploads and unpacks local file C<tarball> (a
2292 I<gzip compressed> tar file) into C<directory>.
2294 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
2296 ("tgz_out", (RErr, [Pathname "directory"; FileOut "tarball"], []), 72, [],
2298 "pack directory into compressed tarball",
2300 This command packs the contents of C<directory> and downloads
2301 it to local file C<tarball>.
2303 To download an uncompressed tarball, use C<guestfs_tar_out>.");
2305 ("mount_ro", (RErr, [Device "device"; String "mountpoint"], []), 73, [],
2306 [InitBasicFS, Always, TestLastFail (
2308 ["mount_ro"; "/dev/sda1"; "/"];
2309 ["touch"; "/new"]]);
2310 InitBasicFS, Always, TestOutput (
2311 [["write"; "/new"; "data"];
2313 ["mount_ro"; "/dev/sda1"; "/"];
2314 ["cat"; "/new"]], "data")],
2315 "mount a guest disk, read-only",
2317 This is the same as the C<guestfs_mount> command, but it
2318 mounts the filesystem with the read-only (I<-o ro>) flag.");
2320 ("mount_options", (RErr, [String "options"; Device "device"; String "mountpoint"], []), 74, [],
2322 "mount a guest disk with mount options",
2324 This is the same as the C<guestfs_mount> command, but it
2325 allows you to set the mount options as for the
2326 L<mount(8)> I<-o> flag.
2328 If the C<options> parameter is an empty string, then
2329 no options are passed (all options default to whatever
2330 the filesystem uses).");
2332 ("mount_vfs", (RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"], []), 75, [],
2334 "mount a guest disk with mount options and vfstype",
2336 This is the same as the C<guestfs_mount> command, but it
2337 allows you to set both the mount options and the vfstype
2338 as for the L<mount(8)> I<-o> and I<-t> flags.");
2340 ("debug", (RString "result", [String "subcmd"; StringList "extraargs"], []), 76, [NotInDocs],
2342 "debugging and internals",
2344 The C<guestfs_debug> command exposes some internals of
2345 C<guestfsd> (the guestfs daemon) that runs inside the
2348 There is no comprehensive help for this command. You have
2349 to look at the file C<daemon/debug.c> in the libguestfs source
2350 to find out what you can do.");
2352 ("lvremove", (RErr, [Device "device"], []), 77, [Optional "lvm2"],
2353 [InitEmpty, Always, TestOutputList (
2354 [["part_disk"; "/dev/sda"; "mbr"];
2355 ["pvcreate"; "/dev/sda1"];
2356 ["vgcreate"; "VG"; "/dev/sda1"];
2357 ["lvcreate"; "LV1"; "VG"; "50"];
2358 ["lvcreate"; "LV2"; "VG"; "50"];
2359 ["lvremove"; "/dev/VG/LV1"];
2360 ["lvs"]], ["/dev/VG/LV2"]);
2361 InitEmpty, Always, TestOutputList (
2362 [["part_disk"; "/dev/sda"; "mbr"];
2363 ["pvcreate"; "/dev/sda1"];
2364 ["vgcreate"; "VG"; "/dev/sda1"];
2365 ["lvcreate"; "LV1"; "VG"; "50"];
2366 ["lvcreate"; "LV2"; "VG"; "50"];
2367 ["lvremove"; "/dev/VG"];
2369 InitEmpty, Always, TestOutputList (
2370 [["part_disk"; "/dev/sda"; "mbr"];
2371 ["pvcreate"; "/dev/sda1"];
2372 ["vgcreate"; "VG"; "/dev/sda1"];
2373 ["lvcreate"; "LV1"; "VG"; "50"];
2374 ["lvcreate"; "LV2"; "VG"; "50"];
2375 ["lvremove"; "/dev/VG"];
2377 "remove an LVM logical volume",
2379 Remove an LVM logical volume C<device>, where C<device> is
2380 the path to the LV, such as C</dev/VG/LV>.
2382 You can also remove all LVs in a volume group by specifying
2383 the VG name, C</dev/VG>.");
2385 ("vgremove", (RErr, [String "vgname"], []), 78, [Optional "lvm2"],
2386 [InitEmpty, Always, TestOutputList (
2387 [["part_disk"; "/dev/sda"; "mbr"];
2388 ["pvcreate"; "/dev/sda1"];
2389 ["vgcreate"; "VG"; "/dev/sda1"];
2390 ["lvcreate"; "LV1"; "VG"; "50"];
2391 ["lvcreate"; "LV2"; "VG"; "50"];
2394 InitEmpty, Always, TestOutputList (
2395 [["part_disk"; "/dev/sda"; "mbr"];
2396 ["pvcreate"; "/dev/sda1"];
2397 ["vgcreate"; "VG"; "/dev/sda1"];
2398 ["lvcreate"; "LV1"; "VG"; "50"];
2399 ["lvcreate"; "LV2"; "VG"; "50"];
2402 "remove an LVM volume group",
2404 Remove an LVM volume group C<vgname>, (for example C<VG>).
2406 This also forcibly removes all logical volumes in the volume
2409 ("pvremove", (RErr, [Device "device"], []), 79, [Optional "lvm2"],
2410 [InitEmpty, Always, TestOutputListOfDevices (
2411 [["part_disk"; "/dev/sda"; "mbr"];
2412 ["pvcreate"; "/dev/sda1"];
2413 ["vgcreate"; "VG"; "/dev/sda1"];
2414 ["lvcreate"; "LV1"; "VG"; "50"];
2415 ["lvcreate"; "LV2"; "VG"; "50"];
2417 ["pvremove"; "/dev/sda1"];
2419 InitEmpty, Always, TestOutputListOfDevices (
2420 [["part_disk"; "/dev/sda"; "mbr"];
2421 ["pvcreate"; "/dev/sda1"];
2422 ["vgcreate"; "VG"; "/dev/sda1"];
2423 ["lvcreate"; "LV1"; "VG"; "50"];
2424 ["lvcreate"; "LV2"; "VG"; "50"];
2426 ["pvremove"; "/dev/sda1"];
2428 InitEmpty, Always, TestOutputListOfDevices (
2429 [["part_disk"; "/dev/sda"; "mbr"];
2430 ["pvcreate"; "/dev/sda1"];
2431 ["vgcreate"; "VG"; "/dev/sda1"];
2432 ["lvcreate"; "LV1"; "VG"; "50"];
2433 ["lvcreate"; "LV2"; "VG"; "50"];
2435 ["pvremove"; "/dev/sda1"];
2437 "remove an LVM physical volume",
2439 This wipes a physical volume C<device> so that LVM will no longer
2442 The implementation uses the C<pvremove> command which refuses to
2443 wipe physical volumes that contain any volume groups, so you have
2444 to remove those first.");
2446 ("set_e2label", (RErr, [Device "device"; String "label"], []), 80, [],
2447 [InitBasicFS, Always, TestOutput (
2448 [["set_e2label"; "/dev/sda1"; "testlabel"];
2449 ["get_e2label"; "/dev/sda1"]], "testlabel")],
2450 "set the ext2/3/4 filesystem label",
2452 This sets the ext2/3/4 filesystem label of the filesystem on
2453 C<device> to C<label>. Filesystem labels are limited to
2456 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
2457 to return the existing label on a filesystem.");
2459 ("get_e2label", (RString "label", [Device "device"], []), 81, [DeprecatedBy "vfs_label"],
2461 "get the ext2/3/4 filesystem label",
2463 This returns the ext2/3/4 filesystem label of the filesystem on
2466 ("set_e2uuid", (RErr, [Device "device"; String "uuid"], []), 82, [],
2467 (let uuid = uuidgen () in
2468 [InitBasicFS, Always, TestOutput (
2469 [["set_e2uuid"; "/dev/sda1"; uuid];
2470 ["get_e2uuid"; "/dev/sda1"]], uuid);
2471 InitBasicFS, Always, TestOutput (
2472 [["set_e2uuid"; "/dev/sda1"; "clear"];
2473 ["get_e2uuid"; "/dev/sda1"]], "");
2474 (* We can't predict what UUIDs will be, so just check the commands run. *)
2475 InitBasicFS, Always, TestRun (
2476 [["set_e2uuid"; "/dev/sda1"; "random"]]);
2477 InitBasicFS, Always, TestRun (
2478 [["set_e2uuid"; "/dev/sda1"; "time"]])]),
2479 "set the ext2/3/4 filesystem UUID",
2481 This sets the ext2/3/4 filesystem UUID of the filesystem on
2482 C<device> to C<uuid>. The format of the UUID and alternatives
2483 such as C<clear>, C<random> and C<time> are described in the
2484 L<tune2fs(8)> manpage.
2486 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
2487 to return the existing UUID of a filesystem.");
2489 ("get_e2uuid", (RString "uuid", [Device "device"], []), 83, [DeprecatedBy "vfs_uuid"],
2490 (* Regression test for RHBZ#597112. *)
2491 (let uuid = uuidgen () in
2492 [InitBasicFS, Always, TestOutput (
2493 [["mke2journal"; "1024"; "/dev/sdb"];
2494 ["set_e2uuid"; "/dev/sdb"; uuid];
2495 ["get_e2uuid"; "/dev/sdb"]], uuid)]),
2496 "get the ext2/3/4 filesystem UUID",
2498 This returns the ext2/3/4 filesystem UUID of the filesystem on
2501 ("fsck", (RInt "status", [String "fstype"; Device "device"], []), 84, [FishOutput FishOutputHexadecimal],
2502 [InitBasicFS, Always, TestOutputInt (
2503 [["umount"; "/dev/sda1"];
2504 ["fsck"; "ext2"; "/dev/sda1"]], 0);
2505 InitBasicFS, Always, TestOutputInt (
2506 [["umount"; "/dev/sda1"];
2507 ["zero"; "/dev/sda1"];
2508 ["fsck"; "ext2"; "/dev/sda1"]], 8)],
2509 "run the filesystem checker",
2511 This runs the filesystem checker (fsck) on C<device> which
2512 should have filesystem type C<fstype>.
2514 The returned integer is the status. See L<fsck(8)> for the
2515 list of status codes from C<fsck>.
2523 Multiple status codes can be summed together.
2527 A non-zero return code can mean \"success\", for example if
2528 errors have been corrected on the filesystem.
2532 Checking or repairing NTFS volumes is not supported
2537 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
2539 ("zero", (RErr, [Device "device"], []), 85, [Progress],
2540 [InitBasicFS, Always, TestOutput (
2541 [["umount"; "/dev/sda1"];
2542 ["zero"; "/dev/sda1"];
2543 ["file"; "/dev/sda1"]], "data")],
2544 "write zeroes to the device",
2546 This command writes zeroes over the first few blocks of C<device>.
2548 How many blocks are zeroed isn't specified (but it's I<not> enough
2549 to securely wipe the device). It should be sufficient to remove
2550 any partition tables, filesystem superblocks and so on.
2552 See also: C<guestfs_zero_device>, C<guestfs_scrub_device>.");
2554 ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [],
2556 * https://bugzilla.redhat.com/show_bug.cgi?id=484986
2557 * https://bugzilla.redhat.com/show_bug.cgi?id=479760
2559 [InitBasicFS, Always, TestOutputTrue (
2560 [["mkdir_p"; "/boot/grub"];
2561 ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
2562 ["grub_install"; "/"; "/dev/vda"];
2563 ["is_dir"; "/boot"]])],
2566 This command installs GRUB (the Grand Unified Bootloader) on
2567 C<device>, with the root directory being C<root>.
2569 Note: If grub-install reports the error
2570 \"No suitable drive was found in the generated device map.\"
2571 it may be that you need to create a C</boot/grub/device.map>
2572 file first that contains the mapping between grub device names
2573 and Linux device names. It is usually sufficient to create
2578 replacing C</dev/vda> with the name of the installation device.");
2580 ("cp", (RErr, [Pathname "src"; Pathname "dest"], []), 87, [],
2581 [InitBasicFS, Always, TestOutput (
2582 [["write"; "/old"; "file content"];
2583 ["cp"; "/old"; "/new"];
2584 ["cat"; "/new"]], "file content");
2585 InitBasicFS, Always, TestOutputTrue (
2586 [["write"; "/old"; "file content"];
2587 ["cp"; "/old"; "/new"];
2588 ["is_file"; "/old"]]);
2589 InitBasicFS, Always, TestOutput (
2590 [["write"; "/old"; "file content"];
2592 ["cp"; "/old"; "/dir/new"];
2593 ["cat"; "/dir/new"]], "file content")],
2596 This copies a file from C<src> to C<dest> where C<dest> is
2597 either a destination filename or destination directory.");
2599 ("cp_a", (RErr, [Pathname "src"; Pathname "dest"], []), 88, [],
2600 [InitBasicFS, Always, TestOutput (
2601 [["mkdir"; "/olddir"];
2602 ["mkdir"; "/newdir"];
2603 ["write"; "/olddir/file"; "file content"];
2604 ["cp_a"; "/olddir"; "/newdir"];
2605 ["cat"; "/newdir/olddir/file"]], "file content")],
2606 "copy a file or directory recursively",
2608 This copies a file or directory from C<src> to C<dest>
2609 recursively using the C<cp -a> command.");
2611 ("mv", (RErr, [Pathname "src"; Pathname "dest"], []), 89, [],
2612 [InitBasicFS, Always, TestOutput (
2613 [["write"; "/old"; "file content"];
2614 ["mv"; "/old"; "/new"];
2615 ["cat"; "/new"]], "file content");
2616 InitBasicFS, Always, TestOutputFalse (
2617 [["write"; "/old"; "file content"];
2618 ["mv"; "/old"; "/new"];
2619 ["is_file"; "/old"]])],
2622 This moves a file from C<src> to C<dest> where C<dest> is
2623 either a destination filename or destination directory.");
2625 ("drop_caches", (RErr, [Int "whattodrop"], []), 90, [],
2626 [InitEmpty, Always, TestRun (
2627 [["drop_caches"; "3"]])],
2628 "drop kernel page cache, dentries and inodes",
2630 This instructs the guest kernel to drop its page cache,
2631 and/or dentries and inode caches. The parameter C<whattodrop>
2632 tells the kernel what precisely to drop, see
2633 L<http://linux-mm.org/Drop_Caches>
2635 Setting C<whattodrop> to 3 should drop everything.
2637 This automatically calls L<sync(2)> before the operation,
2638 so that the maximum guest memory is freed.");
2640 ("dmesg", (RString "kmsgs", [], []), 91, [],
2641 [InitEmpty, Always, TestRun (
2643 "return kernel messages",
2645 This returns the kernel messages (C<dmesg> output) from
2646 the guest kernel. This is sometimes useful for extended
2647 debugging of problems.
2649 Another way to get the same information is to enable
2650 verbose messages with C<guestfs_set_verbose> or by setting
2651 the environment variable C<LIBGUESTFS_DEBUG=1> before
2652 running the program.");
2654 ("ping_daemon", (RErr, [], []), 92, [],
2655 [InitEmpty, Always, TestRun (
2656 [["ping_daemon"]])],
2657 "ping the guest daemon",
2659 This is a test probe into the guestfs daemon running inside
2660 the qemu subprocess. Calling this function checks that the
2661 daemon responds to the ping message, without affecting the daemon
2662 or attached block device(s) in any other way.");
2664 ("equal", (RBool "equality", [Pathname "file1"; Pathname "file2"], []), 93, [],
2665 [InitBasicFS, Always, TestOutputTrue (
2666 [["write"; "/file1"; "contents of a file"];
2667 ["cp"; "/file1"; "/file2"];
2668 ["equal"; "/file1"; "/file2"]]);
2669 InitBasicFS, Always, TestOutputFalse (
2670 [["write"; "/file1"; "contents of a file"];
2671 ["write"; "/file2"; "contents of another file"];
2672 ["equal"; "/file1"; "/file2"]]);
2673 InitBasicFS, Always, TestLastFail (
2674 [["equal"; "/file1"; "/file2"]])],
2675 "test if two files have equal contents",
2677 This compares the two files C<file1> and C<file2> and returns
2678 true if their content is exactly equal, or false otherwise.
2680 The external L<cmp(1)> program is used for the comparison.");
2682 ("strings", (RStringList "stringsout", [Pathname "path"], []), 94, [ProtocolLimitWarning],
2683 [InitISOFS, Always, TestOutputList (
2684 [["strings"; "/known-5"]], ["abcdefghi"; "jklmnopqr"]);
2685 InitISOFS, Always, TestOutputList (
2686 [["strings"; "/empty"]], []);
2687 (* Test for RHBZ#579608, absolute symbolic links. *)
2688 InitISOFS, Always, TestRun (
2689 [["strings"; "/abssymlink"]])],
2690 "print the printable strings in a file",
2692 This runs the L<strings(1)> command on a file and returns
2693 the list of printable strings found.");
2695 ("strings_e", (RStringList "stringsout", [String "encoding"; Pathname "path"], []), 95, [ProtocolLimitWarning],
2696 [InitISOFS, Always, TestOutputList (
2697 [["strings_e"; "b"; "/known-5"]], []);
2698 InitBasicFS, Always, TestOutputList (
2699 [["write"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"];
2700 ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2701 "print the printable strings in a file",
2703 This is like the C<guestfs_strings> command, but allows you to
2704 specify the encoding of strings that are looked for in
2705 the source file C<path>.
2707 Allowed encodings are:
2713 Single 7-bit-byte characters like ASCII and the ASCII-compatible
2714 parts of ISO-8859-X (this is what C<guestfs_strings> uses).
2718 Single 8-bit-byte characters.
2722 16-bit big endian strings such as those encoded in
2723 UTF-16BE or UCS-2BE.
2725 =item l (lower case letter L)
2727 16-bit little endian such as UTF-16LE and UCS-2LE.
2728 This is useful for examining binaries in Windows guests.
2732 32-bit big endian such as UCS-4BE.
2736 32-bit little endian such as UCS-4LE.
2740 The returned strings are transcoded to UTF-8.");
2742 ("hexdump", (RString "dump", [Pathname "path"], []), 96, [ProtocolLimitWarning],
2743 [InitISOFS, Always, TestOutput (
2744 [["hexdump"; "/known-4"]], "00000000 61 62 63 0a 64 65 66 0a 67 68 69 |abc.def.ghi|\n0000000b\n");
2745 (* Test for RHBZ#501888c2 regression which caused large hexdump
2746 * commands to segfault.
2748 InitISOFS, Always, TestRun (
2749 [["hexdump"; "/100krandom"]]);
2750 (* Test for RHBZ#579608, absolute symbolic links. *)
2751 InitISOFS, Always, TestRun (
2752 [["hexdump"; "/abssymlink"]])],
2753 "dump a file in hexadecimal",
2755 This runs C<hexdump -C> on the given C<path>. The result is
2756 the human-readable, canonical hex dump of the file.");
2758 ("zerofree", (RErr, [Device "device"], []), 97, [Optional "zerofree"],
2759 [InitNone, Always, TestOutput (
2760 [["part_disk"; "/dev/sda"; "mbr"];
2761 ["mkfs"; "ext3"; "/dev/sda1"];
2762 ["mount_options"; ""; "/dev/sda1"; "/"];
2763 ["write"; "/new"; "test file"];
2764 ["umount"; "/dev/sda1"];
2765 ["zerofree"; "/dev/sda1"];
2766 ["mount_options"; ""; "/dev/sda1"; "/"];
2767 ["cat"; "/new"]], "test file")],
2768 "zero unused inodes and disk blocks on ext2/3 filesystem",
2770 This runs the I<zerofree> program on C<device>. This program
2771 claims to zero unused inodes and disk blocks on an ext2/3
2772 filesystem, thus making it possible to compress the filesystem
2775 You should B<not> run this program if the filesystem is
2778 It is possible that using this program can damage the filesystem
2779 or data on the filesystem.");
2781 ("pvresize", (RErr, [Device "device"], []), 98, [Optional "lvm2"],
2783 "resize an LVM physical volume",
2785 This resizes (expands or shrinks) an existing LVM physical
2786 volume to match the new size of the underlying device.");
2788 ("sfdisk_N", (RErr, [Device "device"; Int "partnum";
2789 Int "cyls"; Int "heads"; Int "sectors";
2790 String "line"], []), 99, [DangerWillRobinson],
2792 "modify a single partition on a block device",
2794 This runs L<sfdisk(8)> option to modify just the single
2795 partition C<n> (note: C<n> counts from 1).
2797 For other parameters, see C<guestfs_sfdisk>. You should usually
2798 pass C<0> for the cyls/heads/sectors parameters.
2800 See also: C<guestfs_part_add>");
2802 ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [],
2804 "display the partition table",
2806 This displays the partition table on C<device>, in the
2807 human-readable output of the L<sfdisk(8)> command. It is
2808 not intended to be parsed.
2810 See also: C<guestfs_part_list>");
2812 ("sfdisk_kernel_geometry", (RString "partitions", [Device "device"], []), 101, [],
2814 "display the kernel geometry",
2816 This displays the kernel's idea of the geometry of C<device>.
2818 The result is in human-readable format, and not designed to
2821 ("sfdisk_disk_geometry", (RString "partitions", [Device "device"], []), 102, [],
2823 "display the disk geometry from the partition table",
2825 This displays the disk geometry of C<device> read from the
2826 partition table. Especially in the case where the underlying
2827 block device has been resized, this can be different from the
2828 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2830 The result is in human-readable format, and not designed to
2833 ("vg_activate_all", (RErr, [Bool "activate"], []), 103, [Optional "lvm2"],
2835 "activate or deactivate all volume groups",
2837 This command activates or (if C<activate> is false) deactivates
2838 all logical volumes in all volume groups.
2839 If activated, then they are made known to the
2840 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2841 then those devices disappear.
2843 This command is the same as running C<vgchange -a y|n>");
2845 ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"], []), 104, [Optional "lvm2"],
2847 "activate or deactivate some volume groups",
2849 This command activates or (if C<activate> is false) deactivates
2850 all logical volumes in the listed volume groups C<volgroups>.
2851 If activated, then they are made known to the
2852 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2853 then those devices disappear.
2855 This command is the same as running C<vgchange -a y|n volgroups...>
2857 Note that if C<volgroups> is an empty list then B<all> volume groups
2858 are activated or deactivated.");
2860 ("lvresize", (RErr, [Device "device"; Int "mbytes"], []), 105, [Optional "lvm2"],
2861 [InitNone, Always, TestOutput (
2862 [["part_disk"; "/dev/sda"; "mbr"];
2863 ["pvcreate"; "/dev/sda1"];
2864 ["vgcreate"; "VG"; "/dev/sda1"];
2865 ["lvcreate"; "LV"; "VG"; "10"];
2866 ["mkfs"; "ext2"; "/dev/VG/LV"];
2867 ["mount_options"; ""; "/dev/VG/LV"; "/"];
2868 ["write"; "/new"; "test content"];
2870 ["lvresize"; "/dev/VG/LV"; "20"];
2871 ["e2fsck_f"; "/dev/VG/LV"];
2872 ["resize2fs"; "/dev/VG/LV"];
2873 ["mount_options"; ""; "/dev/VG/LV"; "/"];
2874 ["cat"; "/new"]], "test content");
2875 InitNone, Always, TestRun (
2876 (* Make an LV smaller to test RHBZ#587484. *)
2877 [["part_disk"; "/dev/sda"; "mbr"];
2878 ["pvcreate"; "/dev/sda1"];
2879 ["vgcreate"; "VG"; "/dev/sda1"];
2880 ["lvcreate"; "LV"; "VG"; "20"];
2881 ["lvresize"; "/dev/VG/LV"; "10"]])],
2882 "resize an LVM logical volume",
2884 This resizes (expands or shrinks) an existing LVM logical
2885 volume to C<mbytes>. When reducing, data in the reduced part
2888 ("resize2fs", (RErr, [Device "device"], []), 106, [],
2889 [], (* lvresize tests this *)
2890 "resize an ext2, ext3 or ext4 filesystem",
2892 This resizes an ext2, ext3 or ext4 filesystem to match the size of
2893 the underlying device.
2895 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2896 on the C<device> before calling this command. For unknown reasons
2897 C<resize2fs> sometimes gives an error about this and sometimes not.
2898 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2899 calling this function.");
2901 ("find", (RStringList "names", [Pathname "directory"], []), 107, [ProtocolLimitWarning],
2902 [InitBasicFS, Always, TestOutputList (
2903 [["find"; "/"]], ["lost+found"]);
2904 InitBasicFS, Always, TestOutputList (
2908 ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2909 InitBasicFS, Always, TestOutputList (
2910 [["mkdir_p"; "/a/b/c"];
2911 ["touch"; "/a/b/c/d"];
2912 ["find"; "/a/b/"]], ["c"; "c/d"])],
2913 "find all files and directories",
2915 This command lists out all files and directories, recursively,
2916 starting at C<directory>. It is essentially equivalent to
2917 running the shell command C<find directory -print> but some
2918 post-processing happens on the output, described below.
2920 This returns a list of strings I<without any prefix>. Thus
2921 if the directory structure was:
2927 then the returned list from C<guestfs_find> C</tmp> would be
2935 If C<directory> is not a directory, then this command returns
2938 The returned list is sorted.
2940 See also C<guestfs_find0>.");
2942 ("e2fsck_f", (RErr, [Device "device"], []), 108, [],
2943 [], (* lvresize tests this *)
2944 "check an ext2/ext3 filesystem",
2946 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2947 filesystem checker on C<device>, noninteractively (C<-p>),
2948 even if the filesystem appears to be clean (C<-f>).
2950 This command is only needed because of C<guestfs_resize2fs>
2951 (q.v.). Normally you should use C<guestfs_fsck>.");
2953 ("sleep", (RErr, [Int "secs"], []), 109, [],
2954 [InitNone, Always, TestRun (
2956 "sleep for some seconds",
2958 Sleep for C<secs> seconds.");
2960 ("ntfs_3g_probe", (RInt "status", [Bool "rw"; Device "device"], []), 110, [Optional "ntfs3g"],
2961 [InitNone, Always, TestOutputInt (
2962 [["part_disk"; "/dev/sda"; "mbr"];
2963 ["mkfs"; "ntfs"; "/dev/sda1"];
2964 ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2965 InitNone, Always, TestOutputInt (
2966 [["part_disk"; "/dev/sda"; "mbr"];
2967 ["mkfs"; "ext2"; "/dev/sda1"];
2968 ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2969 "probe NTFS volume",
2971 This command runs the L<ntfs-3g.probe(8)> command which probes
2972 an NTFS C<device> for mountability. (Not all NTFS volumes can
2973 be mounted read-write, and some cannot be mounted at all).
2975 C<rw> is a boolean flag. Set it to true if you want to test
2976 if the volume can be mounted read-write. Set it to false if
2977 you want to test if the volume can be mounted read-only.
2979 The return value is an integer which C<0> if the operation
2980 would succeed, or some non-zero value documented in the
2981 L<ntfs-3g.probe(8)> manual page.");
2983 ("sh", (RString "output", [String "command"], []), 111, [],
2984 [], (* XXX needs tests *)
2985 "run a command via the shell",
2987 This call runs a command from the guest filesystem via the
2990 This is like C<guestfs_command>, but passes the command to:
2992 /bin/sh -c \"command\"
2994 Depending on the guest's shell, this usually results in
2995 wildcards being expanded, shell expressions being interpolated
2998 All the provisos about C<guestfs_command> apply to this call.");
3000 ("sh_lines", (RStringList "lines", [String "command"], []), 112, [],
3001 [], (* XXX needs tests *)
3002 "run a command via the shell returning lines",
3004 This is the same as C<guestfs_sh>, but splits the result
3005 into a list of lines.
3007 See also: C<guestfs_command_lines>");
3009 ("glob_expand", (RStringList "paths", [Pathname "pattern"], []), 113, [],
3010 (* Use Pathname here, and hence ABS_PATH (pattern,... in generated
3011 * code in stubs.c, since all valid glob patterns must start with "/".
3012 * There is no concept of "cwd" in libguestfs, hence no "."-relative names.
3014 [InitBasicFS, Always, TestOutputList (
3015 [["mkdir_p"; "/a/b/c"];
3016 ["touch"; "/a/b/c/d"];
3017 ["touch"; "/a/b/c/e"];
3018 ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
3019 InitBasicFS, Always, TestOutputList (
3020 [["mkdir_p"; "/a/b/c"];
3021 ["touch"; "/a/b/c/d"];
3022 ["touch"; "/a/b/c/e"];
3023 ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
3024 InitBasicFS, Always, TestOutputList (
3025 [["mkdir_p"; "/a/b/c"];
3026 ["touch"; "/a/b/c/d"];
3027 ["touch"; "/a/b/c/e"];
3028 ["glob_expand"; "/a/*/x/*"]], [])],
3029 "expand a wildcard path",
3031 This command searches for all the pathnames matching
3032 C<pattern> according to the wildcard expansion rules
3035 If no paths match, then this returns an empty list
3036 (note: not an error).
3038 It is just a wrapper around the C L<glob(3)> function
3039 with flags C<GLOB_MARK|GLOB_BRACE>.
3040 See that manual page for more details.");
3042 ("scrub_device", (RErr, [Device "device"], []), 114, [DangerWillRobinson; Optional "scrub"],
3043 [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *)
3044 [["scrub_device"; "/dev/sdc"]])],
3045 "scrub (securely wipe) a device",
3047 This command writes patterns over C<device> to make data retrieval
3050 It is an interface to the L<scrub(1)> program. See that
3051 manual page for more details.");
3053 ("scrub_file", (RErr, [Pathname "file"], []), 115, [Optional "scrub"],
3054 [InitBasicFS, Always, TestRun (
3055 [["write"; "/file"; "content"];
3056 ["scrub_file"; "/file"]])],
3057 "scrub (securely wipe) a file",
3059 This command writes patterns over a file to make data retrieval
3062 The file is I<removed> after scrubbing.
3064 It is an interface to the L<scrub(1)> program. See that
3065 manual page for more details.");
3067 ("scrub_freespace", (RErr, [Pathname "dir"], []), 116, [Optional "scrub"],
3068 [], (* XXX needs testing *)
3069 "scrub (securely wipe) free space",
3071 This command creates the directory C<dir> and then fills it
3072 with files until the filesystem is full, and scrubs the files
3073 as for C<guestfs_scrub_file>, and deletes them.
3074 The intention is to scrub any free space on the partition
3077 It is an interface to the L<scrub(1)> program. See that
3078 manual page for more details.");
3080 ("mkdtemp", (RString "dir", [Pathname "template"], []), 117, [],
3081 [InitBasicFS, Always, TestRun (
3083 ["mkdtemp"; "/tmp/tmpXXXXXX"]])],
3084 "create a temporary directory",
3086 This command creates a temporary directory. The
3087 C<template> parameter should be a full pathname for the
3088 temporary directory name with the final six characters being
3091 For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
3092 the second one being suitable for Windows filesystems.
3094 The name of the temporary directory that was created
3097 The temporary directory is created with mode 0700
3098 and is owned by root.
3100 The caller is responsible for deleting the temporary
3101 directory and its contents after use.
3103 See also: L<mkdtemp(3)>");
3105 ("wc_l", (RInt "lines", [Pathname "path"], []), 118, [],
3106 [InitISOFS, Always, TestOutputInt (
3107 [["wc_l"; "/10klines"]], 10000);
3108 (* Test for RHBZ#579608, absolute symbolic links. *)
3109 InitISOFS, Always, TestOutputInt (
3110 [["wc_l"; "/abssymlink"]], 10000)],
3111 "count lines in a file",
3113 This command counts the lines in a file, using the
3114 C<wc -l> external command.");
3116 ("wc_w", (RInt "words", [Pathname "path"], []), 119, [],
3117 [InitISOFS, Always, TestOutputInt (
3118 [["wc_w"; "/10klines"]], 10000)],
3119 "count words in a file",
3121 This command counts the words in a file, using the
3122 C<wc -w> external command.");
3124 ("wc_c", (RInt "chars", [Pathname "path"], []), 120, [],
3125 [InitISOFS, Always, TestOutputInt (
3126 [["wc_c"; "/100kallspaces"]], 102400)],
3127 "count characters in a file",
3129 This command counts the characters in a file, using the
3130 C<wc -c> external command.");
3132 ("head", (RStringList "lines", [Pathname "path"], []), 121, [ProtocolLimitWarning],
3133 [InitISOFS, Always, TestOutputList (
3134 [["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"]);
3135 (* Test for RHBZ#579608, absolute symbolic links. *)
3136 InitISOFS, Always, TestOutputList (
3137 [["head"; "/abssymlink"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])],
3138 "return first 10 lines of a file",
3140 This command returns up to the first 10 lines of a file as
3141 a list of strings.");
3143 ("head_n", (RStringList "lines", [Int "nrlines"; Pathname "path"], []), 122, [ProtocolLimitWarning],
3144 [InitISOFS, Always, TestOutputList (
3145 [["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3146 InitISOFS, Always, TestOutputList (
3147 [["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3148 InitISOFS, Always, TestOutputList (
3149 [["head_n"; "0"; "/10klines"]], [])],
3150 "return first N lines of a file",
3152 If the parameter C<nrlines> is a positive number, this returns the first
3153 C<nrlines> lines of the file C<path>.
3155 If the parameter C<nrlines> is a negative number, this returns lines
3156 from the file C<path>, excluding the last C<nrlines> lines.
3158 If the parameter C<nrlines> is zero, this returns an empty list.");
3160 ("tail", (RStringList "lines", [Pathname "path"], []), 123, [ProtocolLimitWarning],
3161 [InitISOFS, Always, TestOutputList (
3162 [["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])],
3163 "return last 10 lines of a file",
3165 This command returns up to the last 10 lines of a file as
3166 a list of strings.");
3168 ("tail_n", (RStringList "lines", [Int "nrlines"; Pathname "path"], []), 124, [ProtocolLimitWarning],
3169 [InitISOFS, Always, TestOutputList (
3170 [["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
3171 InitISOFS, Always, TestOutputList (
3172 [["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
3173 InitISOFS, Always, TestOutputList (
3174 [["tail_n"; "0"; "/10klines"]], [])],
3175 "return last N lines of a file",
3177 If the parameter C<nrlines> is a positive number, this returns the last
3178 C<nrlines> lines of the file C<path>.
3180 If the parameter C<nrlines> is a negative number, this returns lines
3181 from the file C<path>, starting with the C<-nrlines>th line.
3183 If the parameter C<nrlines> is zero, this returns an empty list.");
3185 ("df", (RString "output", [], []), 125, [],
3186 [], (* XXX Tricky to test because it depends on the exact format
3187 * of the 'df' command and other imponderables.
3189 "report file system disk space usage",
3191 This command runs the C<df> command to report disk space used.
3193 This command is mostly useful for interactive sessions. It
3194 is I<not> intended that you try to parse the output string.
3195 Use C<statvfs> from programs.");
3197 ("df_h", (RString "output", [], []), 126, [],
3198 [], (* XXX Tricky to test because it depends on the exact format
3199 * of the 'df' command and other imponderables.
3201 "report file system disk space usage (human readable)",
3203 This command runs the C<df -h> command to report disk space used
3204 in human-readable format.
3206 This command is mostly useful for interactive sessions. It
3207 is I<not> intended that you try to parse the output string.
3208 Use C<statvfs> from programs.");
3210 ("du", (RInt64 "sizekb", [Pathname "path"], []), 127, [],
3211 [InitISOFS, Always, TestOutputInt (
3212 [["du"; "/directory"]], 2 (* ISO fs blocksize is 2K *))],
3213 "estimate file space usage",
3215 This command runs the C<du -s> command to estimate file space
3218 C<path> can be a file or a directory. If C<path> is a directory
3219 then the estimate includes the contents of the directory and all
3220 subdirectories (recursively).
3222 The result is the estimated size in I<kilobytes>
3223 (ie. units of 1024 bytes).");
3225 ("initrd_list", (RStringList "filenames", [Pathname "path"], []), 128, [],
3226 [InitISOFS, Always, TestOutputList (
3227 [["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3";"known-4"; "known-5"])],
3228 "list files in an initrd",
3230 This command lists out files contained in an initrd.
3232 The files are listed without any initial C</> character. The
3233 files are listed in the order they appear (not necessarily
3234 alphabetical). Directory names are listed as separate items.
3236 Old Linux kernels (2.4 and earlier) used a compressed ext2
3237 filesystem as initrd. We I<only> support the newer initramfs
3238 format (compressed cpio files).");
3240 ("mount_loop", (RErr, [Pathname "file"; Pathname "mountpoint"], []), 129, [],
3242 "mount a file using the loop device",
3244 This command lets you mount C<file> (a filesystem image
3245 in a file) on a mount point. It is entirely equivalent to
3246 the command C<mount -o loop file mountpoint>.");
3248 ("mkswap", (RErr, [Device "device"], []), 130, [],
3249 [InitEmpty, Always, TestRun (
3250 [["part_disk"; "/dev/sda"; "mbr"];
3251 ["mkswap"; "/dev/sda1"]])],
3252 "create a swap partition",
3254 Create a swap partition on C<device>.");
3256 ("mkswap_L", (RErr, [String "label"; Device "device"], []), 131, [],
3257 [InitEmpty, Always, TestRun (
3258 [["part_disk"; "/dev/sda"; "mbr"];
3259 ["mkswap_L"; "hello"; "/dev/sda1"]])],
3260 "create a swap partition with a label",
3262 Create a swap partition on C<device> with label C<label>.
3264 Note that you cannot attach a swap label to a block device
3265 (eg. C</dev/sda>), just to a partition. This appears to be
3266 a limitation of the kernel or swap tools.");
3268 ("mkswap_U", (RErr, [String "uuid"; Device "device"], []), 132, [Optional "linuxfsuuid"],
3269 (let uuid = uuidgen () in
3270 [InitEmpty, Always, TestRun (
3271 [["part_disk"; "/dev/sda"; "mbr"];
3272 ["mkswap_U"; uuid; "/dev/sda1"]])]),
3273 "create a swap partition with an explicit UUID",
3275 Create a swap partition on C<device> with UUID C<uuid>.");
3277 ("mknod", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []), 133, [Optional "mknod"],
3278 [InitBasicFS, Always, TestOutputStruct (
3279 [["mknod"; "0o10777"; "0"; "0"; "/node"];
3280 (* NB: default umask 022 means 0777 -> 0755 in these tests *)
3281 ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)]);
3282 InitBasicFS, Always, TestOutputStruct (
3283 [["mknod"; "0o60777"; "66"; "99"; "/node"];
3284 ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
3285 "make block, character or FIFO devices",
3287 This call creates block or character special devices, or
3288 named pipes (FIFOs).
3290 The C<mode> parameter should be the mode, using the standard
3291 constants. C<devmajor> and C<devminor> are the
3292 device major and minor numbers, only used when creating block
3293 and character special devices.
3295 Note that, just like L<mknod(2)>, the mode must be bitwise
3296 OR'd with S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call
3297 just creates a regular file). These constants are
3298 available in the standard Linux header files, or you can use
3299 C<guestfs_mknod_b>, C<guestfs_mknod_c> or C<guestfs_mkfifo>
3300 which are wrappers around this command which bitwise OR
3301 in the appropriate constant for you.
3303 The mode actually set is affected by the umask.");
3305 ("mkfifo", (RErr, [Int "mode"; Pathname "path"], []), 134, [Optional "mknod"],
3306 [InitBasicFS, Always, TestOutputStruct (
3307 [["mkfifo"; "0o777"; "/node"];
3308 ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)])],
3309 "make FIFO (named pipe)",
3311 This call creates a FIFO (named pipe) called C<path> with
3312 mode C<mode>. It is just a convenient wrapper around
3315 The mode actually set is affected by the umask.");
3317 ("mknod_b", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []), 135, [Optional "mknod"],
3318 [InitBasicFS, Always, TestOutputStruct (
3319 [["mknod_b"; "0o777"; "99"; "66"; "/node"];
3320 ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
3321 "make block device node",
3323 This call creates a block device node called C<path> with
3324 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3325 It is just a convenient wrapper around C<guestfs_mknod>.
3327 The mode actually set is affected by the umask.");
3329 ("mknod_c", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []), 136, [Optional "mknod"],
3330 [InitBasicFS, Always, TestOutputStruct (
3331 [["mknod_c"; "0o777"; "99"; "66"; "/node"];
3332 ["stat"; "/node"]], [CompareWithInt ("mode", 0o20755)])],
3333 "make char device node",
3335 This call creates a char device node called C<path> with
3336 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3337 It is just a convenient wrapper around C<guestfs_mknod>.
3339 The mode actually set is affected by the umask.");
3341 ("umask", (RInt "oldmask", [Int "mask"], []), 137, [FishOutput FishOutputOctal],
3342 [InitEmpty, Always, TestOutputInt (
3343 [["umask"; "0o22"]], 0o22)],
3344 "set file mode creation mask (umask)",
3346 This function sets the mask used for creating new files and
3347 device nodes to C<mask & 0777>.
3349 Typical umask values would be C<022> which creates new files
3350 with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and
3351 C<002> which creates new files with permissions like
3352 \"-rw-rw-r--\" or \"-rwxrwxr-x\".
3354 The default umask is C<022>. This is important because it
3355 means that directories and device nodes will be created with
3356 C<0644> or C<0755> mode even if you specify C<0777>.
3358 See also C<guestfs_get_umask>,
3359 L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
3361 This call returns the previous umask.");
3363 ("readdir", (RStructList ("entries", "dirent"), [Pathname "dir"], []), 138, [],
3365 "read directories entries",
3367 This returns the list of directory entries in directory C<dir>.
3369 All entries in the directory are returned, including C<.> and
3370 C<..>. The entries are I<not> sorted, but returned in the same
3371 order as the underlying filesystem.
3373 Also this call returns basic file type information about each
3374 file. The C<ftyp> field will contain one of the following characters:
3412 The L<readdir(3)> call returned a C<d_type> field with an
3417 This function is primarily intended for use by programs. To
3418 get a simple list of names, use C<guestfs_ls>. To get a printable
3419 directory for human consumption, use C<guestfs_ll>.");
3421 ("sfdiskM", (RErr, [Device "device"; StringList "lines"], []), 139, [DangerWillRobinson],
3423 "create partitions on a block device",
3425 This is a simplified interface to the C<guestfs_sfdisk>
3426 command, where partition sizes are specified in megabytes
3427 only (rounded to the nearest cylinder) and you don't need
3428 to specify the cyls, heads and sectors parameters which
3429 were rarely if ever used anyway.
3431 See also: C<guestfs_sfdisk>, the L<sfdisk(8)> manpage
3432 and C<guestfs_part_disk>");
3434 ("zfile", (RString "description", [String "meth"; Pathname "path"], []), 140, [DeprecatedBy "file"],
3436 "determine file type inside a compressed file",
3438 This command runs C<file> after first decompressing C<path>
3441 C<method> must be one of C<gzip>, C<compress> or C<bzip2>.
3443 Since 1.0.63, use C<guestfs_file> instead which can now
3444 process compressed files.");
3446 ("getxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"], []), 141, [Optional "linuxxattrs"],
3448 "list extended attributes of a file or directory",
3450 This call lists the extended attributes of the file or directory
3453 At the system call level, this is a combination of the
3454 L<listxattr(2)> and L<getxattr(2)> calls.
3456 See also: C<guestfs_lgetxattrs>, L<attr(5)>.");
3458 ("lgetxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"], []), 142, [Optional "linuxxattrs"],
3460 "list extended attributes of a file or directory",
3462 This is the same as C<guestfs_getxattrs>, but if C<path>
3463 is a symbolic link, then it returns the extended attributes
3464 of the link itself.");
3466 ("setxattr", (RErr, [String "xattr";
3467 String "val"; Int "vallen"; (* will be BufferIn *)
3468 Pathname "path"], []), 143, [Optional "linuxxattrs"],
3470 "set extended attribute of a file or directory",
3472 This call sets the extended attribute named C<xattr>
3473 of the file C<path> to the value C<val> (of length C<vallen>).
3474 The value is arbitrary 8 bit data.
3476 See also: C<guestfs_lsetxattr>, L<attr(5)>.");
3478 ("lsetxattr", (RErr, [String "xattr";
3479 String "val"; Int "vallen"; (* will be BufferIn *)
3480 Pathname "path"], []), 144, [Optional "linuxxattrs"],
3482 "set extended attribute of a file or directory",
3484 This is the same as C<guestfs_setxattr>, but if C<path>
3485 is a symbolic link, then it sets an extended attribute
3486 of the link itself.");
3488 ("removexattr", (RErr, [String "xattr"; Pathname "path"], []), 145, [Optional "linuxxattrs"],
3490 "remove extended attribute of a file or directory",
3492 This call removes the extended attribute named C<xattr>
3493 of the file C<path>.
3495 See also: C<guestfs_lremovexattr>, L<attr(5)>.");
3497 ("lremovexattr", (RErr, [String "xattr"; Pathname "path"], []), 146, [Optional "linuxxattrs"],
3499 "remove extended attribute of a file or directory",
3501 This is the same as C<guestfs_removexattr>, but if C<path>
3502 is a symbolic link, then it removes an extended attribute
3503 of the link itself.");
3505 ("mountpoints", (RHashtable "mps", [], []), 147, [],
3509 This call is similar to C<guestfs_mounts>. That call returns
3510 a list of devices. This one returns a hash table (map) of
3511 device name to directory where the device is mounted.");
3513 ("mkmountpoint", (RErr, [String "exemptpath"], []), 148, [],
3514 (* This is a special case: while you would expect a parameter
3515 * of type "Pathname", that doesn't work, because it implies
3516 * NEED_ROOT in the generated calling code in stubs.c, and
3517 * this function cannot use NEED_ROOT.
3520 "create a mountpoint",
3522 C<guestfs_mkmountpoint> and C<guestfs_rmmountpoint> are
3523 specialized calls that can be used to create extra mountpoints
3524 before mounting the first filesystem.
3526 These calls are I<only> necessary in some very limited circumstances,
3527 mainly the case where you want to mount a mix of unrelated and/or
3528 read-only filesystems together.
3530 For example, live CDs often contain a \"Russian doll\" nest of
3531 filesystems, an ISO outer layer, with a squashfs image inside, with
3532 an ext2/3 image inside that. You can unpack this as follows
3535 add-ro Fedora-11-i686-Live.iso
3539 mkmountpoint /ext3fs
3541 mount-loop /cd/LiveOS/squashfs.img /sqsh
3542 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
3544 The inner filesystem is now unpacked under the /ext3fs mountpoint.
3546 C<guestfs_mkmountpoint> is not compatible with C<guestfs_umount_all>.
3547 You may get unexpected errors if you try to mix these calls. It is
3548 safest to manually unmount filesystems and remove mountpoints after use.
3550 C<guestfs_umount_all> unmounts filesystems by sorting the paths
3551 longest first, so for this to work for manual mountpoints, you
3552 must ensure that the innermost mountpoints have the longest
3553 pathnames, as in the example code above.
3555 For more details see L<https://bugzilla.redhat.com/show_bug.cgi?id=599503>
3557 Autosync [see C<guestfs_set_autosync>, this is set by default on
3558 handles] means that C<guestfs_umount_all> is called when the handle
3559 is closed which can also trigger these issues.");
3561 ("rmmountpoint", (RErr, [String "exemptpath"], []), 149, [],
3563 "remove a mountpoint",
3565 This calls removes a mountpoint that was previously created
3566 with C<guestfs_mkmountpoint>. See C<guestfs_mkmountpoint>
3567 for full details.");
3569 ("read_file", (RBufferOut "content", [Pathname "path"], []), 150, [ProtocolLimitWarning],
3570 [InitISOFS, Always, TestOutputBuffer (
3571 [["read_file"; "/known-4"]], "abc\ndef\nghi");
3572 (* Test various near large, large and too large files (RHBZ#589039). *)
3573 InitBasicFS, Always, TestLastFail (
3575 ["truncate_size"; "/a"; "4194303"]; (* GUESTFS_MESSAGE_MAX - 1 *)
3576 ["read_file"; "/a"]]);
3577 InitBasicFS, Always, TestLastFail (
3579 ["truncate_size"; "/a"; "4194304"]; (* GUESTFS_MESSAGE_MAX *)
3580 ["read_file"; "/a"]]);
3581 InitBasicFS, Always, TestLastFail (
3583 ["truncate_size"; "/a"; "41943040"]; (* GUESTFS_MESSAGE_MAX * 10 *)
3584 ["read_file"; "/a"]])],
3587 This calls returns the contents of the file C<path> as a
3590 Unlike C<guestfs_cat>, this function can correctly
3591 handle files that contain embedded ASCII NUL characters.
3592 However unlike C<guestfs_download>, this function is limited
3593 in the total size of file that can be handled.");
3595 ("grep", (RStringList "lines", [String "regex"; Pathname "path"], []), 151, [ProtocolLimitWarning],
3596 [InitISOFS, Always, TestOutputList (
3597 [["grep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"]);
3598 InitISOFS, Always, TestOutputList (
3599 [["grep"; "nomatch"; "/test-grep.txt"]], []);
3600 (* Test for RHBZ#579608, absolute symbolic links. *)
3601 InitISOFS, Always, TestOutputList (
3602 [["grep"; "nomatch"; "/abssymlink"]], [])],
3603 "return lines matching a pattern",
3605 This calls the external C<grep> program and returns the
3608 ("egrep", (RStringList "lines", [String "regex"; Pathname "path"], []), 152, [ProtocolLimitWarning],
3609 [InitISOFS, Always, TestOutputList (
3610 [["egrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3611 "return lines matching a pattern",
3613 This calls the external C<egrep> program and returns the
3616 ("fgrep", (RStringList "lines", [String "pattern"; Pathname "path"], []), 153, [ProtocolLimitWarning],
3617 [InitISOFS, Always, TestOutputList (
3618 [["fgrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3619 "return lines matching a pattern",
3621 This calls the external C<fgrep> program and returns the
3624 ("grepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 154, [ProtocolLimitWarning],
3625 [InitISOFS, Always, TestOutputList (
3626 [["grepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3627 "return lines matching a pattern",
3629 This calls the external C<grep -i> program and returns the
3632 ("egrepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 155, [ProtocolLimitWarning],
3633 [InitISOFS, Always, TestOutputList (
3634 [["egrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3635 "return lines matching a pattern",
3637 This calls the external C<egrep -i> program and returns the
3640 ("fgrepi", (RStringList "lines", [String "pattern"; Pathname "path"], []), 156, [ProtocolLimitWarning],
3641 [InitISOFS, Always, TestOutputList (
3642 [["fgrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3643 "return lines matching a pattern",
3645 This calls the external C<fgrep -i> program and returns the
3648 ("zgrep", (RStringList "lines", [String "regex"; Pathname "path"], []), 157, [ProtocolLimitWarning],
3649 [InitISOFS, Always, TestOutputList (
3650 [["zgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3651 "return lines matching a pattern",
3653 This calls the external C<zgrep> program and returns the
3656 ("zegrep", (RStringList "lines", [String "regex"; Pathname "path"], []), 158, [ProtocolLimitWarning],
3657 [InitISOFS, Always, TestOutputList (
3658 [["zegrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3659 "return lines matching a pattern",
3661 This calls the external C<zegrep> program and returns the
3664 ("zfgrep", (RStringList "lines", [String "pattern"; Pathname "path"], []), 159, [ProtocolLimitWarning],
3665 [InitISOFS, Always, TestOutputList (
3666 [["zfgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3667 "return lines matching a pattern",
3669 This calls the external C<zfgrep> program and returns the
3672 ("zgrepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 160, [ProtocolLimitWarning],
3673 [InitISOFS, Always, TestOutputList (
3674 [["zgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3675 "return lines matching a pattern",
3677 This calls the external C<zgrep -i> program and returns the
3680 ("zegrepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 161, [ProtocolLimitWarning],
3681 [InitISOFS, Always, TestOutputList (
3682 [["zegrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3683 "return lines matching a pattern",
3685 This calls the external C<zegrep -i> program and returns the
3688 ("zfgrepi", (RStringList "lines", [String "pattern"; Pathname "path"], []), 162, [ProtocolLimitWarning],
3689 [InitISOFS, Always, TestOutputList (
3690 [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3691 "return lines matching a pattern",
3693 This calls the external C<zfgrep -i> program and returns the
3696 ("realpath", (RString "rpath", [Pathname "path"], []), 163, [Optional "realpath"],
3697 [InitISOFS, Always, TestOutput (
3698 [["realpath"; "/../directory"]], "/directory")],
3699 "canonicalized absolute pathname",
3701 Return the canonicalized absolute pathname of C<path>. The
3702 returned path has no C<.>, C<..> or symbolic link path elements.");
3704 ("ln", (RErr, [String "target"; Pathname "linkname"], []), 164, [],
3705 [InitBasicFS, Always, TestOutputStruct (
3708 ["stat"; "/b"]], [CompareWithInt ("nlink", 2)])],
3709 "create a hard link",
3711 This command creates a hard link using the C<ln> command.");
3713 ("ln_f", (RErr, [String "target"; Pathname "linkname"], []), 165, [],
3714 [InitBasicFS, Always, TestOutputStruct (
3717 ["ln_f"; "/a"; "/b"];
3718 ["stat"; "/b"]], [CompareWithInt ("nlink", 2)])],
3719 "create a hard link",
3721 This command creates a hard link using the C<ln -f> command.
3722 The C<-f> option removes the link (C<linkname>) if it exists already.");
3724 ("ln_s", (RErr, [String "target"; Pathname "linkname"], []), 166, [],
3725 [InitBasicFS, Always, TestOutputStruct (
3727 ["ln_s"; "a"; "/b"];
3728 ["lstat"; "/b"]], [CompareWithInt ("mode", 0o120777)])],
3729 "create a symbolic link",
3731 This command creates a symbolic link using the C<ln -s> command.");
3733 ("ln_sf", (RErr, [String "target"; Pathname "linkname"], []), 167, [],
3734 [InitBasicFS, Always, TestOutput (
3735 [["mkdir_p"; "/a/b"];
3736 ["touch"; "/a/b/c"];
3737 ["ln_sf"; "../d"; "/a/b/c"];
3738 ["readlink"; "/a/b/c"]], "../d")],
3739 "create a symbolic link",
3741 This command creates a symbolic link using the C<ln -sf> command,
3742 The C<-f> option removes the link (C<linkname>) if it exists already.");
3744 ("readlink", (RString "link", [Pathname "path"], []), 168, [],
3745 [] (* XXX tested above *),
3746 "read the target of a symbolic link",
3748 This command reads the target of a symbolic link.");
3750 ("fallocate", (RErr, [Pathname "path"; Int "len"], []), 169, [DeprecatedBy "fallocate64"],
3751 [InitBasicFS, Always, TestOutputStruct (
3752 [["fallocate"; "/a"; "1000000"];
3753 ["stat"; "/a"]], [CompareWithInt ("size", 1_000_000)])],
3754 "preallocate a file in the guest filesystem",
3756 This command preallocates a file (containing zero bytes) named
3757 C<path> of size C<len> bytes. If the file exists already, it
3760 Do not confuse this with the guestfish-specific
3761 C<alloc> command which allocates a file in the host and
3762 attaches it as a device.");
3764 ("swapon_device", (RErr, [Device "device"], []), 170, [],
3765 [InitPartition, Always, TestRun (
3766 [["mkswap"; "/dev/sda1"];
3767 ["swapon_device"; "/dev/sda1"];
3768 ["swapoff_device"; "/dev/sda1"]])],
3769 "enable swap on device",
3771 This command enables the libguestfs appliance to use the
3772 swap device or partition named C<device>. The increased
3773 memory is made available for all commands, for example
3774 those run using C<guestfs_command> or C<guestfs_sh>.
3776 Note that you should not swap to existing guest swap
3777 partitions unless you know what you are doing. They may
3778 contain hibernation information, or other information that
3779 the guest doesn't want you to trash. You also risk leaking
3780 information about the host to the guest this way. Instead,
3781 attach a new host device to the guest and swap on that.");
3783 ("swapoff_device", (RErr, [Device "device"], []), 171, [],
3784 [], (* XXX tested by swapon_device *)
3785 "disable swap on device",
3787 This command disables the libguestfs appliance swap
3788 device or partition named C<device>.
3789 See C<guestfs_swapon_device>.");
3791 ("swapon_file", (RErr, [Pathname "file"], []), 172, [],
3792 [InitBasicFS, Always, TestRun (
3793 [["fallocate"; "/swap"; "8388608"];
3794 ["mkswap_file"; "/swap"];
3795 ["swapon_file"; "/swap"];
3796 ["swapoff_file"; "/swap"]])],
3797 "enable swap on file",
3799 This command enables swap to a file.
3800 See C<guestfs_swapon_device> for other notes.");
3802 ("swapoff_file", (RErr, [Pathname "file"], []), 173, [],
3803 [], (* XXX tested by swapon_file *)
3804 "disable swap on file",
3806 This command disables the libguestfs appliance swap on file.");
3808 ("swapon_label", (RErr, [String "label"], []), 174, [],
3809 [InitEmpty, Always, TestRun (
3810 [["part_disk"; "/dev/sdb"; "mbr"];
3811 ["mkswap_L"; "swapit"; "/dev/sdb1"];
3812 ["swapon_label"; "swapit"];
3813 ["swapoff_label"; "swapit"];
3814 ["zero"; "/dev/sdb"];
3815 ["blockdev_rereadpt"; "/dev/sdb"]])],
3816 "enable swap on labeled swap partition",
3818 This command enables swap to a labeled swap partition.
3819 See C<guestfs_swapon_device> for other notes.");
3821 ("swapoff_label", (RErr, [String "label"], []), 175, [],
3822 [], (* XXX tested by swapon_label *)
3823 "disable swap on labeled swap partition",
3825 This command disables the libguestfs appliance swap on
3826 labeled swap partition.");
3828 ("swapon_uuid", (RErr, [String "uuid"], []), 176, [Optional "linuxfsuuid"],
3829 (let uuid = uuidgen () in
3830 [InitEmpty, Always, TestRun (
3831 [["mkswap_U"; uuid; "/dev/sdb"];
3832 ["swapon_uuid"; uuid];
3833 ["swapoff_uuid"; uuid]])]),
3834 "enable swap on swap partition by UUID",
3836 This command enables swap to a swap partition with the given UUID.
3837 See C<guestfs_swapon_device> for other notes.");
3839 ("swapoff_uuid", (RErr, [String "uuid"], []), 177, [Optional "linuxfsuuid"],
3840 [], (* XXX tested by swapon_uuid *)
3841 "disable swap on swap partition by UUID",
3843 This command disables the libguestfs appliance swap partition
3844 with the given UUID.");
3846 ("mkswap_file", (RErr, [Pathname "path"], []), 178, [],
3847 [InitBasicFS, Always, TestRun (
3848 [["fallocate"; "/swap"; "8388608"];
3849 ["mkswap_file"; "/swap"]])],
3850 "create a swap file",
3854 This command just writes a swap file signature to an existing
3855 file. To create the file itself, use something like C<guestfs_fallocate>.");
3857 ("inotify_init", (RErr, [Int "maxevents"], []), 179, [Optional "inotify"],
3858 [InitISOFS, Always, TestRun (
3859 [["inotify_init"; "0"]])],
3860 "create an inotify handle",
3862 This command creates a new inotify handle.
3863 The inotify subsystem can be used to notify events which happen to
3864 objects in the guest filesystem.
3866 C<maxevents> is the maximum number of events which will be
3867 queued up between calls to C<guestfs_inotify_read> or
3868 C<guestfs_inotify_files>.
3869 If this is passed as C<0>, then the kernel (or previously set)
3870 default is used. For Linux 2.6.29 the default was 16384 events.
3871 Beyond this limit, the kernel throws away events, but records
3872 the fact that it threw them away by setting a flag
3873 C<IN_Q_OVERFLOW> in the returned structure list (see
3874 C<guestfs_inotify_read>).
3876 Before any events are generated, you have to add some
3877 watches to the internal watch list. See:
3878 C<guestfs_inotify_add_watch>,
3879 C<guestfs_inotify_rm_watch> and
3880 C<guestfs_inotify_watch_all>.
3882 Queued up events should be read periodically by calling
3883 C<guestfs_inotify_read>
3884 (or C<guestfs_inotify_files> which is just a helpful
3885 wrapper around C<guestfs_inotify_read>). If you don't
3886 read the events out often enough then you risk the internal
3889 The handle should be closed after use by calling
3890 C<guestfs_inotify_close>. This also removes any
3891 watches automatically.
3893 See also L<inotify(7)> for an overview of the inotify interface
3894 as exposed by the Linux kernel, which is roughly what we expose
3895 via libguestfs. Note that there is one global inotify handle
3896 per libguestfs instance.");
3898 ("inotify_add_watch", (RInt64 "wd", [Pathname "path"; Int "mask"], []), 180, [Optional "inotify"],
3899 [InitBasicFS, Always, TestOutputList (
3900 [["inotify_init"; "0"];
3901 ["inotify_add_watch"; "/"; "1073741823"];
3904 ["inotify_files"]], ["a"; "b"])],
3905 "add an inotify watch",
3907 Watch C<path> for the events listed in C<mask>.
3909 Note that if C<path> is a directory then events within that
3910 directory are watched, but this does I<not> happen recursively
3911 (in subdirectories).
3913 Note for non-C or non-Linux callers: the inotify events are
3914 defined by the Linux kernel ABI and are listed in
3915 C</usr/include/sys/inotify.h>.");
3917 ("inotify_rm_watch", (RErr, [Int(*XXX64*) "wd"], []), 181, [Optional "inotify"],
3919 "remove an inotify watch",
3921 Remove a previously defined inotify watch.
3922 See C<guestfs_inotify_add_watch>.");
3924 ("inotify_read", (RStructList ("events", "inotify_event"), [], []), 182, [Optional "inotify"],
3926 "return list of inotify events",
3928 Return the complete queue of events that have happened
3929 since the previous read call.
3931 If no events have happened, this returns an empty list.
3933 I<Note>: In order to make sure that all events have been
3934 read, you must call this function repeatedly until it
3935 returns an empty list. The reason is that the call will
3936 read events up to the maximum appliance-to-host message
3937 size and leave remaining events in the queue.");
3939 ("inotify_files", (RStringList "paths", [], []), 183, [Optional "inotify"],
3941 "return list of watched files that had events",
3943 This function is a helpful wrapper around C<guestfs_inotify_read>
3944 which just returns a list of pathnames of objects that were
3945 touched. The returned pathnames are sorted and deduplicated.");
3947 ("inotify_close", (RErr, [], []), 184, [Optional "inotify"],
3949 "close the inotify handle",
3951 This closes the inotify handle which was previously
3952 opened by inotify_init. It removes all watches, throws
3953 away any pending events, and deallocates all resources.");
3955 ("setcon", (RErr, [String "context"], []), 185, [Optional "selinux"],
3957 "set SELinux security context",
3959 This sets the SELinux security context of the daemon
3960 to the string C<context>.
3962 See the documentation about SELINUX in L<guestfs(3)>.");
3964 ("getcon", (RString "context", [], []), 186, [Optional "selinux"],
3966 "get SELinux security context",
3968 This gets the SELinux security context of the daemon.
3970 See the documentation about SELINUX in L<guestfs(3)>,
3971 and C<guestfs_setcon>");
3973 ("mkfs_b", (RErr, [String "fstype"; Int "blocksize"; Device "device"], []), 187, [],
3974 [InitEmpty, Always, TestOutput (
3975 [["part_disk"; "/dev/sda"; "mbr"];
3976 ["mkfs_b"; "ext2"; "4096"; "/dev/sda1"];
3977 ["mount_options"; ""; "/dev/sda1"; "/"];
3978 ["write"; "/new"; "new file contents"];
3979 ["cat"; "/new"]], "new file contents");
3980 InitEmpty, Always, TestRun (
3981 [["part_disk"; "/dev/sda"; "mbr"];
3982 ["mkfs_b"; "vfat"; "32768"; "/dev/sda1"]]);
3983 InitEmpty, Always, TestLastFail (
3984 [["part_disk"; "/dev/sda"; "mbr"];
3985 ["mkfs_b"; "vfat"; "32769"; "/dev/sda1"]]);
3986 InitEmpty, Always, TestLastFail (
3987 [["part_disk"; "/dev/sda"; "mbr"];
3988 ["mkfs_b"; "vfat"; "33280"; "/dev/sda1"]]);
3989 InitEmpty, IfAvailable "ntfsprogs", TestRun (
3990 [["part_disk"; "/dev/sda"; "mbr"];
3991 ["mkfs_b"; "ntfs"; "32768"; "/dev/sda1"]])],
3992 "make a filesystem with block size",
3994 This call is similar to C<guestfs_mkfs>, but it allows you to
3995 control the block size of the resulting filesystem. Supported
3996 block sizes depend on the filesystem type, but typically they
3997 are C<1024>, C<2048> or C<4096> only.
3999 For VFAT and NTFS the C<blocksize> parameter is treated as
4000 the requested cluster size.");
4002 ("mke2journal", (RErr, [Int "blocksize"; Device "device"], []), 188, [],
4003 [InitEmpty, Always, TestOutput (
4004 [["part_init"; "/dev/sda"; "mbr"];
4005 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
4006 ["part_add"; "/dev/sda"; "p"; "204800"; "-64"];
4007 ["mke2journal"; "4096"; "/dev/sda1"];
4008 ["mke2fs_J"; "ext2"; "4096"; "/dev/sda2"; "/dev/sda1"];
4009 ["mount_options"; ""; "/dev/sda2"; "/"];
4010 ["write"; "/new"; "new file contents"];
4011 ["cat"; "/new"]], "new file contents")],
4012 "make ext2/3/4 external journal",
4014 This creates an ext2 external journal on C<device>. It is equivalent
4017 mke2fs -O journal_dev -b blocksize device");
4019 ("mke2journal_L", (RErr, [Int "blocksize"; String "label"; Device "device"], []), 189, [],
4020 [InitEmpty, Always, TestOutput (
4021 [["part_init"; "/dev/sda"; "mbr"];
4022 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
4023 ["part_add"; "/dev/sda"; "p"; "204800"; "-64"];
4024 ["mke2journal_L"; "4096"; "JOURNAL"; "/dev/sda1"];
4025 ["mke2fs_JL"; "ext2"; "4096"; "/dev/sda2"; "JOURNAL"];
4026 ["mount_options"; ""; "/dev/sda2"; "/"];
4027 ["write"; "/new"; "new file contents"];
4028 ["cat"; "/new"]], "new file contents")],
4029 "make ext2/3/4 external journal with label",
4031 This creates an ext2 external journal on C<device> with label C<label>.");
4033 ("mke2journal_U", (RErr, [Int "blocksize"; String "uuid"; Device "device"], []), 190, [Optional "linuxfsuuid"],
4034 (let uuid = uuidgen () in
4035 [InitEmpty, Always, TestOutput (
4036 [["part_init"; "/dev/sda"; "mbr"];
4037 ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
4038 ["part_add"; "/dev/sda"; "p"; "204800"; "-64"];
4039 ["mke2journal_U"; "4096"; uuid; "/dev/sda1"];
4040 ["mke2fs_JU"; "ext2"; "4096"; "/dev/sda2"; uuid];
4041 ["mount_options"; ""; "/dev/sda2"; "/"];
4042 ["write"; "/new"; "new file contents"];
4043 ["cat"; "/new"]], "new file contents")]),
4044 "make ext2/3/4 external journal with UUID",
4046 This creates an ext2 external journal on C<device> with UUID C<uuid>.");
4048 ("mke2fs_J", (RErr, [String "fstype"; Int "blocksize"; Device "device"; Device "journal"], []), 191, [],
4050 "make ext2/3/4 filesystem with external journal",
4052 This creates an ext2/3/4 filesystem on C<device> with
4053 an external journal on C<journal>. It is equivalent
4056 mke2fs -t fstype -b blocksize -J device=<journal> <device>
4058 See also C<guestfs_mke2journal>.");
4060 ("mke2fs_JL", (RErr, [String "fstype"; Int "blocksize"; Device "device"; String "label"], []), 192, [],
4062 "make ext2/3/4 filesystem with external journal",
4064 This creates an ext2/3/4 filesystem on C<device> with
4065 an external journal on the journal labeled C<label>.
4067 See also C<guestfs_mke2journal_L>.");
4069 ("mke2fs_JU", (RErr, [String "fstype"; Int "blocksize"; Device "device"; String "uuid"], []), 193, [Optional "linuxfsuuid"],
4071 "make ext2/3/4 filesystem with external journal",
4073 This creates an ext2/3/4 filesystem on C<device> with
4074 an external journal on the journal with UUID C<uuid>.
4076 See also C<guestfs_mke2journal_U>.");
4078 ("modprobe", (RErr, [String "modulename"], []), 194, [Optional "linuxmodules"],
4079 [InitNone, Always, TestRun [["modprobe"; "fat"]]],
4080 "load a kernel module",
4082 This loads a kernel module in the appliance.
4084 The kernel module must have been whitelisted when libguestfs
4085 was built (see C<appliance/kmod.whitelist.in> in the source).");
4087 ("echo_daemon", (RString "output", [StringList "words"], []), 195, [],
4088 [InitNone, Always, TestOutput (
4089 [["echo_daemon"; "This is a test"]], "This is a test"
4091 "echo arguments back to the client",
4093 This command concatenates the list of C<words> passed with single spaces
4094 between them and returns the resulting string.
4096 You can use this command to test the connection through to the daemon.
4098 See also C<guestfs_ping_daemon>.");
4100 ("find0", (RErr, [Pathname "directory"; FileOut "files"], []), 196, [],
4101 [], (* There is a regression test for this. *)
4102 "find all files and directories, returning NUL-separated list",
4104 This command lists out all files and directories, recursively,
4105 starting at C<directory>, placing the resulting list in the
4106 external file called C<files>.
4108 This command works the same way as C<guestfs_find> with the
4109 following exceptions:
4115 The resulting list is written to an external file.
4119 Items (filenames) in the result are separated
4120 by C<\\0> characters. See L<find(1)> option I<-print0>.
4124 This command is not limited in the number of names that it
4129 The result list is not sorted.
4133 ("case_sensitive_path", (RString "rpath", [Pathname "path"], []), 197, [],
4134 [InitISOFS, Always, TestOutput (
4135 [["case_sensitive_path"; "/DIRECTORY"]], "/directory");
4136 InitISOFS, Always, TestOutput (
4137 [["case_sensitive_path"; "/DIRECTORY/"]], "/directory");
4138 InitISOFS, Always, TestOutput (
4139 [["case_sensitive_path"; "/Known-1"]], "/known-1");
4140 InitISOFS, Always, TestLastFail (
4141 [["case_sensitive_path"; "/Known-1/"]]);
4142 InitBasicFS, Always, TestOutput (
4144 ["mkdir"; "/a/bbb"];
4145 ["touch"; "/a/bbb/c"];
4146 ["case_sensitive_path"; "/A/bbB/C"]], "/a/bbb/c");
4147 InitBasicFS, Always, TestOutput (
4149 ["mkdir"; "/a/bbb"];
4150 ["touch"; "/a/bbb/c"];
4151 ["case_sensitive_path"; "/A////bbB/C"]], "/a/bbb/c");
4152 InitBasicFS, Always, TestLastFail (
4154 ["mkdir"; "/a/bbb"];
4155 ["touch"; "/a/bbb/c"];
4156 ["case_sensitive_path"; "/A/bbb/../bbb/C"]])],
4157 "return true path on case-insensitive filesystem",
4159 This can be used to resolve case insensitive paths on
4160 a filesystem which is case sensitive. The use case is
4161 to resolve paths which you have read from Windows configuration
4162 files or the Windows Registry, to the true path.
4164 The command handles a peculiarity of the Linux ntfs-3g
4165 filesystem driver (and probably others), which is that although
4166 the underlying filesystem is case-insensitive, the driver
4167 exports the filesystem to Linux as case-sensitive.
4169 One consequence of this is that special directories such
4170 as C<c:\\windows> may appear as C</WINDOWS> or C</windows>
4171 (or other things) depending on the precise details of how
4172 they were created. In Windows itself this would not be
4175 Bug or feature? You decide:
4176 L<http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
4178 This function resolves the true case of each element in the
4179 path and returns the case-sensitive path.
4181 Thus C<guestfs_case_sensitive_path> (\"/Windows/System32\")
4182 might return C<\"/WINDOWS/system32\"> (the exact return value
4183 would depend on details of how the directories were originally
4184 created under Windows).
4187 This function does not handle drive names, backslashes etc.
4189 See also C<guestfs_realpath>.");
4191 ("vfs_type", (RString "fstype", [Device "device"], []), 198, [],
4192 [InitBasicFS, Always, TestOutput (
4193 [["vfs_type"; "/dev/sda1"]], "ext2")],
4194 "get the Linux VFS type corresponding to a mounted device",
4196 This command gets the filesystem type corresponding to
4197 the filesystem on C<device>.
4199 For most filesystems, the result is the name of the Linux
4200 VFS module which would be used to mount this filesystem
4201 if you mounted it without specifying the filesystem type.
4202 For example a string such as C<ext3> or C<ntfs>.");
4204 ("truncate", (RErr, [Pathname "path"], []), 199, [],
4205 [InitBasicFS, Always, TestOutputStruct (
4206 [["write"; "/test"; "some stuff so size is not zero"];
4207 ["truncate"; "/test"];
4208 ["stat"; "/test"]], [CompareWithInt ("size", 0)])],
4209 "truncate a file to zero size",
4211 This command truncates C<path> to a zero-length file. The
4212 file must exist already.");
4214 ("truncate_size", (RErr, [Pathname "path"; Int64 "size"], []), 200, [],
4215 [InitBasicFS, Always, TestOutputStruct (
4216 [["touch"; "/test"];
4217 ["truncate_size"; "/test"; "1000"];
4218 ["stat"; "/test"]], [CompareWithInt ("size", 1000)])],
4219 "truncate a file to a particular size",
4221 This command truncates C<path> to size C<size> bytes. The file
4224 If the current file size is less than C<size> then
4225 the file is extended to the required size with zero bytes.
4226 This creates a sparse file (ie. disk blocks are not allocated
4227 for the file until you write to it). To create a non-sparse
4228 file of zeroes, use C<guestfs_fallocate64> instead.");
4230 ("utimens", (RErr, [Pathname "path"; Int64 "atsecs"; Int64 "atnsecs"; Int64 "mtsecs"; Int64 "mtnsecs"], []), 201, [],
4231 [InitBasicFS, Always, TestOutputStruct (
4232 [["touch"; "/test"];
4233 ["utimens"; "/test"; "12345"; "67890"; "9876"; "5432"];
4234 ["stat"; "/test"]], [CompareWithInt ("mtime", 9876)])],
4235 "set timestamp of a file with nanosecond precision",
4237 This command sets the timestamps of a file with nanosecond
4240 C<atsecs, atnsecs> are the last access time (atime) in secs and
4241 nanoseconds from the epoch.
4243 C<mtsecs, mtnsecs> are the last modification time (mtime) in
4244 secs and nanoseconds from the epoch.
4246 If the C<*nsecs> field contains the special value C<-1> then
4247 the corresponding timestamp is set to the current time. (The
4248 C<*secs> field is ignored in this case).
4250 If the C<*nsecs> field contains the special value C<-2> then
4251 the corresponding timestamp is left unchanged. (The
4252 C<*secs> field is ignored in this case).");
4254 ("mkdir_mode", (RErr, [Pathname "path"; Int "mode"], []), 202, [],
4255 [InitBasicFS, Always, TestOutputStruct (
4256 [["mkdir_mode"; "/test"; "0o111"];
4257 ["stat"; "/test"]], [CompareWithInt ("mode", 0o40111)])],
4258 "create a directory with a particular mode",
4260 This command creates a directory, setting the initial permissions
4261 of the directory to C<mode>.
4263 For common Linux filesystems, the actual mode which is set will
4264 be C<mode & ~umask & 01777>. Non-native-Linux filesystems may
4265 interpret the mode in other ways.
4267 See also C<guestfs_mkdir>, C<guestfs_umask>");
4269 ("lchown", (RErr, [Int "owner"; Int "group"; Pathname "path"], []), 203, [],
4271 "change file owner and group",
4273 Change the file owner to C<owner> and group to C<group>.
4274 This is like C<guestfs_chown> but if C<path> is a symlink then
4275 the link itself is changed, not the target.
4277 Only numeric uid and gid are supported. If you want to use
4278 names, you will need to locate and parse the password file
4279 yourself (Augeas support makes this relatively easy).");
4281 ("lstatlist", (RStructList ("statbufs", "stat"), [Pathname "path"; StringList "names"], []), 204, [],
4283 "lstat on multiple files",
4285 This call allows you to perform the C<guestfs_lstat> operation
4286 on multiple files, where all files are in the directory C<path>.
4287 C<names> is the list of files from this directory.
4289 On return you get a list of stat structs, with a one-to-one
4290 correspondence to the C<names> list. If any name did not exist
4291 or could not be lstat'd, then the C<ino> field of that structure
4294 This call is intended for programs that want to efficiently
4295 list a directory contents without making many round-trips.
4296 See also C<guestfs_lxattrlist> for a similarly efficient call
4297 for getting extended attributes. Very long directory listings
4298 might cause the protocol message size to be exceeded, causing
4299 this call to fail. The caller must split up such requests
4300 into smaller groups of names.");
4302 ("lxattrlist", (RStructList ("xattrs", "xattr"), [Pathname "path"; StringList "names"], []), 205, [Optional "linuxxattrs"],
4304 "lgetxattr on multiple files",
4306 This call allows you to get the extended attributes
4307 of multiple files, where all files are in the directory C<path>.
4308 C<names> is the list of files from this directory.
4310 On return you get a flat list of xattr structs which must be
4311 interpreted sequentially. The first xattr struct always has a zero-length
4312 C<attrname>. C<attrval> in this struct is zero-length
4313 to indicate there was an error doing C<lgetxattr> for this
4314 file, I<or> is a C string which is a decimal number
4315 (the number of following attributes for this file, which could
4316 be C<\"0\">). Then after the first xattr struct are the
4317 zero or more attributes for the first named file.
4318 This repeats for the second and subsequent files.
4320 This call is intended for programs that want to efficiently
4321 list a directory contents without making many round-trips.
4322 See also C<guestfs_lstatlist> for a similarly efficient call
4323 for getting standard stats. Very long directory listings
4324 might cause the protocol message size to be exceeded, causing
4325 this call to fail. The caller must split up such requests
4326 into smaller groups of names.");
4328 ("readlinklist", (RStringList "links", [Pathname "path"; StringList "names"], []), 206, [],
4330 "readlink on multiple files",
4332 This call allows you to do a C<readlink> operation
4333 on multiple files, where all files are in the directory C<path>.
4334 C<names> is the list of files from this directory.
4336 On return you get a list of strings, with a one-to-one
4337 correspondence to the C<names> list. Each string is the
4338 value of the symbolic link.
4340 If the C<readlink(2)> operation fails on any name, then
4341 the corresponding result string is the empty string C<\"\">.
4342 However the whole operation is completed even if there
4343 were C<readlink(2)> errors, and so you can call this
4344 function with names where you don't know if they are
4345 symbolic links already (albeit slightly less efficient).
4347 This call is intended for programs that want to efficiently
4348 list a directory contents without making many round-trips.
4349 Very long directory listings might cause the protocol
4350 message size to be exceeded, causing
4351 this call to fail. The caller must split up such requests
4352 into smaller groups of names.");
4354 ("pread", (RBufferOut "content", [Pathname "path"; Int "count"; Int64 "offset"], []), 207, [ProtocolLimitWarning],
4355 [InitISOFS, Always, TestOutputBuffer (
4356 [["pread"; "/known-4"; "1"; "3"]], "\n");
4357 InitISOFS, Always, TestOutputBuffer (
4358 [["pread"; "/empty"; "0"; "100"]], "")],
4359 "read part of a file",
4361 This command lets you read part of a file. It reads C<count>
4362 bytes of the file, starting at C<offset>, from file C<path>.
4364 This may read fewer bytes than requested. For further details
4365 see the L<pread(2)> system call.
4367 See also C<guestfs_pwrite>, C<guestfs_pread_device>.");
4369 ("part_init", (RErr, [Device "device"; String "parttype"], []), 208, [],
4370 [InitEmpty, Always, TestRun (
4371 [["part_init"; "/dev/sda"; "gpt"]])],
4372 "create an empty partition table",
4374 This creates an empty partition table on C<device> of one of the
4375 partition types listed below. Usually C<parttype> should be
4376 either C<msdos> or C<gpt> (for large disks).
4378 Initially there are no partitions. Following this, you should
4379 call C<guestfs_part_add> for each partition required.
4381 Possible values for C<parttype> are:
4385 =item B<efi> | B<gpt>
4387 Intel EFI / GPT partition table.
4389 This is recommended for >= 2 TB partitions that will be accessed
4390 from Linux and Intel-based Mac OS X. It also has limited backwards
4391 compatibility with the C<mbr> format.
4393 =item B<mbr> | B<msdos>
4395 The standard PC \"Master Boot Record\" (MBR) format used
4396 by MS-DOS and Windows. This partition type will B<only> work
4397 for device sizes up to 2 TB. For large disks we recommend
4402 Other partition table types that may work but are not
4411 =item B<amiga> | B<rdb>
4413 Amiga \"Rigid Disk Block\" format.
4421 DASD, used on IBM mainframes.
4429 Old Mac partition format. Modern Macs use C<gpt>.
4433 NEC PC-98 format, common in Japan apparently.
4441 ("part_add", (RErr, [Device "device"; String "prlogex"; Int64 "startsect"; Int64 "endsect"], []), 209, [],
4442 [InitEmpty, Always, TestRun (
4443 [["part_init"; "/dev/sda"; "mbr"];
4444 ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]]);
4445 InitEmpty, Always, TestRun (
4446 [["part_init"; "/dev/sda"; "gpt"];
4447 ["part_add"; "/dev/sda"; "primary"; "34"; "127"];
4448 ["part_add"; "/dev/sda"; "primary"; "128"; "-34"]]);
4449 InitEmpty, Always, TestRun (
4450 [["part_init"; "/dev/sda"; "mbr"];
4451 ["part_add"; "/dev/sda"; "primary"; "32"; "127"];
4452 ["part_add"; "/dev/sda"; "primary"; "128"; "255"];
4453 ["part_add"; "/dev/sda"; "primary"; "256"; "511"];
4454 ["part_add"; "/dev/sda"; "primary"; "512"; "-1"]])],
4455 "add a partition to the device",
4457 This command adds a partition to C<device>. If there is no partition
4458 table on the device, call C<guestfs_part_init> first.
4460 The C<prlogex> parameter is the type of partition. Normally you
4461 should pass C<p> or C<primary> here, but MBR partition tables also
4462 support C<l> (or C<logical>) and C<e> (or C<extended>) partition
4465 C<startsect> and C<endsect> are the start and end of the partition
4466 in I<sectors>. C<endsect> may be negative, which means it counts
4467 backwards from the end of the disk (C<-1> is the last sector).
4469 Creating a partition which covers the whole disk is not so easy.
4470 Use C<guestfs_part_disk> to do that.");
4472 ("part_disk", (RErr, [Device "device"; String "parttype"], []), 210, [DangerWillRobinson],
4473 [InitEmpty, Always, TestRun (
4474 [["part_disk"; "/dev/sda"; "mbr"]]);
4475 InitEmpty, Always, TestRun (
4476 [["part_disk"; "/dev/sda"; "gpt"]])],
4477 "partition whole disk with a single primary partition",
4479 This command is simply a combination of C<guestfs_part_init>
4480 followed by C<guestfs_part_add> to create a single primary partition
4481 covering the whole disk.
4483 C<parttype> is the partition table type, usually C<mbr> or C<gpt>,
4484 but other possible values are described in C<guestfs_part_init>.");
4486 ("part_set_bootable", (RErr, [Device "device"; Int "partnum"; Bool "bootable"], []), 211, [],
4487 [InitEmpty, Always, TestRun (
4488 [["part_disk"; "/dev/sda"; "mbr"];
4489 ["part_set_bootable"; "/dev/sda"; "1"; "true"]])],
4490 "make a partition bootable",
4492 This sets the bootable flag on partition numbered C<partnum> on
4493 device C<device>. Note that partitions are numbered from 1.
4495 The bootable flag is used by some operating systems (notably
4496 Windows) to determine which partition to boot from. It is by
4497 no means universally recognized.");
4499 ("part_set_name", (RErr, [Device "device"; Int "partnum"; String "name"], []), 212, [],
4500 [InitEmpty, Always, TestRun (
4501 [["part_disk"; "/dev/sda"; "gpt"];
4502 ["part_set_name"; "/dev/sda"; "1"; "thepartname"]])],
4503 "set partition name",
4505 This sets the partition name on partition numbered C<partnum> on
4506 device C<device>. Note that partitions are numbered from 1.
4508 The partition name can only be set on certain types of partition
4509 table. This works on C<gpt> but not on C<mbr> partitions.");
4511 ("part_list", (RStructList ("partitions", "partition"), [Device "device"], []), 213, [],
4512 [], (* XXX Add a regression test for this. *)
4513 "list partitions on a device",
4515 This command parses the partition table on C<device> and
4516 returns the list of partitions found.
4518 The fields in the returned structure are:
4524 Partition number, counting from 1.
4528 Start of the partition I<in bytes>. To get sectors you have to
4529 divide by the device's sector size, see C<guestfs_blockdev_getss>.
4533 End of the partition in bytes.
4537 Size of the partition in bytes.
4541 ("part_get_parttype", (RString "parttype", [Device "device"], []), 214, [],
4542 [InitEmpty, Always, TestOutput (
4543 [["part_disk"; "/dev/sda"; "gpt"];
4544 ["part_get_parttype"; "/dev/sda"]], "gpt")],
4545 "get the partition table type",
4547 This command examines the partition table on C<device> and
4548 returns the partition table type (format) being used.
4550 Common return values include: C<msdos> (a DOS/Windows style MBR
4551 partition table), C<gpt> (a GPT/EFI-style partition table). Other
4552 values are possible, although unusual. See C<guestfs_part_init>
4555 ("fill", (RErr, [Int "c"; Int "len"; Pathname "path"], []), 215, [Progress],
4556 [InitBasicFS, Always, TestOutputBuffer (
4557 [["fill"; "0x63"; "10"; "/test"];
4558 ["read_file"; "/test"]], "cccccccccc")],
4559 "fill a file with octets",
4561 This command creates a new file called C<path>. The initial
4562 content of the file is C<len> octets of C<c>, where C<c>
4563 must be a number in the range C<[0..255]>.
4565 To fill a file with zero bytes (sparsely), it is
4566 much more efficient to use C<guestfs_truncate_size>.
4567 To create a file with a pattern of repeating bytes
4568 use C<guestfs_fill_pattern>.");
4570 ("available", (RErr, [StringList "groups"], []), 216, [],
4571 [InitNone, Always, TestRun [["available"; ""]]],
4572 "test availability of some parts of the API",
4574 This command is used to check the availability of some
4575 groups of functionality in the appliance, which not all builds of
4576 the libguestfs appliance will be able to provide.
4578 The libguestfs groups, and the functions that those
4579 groups correspond to, are listed in L<guestfs(3)/AVAILABILITY>.
4580 You can also fetch this list at runtime by calling
4581 C<guestfs_available_all_groups>.
4583 The argument C<groups> is a list of group names, eg:
4584 C<[\"inotify\", \"augeas\"]> would check for the availability of
4585 the Linux inotify functions and Augeas (configuration file
4588 The command returns no error if I<all> requested groups are available.
4590 It fails with an error if one or more of the requested
4591 groups is unavailable in the appliance.
4593 If an unknown group name is included in the
4594 list of groups then an error is always returned.
4602 You must call C<guestfs_launch> before calling this function.
4604 The reason is because we don't know what groups are
4605 supported by the appliance/daemon until it is running and can
4610 If a group of functions is available, this does not necessarily
4611 mean that they will work. You still have to check for errors
4612 when calling individual API functions even if they are
4617 It is usually the job of distro packagers to build
4618 complete functionality into the libguestfs appliance.
4619 Upstream libguestfs, if built from source with all
4620 requirements satisfied, will support everything.
4624 This call was added in version C<1.0.80>. In previous
4625 versions of libguestfs all you could do would be to speculatively
4626 execute a command to find out if the daemon implemented it.
4627 See also C<guestfs_version>.
4631 ("dd", (RErr, [Dev_or_Path "src"; Dev_or_Path "dest"], []), 217, [],
4632 [InitBasicFS, Always, TestOutputBuffer (
4633 [["write"; "/src"; "hello, world"];
4634 ["dd"; "/src"; "/dest"];
4635 ["read_file"; "/dest"]], "hello, world")],
4636 "copy from source to destination using dd",
4638 This command copies from one source device or file C<src>
4639 to another destination device or file C<dest>. Normally you
4640 would use this to copy to or from a device or partition, for
4641 example to duplicate a filesystem.
4643 If the destination is a device, it must be as large or larger
4644 than the source file or device, otherwise the copy will fail.
4645 This command cannot do partial copies (see C<guestfs_copy_size>).");
4647 ("filesize", (RInt64 "size", [Pathname "file"], []), 218, [],
4648 [InitBasicFS, Always, TestOutputInt (
4649 [["write"; "/file"; "hello, world"];
4650 ["filesize"; "/file"]], 12)],
4651 "return the size of the file in bytes",
4653 This command returns the size of C<file> in bytes.
4655 To get other stats about a file, use C<guestfs_stat>, C<guestfs_lstat>,
4656 C<guestfs_is_dir>, C<guestfs_is_file> etc.
4657 To get the size of block devices, use C<guestfs_blockdev_getsize64>.");
4659 ("lvrename", (RErr, [String "logvol"; String "newlogvol"], []), 219, [],
4660 [InitBasicFSonLVM, Always, TestOutputList (
4661 [["lvrename"; "/dev/VG/LV"; "/dev/VG/LV2"];
4662 ["lvs"]], ["/dev/VG/LV2"])],
4663 "rename an LVM logical volume",
4665 Rename a logical volume C<logvol> with the new name C<newlogvol>.");
4667 ("vgrename", (RErr, [String "volgroup"; String "newvolgroup"], []), 220, [],
4668 [InitBasicFSonLVM, Always, TestOutputList (
4670 ["vg_activate"; "false"; "VG"];
4671 ["vgrename"; "VG"; "VG2"];
4672 ["vg_activate"; "true"; "VG2"];
4673 ["mount_options"; ""; "/dev/VG2/LV"; "/"];
4674 ["vgs"]], ["VG2"])],
4675 "rename an LVM volume group",
4677 Rename a volume group C<volgroup> with the new name C<newvolgroup>.");
4679 ("initrd_cat", (RBufferOut "content", [Pathname "initrdpath"; String "filename"], []), 221, [ProtocolLimitWarning],
4680 [InitISOFS, Always, TestOutputBuffer (
4681 [["initrd_cat"; "/initrd"; "known-4"]], "abc\ndef\nghi")],
4682 "list the contents of a single file in an initrd",
4684 This command unpacks the file C<filename> from the initrd file
4685 called C<initrdpath>. The filename must be given I<without> the
4686 initial C</> character.
4688 For example, in guestfish you could use the following command
4689 to examine the boot script (usually called C</init>)
4690 contained in a Linux initrd or initramfs image:
4692 initrd-cat /boot/initrd-<version>.img init
4694 See also C<guestfs_initrd_list>.");
4696 ("pvuuid", (RString "uuid", [Device "device"], []), 222, [],
4698 "get the UUID of a physical volume",
4700 This command returns the UUID of the LVM PV C<device>.");
4702 ("vguuid", (RString "uuid", [String "vgname"], []), 223, [],
4704 "get the UUID of a volume group",
4706 This command returns the UUID of the LVM VG named C<vgname>.");
4708 ("lvuuid", (RString "uuid", [Device "device"], []), 224, [],
4710 "get the UUID of a logical volume",
4712 This command returns the UUID of the LVM LV C<device>.");
4714 ("vgpvuuids", (RStringList "uuids", [String "vgname"], []), 225, [],
4716 "get the PV UUIDs containing the volume group",
4718 Given a VG called C<vgname>, this returns the UUIDs of all
4719 the physical volumes that this volume group resides on.
4721 You can use this along with C<guestfs_pvs> and C<guestfs_pvuuid>
4722 calls to associate physical volumes and volume groups.
4724 See also C<guestfs_vglvuuids>.");
4726 ("vglvuuids", (RStringList "uuids", [String "vgname"], []), 226, [],
4728 "get the LV UUIDs of all LVs in the volume group",
4730 Given a VG called C<vgname>, this returns the UUIDs of all
4731 the logical volumes created in this volume group.
4733 You can use this along with C<guestfs_lvs> and C<guestfs_lvuuid>
4734 calls to associate logical volumes and volume groups.
4736 See also C<guestfs_vgpvuuids>.");
4738 ("copy_size", (RErr, [Dev_or_Path "src"; Dev_or_Path "dest"; Int64 "size"], []), 227, [Progress],
4739 [InitBasicFS, Always, TestOutputBuffer (
4740 [["write"; "/src"; "hello, world"];
4741 ["copy_size"; "/src"; "/dest"; "5"];
4742 ["read_file"; "/dest"]], "hello")],
4743 "copy size bytes from source to destination using dd",
4745 This command copies exactly C<size> bytes from one source device
4746 or file C<src> to another destination device or file C<dest>.
4748 Note this will fail if the source is too short or if the destination
4749 is not large enough.");
4751 ("zero_device", (RErr, [Device "device"], []), 228, [DangerWillRobinson; Progress],
4752 [InitBasicFSonLVM, Always, TestRun (
4753 [["zero_device"; "/dev/VG/LV"]])],
4754 "write zeroes to an entire device",
4756 This command writes zeroes over the entire C<device>. Compare
4757 with C<guestfs_zero> which just zeroes the first few blocks of
4760 ("txz_in", (RErr, [FileIn "tarball"; Pathname "directory"], []), 229, [Optional "xz"],
4761 [InitBasicFS, Always, TestOutput (
4762 [["txz_in"; "../images/helloworld.tar.xz"; "/"];
4763 ["cat"; "/hello"]], "hello\n")],
4764 "unpack compressed tarball to directory",
4766 This command uploads and unpacks local file C<tarball> (an
4767 I<xz compressed> tar file) into C<directory>.");
4769 ("txz_out", (RErr, [Pathname "directory"; FileOut "tarball"], []), 230, [Optional "xz"],
4771 "pack directory into compressed tarball",
4773 This command packs the contents of C<directory> and downloads
4774 it to local file C<tarball> (as an xz compressed tar archive).");
4776 ("ntfsresize", (RErr, [Device "device"], []), 231, [Optional "ntfsprogs"],
4778 "resize an NTFS filesystem",
4780 This command resizes an NTFS filesystem, expanding or
4781 shrinking it to the size of the underlying device.
4782 See also L<ntfsresize(8)>.");
4784 ("vgscan", (RErr, [], []), 232, [],
4785 [InitEmpty, Always, TestRun (
4787 "rescan for LVM physical volumes, volume groups and logical volumes",
4789 This rescans all block devices and rebuilds the list of LVM
4790 physical volumes, volume groups and logical volumes.");
4792 ("part_del", (RErr, [Device "device"; Int "partnum"], []), 233, [],
4793 [InitEmpty, Always, TestRun (
4794 [["part_init"; "/dev/sda"; "mbr"];
4795 ["part_add"; "/dev/sda"; "primary"; "1"; "-1"];
4796 ["part_del"; "/dev/sda"; "1"]])],
4797 "delete a partition",
4799 This command deletes the partition numbered C<partnum> on C<device>.
4801 Note that in the case of MBR partitioning, deleting an
4802 extended partition also deletes any logical partitions
4805 ("part_get_bootable", (RBool "bootable", [Device "device"; Int "partnum"], []), 234, [],
4806 [InitEmpty, Always, TestOutputTrue (
4807 [["part_init"; "/dev/sda"; "mbr"];
4808 ["part_add"; "/dev/sda"; "primary"; "1"; "-1"];
4809 ["part_set_bootable"; "/dev/sda"; "1"; "true"];
4810 ["part_get_bootable"; "/dev/sda"; "1"]])],
4811 "return true if a partition is bootable",
4813 This command returns true if the partition C<partnum> on
4814 C<device> has the bootable flag set.
4816 See also C<guestfs_part_set_bootable>.");
4818 ("part_get_mbr_id", (RInt "idbyte", [Device "device"; Int "partnum"], []), 235, [FishOutput FishOutputHexadecimal],
4819 [InitEmpty, Always, TestOutputInt (
4820 [["part_init"; "/dev/sda"; "mbr"];
4821 ["part_add"; "/dev/sda"; "primary"; "1"; "-1"];
4822 ["part_set_mbr_id"; "/dev/sda"; "1"; "0x7f"];
4823 ["part_get_mbr_id"; "/dev/sda"; "1"]], 0x7f)],
4824 "get the MBR type byte (ID byte) from a partition",
4826 Returns the MBR type byte (also known as the ID byte) from
4827 the numbered partition C<partnum>.
4829 Note that only MBR (old DOS-style) partitions have type bytes.
4830 You will get undefined results for other partition table
4831 types (see C<guestfs_part_get_parttype>).");
4833 ("part_set_mbr_id", (RErr, [Device "device"; Int "partnum"; Int "idbyte"], []), 236, [],
4834 [], (* tested by part_get_mbr_id *)
4835 "set the MBR type byte (ID byte) of a partition",
4837 Sets the MBR type byte (also known as the ID byte) of
4838 the numbered partition C<partnum> to C<idbyte>. Note
4839 that the type bytes quoted in most documentation are
4840 in fact hexadecimal numbers, but usually documented
4841 without any leading \"0x\" which might be confusing.
4843 Note that only MBR (old DOS-style) partitions have type bytes.
4844 You will get undefined results for other partition table
4845 types (see C<guestfs_part_get_parttype>).");
4847 ("checksum_device", (RString "checksum", [String "csumtype"; Device "device"], []), 237, [],
4848 [InitISOFS, Always, TestOutputFileMD5 (
4849 [["checksum_device"; "md5"; "/dev/sdd"]],
4850 "../images/test.iso")],
4851 "compute MD5, SHAx or CRC checksum of the contents of a device",
4853 This call computes the MD5, SHAx or CRC checksum of the
4854 contents of the device named C<device>. For the types of
4855 checksums supported see the C<guestfs_checksum> command.");
4857 ("lvresize_free", (RErr, [Device "lv"; Int "percent"], []), 238, [Optional "lvm2"],
4858 [InitNone, Always, TestRun (
4859 [["part_disk"; "/dev/sda"; "mbr"];
4860 ["pvcreate"; "/dev/sda1"];
4861 ["vgcreate"; "VG"; "/dev/sda1"];
4862 ["lvcreate"; "LV"; "VG"; "10"];
4863 ["lvresize_free"; "/dev/VG/LV"; "100"]])],
4864 "expand an LV to fill free space",
4866 This expands an existing logical volume C<lv> so that it fills
4867 C<pc>% of the remaining free space in the volume group. Commonly
4868 you would call this with pc = 100 which expands the logical volume
4869 as much as possible, using all remaining free space in the volume
4872 ("aug_clear", (RErr, [String "augpath"], []), 239, [Optional "augeas"],
4873 [], (* XXX Augeas code needs tests. *)
4874 "clear Augeas path",
4876 Set the value associated with C<path> to C<NULL>. This
4877 is the same as the L<augtool(1)> C<clear> command.");
4879 ("get_umask", (RInt "mask", [], []), 240, [FishOutput FishOutputOctal],
4880 [InitEmpty, Always, TestOutputInt (
4881 [["get_umask"]], 0o22)],
4882 "get the current umask",
4884 Return the current umask. By default the umask is C<022>
4885 unless it has been set by calling C<guestfs_umask>.");
4887 ("debug_upload", (RErr, [FileIn "filename"; String "tmpname"; Int "mode"], []), 241, [NotInDocs],
4889 "upload a file to the appliance (internal use only)",
4891 The C<guestfs_debug_upload> command uploads a file to
4892 the libguestfs appliance.
4894 There is no comprehensive help for this command. You have
4895 to look at the file C<daemon/debug.c> in the libguestfs source
4896 to find out what it is for.");
4898 ("base64_in", (RErr, [FileIn "base64file"; Pathname "filename"], []), 242, [],
4899 [InitBasicFS, Always, TestOutput (
4900 [["base64_in"; "../images/hello.b64"; "/hello"];
4901 ["cat"; "/hello"]], "hello\n")],
4902 "upload base64-encoded data to file",
4904 This command uploads base64-encoded data from C<base64file>
4907 ("base64_out", (RErr, [Pathname "filename"; FileOut "base64file"], []), 243, [],
4909 "download file and encode as base64",
4911 This command downloads the contents of C<filename>, writing
4912 it out to local file C<base64file> encoded as base64.");
4914 ("checksums_out", (RErr, [String "csumtype"; Pathname "directory"; FileOut "sumsfile"], []), 244, [],
4916 "compute MD5, SHAx or CRC checksum of files in a directory",
4918 This command computes the checksums of all regular files in
4919 C<directory> and then emits a list of those checksums to
4920 the local output file C<sumsfile>.
4922 This can be used for verifying the integrity of a virtual
4923 machine. However to be properly secure you should pay
4924 attention to the output of the checksum command (it uses
4925 the ones from GNU coreutils). In particular when the
4926 filename is not printable, coreutils uses a special
4927 backslash syntax. For more information, see the GNU
4928 coreutils info file.");
4930 ("fill_pattern", (RErr, [String "pattern"; Int "len"; Pathname "path"], []), 245, [Progress],
4931 [InitBasicFS, Always, TestOutputBuffer (
4932 [["fill_pattern"; "abcdefghijklmnopqrstuvwxyz"; "28"; "/test"];
4933 ["read_file"; "/test"]], "abcdefghijklmnopqrstuvwxyzab")],
4934 "fill a file with a repeating pattern of bytes",
4936 This function is like C<guestfs_fill> except that it creates
4937 a new file of length C<len> containing the repeating pattern
4938 of bytes in C<pattern>. The pattern is truncated if necessary
4939 to ensure the length of the file is exactly C<len> bytes.");
4941 ("write", (RErr, [Pathname "path"; BufferIn "content"], []), 246, [ProtocolLimitWarning],
4942 [InitBasicFS, Always, TestOutput (
4943 [["write"; "/new"; "new file contents"];
4944 ["cat"; "/new"]], "new file contents");
4945 InitBasicFS, Always, TestOutput (
4946 [["write"; "/new"; "\nnew file contents\n"];
4947 ["cat"; "/new"]], "\nnew file contents\n");
4948 InitBasicFS, Always, TestOutput (
4949 [["write"; "/new"; "\n\n"];
4950 ["cat"; "/new"]], "\n\n");
4951 InitBasicFS, Always, TestOutput (
4952 [["write"; "/new"; ""];
4953 ["cat"; "/new"]], "");
4954 InitBasicFS, Always, TestOutput (
4955 [["write"; "/new"; "\n\n\n"];
4956 ["cat"; "/new"]], "\n\n\n");
4957 InitBasicFS, Always, TestOutput (
4958 [["write"; "/new"; "\n"];
4959 ["cat"; "/new"]], "\n")],
4960 "create a new file",
4962 This call creates a file called C<path>. The content of the
4963 file is the string C<content> (which can contain any 8 bit data).");
4965 ("pwrite", (RInt "nbytes", [Pathname "path"; BufferIn "content"; Int64 "offset"], []), 247, [ProtocolLimitWarning],
4966 [InitBasicFS, Always, TestOutput (
4967 [["write"; "/new"; "new file contents"];
4968 ["pwrite"; "/new"; "data"; "4"];
4969 ["cat"; "/new"]], "new data contents");
4970 InitBasicFS, Always, TestOutput (
4971 [["write"; "/new"; "new file contents"];
4972 ["pwrite"; "/new"; "is extended"; "9"];
4973 ["cat"; "/new"]], "new file is extended");
4974 InitBasicFS, Always, TestOutput (
4975 [["write"; "/new"; "new file contents"];
4976 ["pwrite"; "/new"; ""; "4"];
4977 ["cat"; "/new"]], "new file contents")],
4978 "write to part of a file",
4980 This command writes to part of a file. It writes the data
4981 buffer C<content> to the file C<path> starting at offset C<offset>.
4983 This command implements the L<pwrite(2)> system call, and like
4984 that system call it may not write the full data requested. The
4985 return value is the number of bytes that were actually written
4986 to the file. This could even be 0, although short writes are
4987 unlikely for regular files in ordinary circumstances.
4989 See also C<guestfs_pread>, C<guestfs_pwrite_device>.");
4991 ("resize2fs_size", (RErr, [Device "device"; Int64 "size"], []), 248, [],
4993 "resize an ext2, ext3 or ext4 filesystem (with size)",
4995 This command is the same as C<guestfs_resize2fs> except that it
4996 allows you to specify the new size (in bytes) explicitly.");
4998 ("pvresize_size", (RErr, [Device "device"; Int64 "size"], []), 249, [Optional "lvm2"],
5000 "resize an LVM physical volume (with size)",
5002 This command is the same as C<guestfs_pvresize> except that it
5003 allows you to specify the new size (in bytes) explicitly.");
5005 ("ntfsresize_size", (RErr, [Device "device"; Int64 "size"], []), 250, [Optional "ntfsprogs"],
5007 "resize an NTFS filesystem (with size)",
5009 This command is the same as C<guestfs_ntfsresize> except that it
5010 allows you to specify the new size (in bytes) explicitly.");
5012 ("available_all_groups", (RStringList "groups", [], []), 251, [],
5013 [InitNone, Always, TestRun [["available_all_groups"]]],
5014 "return a list of all optional groups",
5016 This command returns a list of all optional groups that this
5017 daemon knows about. Note this returns both supported and unsupported
5018 groups. To find out which ones the daemon can actually support
5019 you have to call C<guestfs_available> on each member of the
5022 See also C<guestfs_available> and L<guestfs(3)/AVAILABILITY>.");
5024 ("fallocate64", (RErr, [Pathname "path"; Int64 "len"], []), 252, [],
5025 [InitBasicFS, Always, TestOutputStruct (
5026 [["fallocate64"; "/a"; "1000000"];
5027 ["stat"; "/a"]], [CompareWithInt ("size", 1_000_000)])],
5028 "preallocate a file in the guest filesystem",
5030 This command preallocates a file (containing zero bytes) named
5031 C<path> of size C<len> bytes. If the file exists already, it
5034 Note that this call allocates disk blocks for the file.
5035 To create a sparse file use C<guestfs_truncate_size> instead.
5037 The deprecated call C<guestfs_fallocate> does the same,
5038 but owing to an oversight it only allowed 30 bit lengths
5039 to be specified, effectively limiting the maximum size
5040 of files created through that call to 1GB.
5042 Do not confuse this with the guestfish-specific
5043 C<alloc> and C<sparse> commands which create
5044 a file in the host and attach it as a device.");
5046 ("vfs_label", (RString "label", [Device "device"], []), 253, [],
5047 [InitBasicFS, Always, TestOutput (
5048 [["set_e2label"; "/dev/sda1"; "LTEST"];
5049 ["vfs_label"; "/dev/sda1"]], "LTEST")],
5050 "get the filesystem label",
5052 This returns the filesystem label of the filesystem on
5055 If the filesystem is unlabeled, this returns the empty string.
5057 To find a filesystem from the label, use C<guestfs_findfs_label>.");
5059 ("vfs_uuid", (RString "uuid", [Device "device"], []), 254, [],
5060 (let uuid = uuidgen () in
5061 [InitBasicFS, Always, TestOutput (
5062 [["set_e2uuid"; "/dev/sda1"; uuid];
5063 ["vfs_uuid"; "/dev/sda1"]], uuid)]),
5064 "get the filesystem UUID",
5066 This returns the filesystem UUID of the filesystem on
5069 If the filesystem does not have a UUID, this returns the empty string.
5071 To find a filesystem from the UUID, use C<guestfs_findfs_uuid>.");
5073 ("lvm_set_filter", (RErr, [DeviceList "devices"], []), 255, [Optional "lvm2"],
5074 (* Can't be tested with the current framework because
5075 * the VG is being used by the mounted filesystem, so
5076 * the vgchange -an command we do first will fail.
5079 "set LVM device filter",
5081 This sets the LVM device filter so that LVM will only be
5082 able to \"see\" the block devices in the list C<devices>,
5083 and will ignore all other attached block devices.
5085 Where disk image(s) contain duplicate PVs or VGs, this
5086 command is useful to get LVM to ignore the duplicates, otherwise
5087 LVM can get confused. Note also there are two types
5088 of duplication possible: either cloned PVs/VGs which have
5089 identical UUIDs; or VGs that are not cloned but just happen
5090 to have the same name. In normal operation you cannot
5091 create this situation, but you can do it outside LVM, eg.
5092 by cloning disk images or by bit twiddling inside the LVM
5095 This command also clears the LVM cache and performs a volume
5098 You can filter whole block devices or individual partitions.
5100 You cannot use this if any VG is currently in use (eg.
5101 contains a mounted filesystem), even if you are not
5102 filtering out that VG.");
5104 ("lvm_clear_filter", (RErr, [], []), 256, [],
5105 [], (* see note on lvm_set_filter *)
5106 "clear LVM device filter",
5108 This undoes the effect of C<guestfs_lvm_set_filter>. LVM
5109 will be able to see every block device.
5111 This command also clears the LVM cache and performs a volume
5114 ("luks_open", (RErr, [Device "device"; Key "key"; String "mapname"], []), 257, [Optional "luks"],
5116 "open a LUKS-encrypted block device",
5118 This command opens a block device which has been encrypted
5119 according to the Linux Unified Key Setup (LUKS) standard.
5121 C<device> is the encrypted block device or partition.
5123 The caller must supply one of the keys associated with the
5124 LUKS block device, in the C<key> parameter.
5126 This creates a new block device called C</dev/mapper/mapname>.
5127 Reads and writes to this block device are decrypted from and
5128 encrypted to the underlying C<device> respectively.
5130 If this block device contains LVM volume groups, then
5131 calling C<guestfs_vgscan> followed by C<guestfs_vg_activate_all>
5132 will make them visible.");
5134 ("luks_open_ro", (RErr, [Device "device"; Key "key"; String "mapname"], []), 258, [Optional "luks"],
5136 "open a LUKS-encrypted block device read-only",
5138 This is the same as C<guestfs_luks_open> except that a read-only
5139 mapping is created.");
5141 ("luks_close", (RErr, [Device "device"], []), 259, [Optional "luks"],
5143 "close a LUKS device",
5145 This closes a LUKS device that was created earlier by
5146 C<guestfs_luks_open> or C<guestfs_luks_open_ro>. The
5147 C<device> parameter must be the name of the LUKS mapping
5148 device (ie. C</dev/mapper/mapname>) and I<not> the name
5149 of the underlying block device.");
5151 ("luks_format", (RErr, [Device "device"; Key "key"; Int "keyslot"], []), 260, [Optional "luks"; DangerWillRobinson],
5153 "format a block device as a LUKS encrypted device",
5155 This command erases existing data on C<device> and formats
5156 the device as a LUKS encrypted device. C<key> is the
5157 initial key, which is added to key slot C<slot>. (LUKS
5158 supports 8 key slots, numbered 0-7).");
5160 ("luks_format_cipher", (RErr, [Device "device"; Key "key"; Int "keyslot"; String "cipher"], []), 261, [Optional "luks"; DangerWillRobinson],
5162 "format a block device as a LUKS encrypted device",
5164 This command is the same as C<guestfs_luks_format> but
5165 it also allows you to set the C<cipher> used.");
5167 ("luks_add_key", (RErr, [Device "device"; Key "key"; Key "newkey"; Int "keyslot"], []), 262, [Optional "luks"],
5169 "add a key on a LUKS encrypted device",
5171 This command adds a new key on LUKS device C<device>.
5172 C<key> is any existing key, and is used to access the device.
5173 C<newkey> is the new key to add. C<keyslot> is the key slot
5174 that will be replaced.
5176 Note that if C<keyslot> already contains a key, then this
5177 command will fail. You have to use C<guestfs_luks_kill_slot>
5178 first to remove that key.");
5180 ("luks_kill_slot", (RErr, [Device "device"; Key "key"; Int "keyslot"], []), 263, [Optional "luks"],
5182 "remove a key from a LUKS encrypted device",
5184 This command deletes the key in key slot C<keyslot> from the
5185 encrypted LUKS device C<device>. C<key> must be one of the
5188 ("is_lv", (RBool "lvflag", [Device "device"], []), 264, [Optional "lvm2"],
5189 [InitBasicFSonLVM, IfAvailable "lvm2", TestOutputTrue (
5190 [["is_lv"; "/dev/VG/LV"]]);
5191 InitBasicFSonLVM, IfAvailable "lvm2", TestOutputFalse (
5192 [["is_lv"; "/dev/sda1"]])],
5193 "test if device is a logical volume",
5195 This command tests whether C<device> is a logical volume, and
5196 returns true iff this is the case.");
5198 ("findfs_uuid", (RString "device", [String "uuid"], []), 265, [],
5200 "find a filesystem by UUID",
5202 This command searches the filesystems and returns the one
5203 which has the given UUID. An error is returned if no such
5204 filesystem can be found.
5206 To find the UUID of a filesystem, use C<guestfs_vfs_uuid>.");
5208 ("findfs_label", (RString "device", [String "label"], []), 266, [],
5210 "find a filesystem by label",
5212 This command searches the filesystems and returns the one
5213 which has the given label. An error is returned if no such
5214 filesystem can be found.
5216 To find the label of a filesystem, use C<guestfs_vfs_label>.");
5218 ("is_chardev", (RBool "flag", [Pathname "path"], []), 267, [],
5219 [InitISOFS, Always, TestOutputFalse (
5220 [["is_chardev"; "/directory"]]);
5221 InitBasicFS, Always, TestOutputTrue (
5222 [["mknod_c"; "0o777"; "99"; "66"; "/test"];
5223 ["is_chardev"; "/test"]])],
5224 "test if character device",
5226 This returns C<true> if and only if there is a character device
5227 with the given C<path> name.
5229 See also C<guestfs_stat>.");
5231 ("is_blockdev", (RBool "flag", [Pathname "path"], []), 268, [],
5232 [InitISOFS, Always, TestOutputFalse (
5233 [["is_blockdev"; "/directory"]]);
5234 InitBasicFS, Always, TestOutputTrue (
5235 [["mknod_b"; "0o777"; "99"; "66"; "/test"];
5236 ["is_blockdev"; "/test"]])],
5237 "test if block device",
5239 This returns C<true> if and only if there is a block device
5240 with the given C<path> name.
5242 See also C<guestfs_stat>.");
5244 ("is_fifo", (RBool "flag", [Pathname "path"], []), 269, [],
5245 [InitISOFS, Always, TestOutputFalse (
5246 [["is_fifo"; "/directory"]]);
5247 InitBasicFS, Always, TestOutputTrue (
5248 [["mkfifo"; "0o777"; "/test"];
5249 ["is_fifo"; "/test"]])],
5250 "test if FIFO (named pipe)",
5252 This returns C<true> if and only if there is a FIFO (named pipe)
5253 with the given C<path> name.
5255 See also C<guestfs_stat>.");
5257 ("is_symlink", (RBool "flag", [Pathname "path"], []), 270, [],
5258 [InitISOFS, Always, TestOutputFalse (
5259 [["is_symlink"; "/directory"]]);
5260 InitISOFS, Always, TestOutputTrue (
5261 [["is_symlink"; "/abssymlink"]])],
5262 "test if symbolic link",
5264 This returns C<true> if and only if there is a symbolic link
5265 with the given C<path> name.
5267 See also C<guestfs_stat>.");
5269 ("is_socket", (RBool "flag", [Pathname "path"], []), 271, [],
5270 (* XXX Need a positive test for sockets. *)
5271 [InitISOFS, Always, TestOutputFalse (
5272 [["is_socket"; "/directory"]])],
5275 This returns C<true> if and only if there is a Unix domain socket
5276 with the given C<path> name.
5278 See also C<guestfs_stat>.");
5280 ("part_to_dev", (RString "device", [Device "partition"], []), 272, [],
5281 [InitPartition, Always, TestOutputDevice (
5282 [["part_to_dev"; "/dev/sda1"]], "/dev/sda");
5283 InitEmpty, Always, TestLastFail (
5284 [["part_to_dev"; "/dev/sda"]])],
5285 "convert partition name to device name",
5287 This function takes a partition name (eg. \"/dev/sdb1\") and
5288 removes the partition number, returning the device name
5291 The named partition must exist, for example as a string returned
5292 from C<guestfs_list_partitions>.");
5294 ("upload_offset", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"; Int64 "offset"], []), 273, [],
5295 (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in
5296 [InitBasicFS, Always, TestOutput (
5297 [["upload_offset"; "../COPYING.LIB"; "/COPYING.LIB"; "0"];
5298 ["checksum"; "md5"; "/COPYING.LIB"]], md5)]),
5299 "upload a file from the local machine with offset",
5301 Upload local file C<filename> to C<remotefilename> on the
5304 C<remotefilename> is overwritten starting at the byte C<offset>
5305 specified. The intention is to overwrite parts of existing
5306 files or devices, although if a non-existant file is specified
5307 then it is created with a \"hole\" before C<offset>. The
5308 size of the data written is implicit in the size of the
5311 Note that there is no limit on the amount of data that
5312 can be uploaded with this call, unlike with C<guestfs_pwrite>,
5313 and this call always writes the full amount unless an
5316 See also C<guestfs_upload>, C<guestfs_pwrite>.");
5318 ("download_offset", (RErr, [Dev_or_Path "remotefilename"; FileOut "filename"; Int64 "offset"; Int64 "size"], []), 274, [Progress],
5319 (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in
5320 let offset = string_of_int 100 in
5321 let size = string_of_int ((Unix.stat "COPYING.LIB").Unix.st_size - 100) in
5322 [InitBasicFS, Always, TestOutput (
5323 (* Pick a file from cwd which isn't likely to change. *)
5324 [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
5325 ["download_offset"; "/COPYING.LIB"; "testdownload.tmp"; offset; size];
5326 ["upload_offset"; "testdownload.tmp"; "/COPYING.LIB"; offset];
5327 ["checksum"; "md5"; "/COPYING.LIB"]], md5)]),
5328 "download a file to the local machine with offset and size",
5330 Download file C<remotefilename> and save it as C<filename>
5331 on the local machine.
5333 C<remotefilename> is read for C<size> bytes starting at C<offset>
5334 (this region must be within the file or device).
5336 Note that there is no limit on the amount of data that
5337 can be downloaded with this call, unlike with C<guestfs_pread>,
5338 and this call always reads the full amount unless an
5341 See also C<guestfs_download>, C<guestfs_pread>.");
5343 ("pwrite_device", (RInt "nbytes", [Device "device"; BufferIn "content"; Int64 "offset"], []), 275, [ProtocolLimitWarning],
5344 [InitPartition, Always, TestOutputList (
5345 [["pwrite_device"; "/dev/sda"; "\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000"; "446"];
5346 ["blockdev_rereadpt"; "/dev/sda"];
5347 ["list_partitions"]], [])],
5348 "write to part of a device",
5350 This command writes to part of a device. It writes the data
5351 buffer C<content> to C<device> starting at offset C<offset>.
5353 This command implements the L<pwrite(2)> system call, and like
5354 that system call it may not write the full data requested
5355 (although short writes to disk devices and partitions are
5356 probably impossible with standard Linux kernels).
5358 See also C<guestfs_pwrite>.");
5360 ("pread_device", (RBufferOut "content", [Device "device"; Int "count"; Int64 "offset"], []), 276, [ProtocolLimitWarning],
5361 [InitEmpty, Always, TestOutputBuffer (
5362 [["pread_device"; "/dev/sdd"; "8"; "32768"]], "\001CD001\001\000")],
5363 "read part of a device",
5365 This command lets you read part of a file. It reads C<count>
5366 bytes of C<device>, starting at C<offset>.
5368 This may read fewer bytes than requested. For further details
5369 see the L<pread(2)> system call.
5371 See also C<guestfs_pread>.");
5373 ("lvm_canonical_lv_name", (RString "lv", [Device "lvname"], []), 277, [],
5374 [InitBasicFSonLVM, IfAvailable "lvm2", TestOutput (
5375 [["lvm_canonical_lv_name"; "/dev/mapper/VG-LV"]], "/dev/VG/LV");
5376 InitBasicFSonLVM, IfAvailable "lvm2", TestOutput (
5377 [["lvm_canonical_lv_name"; "/dev/VG/LV"]], "/dev/VG/LV")],
5378 "get canonical name of an LV",
5380 This converts alternative naming schemes for LVs that you
5381 might find to the canonical name. For example, C</dev/mapper/VG-LV>
5382 is converted to C</dev/VG/LV>.
5384 This command returns an error if the C<lvname> parameter does
5385 not refer to a logical volume.
5387 See also C<guestfs_is_lv>.");
5391 let all_functions = non_daemon_functions @ daemon_functions
5393 (* In some places we want the functions to be displayed sorted
5394 * alphabetically, so this is useful:
5396 let all_functions_sorted = List.sort action_compare all_functions
5398 (* This is used to generate the src/MAX_PROC_NR file which
5399 * contains the maximum procedure number, a surrogate for the
5400 * ABI version number. See src/Makefile.am for the details.
5403 let proc_nrs = List.map (
5404 fun (_, _, proc_nr, _, _, _, _) -> proc_nr
5405 ) daemon_functions in
5406 List.fold_left max 0 proc_nrs
5408 (* Non-API meta-commands available only in guestfish.
5410 * Note (1): style, proc_nr and tests fields are all meaningless.
5411 * The only fields which are actually used are the shortname,
5412 * FishAlias flags, shortdesc and longdesc.
5414 * Note (2): to refer to other commands, use L</shortname>.
5416 * Note (3): keep this list sorted by shortname.
5418 let fish_commands = [
5419 ("alloc", (RErr,[], []), -1, [FishAlias "allocate"], [],
5420 "allocate and add a disk file",
5421 " alloc filename size
5423 This creates an empty (zeroed) file of the given size, and then adds
5424 so it can be further examined.
5426 For more advanced image creation, see L<qemu-img(1)> utility.
5428 Size can be specified using standard suffixes, eg. C<1M>.
5430 To create a sparse file, use L</sparse> instead. To create a
5431 prepared disk image, see L</PREPARED DISK IMAGES>.");
5433 ("copy_in", (RErr,[], []), -1, [], [],
5434 "copy local files or directories into an image",
5435 " copy-in local [local ...] /remotedir
5437 C<copy-in> copies local files or directories recursively into the disk
5438 image, placing them in the directory called C</remotedir> (which must
5439 exist). This guestfish meta-command turns into a sequence of
5440 L</tar-in> and other commands as necessary.
5442 Multiple local files and directories can be specified, but the last
5443 parameter must always be a remote directory. Wildcards cannot be
5446 ("copy_out", (RErr,[], []), -1, [], [],
5447 "copy remote files or directories out of an image",
5448 " copy-out remote [remote ...] localdir
5450 C<copy-out> copies remote files or directories recursively out of the
5451 disk image, placing them on the host disk in a local directory called
5452 C<localdir> (which must exist). This guestfish meta-command turns
5453 into a sequence of L</download>, L</tar-out> and other commands as
5456 Multiple remote files and directories can be specified, but the last
5457 parameter must always be a local directory. To download to the
5458 current directory, use C<.> as in:
5462 Wildcards cannot be used in the ordinary command, but you can use
5463 them with the help of L</glob> like this:
5465 glob copy-out /home/* .");
5467 ("echo", (RErr,[], []), -1, [], [],
5468 "display a line of text",
5471 This echos the parameters to the terminal.");
5473 ("edit", (RErr,[], []), -1, [FishAlias "vi"; FishAlias "emacs"], [],
5477 This is used to edit a file. It downloads the file, edits it
5478 locally using your editor, then uploads the result.
5480 The editor is C<$EDITOR>. However if you use the alternate
5481 commands C<vi> or C<emacs> you will get those corresponding
5484 ("glob", (RErr,[], []), -1, [], [],
5485 "expand wildcards in command",
5486 " glob command args...
5488 Expand wildcards in any paths in the args list, and run C<command>
5489 repeatedly on each matching path.
5491 See L</WILDCARDS AND GLOBBING>.");
5493 ("hexedit", (RErr,[], []), -1, [], [],
5494 "edit with a hex editor",
5495 " hexedit <filename|device>
5496 hexedit <filename|device> <max>
5497 hexedit <filename|device> <start> <max>
5499 Use hexedit (a hex editor) to edit all or part of a binary file
5502 This command works by downloading potentially the whole file or
5503 device, editing it locally, then uploading it. If the file or
5504 device is large, you have to specify which part you wish to edit
5505 by using C<max> and/or C<start> C<max> parameters.
5506 C<start> and C<max> are specified in bytes, with the usual
5507 modifiers allowed such as C<1M> (1 megabyte).
5509 For example to edit the first few sectors of a disk you
5514 which would allow you to edit anywhere within the first megabyte
5517 To edit the superblock of an ext2 filesystem on C</dev/sda1>, do:
5519 hexedit /dev/sda1 0x400 0x400
5521 (assuming the superblock is in the standard location).
5523 This command requires the external L<hexedit(1)> program. You
5524 can specify another program to use by setting the C<HEXEDITOR>
5525 environment variable.
5527 See also L</hexdump>.");
5529 ("lcd", (RErr,[], []), -1, [], [],
5530 "change working directory",
5533 Change the local directory, ie. the current directory of guestfish
5536 Note that C<!cd> won't do what you might expect.");
5538 ("man", (RErr,[], []), -1, [FishAlias "manual"], [],
5542 Opens the manual page for guestfish.");
5544 ("more", (RErr,[], []), -1, [FishAlias "less"], [],
5550 This is used to view a file.
5552 The default viewer is C<$PAGER>. However if you use the alternate
5553 command C<less> you will get the C<less> command specifically.");
5555 ("reopen", (RErr,[], []), -1, [], [],
5556 "close and reopen libguestfs handle",
5559 Close and reopen the libguestfs handle. It is not necessary to use
5560 this normally, because the handle is closed properly when guestfish
5561 exits. However this is occasionally useful for testing.");
5563 ("sparse", (RErr,[], []), -1, [], [],
5564 "create a sparse disk image and add",
5565 " sparse filename size
5567 This creates an empty sparse file of the given size, and then adds
5568 so it can be further examined.
5570 In all respects it works the same as the L</alloc> command, except that
5571 the image file is allocated sparsely, which means that disk blocks are
5572 not assigned to the file until they are needed. Sparse disk files
5573 only use space when written to, but they are slower and there is a
5574 danger you could run out of real disk space during a write operation.
5576 For more advanced image creation, see L<qemu-img(1)> utility.
5578 Size can be specified using standard suffixes, eg. C<1M>.");
5580 ("supported", (RErr,[], []), -1, [], [],
5581 "list supported groups of commands",
5584 This command returns a list of the optional groups
5585 known to the daemon, and indicates which ones are
5586 supported by this build of the libguestfs appliance.
5588 See also L<guestfs(3)/AVAILABILITY>.");
5590 ("time", (RErr,[], []), -1, [], [],
5591 "print elapsed time taken to run a command",
5592 " time command args...
5594 Run the command as usual, but print the elapsed time afterwards. This
5595 can be useful for benchmarking operations.");