Generator now runs automatically when it has changed.

[libguestfs.git] / guestfish-actions.pod

diff --git a/guestfish-actions.pod b/guestfish-actions.pod
index eee402c..e635e54 100644 (file)
--- a/guestfish-actions.pod
+++ b/guestfish-actions.pod
@@ -26,7 +26,8 @@ for whatever operations you want to perform (ie. read access if you
 just want to read the image or write access if you want to modify the
 image).
 
 just want to read the image or write access if you want to modify the
 image).
 

-This is equivalent to the qemu parameter C<-drive file=filename,cache=off>.
+This is equivalent to the qemu parameter
+C<-drive file=filename,cache=off,if=virtio>.

 
 Note that this call checks for the existence of C<filename>.  This
 stops you from specifying other types of drive which are supported
 
 Note that this call checks for the existence of C<filename>.  This
 stops you from specifying other types of drive which are supported


@@ -47,7 +48,7 @@ handle is closed.  We don't currently have any method to enable
 changes to be committed, although qemu can support this.
 
 This is equivalent to the qemu parameter
 changes to be committed, although qemu can support this.
 
 This is equivalent to the qemu parameter

-C<-drive file=filename,snapshot=on>.
+C<-drive file=filename,snapshot=on,if=virtio>.

 
 Note that this call checks for the existence of C<filename>.  This
 stops you from specifying other types of drive which are supported
 
 Note that this call checks for the existence of C<filename>.  This
 stops you from specifying other types of drive which are supported


@@ -479,6 +480,27 @@ There is no comprehensive help for this command.  You have
 to look at the file C<daemon/debug.c> in the libguestfs source
 to find out what you can do.
 
 to look at the file C<daemon/debug.c> in the libguestfs source
 to find out what you can do.
 

+=head2 df
+
+ df
+
+This command runs the C<df> command to report disk space used.
+
+This command is mostly useful for interactive sessions.  It
+is I<not> intended that you try to parse the output string.
+Use C<statvfs> from programs.
+
+=head2 df-h
+
+ df-h
+
+This command runs the C<df -h> command to report disk space used
+in human-readable format.
+
+This command is mostly useful for interactive sessions.  It
+is I<not> intended that you try to parse the output string.
+Use C<statvfs> from programs.
+

 =head2 dmesg
 
  dmesg
 =head2 dmesg
 
  dmesg


@@ -519,6 +541,20 @@ 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.
 

+=head2 du
+
+ du path
+
+This command runs the C<du -s> command to estimate file space
+usage for C<path>.
+
+C<path> can be a file or a directory.  If C<path> is a directory
+then the estimate includes the contents of the directory and all
+subdirectories (recursively).
+
+The result is the estimated size in I<kilobytes>
+(ie. units of 1024 bytes).
+

 =head2 e2fsck-f
 
  e2fsck-f device
 =head2 e2fsck-f
 
  e2fsck-f device


@@ -650,6 +686,20 @@ C<device>.
 This returns the ext2/3/4 filesystem UUID of the filesystem on
 C<device>.
 
 This returns the ext2/3/4 filesystem UUID of the filesystem on
 C<device>.
 

+=head2 get-memsize
+
+ get-memsize
+
+This gets the memory size in megabytes allocated to the
+qemu subprocess.
+
+If C<set-memsize> was not called
+on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
+then this returns the compiled-in default value for memsize.
+
+For more information on the architecture of libguestfs,
+see L<guestfs(3)>.
+

 =head2 get-path
 
  get-path
 =head2 get-path
 
  get-path


@@ -705,6 +755,33 @@ See that manual page for more details.
 This command installs GRUB (the Grand Unified Bootloader) on
 C<device>, with the root directory being C<root>.
 
 This command installs GRUB (the Grand Unified Bootloader) on
 C<device>, with the root directory being C<root>.
 

+=head2 head
+
+ head path
+
+This command returns up to the first 10 lines of a file as
+a list of strings.
+
+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 head-n
+
+ head-n nrlines path
+
+If the parameter C<nrlines> is a positive number, this returns the first
+C<nrlines> lines of the file C<path>.
+
+If the parameter C<nrlines> is a negative number, this returns lines
+from the file C<path>, excluding the last C<nrlines> lines.
+
+If the parameter C<nrlines> is zero, this returns an empty list.
+
+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 hexdump
 
  hexdump path
 =head2 hexdump
 
  hexdump path


@@ -716,6 +793,20 @@ Because of the message protocol, there is a transfer limit
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 

+=head2 initrd-list
+
+ initrd-list path
+
+This command lists out files contained in an initrd.
+
+The files are listed without any initial C</> character.  The
+files are listed in the order they appear (not necessarily
+alphabetical).  Directory names are listed as separate items.
+
+Old Linux kernels (2.4 and earlier) used a compressed ext2
+filesystem as initrd.  We I<only> support the newer initramfs
+format (compressed cpio files).
+

 =head2 is-busy
 
  is-busy
 =head2 is-busy
 
  is-busy


@@ -913,20 +1004,31 @@ as necessary.  This is like the C<mkdir -p> shell command.
 
 This command creates a temporary directory.  The
 C<template> parameter should be a full pathname for the
 
 This command creates a temporary directory.  The
 C<template> parameter should be a full pathname for the

-temporary directory with the six characters being
+temporary directory name with the final six characters being

 "XXXXXX".
 
 "XXXXXX".
 

-For example: "/tmp/tmpXXXXXX" or "/Temp/tmpXXXXXX",
-the second one being suitable for Windows.
+For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX",
+the second one being suitable for Windows filesystems.

 
 The name of the temporary directory that was created
 is returned.
 
 
 The name of the temporary directory that was created
 is returned.
 

+The temporary directory is created with mode 0700
+and is owned by root.
+

 The caller is responsible for deleting the temporary
 directory and its contents after use.
 
 See also: L<mkdtemp(3)>
 
 The caller is responsible for deleting the temporary
 directory and its contents after use.
 
 See also: L<mkdtemp(3)>
 

+=head2 mkfifo
+
+ mkfifo mode path
+
+This call creates a FIFO (named pipe) called C<path> with
+mode C<mode>.  It is just a convenient wrapper around
+C<mknod>.
+

 =head2 mkfs
 
  mkfs fstype device
 =head2 mkfs
 
  mkfs fstype device


@@ -935,6 +1037,52 @@ This creates a filesystem on C<device> (usually a partition
 or LVM logical volume).  The filesystem type is C<fstype>, for
 example C<ext3>.
 
 or LVM logical volume).  The filesystem type is C<fstype>, for
 example C<ext3>.
 

+=head2 mknod
+
+ mknod mode devmajor devminor path
+
+This call creates block or character special devices, or
+named pipes (FIFOs).
+
+The C<mode> parameter should be the mode, using the standard
+constants.  C<devmajor> and C<devminor> are the
+device major and minor numbers, only used when creating block
+and character special devices.
+
+=head2 mknod-b
+
+ mknod-b mode devmajor devminor path
+
+This call creates a block device node called C<path> with
+mode C<mode> and device major/minor C<devmajor> and C<devminor>.
+It is just a convenient wrapper around C<mknod>.
+
+=head2 mknod-c
+
+ mknod-c mode devmajor devminor path
+
+This call creates a char device node called C<path> with
+mode C<mode> and device major/minor C<devmajor> and C<devminor>.
+It is just a convenient wrapper around C<mknod>.
+
+=head2 mkswap
+
+ mkswap device
+
+Create a swap partition on C<device>.
+
+=head2 mkswap-L
+
+ mkswap-L label device
+
+Create a swap partition on C<device> with label C<label>.
+
+=head2 mkswap-U
+
+ mkswap-U uuid device
+
+Create a swap partition on C<device> with UUID C<uuid>.
+

 =head2 mount
 
  mount device mountpoint
 =head2 mount
 
  mount device mountpoint


@@ -956,6 +1104,14 @@ on the underlying device.
 The filesystem options C<sync> and C<noatime> are set with this
 call, in order to improve reliability.
 
 The filesystem options C<sync> and C<noatime> are set with this
 call, in order to improve reliability.
 

+=head2 mount-loop
+
+ mount-loop file mountpoint
+
+This command lets you mount C<file> (a filesystem image
+in a file) on a mount point.  It is entirely equivalent to
+the command C<mount -o loop file mountpoint>.
+

 =head2 mount-options
 
  mount-options options device mountpoint
 =head2 mount-options
 
  mount-options options device mountpoint


@@ -1079,6 +1235,20 @@ Note that this function cannot correctly handle binary files
 as end of line).  For those you need to use the C<read-file>
 function which has a more complex interface.
 
 as end of line).  For those you need to use the C<read-file>
 function which has a more complex interface.
 

+=head2 readdir
+
+ readdir dir
+
+This returns the list of directory entries in directory C<dir>.
+
+All entries in the directory are returned, including C<.> and
+C<..>.  The entries are I<not> sorted, but returned in the same
+order as the underlying filesystem.
+
+This function is primarily intended for use by programs.  To
+get a simple list of names, use C<ls>.  To get a printable
+directory for human consumption, use C<ll>.
+

 =head2 resize2fs
 
  resize2fs device
 =head2 resize2fs
 
  resize2fs device


@@ -1198,6 +1368,21 @@ L<tune2fs(8)> manpage.
 You can use either C<tune2fs-l> or C<get-e2uuid>
 to return the existing UUID of a filesystem.
 
 You can use either C<tune2fs-l> or C<get-e2uuid>
 to return the existing UUID of a filesystem.
 

+=head2 set-memsize | memsize
+
+ set-memsize memsize
+
+This sets the memory size in megabytes allocated to the
+qemu subprocess.  This only has any effect if called before
+C<launch>.
+
+You can also change this by setting the environment
+variable C<LIBGUESTFS_MEMSIZE> before the handle is
+created.
+
+For more information on the architecture of libguestfs,
+see L<guestfs(3)>.
+

 =head2 set-path | path
 
  set-path path
 =head2 set-path | path
 
  set-path path


@@ -1263,7 +1448,7 @@ can easily destroy all your data>.
 
 =head2 sfdisk-N
 
 
 =head2 sfdisk-N
 

- sfdisk-N device n cyls heads sectors line
+ sfdisk-N device partnum cyls heads sectors line

 
 This runs L<sfdisk(8)> option to modify just the single
 partition C<n> (note: C<n> counts from 1).
 
 This runs L<sfdisk(8)> option to modify just the single
 partition C<n> (note: C<n> counts from 1).


@@ -1392,6 +1577,33 @@ underlying disk image.
 You should always call this if you have modified a disk image, before
 closing the handle.
 
 You should always call this if you have modified a disk image, before
 closing the handle.
 

+=head2 tail
+
+ tail path
+
+This command returns up to the last 10 lines of a file as
+a list of strings.
+
+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 tail-n
+
+ tail-n nrlines path
+
+If the parameter C<nrlines> is a positive number, this returns the last
+C<nrlines> lines of the file C<path>.
+
+If the parameter C<nrlines> is a negative number, this returns lines
+from the file C<path>, starting with the C<-nrlines>th line.
+
+If the parameter C<nrlines> is zero, this returns an empty list.
+
+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 tar-in
 
  tar-in (tarfile|-) directory
 =head2 tar-in
 
  tar-in (tarfile|-) directory


@@ -1456,6 +1668,26 @@ manpage for more details.  The list of fields returned isn't
 clearly defined, and depends on both the version of C<tune2fs>
 that libguestfs was built against, and the filesystem itself.
 
 clearly defined, and depends on both the version of C<tune2fs>
 that libguestfs was built against, and the filesystem itself.
 

+=head2 umask
+
+ umask mask
+
+This function sets the mask used for creating new files and
+device nodes to C<mask & 0777>.
+
+Typical umask values would be C<022> which creates new files
+with permissions like "-rw-r--r--" or "-rwxr-xr-x", and
+C<002> which creates new files with permissions like
+"-rw-rw-r--" or "-rwxrwxr-x".
+
+The default umask is C<022>.  This is important because it
+means that directories and device nodes will be created with
+C<0644> or C<0755> mode even if you specify C<0777>.
+
+See also L<umask(2)>, C<mknod>, C<mkdir>.
+
+This call returns the previous umask.
+

 =head2 umount | unmount
 
  umount pathordevice
 =head2 umount | unmount
 
  umount pathordevice


@@ -1547,6 +1779,27 @@ See also C<vgs-full>.
 List all the volumes groups detected.  This is the equivalent
 of the L<vgs(8)> command.  The "full" version includes all fields.
 
 List all the volumes groups detected.  This is the equivalent
 of the L<vgs(8)> command.  The "full" version includes all fields.
 

+=head2 wc-c
+
+ wc-c path
+
+This command counts the characters in a file, using the
+C<wc -c> external command.
+
+=head2 wc-l
+
+ wc-l path
+
+This command counts the lines in a file, using the
+C<wc -l> external command.
+
+=head2 wc-w
+
+ wc-w path
+
+This command counts the words in a file, using the
+C<wc -w> external command.
+

 =head2 write-file
 
  write-file path content size
 =head2 write-file
 
  write-file path content size