[],
"get type of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the type of the inspected operating system.
Currently defined types are:
[],
"get architecture of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the architecture of the inspected operating system.
The possible return values are listed under
C<guestfs_file_architecture>.
[],
"get distro of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the distro (distribution) of the inspected operating
system.
[],
"get major version of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the major version number of the inspected operating
system.
[],
"get minor version of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the minor version number of the inspected operating
system.
[],
"get product name of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the product name of the inspected operating
system. The product name is generally some freeform string
which can be displayed to the user, but should not be
[],
"get mountpoints of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns a hash of where we think the filesystems
associated with this operating system should be mounted.
Callers should note that this is at best an educated guess
[],
"get filesystems associated with inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns a list of all the filesystems that we think
are associated with this operating system. This includes
the root filesystem, other ordinary filesystems, and
[],
"get Windows systemroot of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the Windows systemroot of the inspected guest.
The systemroot is a directory path such as C</WINDOWS>.
[],
"get package format used by the operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This function and C<guestfs_inspect_get_package_management> return
the package format and package management tool used by the
inspected operating system. For example for Fedora these
[],
"get package management tool used by the operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
C<guestfs_inspect_get_package_format> and this function return
the package format and package management tool used by the
inspected operating system. For example for Fedora these
[],
"get list of applications installed in the operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
Return the list of applications installed in the operating system.
I<Note:> This call works differently from other parts of the
[],
"get hostname of the operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This function returns the hostname of the operating system
as found by inspection of the guest's configuration files.
[],
"get format of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the format of the inspected operating system. You
can use it to detect install images, live CDs and similar.
[],
"get live flag for install disk",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
If C<guestfs_inspect_get_format> returns C<installer> (this
is an install disk), then this returns true if a live image
was detected on the disk.
[],
"get netinst (network installer) flag for install disk",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
If C<guestfs_inspect_get_format> returns C<installer> (this
is an install disk), then this returns true if the disk is
a network installer, ie. not a self-contained install CD but
[],
"get multipart flag for install disk",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
If C<guestfs_inspect_get_format> returns C<installer> (this
is an install disk), then this returns true if the disk is
part of a set.
[],
"get product variant of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the product variant of the inspected operating
system.
[],
"get Windows CurrentControlSet of inspected operating system",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This returns the Windows CurrentControlSet of the inspected guest.
The CurrentControlSet is a registry key name such as C<ControlSet001>.
[],
"get drive letter mappings",
"\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
This call is useful for Windows which uses a primitive system
of assigning drive letters (like \"C:\") to partitions.
This inspection API examines the Windows Registry to find out
See also C<guestfs_inspect_get_mountpoints>,
C<guestfs_inspect_get_filesystems>.");
+ ("inspect_get_icon", (RBufferOut "icon", [Device "root"], [Bool "favicon"; Bool "highquality"]), -1, [],
+ [],
+ "get the icon corresponding to this operating system",
+ "\
+This function returns an icon corresponding to the inspected
+operating system. The icon is returned as a buffer containing a
+PNG image (re-encoded to PNG if necessary).
+
+If it was not possible to get an icon this function returns a
+zero-length (non-NULL) buffer. I<Callers must check for this case>.
+
+Libguestfs will start by looking for a file called
+C</etc/favicon.png> or C<C:\\etc\\favicon.png>
+and if it has the correct format, the contents of this file will
+be returned. You can disable favicons by passing the
+optional C<favicon> boolean as false (default is true).
+
+If finding the favicon fails, then we look in other places in the
+guest for a suitable icon.
+
+If the optional C<highquality> boolean is true then
+only high quality icons are returned, which means only icons of
+high resolution with an alpha channel. The default (false) is
+to return any icon we can, even if it is of substandard quality.
+
+Notes:
+
+=over 4
+
+=item *
+
+Unlike most other inspection API calls, the guest's disks must be
+mounted up before you call this, since it needs to read information
+from the guest filesystem during the call.
+
+=item *
+
+B<Security:> The icon data comes from the untrusted guest,
+and should be treated with caution. PNG files have been
+known to contain exploits. Ensure that libpng (or other relevant
+libraries) are fully up to date before trying to process or
+display the icon.
+
+=item *
+
+The PNG image returned can be any size. It might not be square.
+Libguestfs tries to return the largest, highest quality
+icon available. The application must scale the icon to the
+required size.
+
+=item *
+
+Extracting icons from Windows guests requires the external
+C<wrestool> program from the C<icoutils> package, and
+several programs (C<bmptopnm>, C<pnmtopng>, C<pamcut>)
+from the C<netpbm> package. These must be installed separately.
+
+=item *
+
+Operating system icons are usually trademarks. Seek legal
+advice before using trademarks in applications.
+
+=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.");
+
]
(* daemon_functions are any functions which cause some action
"\
This command activates or (if C<activate> is false) deactivates
all logical volumes in all volume groups.
-If activated, then they are made known to the
-kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
-then those devices disappear.
This command is the same as running C<vgchange -a y|n>");
"\
This command activates or (if C<activate> is false) deactivates
all logical volumes in the listed volume groups C<volgroups>.
-If activated, then they are made known to the
-kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
-then those devices disappear.
This command is the same as running C<vgchange -a y|n volgroups...>
=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 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"],
[],
See also C<guestfs_is_lv>.");
- ("mkfs_opts", (RErr, [String "fstype"; Device "device"], [Int "blocksize"; String "features"]), 278, [],
+ ("mkfs_opts", (RErr, [String "fstype"; Device "device"], [Int "blocksize"; String "features"; Int "inode"; Int "sectorsize"]), 278, [],
[InitEmpty, Always, TestOutput (
[["part_disk"; "/dev/sda"; "mbr"];
- ["mkfs_opts"; "ext2"; "/dev/sda1"; "4096"; ""];
+ ["mkfs_opts"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""];
["mount_options"; ""; "/dev/sda1"; "/"];
["write"; "/new"; "new file contents"];
["cat"; "/new"]], "new file contents")],
You cannot use this optional parameter with the C<gfs> or
C<gfs2> filesystem type.
+=item C<inode>
+
+This passes the I<-I> parameter to the external L<mke2fs(8)> program
+which sets the inode size (only for ext2/3/4 filesystems at present).
+
+=item C<sectorsize>
+
+This passes the I<-S> parameter to external L<mkfs.ufs(8)> program,
+which sets sector size for ufs filesystem.
+
=back");
("getxattr", (RBufferOut "xattr", [Pathname "path"; String "name"], []), 279, [Optional "linuxxattrs"],
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>.");
+
]
let all_functions = non_daemon_functions @ daemon_functions
glob copy-out /home/* .");
+ ("display", (RErr,[], []), -1, [], [],
+ "display an image",
+ " display filename
+
+Use C<display> (a graphical display program) to display an image
+file. It downloads the file, and runs C<display> on it.
+
+To use an alternative program, set the C<GUESTFISH_DISPLAY_IMAGE>
+environment variable. For example to use the GNOME display program:
+
+ export GUESTFISH_DISPLAY_IMAGE=eog
+
+See also L<display(1)>.");
+
("echo", (RErr,[], []), -1, [], [],
"display a line of text",
" echo [params ...]
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