must do that first (supplying the necessary keys) if the
disk is encrypted.
-Please read L<guestfs(3)/INSPECTION> for more details.");
+Please read L<guestfs(3)/INSPECTION> for more details.
+
+See also C<guestfs_list_filesystems>.");
("inspect_get_type", (RString "name", [Device "root"]), -1, [],
[],
"\
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<guestfs_mount> and C<guestfs_umount>, 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<guestfs_inspect_os> to look for OSes).");
+
]
(* daemon_functions are any functions which cause some action
"\
List all the block devices.
-The full block device names are returned, eg. C</dev/sda>");
+The full block device names are returned, eg. C</dev/sda>.
+
+See also C<guestfs_list_filesystems>.");
("list_partitions", (RStringList "partitions", []), 8, [],
[InitBasicFS, Always, TestOutputListOfDevices (
The full partition device names are returned, eg. C</dev/sda1>
This does not return logical volumes. For that you will need to
-call C<guestfs_lvs>.");
+call C<guestfs_lvs>.
+
+See also C<guestfs_list_filesystems>.");
("pvs", (RStringList "physvols", []), 9, [Optional "lvm2"],
[InitBasicFSonLVM, Always, TestOutputListOfDevices (
This returns a list of the logical volume device names
(eg. C</dev/VolGroup00/LogVol00>).
-See also C<guestfs_lvs_full>.");
+See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>.");
("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 12, [Optional "lvm2"],
[], (* XXX how to test? *)
This may read fewer bytes than requested. For further details
see the L<pread(2)> system call.
-See also C<guestfs_pwrite>.");
+See also C<guestfs_pwrite>, C<guestfs_pread_device>.");
("part_init", (RErr, [Device "device"; String "parttype"]), 208, [],
[InitEmpty, Always, TestRun (
types (see C<guestfs_part_get_parttype>).");
("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
to the file. This could even be 0, although short writes are
unlikely for regular files in ordinary circumstances.
-See also C<guestfs_pread>.");
+See also C<guestfs_pread>, C<guestfs_pwrite_device>.");
("resize2fs_size", (RErr, [Device "device"; Int64 "size"]), 248, [],
[],
See also C<guestfs_stat>.");
+ ("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<guestfs_list_partitions>.");
+
+ ("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<filename> to C<remotefilename> on the
+filesystem.
+
+C<remotefilename> is overwritten starting at the byte C<offset>
+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<offset>. The
+size of the data written is implicit in the size of the
+source C<filename>.
+
+Note that there is no limit on the amount of data that
+can be uploaded with this call, unlike with C<guestfs_pwrite>,
+and this call always writes the full amount unless an
+error occurs.
+
+See also C<guestfs_upload>, C<guestfs_pwrite>.");
+
+ ("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<remotefilename> and save it as C<filename>
+on the local machine.
+
+C<remotefilename> is read for C<size> bytes starting at C<offset>
+(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<guestfs_pread>,
+and this call always reads the full amount unless an
+error occurs.
+
+See also C<guestfs_download>, C<guestfs_pread>.");
+
+ ("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<content> to C<device> starting at offset C<offset>.
+
+This command implements the L<pwrite(2)> 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<guestfs_pwrite>.");
+
+ ("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<count>
+bytes of C<device>, starting at C<offset>.
+
+This may read fewer bytes than requested. For further details
+see the L<pread(2)> system call.
+
+See also C<guestfs_pread>.");
+
]
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
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</shortname>.
+ *
+ * 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<qemu-img(1)> utility.
+
+Size can be specified using standard suffixes, eg. C<1M>.
+
+To create a sparse file, use L</sparse> instead. To create a
+prepared disk image, see L</PREPARED DISK IMAGES>.");
+
+ ("copy_in", (RErr,[]), -1, [], [],
+ "copy local files or directories into an image",
+ " copy-in local [local ...] /remotedir
+
+C<copy-in> copies local files or directories recursively into the disk
+image, placing them in the directory called C</remotedir> (which must
+exist). This guestfish meta-command turns into a sequence of
+L</tar-in> 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<copy-out> copies remote files or directories recursively out of the
+disk image, placing them on the host disk in a local directory called
+C<localdir> (which must exist). This guestfish meta-command turns
+into a sequence of L</download>, L</tar-out> 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</glob> 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<vi> or C<emacs> 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<command>
+repeatedly on each matching path.
+
+See L</WILDCARDS AND GLOBBING>.");
+
+ ("hexedit", (RErr,[]), -1, [], [],
+ "edit with a hex editor",
+ " hexedit <filename|device>
+ hexedit <filename|device> <max>
+ hexedit <filename|device> <start> <max>
+
+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<max> and/or C<start> C<max> parameters.
+C<start> and C<max> 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</dev/sda1>, do:
+
+ hexedit /dev/sda1 0x400 0x400
+
+(assuming the superblock is in the standard location).
+
+This command requires the external L<hexedit(1)> program. You
+can specify another program to use by setting the C<HEXEDITOR>
+environment variable.
+
+See also L</hexdump>.");
+
+ ("lcd", (RErr,[]), -1, [], [],
+ "change working directory",
+ " lcd directory
+
+Change the local directory, ie. the current directory of guestfish
+itself.
+
+Note that C<!cd> 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<less> you will get the C<less> 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</alloc> 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<qemu-img(1)> 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<guestfs(3)/AVAILABILITY>.");
+
+ ("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.");
+
+]
git.annexia.org / libguestfs.git / blobdiff