Added guestfish(1) manpage.

.gitignore

@@ -24,6 +24,7 @@ emptydisk
 examples/df
 examples/hello
 fish/guestfish
+guestfish.1
 guestfs.3
 initramfs
 initramfs.timestamp

Makefile.am

@@ -32,6 +32,7 @@ endif
 EXTRA_DIST = \
 	make-initramfs.sh update-initramfs.sh \
 	guestfs.pod guestfs-actions.pod guestfs-structs.pod \
+	guestfish.pod guestfish-actions.pod \
 	libguestfs.spec \
 	HACKING
 
@@ -66,11 +67,11 @@ CLEANFILES = $(fs_DATA) emptydisk
 clean-local:
 	rm -rf initramfs
 
-# Manual page.
+# Manual pages.
 # guestfs-actions.pod and guestfs-structs are autogenerated.  There is
 # no include mechanism for POD, so we have to do it by hand.
 
-man_MANS = guestfs.3
+man_MANS = guestfs.3 guestfish.1
 
 guestfs.3: guestfs.pod guestfs-actions.pod guestfs-structs.pod
 	sed \
@@ -84,6 +85,17 @@ guestfs.3: guestfs.pod guestfs-actions.pod guestfs-structs.pod
 	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
 	  > $@
 
+guestfish.1: guestfish.pod guestfish-actions.pod
+	sed \
+	  -e '/@ACTIONS@/rguestfish-actions.pod' -e 's/@ACTIONS@//' \
+	  < $< | \
+	$(POD2MAN) \
+	  --section 1 \
+	  -c "Virtualization Support" \
+	  --name "guestfish" \
+	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
+	  > $@
+
 # Test-boot the image.
 
 test-boot: emptydisk

guestfish-actions.pod

@@ -0,0 +1,148 @@
+=head2 cat
+
+ cat path
+
+Return the contents of the file named C<path>.
+
+Note that this function cannot correctly handle binary files
+(specifically, files containing C<\0> character which is treated
+as end of string).  For those you need to use the C<guestfs_read_file>
+function which has a more complex interface.
+
+=head2 list-devices
+
+ list-devices
+
+List all the block devices.
+
+The full block device names are returned, eg. C</dev/sda>
+
+
+=head2 list-partitions
+
+ list-partitions
+
+List all the partitions detected on all block devices.
+
+The full partition device names are returned, eg. C</dev/sda1>
+
+This does not return logical volumes.  For that you will need to
+call C<guestfs_lvs>.
+
+=head2 ll
+
+ ll directory
+
+List the files in C<directory> (relative to the root directory,
+there is no cwd) in the format of 'ls -la'.
+
+This command is mostly useful for interactive sessions.  It
+is I<not> intended that you try to parse the output string.
+
+=head2 ls
+
+ ls directory
+
+List the files in C<directory> (relative to the root directory,
+there is no cwd).  The '.' and '..' entries are not returned, but
+hidden files are shown.
+
+This command is mostly useful for interactive sessions.  Programs
+should probably use C<guestfs_readdir> instead.
+
+=head2 lvs
+
+ lvs
+
+List all the logical volumes detected.  This is the equivalent
+of the L<lvs(8)> command.
+
+This returns a list of the logical volume device names
+(eg. C</dev/VolGroup00/LogVol00>).
+
+See also C<guestfs_lvs_full>.
+
+=head2 lvs-full
+
+ lvs-full
+
+List all the logical volumes detected.  This is the equivalent
+of the L<lvs(8)> command.  The "full" version includes all fields.
+
+=head2 mount
+
+ mount device mountpoint
+
+Mount a guest disk at a position in the filesystem.  Block devices
+are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
+the guest.  If those block devices contain partitions, they will have
+the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
+names can be used.
+
+The rules are the same as for L<mount(2)>:  A filesystem must
+first be mounted on C</> before others can be mounted.  Other
+filesystems can only be mounted on directories which already
+exist.
+
+The mounted filesystem is writable, if we have sufficient permissions
+on the underlying device.
+
+The filesystem options C<sync> and C<noatime> are set with this
+call, in order to improve reliability.
+
+=head2 pvs
+
+ pvs
+
+List all the physical volumes detected.  This is the equivalent
+of the L<pvs(8)> command.
+
+This returns a list of just the device names that contain
+PVs (eg. C</dev/sda2>).
+
+See also C<guestfs_pvs_full>.
+
+=head2 pvs-full
+
+ pvs-full
+
+List all the physical volumes detected.  This is the equivalent
+of the L<pvs(8)> command.  The "full" version includes all fields.
+
+=head2 sync
+
+ sync
+
+This syncs the disk, so that any writes are flushed through to the
+underlying disk image.
+
+You should always call this if you have modified a disk image, before
+calling C<guestfs_close>.
+
+=head2 touch
+
+ touch path
+
+Touch acts like the L<touch(1)> command.  It can be used to
+update the timestamps on a file, or, if the file does not exist,
+to create a new zero-length file.
+
+=head2 vgs
+
+ vgs
+
+List all the volumes groups detected.  This is the equivalent
+of the L<vgs(8)> command.
+
+This returns a list of just the volume group names that were
+detected (eg. C<VolGroup00>).
+
+See also C<guestfs_vgs_full>.
+
+=head2 vgs-full
+
+ vgs-full
+
+List all the volumes groups detected.  This is the equivalent
+of the L<vgs(8)> command.  The "full" version includes all fields.
+

guestfish.pod

@@ -0,0 +1,268 @@
+=encoding utf8
+
+=head1 NAME
+
+guestfish - the libguestfs filesystem interactive shell
+
+=head1 SYNOPSIS
+
+ guestfish [--options] [commands]
+
+=head1 EXAMPLES
+
+=head2 From shell scripts
+
+Create a new C</etc/motd> file in a guest:
+
+ guestfish <<_EOF_
+ add disk.img
+ run
+ mount /dev/VolGroup00/LogVol00 /
+ upload new_motd /etc/motd
+ _EOF_
+
+List the LVs in a guest:
+
+ guestfish <<_EOF_
+ add disk.img
+ run
+ lvs
+ _EOF_
+
+=head2 On the command line
+
+List the LVM PVs in a guest image:
+
+ guestfish add disk.img : run : pvs
+
+Remove C</boot/grub/menu.lst> (in reality not such a great idea):
+
+ guestfish --add disk.img \
+   --mount /dev/VolGroup00/LogVol00 \
+   --mount /dev/sda1:/boot \
+   rm /boot/grub/menu.lst : \
+   sync : exit
+
+=head2 As an interactive shell
+
+ $ guestfish
+ 
+ Welcome to guestfish, the libguestfs filesystem interactive shell for
+ editing virtual machine filesystems.
+ 
+ Type: 'help' for help with commands
+       'quit' to quit the shell
+ 
+ ><fs> help
+
+=head1 DESCRIPTION
+
+Guestfish is a shell and command-line tool for examining and modifying
+virtual machine filesystems.  It uses libguestfs and exposes all of
+the functionality of the guestfs API, see L<guestfs(3)>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--help>
+
+Displays general help on options.
+
+=item B<-h> | B<--cmd-help>
+
+Lists all available guestfish commands.
+
+=item B<-h cmd> | B<--cmd-help cmd>
+
+Displays detailed help on a single command C<cmd>.
+
+=item B<-a image> | B<--add image>
+
+Add a block device or virtual machine image to the shell.
+
+=item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>
+
+Mount the named partition or logical volume on the given mountpoint.
+
+If the mountpoint is omitted, it defaults to C</>.
+
+You have to mount something on C</> before most commands will work.
+
+If any C<-m> or C<--mount> options are given, the guest is
+automatically launched.
+
+=item B<-n> | B<--no-sync>
+
+Disable autosync.  This is enabled by default.  See the discussion
+of autosync in the L<guestfs(3)> manpage.
+
+=item B<-v> | B<--verbose>
+
+Enable very verbose messages.  This is particularly useful if you find
+a bug.
+
+=back
+
+=head1 COMMANDS ON COMMAND LINE
+
+Any additional (non-option) arguments are treated as commands to
+execute.
+
+Commands to execute should be separated by a colon (C<:>), where the
+colon is a separate parameter.  Thus:
+
+ guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
+
+If there are no additional arguments, then we enter a shell, either an
+interactive shell with a prompt (if the input is a terminal) or a
+non-interactive shell.
+
+In either command line mode or non-interactive shell, the first
+command that gives an error causes the whole shell to exit.  In
+interactive mode (with a prompt) if a command fails, you can continue
+to enter commands.
+
+=head1 USING launch (OR run)
+
+As with L<guestfs(3)>, you must first configure your guest by adding
+disks, then launch it, then mount any disks you need, and finally
+issue actions/commands.  So the general order of the day is:
+
+=over 4
+
+=item *
+
+add or -a/--add
+
+=item *
+
+launch (aka run)
+
+=item *
+
+mount or -m/--mount
+
+=item *
+
+any other commands
+
+=back
+
+C<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
+your guest before mounting or performing any other commands.
+
+The only exception is that if the C<-m> or C<--mount> option was
+given, the guest is automatically run for you (simply because
+guestfish can't mount the disks you asked for without doing this).
+
+=head1 COMMANDS
+
+=head2 help
+
+ help
+ help cmd
+
+Without any parameter, this lists all commands.  With a C<cmd>
+parameter, this displays detailed help for a command.
+
+=head2 quit | exit
+
+This exits guestfish.  You can also use C<^D> key.
+
+=head2 add | drive | add-drive
+
+ add filename
+
+This adds a block device to be examined or modified.
+
+=head2 cdrom | add-cdrom
+
+ cdrom iso-file
+
+This adds a CD-ROM device to be examined.
+
+=head2 alloc | allocate
+
+ 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 (where C<nn> means a number):
+
+=over 4
+
+=item C<nn>
+
+number of kilobytes, eg: C<1440> = standard 3.5in floppy
+
+=item C<nn>K or C<nn>KB
+
+number of kilobytes
+
+=item C<nn>M or C<nn>MB
+
+number of megabytes
+
+=item C<nn>G or C<nn>GB
+
+number of gigabytes
+
+=item C<nn>sects
+
+number of 512 byte sectors
+
+=back
+
+=head2 launch | run
+
+Launch the guest so that you can issue other commands (see below).
+
+@ACTIONS@
+
+=head1 ENVIRONMENT VARIABLES
+
+=over 4
+
+=item LIBGUESTFS_DEBUG
+
+Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This has the
+same effect as using the B<-v> option.
+
+=item LIBGUESTFS_PATH
+
+Set the path that guestfish uses to search for kernel and initrd.img.
+See the discussion of paths in L<guestfs(3)>.
+
+=back
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<http://et.redhat.com/~rjones/libguestfs>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2009 Red Hat Inc.
+L<http://et.redhat.com/~rjones/libguestfs>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

libguestfs.spec.in

@@ -121,6 +121,7 @@ rm -rf $RPM_BUILD_ROOT
 %files -n guestfish
 %defattr(-,root,root,-)
 %{_bindir}/guestfish
+%{_mandir}/man1/guestfish.1*
 
 
 %changelog

src/generator.ml

@@ -1249,6 +1249,22 @@ FTP."
   pr "}\n";
   pr "\n"
 
+(* Generate the POD documentation for guestfish. *)
+and generate_fish_actions_pod () =
+  List.iter (
+    fun (name, style, _, _, _, longdesc) ->
+      let name = replace name '_' '-' in
+      pr "=head2 %s\n\n" name;
+      pr " %s" name;
+      iter_args (
+	function
+	| String n -> pr " %s" n
+      ) (snd style);
+      pr "\n";
+      pr "\n";
+      pr "%s\n\n" longdesc
+  ) sorted_functions
+
 (* Generate a C function prototype. *)
 and generate_prototype ?(extern = true) ?(static = false) ?(semicolon = true)
     ?(single_line = false) ?(newline = false) ?(in_daemon = false)
@@ -1355,4 +1371,8 @@ let () =
 
   let close = output_to "guestfs-actions.pod" in
   generate_actions_pod ();
+  close ();
+
+  let close = output_to "guestfish-actions.pod" in
+  generate_fish_actions_pod ();
   close ()