X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfish-actions.pod;h=fa82ef1b11853c4a25f9496bf0e6d311af287738;hp=04343af2d9bc33999664f8592de1f96811ddd8db;hb=c41fe04a652437c920acb0e820762c53bf44a139;hpb=0faa5dde7b992ba11bb88f77b3424676c7c492e4 diff --git a/guestfish-actions.pod b/guestfish-actions.pod index 04343af..fa82ef1 100644 --- a/guestfish-actions.pod +++ b/guestfish-actions.pod @@ -372,6 +372,13 @@ The first element is the name of the program to run. Subsequent elements are parameters. The list must be non-empty (ie. must contain a program name). +The return value is anything printed to I by +the command. + +If the command returns a non-zero exit status, then +this function returns an error message. The error message +string is the content of I from the command. + The C<$PATH> environment variable will contain at least C and C. If you require a program from another location, you should provide the full path in the @@ -383,6 +390,10 @@ correct places. It is the caller's responsibility to ensure all filesystems that are needed are mounted at the right locations. +Because of the message protocol, there is a transfer limit +of somewhere between 2MB and 4MB. To transfer large files you should use +FTP. + =head2 command-lines command-lines 'arguments ...' @@ -390,6 +401,10 @@ locations. This is the same as C, but splits the result into a list of lines. +Because of the message protocol, there is a transfer limit +of somewhere between 2MB and 4MB. To transfer large files you should use +FTP. + =head2 config config qemuparam qemuvalue @@ -469,6 +484,17 @@ Setting C to 3 should drop everything. This automatically calls L before the operation, so that the maximum guest memory is freed. +=head2 e2fsck-f + + e2fsck-f device + +This runs C, ie. runs the ext2/ext3 +filesystem checker on C, noninteractively (C<-p>), +even if the filesystem appears to be clean (C<-f>). + +This command is only needed because of C +(q.v.). Normally you should use C. + =head2 equal equal file1 file2 @@ -499,6 +525,35 @@ The exact command which runs is C. Note in particular that the filename is not prepended to the output (the C<-b> option). +=head2 find + + find directory + +This command lists out all files and directories, recursively, +starting at C. It is essentially equivalent to +running the shell command C but some +post-processing happens on the output, described below. + +This returns a list of strings I. Thus +if the directory structure was: + + /tmp/a + /tmp/b + /tmp/c/d + +then the returned list from C C would be +4 elements: + + a + b + c + c/d + +If C is not a directory, then this command returns +an error. + +The returned list is sorted. + =head2 fsck fsck fstype device @@ -531,6 +586,15 @@ Checking or repairing NTFS volumes is not supported This command is entirely equivalent to running C. +=head2 get-append + + get-append + +Return the additional kernel options which are added to the +guest kernel command line. + +If C then no options are added. + =head2 get-autosync get-autosync @@ -753,6 +817,14 @@ the path to the LV, such as C. You can also remove all LVs in a volume group by specifying the VG name, C. +=head2 lvresize + + lvresize device mbytes + +This resizes (expands or shrinks) an existing LVM logical +volume to C. When reducing, data in the reduced part +is lost. + =head2 lvs lvs @@ -881,6 +953,13 @@ The implementation uses the C command which refuses to wipe physical volumes that contain any volume groups, so you have to remove those first. +=head2 pvresize + + pvresize device + +This resizes (expands or shrinks) an existing LVM physical +volume to match the new size of the underlying device. + =head2 pvs pvs @@ -914,6 +993,19 @@ Note that this function cannot correctly handle binary files as end of line). For those you need to use the C function which has a more complex interface. +=head2 resize2fs + + resize2fs device + +This resizes an ext2 or ext3 filesystem to match the size of +the underlying device. + +I It is sometimes required that you run C +on the C before calling this command. For unknown reasons +C sometimes gives an error about this and sometimes not. +In any case, it is always safe to call C before +calling this function. + =head2 rm rm path @@ -934,6 +1026,19 @@ command. Remove the single directory C. +=head2 set-append | append + + set-append append + +This function is used to add additional options to the +guest kernel command line. + +The default is C unless overridden by setting +C environment variable. + +Setting C to C means I additional options +are passed (libguestfs always adds a few of its own). + =head2 set-autosync | autosync set-autosync true|false @@ -978,9 +1083,6 @@ Set the path that libguestfs searches for kernel and initrd.img. The default is C<$libdir/guestfs> unless overridden by setting C environment variable. -The string C is stashed in the libguestfs handle, so the caller -must make sure it remains valid for the lifetime of the handle. - Setting C to C restores the default path. =head2 set-qemu | qemu @@ -995,9 +1097,6 @@ configure script. You can also override this by setting the C environment variable. -The string C is stashed in the libguestfs handle, so the caller -must make sure it remains valid for the lifetime of the handle. - Setting C to C restores the default qemu binary. =head2 set-verbose | verbose @@ -1033,9 +1132,53 @@ To create a single partition occupying the whole disk, you would pass C as a single element list, when the single element being the string C<,> (comma). +See also: C, C + B. +=head2 sfdisk-N + + sfdisk-N device n cyls heads sectors line + +This runs L option to modify just the single +partition C (note: C counts from 1). + +For other parameters, see C. You should usually +pass C<0> for the cyls/heads/sectors parameters. + +B. + +=head2 sfdisk-disk-geometry + + sfdisk-disk-geometry device + +This displays the disk geometry of C read from the +partition table. Especially in the case where the underlying +block device has been resized, this can be different from the +kernel's idea of the geometry (see C). + +The result is in human-readable format, and not designed to +be parsed. + +=head2 sfdisk-kernel-geometry + + sfdisk-kernel-geometry device + +This displays the kernel's idea of the geometry of C. + +The result is in human-readable format, and not designed to +be parsed. + +=head2 sfdisk-l + + sfdisk-l device + +This displays the partition table on C, in the +human-readable output of the L command. It is +not intended to be parsed. + =head2 stat stat path @@ -1186,6 +1329,33 @@ See also C. Use C<-> instead of a filename to read/write from stdin/stdout. +=head2 vg-activate + + vg-activate true|false 'volgroups ...' + +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 + +Note that if C is an empty list then B volume groups +are activated or deactivated. + +=head2 vg-activate-all + + vg-activate-all true|false + +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 + =head2 vgcreate vgcreate volgroup 'physvols ...' @@ -1252,3 +1422,18 @@ 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. +=head2 zerofree + + zerofree device + +This runs the I program on C. This program +claims to zero unused inodes and disk blocks on an ext2/3 +filesystem, thus making it possible to compress the filesystem +more effectively. + +You should B run this program if the filesystem is +mounted. + +It is possible that using this program can damage the filesystem +or data on the filesystem. +