fish: Allow -<<END as a syntax for uploading "heredocs".

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 13a9fa7..836c4f7 100644 (file)
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -98,7 +98,7 @@ the functionality of the guestfs API, see L<guestfs(3)>.
 
 Guestfish gives you structured access to the libguestfs API, from
 shell scripts or the command line or interactively.  If you want to
-rescue a broken virtual machine image, you might want to look at the
+rescue a broken virtual machine image, you should look at the
 L<virt-rescue(1)> command.
 
 Using guestfish in read/write mode on live virtual machines can be
@@ -296,6 +296,27 @@ must be escaped with a backslash.
  command "/bin/echo 'foo      bar'"
  command "/bin/echo \'foo\'"
 
+=head1 NUMBERS
+
+Commands which take integers as parameters use the C convention which
+is to use C<0> to prefix an octal number or C<0x> to prefix a
+hexadecimal number.  For example:
+
+ 1234      decimal number 1234
+ 02322     octal number, equivalent to decimal 1234
+ 0x4d2     hexadecimal number, equivalent to decimal 1234
+
+When using the C<chmod> command, you almost always want to specify an
+octal number for the mode, and you must prefix it with C<0> (unlike
+the Unix L<chmod(1)> program):
+
+ chmod 0777 /public  # OK
+ chmod 777 /public   # WRONG! This is mode 777 decimal = 01411 octal.
+
+Commands that return numbers usually print them in decimal, but
+some commands print numbers in other radices (eg. C<umask> prints
+the mode in octal, preceeded by C<0>).
+
 =head1 WILDCARDS AND GLOBBING
 
 Neither guestfish nor the underlying guestfs API performs
@@ -348,6 +369,9 @@ will create a directory C<local> on the host, and then export
 the contents of C</remote> on the mounted filesystem to
 C<local/remote-data.tar.gz>.  (See C<tgz-out>).
 
+To change the local directory, use the C<lcd> command.  C<!cd> will
+have no effect, due to the way that subprocesses work in Unix.
+
 =head1 PIPES
 
 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the
@@ -363,6 +387,7 @@ Other examples:
 
  hexdump /bin/ls | head
  list-devices | tail -1
+ tgz-out / - | tar ztf -
 
 The space before the pipe symbol is required, any space after the pipe
 symbol is optional.  Everything after the pipe symbol is just passed
@@ -461,6 +486,39 @@ user ID of the process, and C<$PID> is the process ID of the server.
 
 Guestfish client and server versions must match exactly.
 
+=head1 UPLOADING AND DOWNLOADING FILES
+
+For commands such as C<upload>, C<download>, C<tar-in>, C<tar-out> and
+others which upload from or download to a local file, you can use the
+special filename C<-> to mean "from stdin" or "to stdout".  For example:
+
+ upload - /foo
+
+reads stdin and creates from that a file C</foo> in the disk image,
+and:
+
+ tar-out /etc - | tar tf -
+
+writes the tarball to stdout and then pipes that into the external
+"tar" command (see L</PIPES>).
+
+When using C<-> to read from stdin, the input is read up to the end of
+stdin.  You can also use a special "heredoc"-like syntax to read up to
+some arbitrary end marker:
+
+ upload -<<END /foo
+ input line 1
+ input line 2
+ input line 3
+ END
+
+Any string of characters can be used instead of C<END>.  The end
+marker must appear on a line of its own, without any preceeding or
+following characters (not even spaces).
+
+Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to
+upload local files (so-called "FileIn" parameters in the generator).
+
 =head1 GUESTFISH COMMANDS
 
 The commands in this section are guestfish convenience commands, in
@@ -719,11 +777,16 @@ I<1> if there was an error.
 L<guestfs(3)>,
 L<http://libguestfs.org/>,
 L<virt-cat(1)>,
+L<virt-df(1)>,
 L<virt-edit(1)>,
 L<virt-list-filesystems(1)>,
+L<virt-list-partitions(1)>,
 L<virt-ls(1)>,
+L<virt-make-fs(1)>,
 L<virt-rescue(1)>,
-L<virt-tar(1)>.
+L<virt-resize(1)>,
+L<virt-tar(1)>,
+L<virt-win-reg(1)>.
 
 =head1 AUTHORS