X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=generator%2Fgenerator_actions.ml;h=c684e3587093aa0b9f7456292c89a96310e657e0;hp=abf3475a1b74e41400c90befe7e6da1352590baf;hb=7739d7f471f9575828bd32489695d92dde005a9c;hpb=c49fc3831d12788c27b90d12f06a1cd69a88e3be diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml index abf3475..c684e35 100644 --- a/generator/generator_actions.ml +++ b/generator/generator_actions.ml @@ -113,7 +113,7 @@ using L. You should call this after configuring the handle (eg. adding drives) but before performing any actions."); - ("wait_ready", (RErr, [], []), -1, [NotInFish], + ("wait_ready", (RErr, [], []), -1, [NotInFish; DeprecatedBy "launch"], [], "wait until the qemu subprocess launches (no op)", "\ @@ -726,9 +726,6 @@ See also C."); [], "get type of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the type of the inspected operating system. Currently defined types are: @@ -761,9 +758,6 @@ Please read L for more details."); [], "get architecture of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the architecture of the inspected operating system. The possible return values are listed under C. @@ -777,9 +771,6 @@ Please read L for more details."); [], "get distro of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the distro (distribution) of the inspected operating system. @@ -863,9 +854,6 @@ Please read L for more details."); [], "get major version of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the major version number of the inspected operating system. @@ -884,9 +872,6 @@ Please read L for more details."); [], "get minor version of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the minor version number of the inspected operating system. @@ -899,9 +884,6 @@ See also C."); [], "get product name of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - 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 @@ -916,9 +898,6 @@ Please read L for more details."); [], "get mountpoints of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - 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 @@ -949,9 +928,6 @@ See also C."); [], "get filesystems associated with inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - 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 @@ -1064,9 +1040,6 @@ deprecated C call (q.v.) [], "get Windows systemroot of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the Windows systemroot of the inspected guest. The systemroot is a directory path such as C. @@ -1096,7 +1069,7 @@ Please read L for more details."); 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."); - ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"; Bool "live"]), -1, [FishAlias "domain"], + ("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", "\ @@ -1130,6 +1103,11 @@ XML definition. The default (if the flag is omitted) is never to try. See L for more information. +If the C flag is true (default is false) then a UUID +I be passed instead of the domain name. The C string is +treated as a UUID first and looked up, and if that lookup fails +then we treat C as a name as usual. + The other optional parameters are passed directly through to C."); @@ -1173,9 +1151,6 @@ C."); [], "get package format used by the operating system", "\ -This function should only be called with a root device string -as returned by C. - This function and C return the package format and package management tool used by the inspected operating system. For example for Fedora these @@ -1195,9 +1170,6 @@ Please read L for more details."); [], "get package management tool used by the operating system", "\ -This function should only be called with a root device string -as returned by C. - C and this function return the package format and package management tool used by the inspected operating system. For example for Fedora these @@ -1219,9 +1191,6 @@ Please read L for more details."); [], "get list of applications installed in the operating system", "\ -This function should only be called with a root device string -as returned by C. - Return the list of applications installed in the operating system. I This call works differently from other parts of the @@ -1318,9 +1287,6 @@ Please read L for more details."); [], "get hostname of the operating system", "\ -This function should only be called with a root device string -as returned by C. - This function returns the hostname of the operating system as found by inspection of the guest's configuration files. @@ -1333,9 +1299,6 @@ Please read L for more details."); [], "get format of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the format of the inspected operating system. You can use it to detect install images, live CDs and similar. @@ -1367,9 +1330,6 @@ Please read L for more details."); [], "get live flag for install disk", "\ -This function should only be called with a root device string -as returned by C. - If C returns C (this is an install disk), then this returns true if a live image was detected on the disk. @@ -1380,9 +1340,6 @@ Please read L for more details."); [], "get netinst (network installer) flag for install disk", "\ -This function should only be called with a root device string -as returned by C. - If C returns C (this is an install disk), then this returns true if the disk is a network installer, ie. not a self-contained install CD but @@ -1395,9 +1352,6 @@ Please read L for more details."); [], "get multipart flag for install disk", "\ -This function should only be called with a root device string -as returned by C. - If C returns C (this is an install disk), then this returns true if the disk is part of a set. @@ -1439,9 +1393,6 @@ Return the current attach method. See C."); [], "get product variant of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the product variant of the inspected operating system. @@ -1469,9 +1420,6 @@ C."); [], "get Windows CurrentControlSet of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the Windows CurrentControlSet of the inspected guest. The CurrentControlSet is a registry key name such as C. @@ -1485,9 +1433,6 @@ Please read L for more details."); [], "get drive letter mappings", "\ -This function should only be called with a root device string -as returned by C. - 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 @@ -1517,6 +1462,89 @@ Please read L for more details. See also C, C."); + ("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. + +Libguestfs will start by looking for a file called +C or C +and if it has the correct format, the contents of this file will +be returned. You can disable favicons by passing the +optional C 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 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 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 program from the C package, and +several programs (C, C, C) +from the C 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 is true, child processes are placed into +their own process group. + +The practical upshot of this is that signals like C (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 @@ -1524,7 +1552,7 @@ C."); *) let daemon_functions = [ - ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [], + ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [DeprecatedBy "mount_options"], [InitEmpty, Always, TestOutput ( [["part_disk"; "/dev/sda"; "mbr"]; ["mkfs"; "ext2"; "/dev/sda1"]; @@ -1793,7 +1821,12 @@ do not overwrite original. Overrides C. =item C = 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 +environment variable or call C. =item C = 8 @@ -2132,7 +2165,7 @@ example C."); ("sfdisk", (RErr, [Device "device"; Int "cyls"; Int "heads"; Int "sectors"; - StringList "lines"], []), 43, [DangerWillRobinson], + StringList "lines"], []), 43, [DangerWillRobinson; DeprecatedBy "part_add"], [], "create partitions on a block device", "\ @@ -2263,15 +2296,12 @@ The exact command which runs is C. Note in particular that the filename is not prepended to the output (the I<-b> option). -This command can also be used on C devices -(and partitions, LV names). You can for example use this -to determine if a device contains a filesystem, although -it's usually better to use C. +The output depends on the output of the underlying L +command and it can change in future in ways beyond our control. +In other words, the output is not guaranteed by the ABI. -If the C does not begin with C then -this command only works for the content of regular files. -For other file types (directory, symbolic link etc) it -will just return the string C etc."); +See also: L, C, C, +C, C (etc), C."); ("command", (RString "output", [StringList "arguments"], []), 50, [ProtocolLimitWarning], [InitScratchFS, Always, TestOutput ( @@ -2965,10 +2995,9 @@ Checking or repairing NTFS volumes is not supported This command is entirely equivalent to running C."); ("zero", (RErr, [Device "device"], []), 85, [Progress], - [InitBasicFS, Always, TestOutput ( + [InitBasicFS, Always, TestRun ( [["umount"; "/dev/sda1"]; - ["zero"; "/dev/sda1"]; - ["file"; "/dev/sda1"]], "data")], + ["zero"; "/dev/sda1"]])], "write zeroes to the device", "\ This command writes zeroes over the first few blocks of C. @@ -2977,7 +3006,8 @@ How many blocks are zeroed isn't specified (but it's I enough to securely wipe the device). It should be sufficient to remove any partition tables, filesystem superblocks and so on. -See also: C, C."); +See also: C, C, +C"); ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [], (* See: @@ -3223,7 +3253,7 @@ volume to match the new size of the underlying device."); ("sfdisk_N", (RErr, [Device "device"; Int "partnum"; Int "cyls"; Int "heads"; Int "sectors"; - String "line"], []), 99, [DangerWillRobinson], + String "line"], []), 99, [DangerWillRobinson; DeprecatedBy "part_add"], [], "modify a single partition on a block device", "\ @@ -3235,7 +3265,7 @@ pass C<0> for the cyls/heads/sectors parameters. See also: C"); - ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [], + ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [DeprecatedBy "part_list"], [], "display the partition table", "\ @@ -3272,9 +3302,6 @@ be parsed."); "\ This command activates or (if C 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 devices. If deactivated, -then those devices disappear. This command is the same as running C"); @@ -3284,9 +3311,6 @@ This command is the same as running C"); "\ This command activates or (if C is false) deactivates all logical volumes in the listed volume groups C. -If activated, then they are made known to the -kernel, ie. they appear as C devices. If deactivated, -then those devices disappear. This command is the same as running C @@ -3854,7 +3878,7 @@ This function is primarily intended for use by programs. To get a simple list of names, use C. To get a printable directory for human consumption, use C."); - ("sfdiskM", (RErr, [Device "device"; StringList "lines"], []), 139, [DangerWillRobinson], + ("sfdiskM", (RErr, [Device "device"; StringList "lines"], []), 139, [DangerWillRobinson; DeprecatedBy "part_add"], [], "create partitions on a block device", "\ @@ -4824,7 +4848,9 @@ Possible values for C are: =over 4 -=item B | B +=item B + +=item B Intel EFI / GPT partition table. @@ -4832,7 +4858,9 @@ This is recommended for >= 2 TB partitions that will be accessed from Linux and Intel-based Mac OS X. It also has limited backwards compatibility with the C format. -=item B | B +=item B + +=item B The standard PC \"Master Boot Record\" (MBR) format used by MS-DOS and Windows. This partition type will B work @@ -4850,7 +4878,9 @@ supported include: AIX disk labels. -=item B | B +=item B + +=item B Amiga \"Rigid Disk Block\" format. @@ -5218,12 +5248,21 @@ I tar file) into C."); This command packs the contents of C and downloads it to local file C (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 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."); ("vgscan", (RErr, [], []), 232, [], @@ -5405,7 +5444,9 @@ to ensure the length of the file is exactly C bytes."); "create a new file", "\ This call creates a file called C. The content of the -file is the string C (which can contain any 8 bit data)."); +file is the string C (which can contain any 8 bit data). + +See also C."); ("pwrite", (RInt "nbytes", [Pathname "path"; BufferIn "content"; Int64 "offset"], []), 247, [ProtocolLimitWarning], [InitScratchFS, Always, TestOutput ( @@ -5447,7 +5488,7 @@ allows you to specify the new size (in bytes) explicitly."); This command is the same as C 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)", "\ @@ -5574,7 +5615,10 @@ encrypted to the underlying C respectively. If this block device contains LVM volume groups, then calling C followed by C -will make them visible."); +will make them visible. + +Use C to list all device mapper +devices."); ("luks_open_ro", (RErr, [Device "device"; Key "key"; String "mapname"], []), 258, [Optional "luks"], [], @@ -5832,10 +5876,10 @@ not refer to a logical volume. See also C."); - ("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")], @@ -5870,6 +5914,16 @@ for more details. You cannot use this optional parameter with the C or C filesystem type. +=item C + +This passes the I<-I> parameter to the external L program +which sets the inode size (only for ext2/3/4 filesystems at present). + +=item C + +This passes the I<-S> parameter to external L program, +which sets sector size for ufs filesystem. + =back"); ("getxattr", (RBufferOut "xattr", [Pathname "path"; String "name"], []), 279, [Optional "linuxxattrs"], @@ -5935,6 +5989,129 @@ Instead, use the autosync flag (C) to control whether or not this operation is performed when the handle is closed."); + ("is_zero", (RBool "zeroflag", [Pathname "path"], []), 283, [], + [InitISOFS, Always, TestOutputTrue ( + [["is_zero"; "/100kallzeroes"]]); + InitISOFS, Always, TestOutputFalse ( + [["is_zero"; "/100kallspaces"]])], + "test if a file contains all zero bytes", + "\ +This returns true iff the file exists and the file is empty or +it contains all zero bytes."); + + ("is_zero_device", (RBool "zeroflag", [Device "device"], []), 284, [], + [InitBasicFS, Always, TestOutputTrue ( + [["umount"; "/dev/sda1"]; + ["zero_device"; "/dev/sda1"]; + ["is_zero_device"; "/dev/sda1"]]); + InitBasicFS, Always, TestOutputFalse ( + [["is_zero_device"; "/dev/sda1"]])], + "test if a device contains all zero bytes", + "\ +This returns true iff the device exists and contains all zero bytes. + +Note that for large devices this can take a long time to run."); + + ("list_9p", (RStringList "mounttags", [], []), 285, [], + [], + "list 9p filesystems", + "\ +List all 9p filesystems attached to the guest. A list of +mount tags is returned."); + + ("mount_9p", (RErr, [String "mounttag"; String "mountpoint"], [String "options"]), 286, [], + [], + "mount 9p filesystem", + "\ +Mount the virtio-9p filesystem with the tag C on the +directory C. + +If required, C will be automatically added to the options. +Any other options required can be passed in the optional C +parameter."); + + ("list_dm_devices", (RStringList "devices", [], []), 287, [], + [], + "list device mapper devices", + "\ +List all device mapper devices. + +The returned list contains C devices, eg. ones created +by a previous call to C. + +Device mapper devices which correspond to logical volumes are I +returned in this list. Call C 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 + +The new size (in bytes) of the filesystem. If omitted, the filesystem +is resized to fit the container (eg. partition). + +=item C + +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 set the C option then it is not +possible to call C multiple times on a +single filesystem without booting into Windows between each resize. + +=back + +See also L."); + + ("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 + +The new size (in bytes) of the filesystem. If omitted, the filesystem +is resized to the maximum size. + +=back + +See also L."); + + ("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 to the end of file C. If +C does not exist, then a new file is created. + +See also C."); + ] let all_functions = non_daemon_functions @ daemon_functions @@ -6013,6 +6190,20 @@ them with the help of L like this: glob copy-out /home/* ."); + ("display", (RErr,[], []), -1, [], [], + "display an image", + " display filename + +Use C (a graphical display program) to display an image +file. It downloads the file, and runs C on it. + +To use an alternative program, set the C +environment variable. For example to use the GNOME display program: + + export GUESTFISH_DISPLAY_IMAGE=eog + +See also L."); + ("echo", (RErr,[], []), -1, [], [], "display a line of text", " echo [params ...] @@ -6109,6 +6300,17 @@ Close and reopen the libguestfs handle. It is not necessary to use 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 to the string C. + +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 @@ -6143,4 +6345,10 @@ See also L."); 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 from the environment."); + ]