X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=generator%2Fgenerator_actions.ml;h=c9890a67cdad691d58b1175dbdbff0e4f1b369e6;hp=bde9e6c72c341684a3f488595693f31bf3940752;hb=6391d1a7cfa10337a75465c72d49df3c9ebc65ca;hpb=04d8209077d2227eb1d42695ba71147f78987050 diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml index bde9e6c..c9890a6 100644 --- a/generator/generator_actions.ml +++ b/generator/generator_actions.ml @@ -747,7 +747,9 @@ This function cannot decrypt encrypted disks. The caller must do that first (supplying the necessary keys) if the disk is encrypted. -Please read L for more details."); +Please read L for more details. + +See also C."); ("inspect_get_type", (RString "name", [Device "root"]), -1, [], [], @@ -955,6 +957,39 @@ it has no effect."); "\ This returns the enable network flag."); + ("list_filesystems", (RHashtable "fses", []), -1, [], + [], + "list filesystems", + "\ +This inspection command looks for filesystems on partitions, +block devices and logical volumes, returning a list of devices +containing filesystems and their type. + +The return value is a hash, where the keys are the devices +containing filesystems, and the values are the filesystem types. +For example: + + \"/dev/sda1\" => \"ntfs\" + \"/dev/sda2\" => \"ext2\" + \"/dev/vg_guest/lv_root\" => \"ext4\" + \"/dev/vg_guest/lv_swap\" => \"swap\" + +The value can have the special value \"unknown\", meaning the +content of the device is undetermined or empty. +\"swap\" means a Linux swap partition. + +This command runs other libguestfs commands, which might include +C and C, and therefore you should +use this soon after launch and only when nothing is mounted. + +Not all of the filesystems returned will be mountable. In +particular, swap partitions are returned in the list. Also +this command does not check that each filesystem +found is valid and mountable, and some filesystems might +be mountable but require special options. Filesystems may +not all belong to a single logical operating system +(use C to look for OSes)."); + ] (* daemon_functions are any functions which cause some action @@ -1064,7 +1099,9 @@ should probably use C instead."); "\ List all the block devices. -The full block device names are returned, eg. C"); +The full block device names are returned, eg. C. + +See also C."); ("list_partitions", (RStringList "partitions", []), 8, [], [InitBasicFS, Always, TestOutputListOfDevices ( @@ -1079,7 +1116,9 @@ List all the partitions detected on all block devices. The full partition device names are returned, eg. C This does not return logical volumes. For that you will need to -call C."); +call C. + +See also C."); ("pvs", (RStringList "physvols", []), 9, [Optional "lvm2"], [InitBasicFSonLVM, Always, TestOutputListOfDevices ( @@ -1143,7 +1182,7 @@ of the L command. This returns a list of the logical volume device names (eg. C). -See also C."); +See also C, C."); ("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 12, [Optional "lvm2"], [], (* XXX how to test? *) @@ -4151,7 +4190,7 @@ bytes of the file, starting at C, from file C. This may read fewer bytes than requested. For further details see the L system call. -See also C."); +See also C, C."); ("part_init", (RErr, [Device "device"; String "parttype"]), 208, [], [InitEmpty, Always, TestRun ( @@ -4632,9 +4671,9 @@ You will get undefined results for other partition table types (see C)."); ("checksum_device", (RString "checksum", [String "csumtype"; Device "device"]), 237, [], - [InitISOFS, Always, TestOutput ( + [InitISOFS, Always, TestOutputFileMD5 ( [["checksum_device"; "md5"; "/dev/sdd"]], - (Digest.to_hex (Digest.file "images/test.iso")))], + "../images/test.iso")], "compute MD5, SHAx or CRC checksum of the contents of a device", "\ This call computes the MD5, SHAx or CRC checksum of the @@ -4773,7 +4812,7 @@ return value is the number of bytes that were actually written to the file. This could even be 0, although short writes are unlikely for regular files in ordinary circumstances. -See also C."); +See also C, C."); ("resize2fs_size", (RErr, [Device "device"; Int64 "size"]), 248, [], [], @@ -5064,6 +5103,99 @@ with the given C name. See also C."); + ("part_to_dev", (RString "device", [Device "partition"]), 272, [], + [InitPartition, Always, TestOutputDevice ( + [["part_to_dev"; "/dev/sda1"]], "/dev/sda"); + InitEmpty, Always, TestLastFail ( + [["part_to_dev"; "/dev/sda"]])], + "convert partition name to device name", + "\ +This function takes a partition name (eg. \"/dev/sdb1\") and +removes the partition number, returning the device name +(eg. \"/dev/sdb\"). + +The named partition must exist, for example as a string returned +from C."); + + ("upload_offset", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"; Int64 "offset"]), 273, [], + (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in + [InitBasicFS, Always, TestOutput ( + [["upload_offset"; "../COPYING.LIB"; "/COPYING.LIB"; "0"]; + ["checksum"; "md5"; "/COPYING.LIB"]], md5)]), + "upload a file from the local machine with offset", + "\ +Upload local file C to C on the +filesystem. + +C is overwritten starting at the byte C +specified. The intention is to overwrite parts of existing +files or devices, although if a non-existant file is specified +then it is created with a \"hole\" before C. The +size of the data written is implicit in the size of the +source C. + +Note that there is no limit on the amount of data that +can be uploaded with this call, unlike with C, +and this call always writes the full amount unless an +error occurs. + +See also C, C."); + + ("download_offset", (RErr, [Dev_or_Path "remotefilename"; FileOut "filename"; Int64 "offset"; Int64 "size"]), 274, [Progress], + (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in + let offset = string_of_int 100 in + let size = string_of_int ((Unix.stat "COPYING.LIB").Unix.st_size - 100) in + [InitBasicFS, Always, TestOutput ( + (* Pick a file from cwd which isn't likely to change. *) + [["upload"; "../COPYING.LIB"; "/COPYING.LIB"]; + ["download_offset"; "/COPYING.LIB"; "testdownload.tmp"; offset; size]; + ["upload_offset"; "testdownload.tmp"; "/COPYING.LIB"; offset]; + ["checksum"; "md5"; "/COPYING.LIB"]], md5)]), + "download a file to the local machine with offset and size", + "\ +Download file C and save it as C +on the local machine. + +C is read for C bytes starting at C +(this region must be within the file or device). + +Note that there is no limit on the amount of data that +can be downloaded with this call, unlike with C, +and this call always reads the full amount unless an +error occurs. + +See also C, C."); + + ("pwrite_device", (RInt "nbytes", [Device "device"; BufferIn "content"; Int64 "offset"]), 275, [ProtocolLimitWarning], + [InitPartition, Always, TestOutputList ( + [["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"]; + ["blockdev_rereadpt"; "/dev/sda"]; + ["list_partitions"]], [])], + "write to part of a device", + "\ +This command writes to part of a device. It writes the data +buffer C to C starting at offset C. + +This command implements the L system call, and like +that system call it may not write the full data requested +(although short writes to disk devices and partitions are +probably impossible with standard Linux kernels). + +See also C."); + + ("pread_device", (RBufferOut "content", [Device "device"; Int "count"; Int64 "offset"]), 276, [ProtocolLimitWarning], + [InitEmpty, Always, TestOutputBuffer ( + [["pread_device"; "/dev/sdd"; "8"; "32768"]], "\001CD001\001\000")], + "read part of a device", + "\ +This command lets you read part of a file. It reads C +bytes of C, starting at C. + +This may read fewer bytes than requested. For further details +see the L system call. + +See also C."); + ] let all_functions = non_daemon_functions @ daemon_functions @@ -5071,9 +5203,7 @@ let all_functions = non_daemon_functions @ daemon_functions (* In some places we want the functions to be displayed sorted * alphabetically, so this is useful: *) -let all_functions_sorted = - List.sort (fun (n1,_,_,_,_,_,_) (n2,_,_,_,_,_,_) -> - compare n1 n2) all_functions +let all_functions_sorted = List.sort action_compare all_functions (* This is used to generate the src/MAX_PROC_NR file which * contains the maximum procedure number, a surrogate for the @@ -5084,3 +5214,194 @@ let max_proc_nr = fun (_, _, proc_nr, _, _, _, _) -> proc_nr ) daemon_functions in List.fold_left max 0 proc_nrs + +(* Non-API meta-commands available only in guestfish. + * + * Note (1): args/return value, proc_nr and tests fields are all + * meaningless. The only fields which are actually used are the + * shortname, FishAlias flags, shortdesc and longdesc. + * + * Note (2): to refer to other commands, use L. + * + * Note (3): keep this list sorted by shortname. + *) +let fish_commands = [ + ("alloc", (RErr,[]), -1, [FishAlias "allocate"], [], + "allocate and add a disk file", + " alloc filename size + +This creates an empty (zeroed) file of the given size, and then adds +so it can be further examined. + +For more advanced image creation, see L utility. + +Size can be specified using standard suffixes, eg. C<1M>. + +To create a sparse file, use L instead. To create a +prepared disk image, see L."); + + ("copy_in", (RErr,[]), -1, [], [], + "copy local files or directories into an image", + " copy-in local [local ...] /remotedir + +C copies local files or directories recursively into the disk +image, placing them in the directory called C (which must +exist). This guestfish meta-command turns into a sequence of +L and other commands as necessary. + +Multiple local files and directories can be specified, but the last +parameter must always be a remote directory. Wildcards cannot be +used."); + + ("copy_out", (RErr,[]), -1, [], [], + "copy remote files or directories out of an image", + " copy-out remote [remote ...] localdir + +C copies remote files or directories recursively out of the +disk image, placing them on the host disk in a local directory called +C (which must exist). This guestfish meta-command turns +into a sequence of L, L and other commands as +necessary. + +Multiple remote files and directories can be specified, but the last +parameter must always be a local directory. To download to the +current directory, use C<.> as in: + + copy-out /home . + +Wildcards cannot be used in the ordinary command, but you can use +them with the help of L like this: + + glob copy-out /home/* ."); + + ("echo", (RErr,[]), -1, [], [], + "display a line of text", + " echo [params ...] + +This echos the parameters to the terminal."); + + ("edit", (RErr,[]), -1, [FishAlias "vi"; FishAlias "emacs"], [], + "edit a file", + " edit filename + +This is used to edit a file. It downloads the file, edits it +locally using your editor, then uploads the result. + +The editor is C<$EDITOR>. However if you use the alternate +commands C or C you will get those corresponding +editors."); + + ("glob", (RErr,[]), -1, [], [], + "expand wildcards in command", + " glob command args... + +Expand wildcards in any paths in the args list, and run C +repeatedly on each matching path. + +See L."); + + ("hexedit", (RErr,[]), -1, [], [], + "edit with a hex editor", + " hexedit + hexedit + hexedit + +Use hexedit (a hex editor) to edit all or part of a binary file +or block device. + +This command works by downloading potentially the whole file or +device, editing it locally, then uploading it. If the file or +device is large, you have to specify which part you wish to edit +by using C and/or C C parameters. +C and C are specified in bytes, with the usual +modifiers allowed such as C<1M> (1 megabyte). + +For example to edit the first few sectors of a disk you +might do: + + hexedit /dev/sda 1M + +which would allow you to edit anywhere within the first megabyte +of the disk. + +To edit the superblock of an ext2 filesystem on C, do: + + hexedit /dev/sda1 0x400 0x400 + +(assuming the superblock is in the standard location). + +This command requires the external L program. You +can specify another program to use by setting the C +environment variable. + +See also L."); + + ("lcd", (RErr,[]), -1, [], [], + "change working directory", + " lcd directory + +Change the local directory, ie. the current directory of guestfish +itself. + +Note that C won't do what you might expect."); + + ("man", (RErr,[]), -1, [FishAlias "manual"], [], + "open the manual", + " man + +Opens the manual page for guestfish."); + + ("more", (RErr,[]), -1, [FishAlias "less"], [], + "view a file", + " more filename + + less filename + +This is used to view a file. + +The default viewer is C<$PAGER>. However if you use the alternate +command C you will get the C command specifically."); + + ("reopen", (RErr,[]), -1, [], [], + "close and reopen libguestfs handle", + " reopen + +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."); + + ("sparse", (RErr,[]), -1, [], [], + "create a sparse disk image and add", + " sparse filename size + +This creates an empty sparse file of the given size, and then adds +so it can be further examined. + +In all respects it works the same as the L command, except that +the image file is allocated sparsely, which means that disk blocks are +not assigned to the file until they are needed. Sparse disk files +only use space when written to, but they are slower and there is a +danger you could run out of real disk space during a write operation. + +For more advanced image creation, see L utility. + +Size can be specified using standard suffixes, eg. C<1M>."); + + ("supported", (RErr,[]), -1, [], [], + "list supported groups of commands", + " supported + +This command returns a list of the optional groups +known to the daemon, and indicates which ones are +supported by this build of the libguestfs appliance. + +See also L."); + + ("time", (RErr,[]), -1, [], [], + "print elapsed time taken to run a command", + " time command args... + +Run the command as usual, but print the elapsed time afterwards. This +can be useful for benchmarking operations."); + +]