Generated code for e2fsck-f command.

[libguestfs.git] / perl / lib / Sys / Guestfs.pm

diff --git a/perl/lib/Sys/Guestfs.pm b/perl/lib/Sys/Guestfs.pm
index d059ae4..cba0032 100644 (file)
--- a/perl/lib/Sys/Guestfs.pm
+++ b/perl/lib/Sys/Guestfs.pm
@@ -405,6 +405,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).
 
 Subsequent elements are parameters.  The list must be
 non-empty (ie. must contain a program name).
 

+The return value is anything printed to I<stdout> 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<stderr> from the command.
+

 The C<$PATH> environment variable will contain at least
 C</usr/bin> and C</bin>.  If you require a program from
 another location, you should provide the full path in the
 The C<$PATH> environment variable will contain at least
 C</usr/bin> and C</bin>.  If you require a program from
 another location, you should provide the full path in the


@@ -416,11 +423,19 @@ correct places.  It is the caller's responsibility to ensure
 all filesystems that are needed are mounted at the right
 locations.
 
 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.
+

 =item @lines = $h->command_lines (\@arguments);
 
 This is the same as C<$h-E<gt>command>, but splits the
 result into a list of lines.
 
 =item @lines = $h->command_lines (\@arguments);
 
 This is the same as C<$h-E<gt>command>, 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.
+

 =item $h->config ($qemuparam, $qemuvalue);
 
 This can be used to add arbitrary qemu command line parameters
 =item $h->config ($qemuparam, $qemuvalue);
 
 This can be used to add arbitrary qemu command line parameters


@@ -484,6 +499,23 @@ Setting C<whattodrop> to 3 should drop everything.
 This automatically calls L<sync(2)> before the operation,
 so that the maximum guest memory is freed.
 
 This automatically calls L<sync(2)> before the operation,
 so that the maximum guest memory is freed.
 

+=item $h->e2fsck_f ($device);
+
+This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
+filesystem checker on C<device>, noninteractively (C<-p>),
+even if the filesystem appears to be clean (C<-f>).
+
+This command is only needed because of C<$h-E<gt>resize2fs>
+(q.v.).  Normally you should use C<$h-E<gt>fsck>.
+
+=item $h->end_busy ();
+
+This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
+state as is.  This is only used when implementing
+actions using the low-level API.
+
+For more information on states, see L<guestfs(3)>.
+

 =item $equality = $h->equal ($file1, $file2);
 
 This compares the two files C<file1> and C<file2> and returns
 =item $equality = $h->equal ($file1, $file2);
 
 This compares the two files C<file1> and C<file2> and returns


@@ -508,6 +540,33 @@ The exact command which runs is C<file -bsL path>.  Note in
 particular that the filename is not prepended to the output
 (the C<-b> option).
 
 particular that the filename is not prepended to the output
 (the C<-b> option).
 

+=item @names = $h->find ($directory);
+
+This command lists out all files and directories, recursively,
+starting at C<directory>.  It is essentially equivalent to
+running the shell command C<find directory -print> but some
+post-processing happens on the output, described below.
+
+This returns a list of strings I<without any prefix>.  Thus
+if the directory structure was:
+
+ /tmp/a
+ /tmp/b
+ /tmp/c/d
+
+then the returned list from C<$h-E<gt>find> C</tmp> would be
+4 elements:
+
+ a
+ b
+ c
+ c/d
+
+If C<directory> is not a directory, then this command returns
+an error.
+
+The returned list is sorted.
+

 =item $status = $h->fsck ($fstype, $device);
 
 This runs the filesystem checker (fsck) on C<device> which
 =item $status = $h->fsck ($fstype, $device);
 
 This runs the filesystem checker (fsck) on C<device> which


@@ -538,6 +597,13 @@ Checking or repairing NTFS volumes is not supported
 
 This command is entirely equivalent to running C<fsck -a -t fstype device>.
 
 
 This command is entirely equivalent to running C<fsck -a -t fstype device>.
 

+=item $append = $h->get_append ();
+
+Return the additional kernel options which are added to the
+guest kernel command line.
+
+If C<NULL> then no options are added.
+

 =item $autosync = $h->get_autosync ();
 
 Get the autosync flag.
 =item $autosync = $h->get_autosync ();
 
 Get the autosync flag.


@@ -710,6 +776,12 @@ the path to the LV, such as C</dev/VG/LV>.
 You can also remove all LVs in a volume group by specifying
 the VG name, C</dev/VG>.
 
 You can also remove all LVs in a volume group by specifying
 the VG name, C</dev/VG>.
 

+=item $h->lvresize ($device, $mbytes);
+
+This resizes (expands or shrinks) an existing LVM logical
+volume to C<mbytes>.  When reducing, data in the reduced part
+is lost.
+

 =item @logvols = $h->lvs ();
 
 List all the logical volumes detected.  This is the equivalent
 =item @logvols = $h->lvs ();
 
 List all the logical volumes detected.  This is the equivalent


@@ -810,6 +882,11 @@ The implementation uses the C<pvremove> command which refuses to
 wipe physical volumes that contain any volume groups, so you have
 to remove those first.
 
 wipe physical volumes that contain any volume groups, so you have
 to remove those first.
 

+=item $h->pvresize ($device);
+
+This resizes (expands or shrinks) an existing LVM physical
+volume to match the new size of the underlying device.
+

 =item @physvols = $h->pvs ();
 
 List all the physical volumes detected.  This is the equivalent
 =item @physvols = $h->pvs ();
 
 List all the physical volumes detected.  This is the equivalent


@@ -837,6 +914,17 @@ Note that this function cannot correctly handle binary files
 as end of line).  For those you need to use the C<$h-E<gt>read_file>
 function which has a more complex interface.
 
 as end of line).  For those you need to use the C<$h-E<gt>read_file>
 function which has a more complex interface.
 

+=item $h->resize2fs ($device);
+
+This resizes an ext2 or ext3 filesystem to match the size of
+the underlying device.
+
+I<Note:> It is sometimes required that you run C<$h-E<gt>e2fsck_f>
+on the C<device> before calling this command.  For unknown reasons
+C<resize2fs> sometimes gives an error about this and sometimes not.
+In any case, it is always safe to call C<$h-E<gt>e2fsck_f> before
+calling this function.
+

 =item $h->rm ($path);
 
 Remove the single file C<path>.
 =item $h->rm ($path);
 
 Remove the single file C<path>.


@@ -851,6 +939,17 @@ command.
 
 Remove the single directory C<path>.
 
 
 Remove the single directory C<path>.
 

+=item $h->set_append ($append);
+
+This function is used to add additional options to the
+guest kernel command line.
+
+The default is C<NULL> unless overridden by setting
+C<LIBGUESTFS_APPEND> environment variable.
+
+Setting C<append> to C<NULL> means I<no> additional options
+are passed (libguestfs always adds a few of its own).
+

 =item $h->set_autosync ($autosync);
 
 If C<autosync> is true, this enables autosync.  Libguestfs will make a
 =item $h->set_autosync ($autosync);
 
 If C<autosync> is true, this enables autosync.  Libguestfs will make a


@@ -894,9 +993,6 @@ Set the path that libguestfs searches for kernel and initrd.img.
 The default is C<$libdir/guestfs> unless overridden by setting
 C<LIBGUESTFS_PATH> environment variable.
 
 The default is C<$libdir/guestfs> unless overridden by setting
 C<LIBGUESTFS_PATH> environment variable.
 

-The string C<path> is stashed in the libguestfs handle, so the caller
-must make sure it remains valid for the lifetime of the handle.
-

 Setting C<path> to C<NULL> restores the default path.
 
 =item $h->set_qemu ($qemu);
 Setting C<path> to C<NULL> restores the default path.
 
 =item $h->set_qemu ($qemu);


@@ -909,9 +1005,6 @@ configure script.
 You can also override this by setting the C<LIBGUESTFS_QEMU>
 environment variable.
 
 You can also override this by setting the C<LIBGUESTFS_QEMU>
 environment variable.
 

-The string C<qemu> is stashed in the libguestfs handle, so the caller
-must make sure it remains valid for the lifetime of the handle.
-

 Setting C<qemu> to C<NULL> restores the default qemu binary.
 
 =item $h->set_ready ();
 Setting C<qemu> to C<NULL> restores the default qemu binary.
 
 =item $h->set_ready ();


@@ -950,9 +1043,45 @@ To create a single partition occupying the whole disk, you would
 pass C<lines> as a single element list, when the single element being
 the string C<,> (comma).
 
 pass C<lines> as a single element list, when the single element being
 the string C<,> (comma).
 

+See also: C<$h-E<gt>sfdisk_l>, C<$h-E<gt>sfdisk_N>
+

 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 
 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 

+=item $h->sfdisk_N ($device, $n, $cyls, $heads, $sectors, $line);
+
+This runs L<sfdisk(8)> option to modify just the single
+partition C<n> (note: C<n> counts from 1).
+
+For other parameters, see C<$h-E<gt>sfdisk>.  You should usually
+pass C<0> for the cyls/heads/sectors parameters.
+
+B<This command is dangerous.  Without careful use you
+can easily destroy all your data>.
+
+=item $partitions = $h->sfdisk_disk_geometry ($device);
+
+This displays the disk geometry of C<device> 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<$h-E<gt>sfdisk_kernel_geometry>).
+
+The result is in human-readable format, and not designed to
+be parsed.
+
+=item $partitions = $h->sfdisk_kernel_geometry ($device);
+
+This displays the kernel's idea of the geometry of C<device>.
+
+The result is in human-readable format, and not designed to
+be parsed.
+
+=item $partitions = $h->sfdisk_l ($device);
+
+This displays the partition table on C<device>, in the
+human-readable output of the L<sfdisk(8)> command.  It is
+not intended to be parsed.
+

 =item %statbuf = $h->stat ($path);
 
 Returns file information for the given C<path>.
 =item %statbuf = $h->stat ($path);
 
 Returns file information for the given C<path>.


@@ -1065,6 +1194,29 @@ C<filename> can also be a named pipe.
 
 See also C<$h-E<gt>download>.
 
 
 See also C<$h-E<gt>download>.
 

+=item $h->vg_activate ($activate, \@volgroups);
+
+This command activates or (if C<activate> is false) deactivates
+all logical volumes in the listed volume groups C<volgroups>.
+If activated, then they are made known to the
+kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
+then those devices disappear.
+
+This command is the same as running C<vgchange -a y|n volgroups...>
+
+Note that if C<volgroups> is an empty list then B<all> volume groups
+are activated or deactivated.
+
+=item $h->vg_activate_all ($activate);
+
+This command activates or (if C<activate> 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</dev/mapper> devices.  If deactivated,
+then those devices disappear.
+
+This command is the same as running C<vgchange -a y|n>
+

 =item $h->vgcreate ($volgroup, \@physvols);
 
 This creates an LVM volume group called C<volgroup>
 =item $h->vgcreate ($volgroup, \@physvols);
 
 This creates an LVM volume group called C<volgroup>


@@ -1127,6 +1279,19 @@ How many blocks are zeroed isn't specified (but it's I<not> enough
 to securely wipe the device).  It should be sufficient to remove
 any partition tables, filesystem superblocks and so on.
 
 to securely wipe the device).  It should be sufficient to remove
 any partition tables, filesystem superblocks and so on.
 

+=item $h->zerofree ($device);
+
+This runs the I<zerofree> program on C<device>.  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<not> run this program if the filesystem is
+mounted.
+
+It is possible that using this program can damage the filesystem
+or data on the filesystem.
+

 =cut
 
 1;
 =cut
 
 1;