Slackware.
+=item \"ttylinux\"
+
+ttylinux.
+
=item \"ubuntu\"
Ubuntu.
=back");
+ ("set_pgroup", (RErr, [Bool "pgroup"], []), -1, [FishAlias "pgroup"],
+ [],
+ "set process group flag",
+ "\
+If C<pgroup> is true, child processes are placed into
+their own process group.
+
+The practical upshot of this is that signals like C<SIGINT> (from
+users pressing C<^C>) won't be received by the child process.
+
+The default for this flag is false, because usually you want
+C<^C> to kill the subprocess.");
+
+ ("get_pgroup", (RBool "pgroup", [], []), -1, [],
+ [],
+ "get process group flag",
+ "\
+This returns the process group flag.");
+
+ ("set_smp", (RErr, [Int "smp"], []), -1, [FishAlias "smp"],
+ [],
+ "set number of virtual CPUs in appliance",
+ "\
+Change the number of virtual CPUs assigned to the appliance. The
+default is C<1>. Increasing this may improve performance, though
+often it has no effect.
+
+This function must be called before C<guestfs_launch>.");
+
+ ("get_smp", (RInt "smp", [], []), -1, [],
+ [],
+ "get number of virtual CPUs in appliance",
+ "\
+This returns the number of virtual CPUs assigned to the appliance.");
+
]
(* daemon_functions are any functions which cause some action
*)
let daemon_functions = [
- ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [DeprecatedBy "mount_options"],
+ ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [],
[InitEmpty, Always, TestOutput (
[["part_disk"; "/dev/sda"; "mbr"];
["mkfs"; "ext2"; "/dev/sda1"];
The mounted filesystem is writable, if we have sufficient permissions
on the underlying device.
-B<Important note:>
-When you use this call, the filesystem options C<sync> and C<noatime>
-are set implicitly. This was originally done because we thought it
-would improve reliability, but it turns out that I<-o sync> has a
-very large negative performance impact and negligible effect on
-reliability. Therefore we recommend that you avoid using
-C<guestfs_mount> in any code that needs performance, and instead
-use C<guestfs_mount_options> (use an empty string for the first
-parameter if you don't want any options).");
+Before libguestfs 1.13.16, this call implicitly added the options
+C<sync> and C<noatime>. The C<sync> option greatly slowed
+writes and caused many problems for users. If your program
+might need to work with older versions of libguestfs, use
+C<guestfs_mount_options> instead (using an empty string for the
+first parameter if you don't want any options).");
("sync", (RErr, [], []), 2, [],
[ InitEmpty, Always, TestRun [["sync"]]],
=item C<AUG_TYPE_CHECK> = 4
-Typecheck lenses (can be expensive).
+Typecheck lenses.
+
+This option is only useful when debugging Augeas lenses. Use
+of this option may require additional memory for the libguestfs
+appliance. You may need to set the C<LIBGUESTFS_MEMSIZE>
+environment variable or call C<guestfs_set_memsize>.
=item C<AUG_NO_STDINC> = 8
to securely wipe the device). It should be sufficient to remove
any partition tables, filesystem superblocks and so on.
+If blocks are already zero, then this command avoids writing
+zeroes. This prevents the underlying device from becoming non-sparse
+or growing unnecessarily.
+
See also: C<guestfs_zero_device>, C<guestfs_scrub_device>,
C<guestfs_is_zero_device>");
- ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [],
+ ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [Optional "grub"],
(* See:
* https://bugzilla.redhat.com/show_bug.cgi?id=484986
* https://bugzilla.redhat.com/show_bug.cgi?id=479760
["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
["grub_install"; "/"; "/dev/vda"];
["is_dir"; "/boot"]])],
- "install GRUB",
+ "install GRUB 1",
"\
-This command installs GRUB (the Grand Unified Bootloader) on
+This command installs GRUB 1 (the Grand Unified Bootloader) on
C<device>, with the root directory being C<root>.
-Note: If grub-install reports the error
+Notes:
+
+=over 4
+
+=item *
+
+There is currently no way in the API to install grub2, which
+is used by most modern Linux guests. It is possible to run
+the grub2 command from the guest, although see the
+caveats in L<guestfs(3)/RUNNING COMMANDS>.
+
+=item *
+
+This uses C<grub-install> from the host. Unfortunately grub is
+not always compatible with itself, so this only works in rather
+narrow circumstances. Careful testing with each guest version
+is advisable.
+
+=item *
+
+If grub-install reports the error
\"No suitable drive was found in the generated device map.\"
it may be that you need to create a C</boot/grub/device.map>
file first that contains the mapping between grub device names
(hd0) /dev/vda
-replacing C</dev/vda> with the name of the installation device.");
+replacing C</dev/vda> with the name of the installation device.
+
+=back");
("cp", (RErr, [Pathname "src"; Pathname "dest"], []), 87, [],
[InitScratchFS, Always, TestOutput (
=over 4
-=item B<efi> | B<gpt>
+=item B<efi>
+
+=item B<gpt>
Intel EFI / GPT partition table.
from Linux and Intel-based Mac OS X. It also has limited backwards
compatibility with the C<mbr> format.
-=item B<mbr> | B<msdos>
+=item B<mbr>
+
+=item B<msdos>
The standard PC \"Master Boot Record\" (MBR) format used
by MS-DOS and Windows. This partition type will B<only> work
AIX disk labels.
-=item B<amiga> | B<rdb>
+=item B<amiga>
+
+=item B<rdb>
Amiga \"Rigid Disk Block\" format.
"\
This command writes zeroes over the entire C<device>. Compare
with C<guestfs_zero> which just zeroes the first few blocks of
-a device.");
+a device.
+
+If blocks are already zero, then this command avoids writing
+zeroes. This prevents the underlying device from becoming non-sparse
+or growing unnecessarily.");
("txz_in", (RErr, [FileIn "tarball"; Pathname "directory"], []), 229, [Optional "xz"],
[InitScratchFS, Always, TestOutput (
This command packs the contents of C<directory> and downloads
it to local file C<tarball> (as an xz compressed tar archive).");
- ("ntfsresize", (RErr, [Device "device"], []), 231, [Optional "ntfsprogs"],
+ ("ntfsresize", (RErr, [Device "device"], []), 231, [Optional "ntfsprogs"; DeprecatedBy "ntfsresize_opts"],
[],
"resize an NTFS filesystem",
"\
This command resizes an NTFS filesystem, expanding or
shrinking it to the size of the underlying device.
+
+I<Note:> After the resize operation, the filesystem is marked
+as requiring a consistency check (for safety). You have to boot
+into Windows to perform this check and clear this condition.
+Furthermore, ntfsresize refuses to resize filesystems
+which have been marked in this way. So in effect it is
+not possible to call ntfsresize multiple times on a single
+filesystem without booting into Windows between each resize.
+
See also L<ntfsresize(8)>.");
("vgscan", (RErr, [], []), 232, [],
"create a new file",
"\
This call creates a file called C<path>. The content of the
-file is the string C<content> (which can contain any 8 bit data).");
+file is the string C<content> (which can contain any 8 bit data).
+
+See also C<guestfs_write_append>.");
("pwrite", (RInt "nbytes", [Pathname "path"; BufferIn "content"; Int64 "offset"], []), 247, [ProtocolLimitWarning],
[InitScratchFS, Always, TestOutput (
This command is the same as C<guestfs_pvresize> except that it
allows you to specify the new size (in bytes) explicitly.");
- ("ntfsresize_size", (RErr, [Device "device"; Int64 "size"], []), 250, [Optional "ntfsprogs"],
+ ("ntfsresize_size", (RErr, [Device "device"; Int64 "size"], []), 250, [Optional "ntfsprogs"; DeprecatedBy "ntfsresize_opts"],
[],
"resize an NTFS filesystem (with size)",
"\
If this block device contains LVM volume groups, then
calling C<guestfs_vgscan> followed by C<guestfs_vg_activate_all>
-will make them visible.");
+will make them visible.
+
+Use C<guestfs_list_dm_devices> to list all device mapper
+devices.");
("luks_open_ro", (RErr, [Device "device"; Key "key"; String "mapname"], []), 258, [Optional "luks"],
[],
Any other options required can be passed in the optional C<options>
parameter.");
+ ("list_dm_devices", (RStringList "devices", [], []), 287, [],
+ [],
+ "list device mapper devices",
+ "\
+List all device mapper devices.
+
+The returned list contains C</dev/mapper/*> devices, eg. ones created
+by a previous call to C<guestfs_luks_open>.
+
+Device mapper devices which correspond to logical volumes are I<not>
+returned in this list. Call C<guestfs_lvs> if you want to list logical
+volumes.");
+
+ ("ntfsresize_opts", (RErr, [Device "device"], [Int64 "size"; Bool "force"]), 288, [Optional "ntfsprogs"],
+ [],
+ "resize an NTFS filesystem",
+ "\
+This command resizes an NTFS filesystem, expanding or
+shrinking it to the size of the underlying device.
+
+The optional parameters are:
+
+=over 4
+
+=item C<size>
+
+The new size (in bytes) of the filesystem. If omitted, the filesystem
+is resized to fit the container (eg. partition).
+
+=item C<force>
+
+If this option is true, then force the resize of the filesystem
+even if the filesystem is marked as requiring a consistency check.
+
+After the resize operation, the filesystem is always marked
+as requiring a consistency check (for safety). You have to boot
+into Windows to perform this check and clear this condition.
+If you I<don't> set the C<force> option then it is not
+possible to call C<guestfs_ntfsresize_opts> multiple times on a
+single filesystem without booting into Windows between each resize.
+
+=back
+
+See also L<ntfsresize(8)>.");
+
+ ("btrfs_filesystem_resize", (RErr, [Pathname "mountpoint"], [Int64 "size"]), 289, [Optional "btrfs"],
+ [],
+ "resize a btrfs filesystem",
+ "\
+This command resizes a btrfs filesystem.
+
+Note that unlike other resize calls, the filesystem has to be
+mounted and the parameter is the mountpoint not the device
+(this is a requirement of btrfs itself).
+
+The optional parameters are:
+
+=over 4
+
+=item C<size>
+
+The new size (in bytes) of the filesystem. If omitted, the filesystem
+is resized to the maximum size.
+
+=back
+
+See also L<btrfs(8)>.");
+
+ ("write_append", (RErr, [Pathname "path"; BufferIn "content"], []), 290, [ProtocolLimitWarning],
+ [InitScratchFS, Always, TestOutput (
+ [["write"; "/write_append"; "line1\n"];
+ ["write_append"; "/write_append"; "line2\n"];
+ ["write_append"; "/write_append"; "line3a"];
+ ["write_append"; "/write_append"; "line3b\n"];
+ ["cat"; "/write_append"]], "line1\nline2\nline3aline3b\n")],
+ "append content to end of file",
+ "\
+This call appends C<content> to the end of file C<path>. If
+C<path> does not exist, then a new file is created.
+
+See also C<guestfs_write>.");
+
+ ("compress_out", (RErr, [String "ctype"; Pathname "file"; FileOut "zfile"], [Int "level"]), 291, [],
+ [],
+ "output compressed file",
+ "\
+This command compresses C<file> and writes it out to the local
+file C<zfile>.
+
+The compression program used is controlled by the C<ctype> parameter.
+Currently this includes: C<compress>, C<gzip>, C<bzip2>, C<xz> or C<lzop>.
+Some compression types may not be supported by particular builds of
+libguestfs, in which case you will get an error containing the
+substring \"not supported\".
+
+The optional C<level> parameter controls compression level. The
+meaning and default for this parameter depends on the compression
+program being used.");
+
+ ("compress_device_out", (RErr, [String "ctype"; Device "device"; FileOut "zdevice"], [Int "level"]), 292, [],
+ [],
+ "output compressed device",
+ "\
+This command compresses C<device> and writes it out to the local
+file C<zdevice>.
+
+The C<ctype> and optional C<level> parameters have the same meaning
+as in C<guestfs_compress_out>.");
+
]
let all_functions = non_daemon_functions @ daemon_functions
this normally, because the handle is closed properly when guestfish
exits. However this is occasionally useful for testing.");
+ ("setenv", (RErr,[], []), -1, [], [],
+ "set an environment variable",
+ " setenv VAR value
+
+Set the environment variable C<VAR> to the string C<value>.
+
+To print the value of an environment variable use a shell command
+such as:
+
+ !echo $VAR");
+
("sparse", (RErr,[], []), -1, [], [],
"create a sparse disk image and add",
" sparse filename size
Run the command as usual, but print the elapsed time afterwards. This
can be useful for benchmarking operations.");
+ ("unsetenv", (RErr,[], []), -1, [], [],
+ "unset an environment variable",
+ " unsetenv VAR
+
+Remove C<VAR> from the environment.");
+
]