FreeBSD.
+=item \"netbsd\"
+
+NetBSD.
+
=item \"unknown\"
The operating system type could not be determined.
Linux Mint.
+=item \"mageia\"
+
+Mageia.
+
=item \"mandriva\"
Mandriva.
MeeGo.
+=item \"opensuse\"
+
+OpenSUSE.
+
=item \"pardus\"
Pardus.
Slackware.
+=item \"ttylinux\"
+
+ttylinux.
+
=item \"ubuntu\"
Ubuntu.
not all belong to a single logical operating system
(use C<guestfs_inspect_os> to look for OSes).");
- ("add_drive_opts", (RErr, [String "filename"], [Bool "readonly"; String "format"; String "iface"]), -1, [FishAlias "add"],
+ ("add_drive_opts", (RErr, [String "filename"], [Bool "readonly"; String "format"; String "iface"; String "name"]), -1, [FishAlias "add"],
[],
"add an image to examine or modify",
"\
This rarely-used option lets you emulate the behaviour of the
deprecated C<guestfs_add_drive_with_if> call (q.v.)
+=item C<name>
+
+The name the drive had in the original guest, e.g. /dev/sdb. This is used as a
+hint to the guest inspection process if it is available.
+
=back");
("inspect_get_windows_systemroot", (RString "systemroot", [Device "root"], []), -1, [],
This returns the internal QEMU command line. 'debug' commands are
not part of the formal API and can be removed or changed at any time.");
+ ("debug_drives", (RStringList "cmdline", [], []), -1, [NotInDocs],
+ [],
+ "debug the drives (internal use only)",
+ "\
+This returns the internal list of drives. 'debug' commands are
+not part of the formal API and can be removed or changed at any time.");
+
("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"; Bool "live"; Bool "allowuuid"]), -1, [FishAlias "domain"],
[],
"add the disk(s) from a named libvirt domain",
package format I<or> if the operating system does not have
a real packaging system (eg. Windows).
-Possible strings include: C<rpm>, C<deb>, C<ebuild>, C<pisi>, C<pacman>.
+Possible strings include:
+C<rpm>, C<deb>, C<ebuild>, C<pisi>, C<pacman>, C<pkgsrc>.
Future versions of libguestfs may return other strings.
Please read L<guestfs(3)/INSPECTION> for more details.");
Possible strings include: C<yum>, C<up2date>,
C<apt> (for all Debian derivatives),
-C<portage>, C<pisi>, C<pacman>, C<urpmi>.
+C<portage>, C<pisi>, C<pacman>, C<urpmi>, C<zypper>.
Future versions of libguestfs may return other strings.
Please read L<guestfs(3)/INSPECTION> for more details.");
=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 (
"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 (
(eg. \"/dev/sdb\").
The named partition must exist, for example as a string returned
-from C<guestfs_list_partitions>.");
+from C<guestfs_list_partitions>.
+
+See also C<guestfs_part_to_partnum>.");
("upload_offset", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"; Int64 "offset"], []), 273, [Progress],
(let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in
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>.");
+
+ ("part_to_partnum", (RInt "partnum", [Device "partition"], []), 293, [],
+ [InitPartition, Always, TestOutputInt (
+ [["part_to_partnum"; "/dev/sda1"]], 1);
+ InitEmpty, Always, TestLastFail (
+ [["part_to_partnum"; "/dev/sda"]])],
+ "convert partition name to partition number",
+ "\
+This function takes a partition name (eg. \"/dev/sdb1\") and
+returns the partition number (eg. C<1>).
+
+The named partition must exist, for example as a string returned
+from C<guestfs_list_partitions>.
+
+See also C<guestfs_part_to_dev>.");
]
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.");
+
]
git.annexia.org / libguestfs.git / blobdiff