Generated code for head/tail commands.

[libguestfs.git] / guestfish-actions.pod

diff --git a/guestfish-actions.pod b/guestfish-actions.pod
index 4845990..d45c001 100644 (file)
--- a/guestfish-actions.pod
+++ b/guestfish-actions.pod
@@ -26,7 +26,7 @@ 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>.
+This is equivalent to the qemu parameter C<-drive file=filename,cache=off>.

 
 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


@@ -705,6 +705,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


@@ -907,6 +934,29 @@ Create a directory named C<path>.
 Create a directory named C<path>, creating any parent directories
 as necessary.  This is like the C<mkdir -p> shell command.
 
 Create a directory named C<path>, creating any parent directories
 as necessary.  This is like the C<mkdir -p> shell command.
 

+=head2 mkdtemp
+
+ mkdtemp template
+
+This command creates a temporary directory.  The
+C<template> parameter should be a full pathname for the
+temporary directory name with the final six characters being
+"XXXXXX".
+
+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 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)>
+

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


@@ -1092,6 +1142,44 @@ command.
 
 Remove the single directory C<path>.
 
 
 Remove the single directory C<path>.
 

+=head2 scrub-device
+
+ scrub-device device
+
+This command writes patterns over C<device> to make data retrieval
+more difficult.
+
+It is an interface to the L<scrub(1)> program.  See that
+manual page for more details.
+
+B<This command is dangerous.  Without careful use you
+can easily destroy all your data>.
+
+=head2 scrub-file
+
+ scrub-file file
+
+This command writes patterns over a file to make data retrieval
+more difficult.
+
+The file is I<removed> after scrubbing.
+
+It is an interface to the L<scrub(1)> program.  See that
+manual page for more details.
+
+=head2 scrub-freespace
+
+ scrub-freespace dir
+
+This command creates the directory C<dir> and then fills it
+with files until the filesystem is full, and scrubs the files
+as for C<scrub-file>, and deletes them.
+The intention is to scrub any free space on the partition
+containing C<dir>.
+
+It is an interface to the L<scrub(1)> program.  See that
+manual page for more details.
+

 =head2 set-append | append
 
  set-append append
 =head2 set-append | append
 
  set-append append


@@ -1205,7 +1293,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).


@@ -1334,6 +1422,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


@@ -1489,6 +1604,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


@@ -1520,6 +1656,8 @@ 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.
 

+See also: C<scrub-device>.
+

 =head2 zerofree
 
  zerofree device
 =head2 zerofree
 
  zerofree device