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>.");
+
]
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