fish: Document that remote run in cmd substitution context hangs.

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 58f0bd9..5b641ea 100644 (file)
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -176,7 +176,7 @@ force a particular format use the I<--format=..> option.
 
 Using this flag is mostly equivalent to using the C<add> command,
 with C<readonly:true> if the I<--ro> flag was given, and
 
 Using this flag is mostly equivalent to using the C<add> command,
 with C<readonly:true> if the I<--ro> flag was given, and

-with C<format:...> if the I<--format:...> flag was given.
+with C<format:...> if the I<--format=...> flag was given.

 
 =item B<-c URI>
 
 
 =item B<-c URI>
 


@@ -199,6 +199,8 @@ Add disks from the named libvirt domain.  If the I<--ro> option is
 also used, then any libvirt domain can be used.  However in write
 mode, only libvirt domains which are shut down can be named here.
 
 also used, then any libvirt domain can be used.  However in write
 mode, only libvirt domains which are shut down can be named here.
 

+Domain UUIDs can be used instead of names.
+

 Using this flag is mostly equivalent to using the C<add-domain> command,
 with C<readonly:true> if the I<--ro> flag was given, and
 with C<format:...> if the I<--format:...> flag was given.
 Using this flag is mostly equivalent to using the C<add-domain> command,
 with C<readonly:true> if the I<--ro> flag was given, and
 with C<format:...> if the I<--format:...> flag was given.


@@ -473,14 +475,14 @@ and I<--rw> affect whether the other command line options I<-a>,
 I<-c>, I<-d>, I<-i> and I<-m> open disk images read-only or for
 writing.
 
 I<-c>, I<-d>, I<-i> and I<-m> open disk images read-only or for
 writing.
 

-In libguestfs E<le> 1.8, guestfish, guestmount and virt-rescue
+In libguestfs E<le> 1.10, guestfish, guestmount and virt-rescue

 defaulted to opening disk images supplied on the command line for
 write.  To open a disk image read-only you have to do I<-a image --ro>.
 
 This matters: If you accidentally open a live VM disk image writable
 then you will cause irreversible disk corruption.
 
 defaulted to opening disk images supplied on the command line for
 write.  To open a disk image read-only you have to do I<-a image --ro>.
 
 This matters: If you accidentally open a live VM disk image writable
 then you will cause irreversible disk corruption.
 

-By libguestfs 1.10 we intend to change the default the other way.
+In a future libguestfs we intend to change the default the other way.

 Disk images will be opened read-only.  You will have to either specify
 I<guestfish --rw>, I<guestmount --rw>, I<virt-rescue --rw>, or change
 the configuration file C</etc/libguestfs-tools.conf> in order to get
 Disk images will be opened read-only.  You will have to either specify
 I<guestfish --rw>, I<guestmount --rw>, I<virt-rescue --rw>, or change
 the configuration file C</etc/libguestfs-tools.conf> in order to get


@@ -516,6 +518,64 @@ must be escaped with a backslash.
  command "/bin/echo 'foo      bar'"
  command "/bin/echo \'foo\'"
 
  command "/bin/echo 'foo      bar'"
  command "/bin/echo \'foo\'"
 

+=head2 ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS
+
+In double-quoted arguments (only) use backslash to insert special
+characters:
+
+=over 4
+
+=item C<\a>
+
+Alert (bell) character.
+
+=item C<\b>
+
+Backspace character.
+
+=item C<\f>
+
+Form feed character.
+
+=item C<\n>
+
+Newline character.
+
+=item C<\r>
+
+Carriage return character.
+
+=item C<\t>
+
+Horizontal tab character.
+
+=item C<\v>
+
+Vertical tab character.
+
+=item C<\">
+
+A literal double quote character.
+
+=item C<\ooo>
+
+A character with octal value I<ooo>.  There must be precisely 3 octal
+digits (unlike C).
+
+=item C<\xhh>
+
+A character with hex value I<hh>.  There must be precisely 2 hex
+digits.
+
+In the current implementation C<\000> and C<\x00> cannot be used
+in strings.
+
+=item C<\\>
+
+A literal backslash character.
+
+=back
+

 =head1 OPTIONAL ARGUMENTS
 
 Some commands take optional arguments.  These arguments appear in this
 =head1 OPTIONAL ARGUMENTS
 
 Some commands take optional arguments.  These arguments appear in this


@@ -798,19 +858,24 @@ on each one.  Then you can close the mapper device:
 =head1 WINDOWS PATHS
 
 If a path is prefixed with C<win:> then you can use Windows-style
 =head1 WINDOWS PATHS
 
 If a path is prefixed with C<win:> then you can use Windows-style

-paths (with some limitations).  The following commands are equivalent:
+drive letters and paths (with some limitations).  The following
+commands are equivalent:

 
  file /WINDOWS/system32/config/system.LOG
 
 
  file /WINDOWS/system32/config/system.LOG
 

- file win:/windows/system32/config/system.log
-

  file win:\windows\system32\config\system.log
 
  file win:\windows\system32\config\system.log
 

- file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG
+ file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG
+
+The parameter is rewritten "behind the scenes" by looking up the
+position where the drive is mounted, prepending that to the path,
+changing all backslash characters to forward slash, then resolving the
+result using L</case-sensitive-path>.  For example if the E: drive
+was mounted on C</e> then the parameter might be rewritten like this:

 
 

-This syntax implicitly calls C<case-sensitive-path> (q.v.) so it also
-handles case insensitivity like Windows would.  This only works in
-argument positions that expect a path.
+ win:e:\foo\bar => /e/FOO/bar
+
+This only works in argument positions that expect a path.

 
 =head1 UPLOADING AND DOWNLOADING FILES
 
 
 =head1 UPLOADING AND DOWNLOADING FILES
 


@@ -908,6 +973,17 @@ user ID of the process, and C<$PID> is the process ID of the server.
 
 Guestfish client and server versions must match exactly.
 
 
 Guestfish client and server versions must match exactly.
 

+=head2 REMOTE CONTROL RUN COMMAND HANGING
+
+Using the C<run> (or C<launch>) command remotely in a command
+substitution context hangs, ie. don't do (note the backquotes):
+
+ a=`guestfish --remote run`
+
+Since the C<run> command produces no output on stdout, this is not
+useful anyway.  For further information see
+L<https://bugzilla.redhat.com/show_bug.cgi?id=592910>.
+

 =head1 PREPARED DISK IMAGES
 
 Use the I<-N type> or I<--new type> parameter to select one of a set
 =head1 PREPARED DISK IMAGES
 
 Use the I<-N type> or I<--new type> parameter to select one of a set


@@ -1016,6 +1092,21 @@ guestfish returns 0 if the commands completed without error, or
 The C<edit> command uses C<$EDITOR> as the editor.  If not
 set, it uses C<vi>.
 
 The C<edit> command uses C<$EDITOR> as the editor.  If not
 set, it uses C<vi>.
 

+=item FEBOOTSTRAP_KERNEL
+
+=item FEBOOTSTRAP_MODULES
+
+These two environment variables allow the kernel that libguestfs uses
+in the appliance to be selected.  If C<$FEBOOTSTRAP_KERNEL> is not
+set, then the most recent host kernel is chosen.  For more information
+about kernel selection, see L<febootstrap-supermin-helper(8)>.  This
+feature is only available in febootstrap E<ge> 3.8.
+
+=item GUESTFISH_DISPLAY_IMAGE
+
+The C<display> command uses C<$GUESTFISH_DISPLAY_IMAGE> to
+display images.  If not set, it uses L<display(1)>.
+

 =item GUESTFISH_PID
 
 Used with the I<--remote> option to specify the remote guestfish
 =item GUESTFISH_PID
 
 Used with the I<--remote> option to specify the remote guestfish


@@ -1134,9 +1225,9 @@ to make guestfish case sensitive.
 
 =item test2.img (etc)
 
 
 =item test2.img (etc)
 

-When using the C<-N> or C<--new> option, the prepared disk or
+When using the I<-N> or I<--new> option, the prepared disk or

 filesystem will be created in the file C<test1.img> in the current
 filesystem will be created in the file C<test1.img> in the current

-directory.  The second use of C<-N> will use C<test2.img> and so on.
+directory.  The second use of I<-N> will use C<test2.img> and so on.

 Any existing file with the same name will be overwritten.
 
 =back
 Any existing file with the same name will be overwritten.
 
 =back


@@ -1162,7 +1253,9 @@ L<virt-tar(1)>,
 L<virt-tar-in(1)>,
 L<virt-tar-out(1)>,
 L<virt-win-reg(1)>,
 L<virt-tar-in(1)>,
 L<virt-tar-out(1)>,
 L<virt-win-reg(1)>,

-L<hexedit(1)>.
+L<display(1)>,
+L<hexedit(1)>,
+L<febootstrap-supermin-helper(8)>.

 
 =head1 AUTHORS
 
 
 =head1 AUTHORS