Rewrite virt-edit in C.
authorRichard W.M. Jones <rjones@redhat.com>
Fri, 6 May 2011 21:42:07 +0000 (17:42 -0400)
committerRichard W.M. Jones <rjones@redhat.com>
Mon, 9 May 2011 13:23:08 +0000 (14:23 +0100)
12 files changed:
.gitignore
Makefile.am
configure.ac
edit/Makefile.am [new file with mode: 0644]
edit/test-virt-edit.sh [new file with mode: 0755]
edit/virt-edit.c [new file with mode: 0644]
edit/virt-edit.pod [new file with mode: 0644]
images/guest-aux/make-fedora-img.sh
po/POTFILES.in
src/guestfs.pod
tools/Makefile.am
tools/virt-edit [deleted file]

index 06903d4..969aa08 100644 (file)
@@ -68,6 +68,9 @@ depcomp
 df/stamp-virt-df.pod
 df/virt-df
 df/virt-df.1
 df/stamp-virt-df.pod
 df/virt-df
 df/virt-df.1
+edit/stamp-virt-*.pod
+edit/virt-edit
+edit/virt-edit.1
 emptydisk
 examples/create_disk
 examples/guestfs-examples.3
 emptydisk
 examples/create_disk
 examples/guestfs-examples.3
index fcd190a..b475659 100644 (file)
@@ -36,7 +36,7 @@ SUBDIRS += gnulib/tests capitests regressions test-tool
 SUBDIRS += fish
 
 # virt-tools in C.
 SUBDIRS += fish
 
 # virt-tools in C.
-SUBDIRS += cat df inspector rescue
+SUBDIRS += cat df edit inspector rescue
 
 # Language bindings.
 if HAVE_PERL
 
 # Language bindings.
 if HAVE_PERL
index eccbf3c..e24c46d 100644 (file)
@@ -826,6 +826,7 @@ AC_CONFIG_FILES([Makefile
                  csharp/Makefile
                  debian/changelog
                  df/Makefile
                  csharp/Makefile
                  debian/changelog
                  df/Makefile
+                 edit/Makefile
                  examples/Makefile
                  fish/Makefile
                  fuse/Makefile
                  examples/Makefile
                  fish/Makefile
                  fuse/Makefile
diff --git a/edit/Makefile.am b/edit/Makefile.am
new file mode 100644 (file)
index 0000000..5195b51
--- /dev/null
@@ -0,0 +1,75 @@
+# libguestfs virt-edit
+# Copyright (C) 2009-2011 Red Hat Inc.
+#
+# 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.
+
+include $(top_srcdir)/subdir-rules.mk
+
+EXTRA_DIST = \
+       test-virt-edit.sh \
+       virt-edit.pod
+
+CLEANFILES = stamp-virt-edit.pod
+
+bin_PROGRAMS = virt-edit
+
+SHARED_SOURCE_FILES = \
+       ../fish/config.c \
+       ../fish/inspect.c \
+       ../fish/keys.c \
+       ../fish/options.h \
+       ../fish/options.c \
+       ../fish/virt.c
+
+virt_edit_SOURCES = \
+       $(SHARED_SOURCE_FILES) \
+       virt-edit.c
+
+virt_edit_CFLAGS = \
+       -I$(top_srcdir)/src -I$(top_builddir)/src \
+       -I$(top_srcdir)/fish \
+       -I$(srcdir)/../gnulib/lib -I../gnulib/lib \
+       -DLOCALEBASEDIR=\""$(datadir)/locale"\" \
+       $(LIBCONFIG_CFLAGS) \
+       $(WARN_CFLAGS) $(WERROR_CFLAGS)
+
+virt_edit_LDADD = \
+       $(LIBCONFIG_LIBS) \
+       $(top_builddir)/src/libguestfs.la \
+       ../gnulib/lib/libgnu.la
+
+# Manual pages and HTML files for the website.
+man_MANS = virt-edit.1
+noinst_DATA = $(top_builddir)/html/virt-edit.1.html
+
+virt-edit.1 $(top_builddir)/html/virt-edit.1.html: stamp-virt-edit.pod
+
+stamp-virt-edit.pod: virt-edit.pod
+       $(top_srcdir)/podwrapper.sh \
+         --man virt-edit.1 \
+         --html $(top_builddir)/html/virt-edit.1.html \
+         $<
+       touch $@
+
+# Tests.
+
+random_val := $(shell awk 'BEGIN{srand(); print 1+int(255*rand())}' < /dev/null)
+
+TESTS_ENVIRONMENT = \
+       MALLOC_PERTURB_=$(random_val) \
+       LD_LIBRARY_PATH=$(top_builddir)/src/.libs \
+       LIBGUESTFS_PATH=$(top_builddir)/appliance
+
+TESTS = test-virt-edit.sh
diff --git a/edit/test-virt-edit.sh b/edit/test-virt-edit.sh
new file mode 100755 (executable)
index 0000000..d43851b
--- /dev/null
@@ -0,0 +1,42 @@
+#!/bin/bash -
+
+export LANG=C
+set -e
+
+# Make a copy of the Fedora image so we can write to it then
+# discard it.
+cp ../images/fedora.img test.img
+
+# Edit interactively.  We have to simulate this by setting $EDITOR.
+# The command will be: echo newline >> /tmp/file
+export EDITOR='echo newline >>'
+./virt-edit -a test.img /etc/test3
+if [ "$(../cat/virt-cat -a test.img /etc/test3)" != "a
+b
+c
+d
+e
+f
+newline" ]; then
+    echo "$0: error: mismatch in interactive editing of file /etc/test3"
+    exit 1
+fi
+unset EDITOR
+
+# Edit non-interactively, only if we have 'perl' binary.
+if perl --version >/dev/null 2>&1; then
+    ./virt-edit -a test.img /etc/test3 -e 's/^[a-f]/$lineno/'
+    if [ "$(../cat/virt-cat -a test.img /etc/test3)" != "1
+2
+3
+4
+5
+6
+newline" ]; then
+        echo "$0: error: mismatch in non-interactive editing of file /etc/test3"
+        exit 1
+    fi
+fi
+
+# Discard test image.
+rm test.img
diff --git a/edit/virt-edit.c b/edit/virt-edit.c
new file mode 100644 (file)
index 0000000..dc2e130
--- /dev/null
@@ -0,0 +1,666 @@
+/* virt-edit
+ * Copyright (C) 2009-2011 Red Hat Inc.
+ *
+ * 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.
+ */
+
+#include <config.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <inttypes.h>
+#include <unistd.h>
+#include <locale.h>
+#include <getopt.h>
+#include <assert.h>
+#include <libintl.h>
+#include <sys/time.h>
+#include <sys/stat.h>
+#include <utime.h>
+
+#include "progname.h"
+#include "xvasprintf.h"
+#include "c-ctype.h"
+
+#include "guestfs.h"
+#include "options.h"
+
+/* Currently open libguestfs handle. */
+guestfs_h *g;
+
+int read_only = 0;
+int live = 0;
+int verbose = 0;
+int keys_from_stdin = 0;
+int echo_keys = 0;
+const char *libvirt_uri = NULL;
+int inspector = 1;
+
+static const char *backup_extension = NULL;
+static const char *perl_expr = NULL;
+
+static void edit (const char *filename, const char *root);
+static char *edit_interactively (const char *tmpfile);
+static char *edit_non_interactively (const char *tmpfile);
+static int is_windows (guestfs_h *g, const char *root);
+static char *windows_path (guestfs_h *g, const char *root, const char *filename);
+static char *generate_random_name (const char *filename);
+static char *generate_backup_name (const char *filename);
+
+static inline char *
+bad_cast (char const *s)
+{
+  return (char *) s;
+}
+
+static void __attribute__((noreturn))
+usage (int status)
+{
+  if (status != EXIT_SUCCESS)
+    fprintf (stderr, _("Try `%s --help' for more information.\n"),
+             program_name);
+  else {
+    fprintf (stdout,
+           _("%s: Edit a file in a virtual machine\n"
+             "Copyright (C) 2009-2011 Red Hat Inc.\n"
+             "Usage:\n"
+             "  %s [--options] -d domname file [file ...]\n"
+             "  %s [--options] -a disk.img [-a disk.img ...] file [file ...]\n"
+             "Options:\n"
+             "  -a|--add image       Add image\n"
+             "  -b|--backup .ext     Backup original as original.ext\n"
+             "  -c|--connect uri     Specify libvirt URI for -d option\n"
+             "  -d|--domain guest    Add disks from libvirt guest\n"
+             "  --echo-keys          Don't turn off echo for passphrases\n"
+             "  -e|--expr expr       Non-interactive editing using Perl expr\n"
+             "  --format[=raw|..]    Force disk format for -a option\n"
+             "  --help               Display brief help\n"
+             "  --keys-from-stdin    Read passphrases from stdin\n"
+             "  -v|--verbose         Verbose messages\n"
+             "  -V|--version         Display version and exit\n"
+             "  -x                   Trace libguestfs API calls\n"
+             "For more information, see the manpage %s(1).\n"),
+             program_name, program_name, program_name,
+             program_name);
+  }
+  exit (status);
+}
+
+int
+main (int argc, char *argv[])
+{
+  /* Set global program name that is not polluted with libtool artifacts.  */
+  set_program_name (argv[0]);
+
+  setlocale (LC_ALL, "");
+  bindtextdomain (PACKAGE, LOCALEBASEDIR);
+  textdomain (PACKAGE);
+
+  /* We use random(3) below. */
+  srandom (time (NULL));
+
+  enum { HELP_OPTION = CHAR_MAX + 1 };
+
+  static const char *options = "a:b:c:d:e:vVx";
+  static const struct option long_options[] = {
+    { "add", 1, 0, 'a' },
+    { "backup", 1, 0, 'b' },
+    { "connect", 1, 0, 'c' },
+    { "domain", 1, 0, 'd' },
+    { "echo-keys", 0, 0, 0 },
+    { "expr", 1, 0, 'e' },
+    { "format", 2, 0, 0 },
+    { "help", 0, 0, HELP_OPTION },
+    { "keys-from-stdin", 0, 0, 0 },
+    { "verbose", 0, 0, 'v' },
+    { "version", 0, 0, 'V' },
+    { 0, 0, 0, 0 }
+  };
+  struct drv *drvs = NULL;
+  struct drv *drv;
+  const char *format = NULL;
+  int c;
+  int option_index;
+  char *root, **roots;
+
+  g = guestfs_create ();
+  if (g == NULL) {
+    fprintf (stderr, _("guestfs_create: failed to create handle\n"));
+    exit (EXIT_FAILURE);
+  }
+
+  argv[0] = bad_cast (program_name);
+
+  for (;;) {
+    c = getopt_long (argc, argv, options, long_options, &option_index);
+    if (c == -1) break;
+
+    switch (c) {
+    case 0:                    /* options which are long only */
+      if (STREQ (long_options[option_index].name, "keys-from-stdin")) {
+        keys_from_stdin = 1;
+      } else if (STREQ (long_options[option_index].name, "echo-keys")) {
+        echo_keys = 1;
+      } else if (STREQ (long_options[option_index].name, "format")) {
+        if (!optarg || STREQ (optarg, ""))
+          format = NULL;
+        else
+          format = optarg;
+      } else {
+        fprintf (stderr, _("%s: unknown long option: %s (%d)\n"),
+                 program_name, long_options[option_index].name, option_index);
+        exit (EXIT_FAILURE);
+      }
+      break;
+
+    case 'a':
+      OPTION_a;
+      break;
+
+    case 'b':
+      if (backup_extension) {
+        fprintf (stderr, _("%s: -b option given multiple times\n"),
+                 program_name);
+        exit (EXIT_FAILURE);
+      }
+      backup_extension = optarg;
+      break;
+
+    case 'c':
+      OPTION_c;
+      break;
+
+    case 'd':
+      OPTION_d;
+      break;
+
+    case 'e':
+      if (perl_expr) {
+        fprintf (stderr, _("%s: -e option given multiple times\n"),
+                 program_name);
+        exit (EXIT_FAILURE);
+      }
+      perl_expr = optarg;
+      break;
+
+    case 'h':
+      usage (EXIT_SUCCESS);
+
+    case 'v':
+      OPTION_v;
+      break;
+
+    case 'V':
+      OPTION_V;
+      break;
+
+    case 'x':
+      OPTION_x;
+      break;
+
+    case HELP_OPTION:
+      usage (EXIT_SUCCESS);
+
+    default:
+      usage (EXIT_FAILURE);
+    }
+  }
+
+  /* Old-style syntax?  There were no -a or -d options in the old
+   * virt-edit which is how we detect this.
+   */
+  if (drvs == NULL) {
+    /* argc - 1 because last parameter is the single filename. */
+    while (optind < argc - 1) {
+      if (strchr (argv[optind], '/') ||
+          access (argv[optind], F_OK) == 0) { /* simulate -a option */
+        drv = malloc (sizeof (struct drv));
+        if (!drv) {
+          perror ("malloc");
+          exit (EXIT_FAILURE);
+        }
+        drv->type = drv_a;
+        drv->a.filename = argv[optind];
+        drv->a.format = NULL;
+        drv->next = drvs;
+        drvs = drv;
+      } else {                  /* simulate -d option */
+        drv = malloc (sizeof (struct drv));
+        if (!drv) {
+          perror ("malloc");
+          exit (EXIT_FAILURE);
+        }
+        drv->type = drv_d;
+        drv->d.guest = argv[optind];
+        drv->next = drvs;
+        drvs = drv;
+      }
+
+      optind++;
+    }
+  }
+
+  /* These are really constants, but they have to be variables for the
+   * options parsing code.  Assert here that they have known-good
+   * values.
+   */
+  assert (read_only == 0);
+  assert (inspector == 1);
+  assert (live == 0);
+
+  /* User must specify at least one filename on the command line. */
+  if (optind >= argc || argc - optind < 1)
+    usage (EXIT_FAILURE);
+
+  /* User must have specified some drives. */
+  if (drvs == NULL)
+    usage (EXIT_FAILURE);
+
+  /* Add drives. */
+  add_drives (drvs, 'a');
+
+  if (guestfs_launch (g) == -1)
+    exit (EXIT_FAILURE);
+
+  inspect_mount ();
+
+  /* Free up data structures, no longer needed after this point. */
+  free_drives (drvs);
+
+  /* Get root mountpoint. */
+  roots = guestfs_inspect_get_roots (g);
+  if (!roots)
+    exit (EXIT_FAILURE);
+  /* see fish/inspect.c:inspect_mount */
+  assert (roots[0] != NULL && roots[1] == NULL);
+  root = roots[0];
+  free (roots);
+
+  while (optind < argc) {
+    edit (argv[optind], root);
+    optind++;
+  }
+
+  free (root);
+
+  /* Cleanly unmount the disks after editing. */
+  if (guestfs_umount_all (g) == -1 || guestfs_sync (g) == -1)
+    exit (EXIT_FAILURE);
+
+  guestfs_close (g);
+
+  exit (EXIT_SUCCESS);
+}
+
+static void
+edit (const char *filename, const char *root)
+{
+  char *filename_to_free = NULL;
+  const char *tmpdir = guestfs_tmpdir ();
+  char tmpfile[strlen (tmpdir) + 32];
+  sprintf (tmpfile, "%s/virteditXXXXXX", tmpdir);
+  int fd;
+  char fdbuf[32];
+  char *upload_from = NULL;
+  char *newname = NULL;
+  char *backupname = NULL;
+
+  /* Windows?  Special handling is required. */
+  if (is_windows (g, root))
+    filename = filename_to_free = windows_path (g, root, filename);
+
+  /* Download the file to a temporary. */
+  fd = mkstemp (tmpfile);
+  if (fd == -1) {
+    perror ("mkstemp");
+    exit (EXIT_FAILURE);
+  }
+
+  snprintf (fdbuf, sizeof fdbuf, "/dev/fd/%d", fd);
+
+  if (guestfs_download (g, filename, fdbuf) == -1)
+    goto error;
+
+  if (close (fd) == -1) {
+    perror (tmpfile);
+    goto error;
+  }
+
+  if (!perl_expr)
+    upload_from = edit_interactively (tmpfile);
+  else
+    upload_from = edit_non_interactively (tmpfile);
+
+  /* We don't always need to upload: upload_from could be NULL because
+   * the user closed the editor without changing the file.
+   */
+  if (upload_from) {
+    /* Upload to a new file in the same directory, so if it fails we
+     * don't end up with a partially written file.  Give the new file
+     * a completely random name so we have only a tiny chance of
+     * overwriting some existing file.
+     */
+    newname = generate_random_name (filename);
+
+    if (guestfs_upload (g, upload_from, newname) == -1)
+      goto error;
+
+    /* Backup or overwrite the file. */
+    if (backup_extension) {
+      backupname = generate_backup_name (filename);
+      if (guestfs_mv (g, filename, backupname) == -1)
+        goto error;
+    }
+    if (guestfs_mv (g, newname, filename) == -1)
+      goto error;
+  }
+
+  unlink (tmpfile);
+  free (filename_to_free);
+  free (upload_from);
+  free (newname);
+  free (backupname);
+  return;
+
+ error:
+  unlink (tmpfile);
+  exit (EXIT_FAILURE);
+}
+
+static char *
+edit_interactively (const char *tmpfile)
+{
+  struct utimbuf times;
+  struct stat oldstat, newstat;
+  const char *editor;
+  char *cmd;
+  int r;
+  char *ret;
+
+  /* Set the time back a few seconds on the original file.  This is so
+   * that if the user is very fast at editing, or if EDITOR is an
+   * automatic editor, then the edit might happen within the 1 second
+   * granularity of mtime, and we would think the file hasn't changed.
+   */
+  if (stat (tmpfile, &oldstat) == -1) {
+    perror (tmpfile);
+    exit (EXIT_FAILURE);
+  }
+
+  times.actime = oldstat.st_atime - 5;
+  times.modtime = oldstat.st_mtime - 5;
+  if (utime (tmpfile, &times) == -1) {
+    perror ("utimes");
+    exit (EXIT_FAILURE);
+  }
+
+  if (stat (tmpfile, &oldstat) == -1) {
+    perror (tmpfile);
+    exit (EXIT_FAILURE);
+  }
+
+  editor = getenv ("EDITOR");
+  if (editor == NULL)
+    editor = "vi";
+
+  if (asprintf (&cmd, "%s %s", editor, tmpfile) == -1) {
+    perror ("asprintf");
+    exit (EXIT_FAILURE);
+  }
+
+  if (verbose)
+    fprintf (stderr, "%s\n", cmd);
+
+  r = system (cmd);
+  if (r == -1 || WEXITSTATUS (r) != 0)
+    exit (EXIT_FAILURE);
+
+  free (cmd);
+
+  if (stat (tmpfile, &newstat) == -1) {
+    perror (tmpfile);
+    exit (EXIT_FAILURE);
+  }
+
+  if (oldstat.st_ctime == newstat.st_ctime &&
+      oldstat.st_mtime == newstat.st_mtime) {
+    printf ("File not changed.\n");
+    return NULL;
+  }
+
+  ret = strdup (tmpfile);
+  if (!ret) {
+    perror ("strdup");
+    exit (EXIT_FAILURE);
+  }
+
+  return ret;
+}
+
+static char *
+edit_non_interactively (const char *tmpfile)
+{
+  char *cmd, *outfile, *ret;
+  int r;
+
+  assert (perl_expr != NULL);
+
+  /* Pass the expression to Perl via the environment.  This sidesteps
+   * any quoting problems with the already complex Perl command line.
+   */
+  setenv ("virt_edit_expr", perl_expr, 1);
+
+  /* Call out to a canned Perl script. */
+  if (asprintf (&cmd,
+                "perl -e '"
+                "$lineno = 0; "
+                "$expr = $ENV{virt_edit_expr}; "
+                "while (<STDIN>) { "
+                "  $lineno++; "
+                "  eval $expr; "
+                "  die if $@; "
+                "  print STDOUT $_ or die \"print: $!\"; "
+                "} "
+                "close STDOUT or die \"close: $!\"; "
+                "' < %s > %s.out",
+                tmpfile, tmpfile) == -1) {
+    perror ("asprintf");
+    exit (EXIT_FAILURE);
+  }
+
+  if (verbose)
+    fprintf (stderr, "%s\n", cmd);
+
+  r = system (cmd);
+  if (r == -1 || WEXITSTATUS (r) != 0)
+    exit (EXIT_FAILURE);
+
+  free (cmd);
+
+  if (asprintf (&outfile, "%s.out", tmpfile) == -1) {
+    perror ("asprintf");
+    exit (EXIT_FAILURE);
+  }
+
+  if (rename (outfile, tmpfile) == -1) {
+    perror ("rename");
+    exit (EXIT_FAILURE);
+  }
+
+  free (outfile);
+
+  ret = strdup (tmpfile);
+  if (!ret) {
+    perror ("strdup");
+    exit (EXIT_FAILURE);
+  }
+
+  return ret; /* caller will free */
+}
+
+static int
+is_windows (guestfs_h *g, const char *root)
+{
+  char *type;
+  int w;
+
+  type = guestfs_inspect_get_type (g, root);
+  if (!type)
+    return 0;
+
+  w = STREQ (type, "windows");
+  free (type);
+  return w;
+}
+
+static void mount_drive_letter (char drive_letter, const char *root);
+
+static char *
+windows_path (guestfs_h *g, const char *root, const char *path)
+{
+  char *ret;
+  size_t i;
+
+  /* If there is a drive letter, rewrite the path. */
+  if (c_isalpha (path[0]) && path[1] == ':') {
+    char drive_letter = c_tolower (path[0]);
+    /* This returns the newly allocated string. */
+    mount_drive_letter (drive_letter, root);
+    ret = strdup (path + 2);
+    if (ret == NULL) {
+      perror ("strdup");
+      exit (EXIT_FAILURE);
+    }
+  }
+  else if (!*path) {
+    ret = strdup ("/");
+    if (ret == NULL) {
+      perror ("strdup");
+      exit (EXIT_FAILURE);
+    }
+  }
+  else {
+    ret = strdup (path);
+    if (ret == NULL) {
+      perror ("strdup");
+      exit (EXIT_FAILURE);
+    }
+  }
+
+  /* Blindly convert any backslashes into forward slashes.  Is this good? */
+  for (i = 0; i < strlen (ret); ++i)
+    if (ret[i] == '\\')
+      ret[i] = '/';
+
+  char *t = guestfs_case_sensitive_path (g, ret);
+  free (ret);
+  ret = t;
+
+  return ret;
+}
+
+static void
+mount_drive_letter (char drive_letter, const char *root)
+{
+  char **drives;
+  char *device;
+  size_t i;
+
+  /* Resolve the drive letter using the drive mappings table. */
+  drives = guestfs_inspect_get_drive_mappings (g, root);
+  if (drives == NULL || drives[0] == NULL) {
+    fprintf (stderr, _("%s: to use Windows drive letters, this must be a Windows guest\n"),
+             program_name);
+    exit (EXIT_FAILURE);
+  }
+
+  device = NULL;
+  for (i = 0; drives[i] != NULL; i += 2) {
+    if (c_tolower (drives[i][0]) == drive_letter && drives[i][1] == '\0') {
+      device = drives[i+1];
+      break;
+    }
+  }
+
+  if (device == NULL) {
+    fprintf (stderr, _("%s: drive '%c:' not found.\n"),
+             program_name, drive_letter);
+    exit (EXIT_FAILURE);
+  }
+
+  /* Unmount current disk and remount device. */
+  if (guestfs_umount_all (g) == -1)
+    exit (EXIT_FAILURE);
+
+  if (guestfs_mount_options (g, "", device, "/") == -1)
+    exit (EXIT_FAILURE);
+
+  for (i = 0; drives[i] != NULL; ++i)
+    free (drives[i]);
+  free (drives);
+  /* Don't need to free (device) because that string was in the
+   * drives array.
+   */
+}
+
+static char
+random_char (void)
+{
+  char c[] = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  return c[random () % (sizeof c - 1)];
+}
+
+static char *
+generate_random_name (const char *filename)
+{
+  char *ret, *p;
+  size_t i;
+
+  ret = malloc (strlen (filename) + 16);
+  if (!ret) {
+    perror ("malloc");
+    exit (EXIT_FAILURE);
+  }
+  strcpy (ret, filename);
+
+  p = strrchr (ret, '/');
+  assert (p);
+  p++;
+
+  /* Because of "+ 16" above, there should be enough space in the
+   * output buffer to write 8 random characters here.
+   */
+  for (i = 0; i < 8; ++i)
+    *p++ = random_char ();
+  *p++ = '\0';
+
+  return ret; /* caller will free */
+}
+
+static char *
+generate_backup_name (const char *filename)
+{
+  char *ret;
+
+  assert (backup_extension != NULL);
+
+  if (asprintf (&ret, "%s%s", filename, backup_extension) == -1) {
+    perror ("asprintf");
+    exit (EXIT_FAILURE);
+  }
+
+  return ret; /* caller will free */
+}
diff --git a/edit/virt-edit.pod b/edit/virt-edit.pod
new file mode 100644 (file)
index 0000000..ba4e3a6
--- /dev/null
@@ -0,0 +1,381 @@
+=encoding utf8
+
+=head1 NAME
+
+virt-edit - Edit a file in a virtual machine
+
+=head1 SYNOPSIS
+
+ virt-edit [--options] -d domname file [file ...]
+
+ virt-edit [--options] -a disk.img [-a disk.img ...] file [file ...]
+
+ virt-edit [-d domname|-a disk.img] file -e 'expr'
+
+Old-style:
+
+ virt-edit domname file
+
+ virt-edit disk.img [disk.img ...] file
+
+=head1 WARNING
+
+You must I<not> use C<virt-edit> on live virtual machines.  If you do
+this, you risk disk corruption in the VM.  C<virt-edit> tries to stop
+you from doing this, but doesn't catch all cases.
+
+=head1 DESCRIPTION
+
+C<virt-edit> is a command line tool to edit C<file> where each C<file>
+exists in the named virtual machine (or disk image).
+
+Multiple filenames can be given, in which case they are each edited in
+turn.  Each filename must be a full path, starting at the root
+directory (starting with '/').
+
+If you want to just view a file, use L<virt-cat(1)>.
+
+For more complex cases you should look at the L<guestfish(1)> tool
+(see L</USING GUESTFISH> below).
+
+C<virt-edit> cannot be used to create a new file.  L<guestfish(1)> can
+do that and much more.
+
+=head1 EXAMPLES
+
+Edit the named files interactively:
+
+ virt-edit -d mydomain /boot/grub/grub.conf
+
+ virt-edit -d mydomain /etc/passwd
+
+For Windows guests, some Windows paths are understood:
+
+ virt-edit -d mywindomain 'c:\autoexec.bat'
+
+If Perl is installed, you can also edit files non-interactively (see
+L</NON-INTERACTIVE EDITING> below).
+To change the init default level to 5:
+
+ virt-edit -d mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--help>
+
+Display brief help.
+
+=item B<-a> file
+
+=item B<--add> file
+
+Add I<file> which should be a disk image from a virtual machine.  If
+the virtual machine has multiple block devices, you must supply all of
+them with separate I<-a> options.
+
+The format of the disk image is auto-detected.  To override this and
+force a particular format use the I<--format=..> option.
+
+=item B<-b> extension
+
+=item B<--backup> extension
+
+Create a backup of the original file I<in the guest disk image>.
+The backup has the original filename with C<extension> added.
+
+Usually the first character of C<extension> would be a dot C<.>
+so you would write:
+
+ virt-edit -b .orig [etc]
+
+By default, no backup file is made.
+
+=item B<--connect URI> | B<-c URI>
+
+If using libvirt, connect to the given I<URI>.  If omitted, then we
+connect to the default libvirt hypervisor.
+
+If you specify guest block devices directly, then libvirt is not used
+at all.
+
+=item B<-d> guest
+
+=item B<--domain> guest
+
+Add all the disks from the named libvirt guest.  Domain UUIDs can be
+used instead of names.
+
+=item B<--echo-keys>
+
+When prompting for keys and passphrases, virt-cat normally turns
+echoing off so you cannot see what you are typing.  If you are not
+worried about Tempest attacks and there is no one else in the room you
+can specify this flag to see what you are typing.
+
+=item B<--format> raw|qcow2|...
+
+=item B<--format>
+
+The default for the I<-a> option is to auto-detect the format of the
+disk image.  Using this forces the disk format for I<-a> options which
+follow on the command line.  Using I<--format> with no argument
+switches back to auto-detection for subsequent I<-a> options.
+
+For example:
+
+ virt-edit --format=raw -a disk.img file
+
+forces raw format (no auto-detection) for C<disk.img>.
+
+ virt-edit --format=raw -a disk.img --format -a another.img file
+
+forces raw format (no auto-detection) for C<disk.img> and reverts to
+auto-detection for C<another.img>.
+
+If you have untrusted raw-format guest disk images, you should use
+this option to specify the disk format.  This avoids a possible
+security problem with malicious guests (CVE-2010-3851).
+
+=item B<-e> EXPR
+
+=item B<--expr> EXPR
+
+Instead of launching the external editor, non-interactively
+apply the Perl expression C<EXPR> to each line in the file.
+See L</NON-INTERACTIVE EDITING> below.
+
+Be careful to properly quote the expression to prevent it from
+being altered by the shell.
+
+Note that this option is only available when Perl 5 is installed.
+
+=item B<--keys-from-stdin>
+
+Read key or passphrase parameters from stdin.  The default is
+to try to read passphrases from the user by opening C</dev/tty>.
+
+=item B<-v>
+
+=item B<--verbose>
+
+Enable verbose messages for debugging.
+
+=item B<-V>
+
+=item B<--version>
+
+Display version number and exit.
+
+=item B<-x>
+
+Enable tracing of libguestfs API calls.
+
+=back
+
+=head1 OLD-STYLE COMMAND LINE ARGUMENTS
+
+Previous versions of virt-edit allowed you to write either:
+
+ virt-edit disk.img [disk.img ...] file
+
+or
+
+ virt-edit guestname file
+
+whereas in this version you should use I<-a> or I<-d> respectively
+to avoid the confusing case where a disk image might have the same
+name as a guest.
+
+For compatibility the old style is still supported.
+
+=head1 NON-INTERACTIVE EDITING
+
+C<virt-edit> normally calls out to C<$EDITOR> (or vi) so
+the system administrator can interactively edit the file.
+
+There are two ways also to use C<virt-edit> from scripts in order to
+make automated edits to files.  (Note that although you I<can> use
+C<virt-edit> like this, it's less error-prone to write scripts
+directly using the libguestfs API and Augeas for configuration file
+editing.)
+
+The first method is to temporarily set C<$EDITOR> to any script or
+program you want to run.  The script is invoked as C<$EDITOR tmpfile>
+and it should update C<tmpfile> in place however it likes.
+
+The second method is to use the I<-e> parameter of C<virt-edit> to run
+a short Perl snippet in the style of L<sed(1)>.  For example to
+replace all instances of C<foo> with C<bar> in a file:
+
+ virt-edit -d domname filename -e 's/foo/bar/'
+
+The full power of Perl regular expressions can be used (see
+L<perlre(1)>).  For example to delete root's password you could do:
+
+ virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'
+
+What really happens is that the snippet is evaluated as a Perl
+expression for each line of the file.  The line, including the final
+C<\n>, is passed in C<$_> and the expression should update C<$_> or
+leave it unchanged.
+
+To delete a line, set C<$_> to the empty string.  For example, to
+delete the C<apache> user account from the password file you can do:
+
+ virt-edit -d mydomain /etc/passwd -e '$_ = "" if /^apache:/'
+
+To insert a line, prepend or append it to C<$_>.  However appending
+lines to the end of the file is rather difficult this way since there
+is no concept of "last line of the file" - your expression just
+doesn't get called again.  You might want to use the first method
+(setting C<$EDITOR>) if you want to do this.
+
+The variable C<$lineno> contains the current line number.
+As is traditional, the first line in the file is number C<1>.
+
+The return value from the expression is ignored, but the expression
+may call C<die> in order to abort the whole program, leaving the
+original file untouched.
+
+Remember when matching the end of a line that C<$_> may contain the
+final C<\n>, or (for DOS files) C<\r\n>, or if the file does not end
+with a newline then neither of these.  Thus to match or substitute
+some text at the end of a line, use this regular expression:
+
+ /some text(\r?\n)?$/
+
+Alternately, use the perl C<chomp> function, being careful not to
+chomp C<$_> itself (since that would remove all newlines from the
+file):
+
+ my $m = $_; chomp $m; $m =~ /some text$/
+
+=head1 WINDOWS PATHS
+
+C<virt-edit> has a limited ability to understand Windows drive letters
+and paths (eg. C<E:\foo\bar.txt>).
+
+If and only if the guest is running Windows then:
+
+=over 4
+
+=item *
+
+Drive letter prefixes like C<C:> are resolved against the
+Windows Registry to the correct filesystem.
+
+=item *
+
+Any backslash (C<\>) characters in the path are replaced
+with forward slashes so that libguestfs can process it.
+
+=item *
+
+The path is resolved case insensitively to locate the file
+that should be edited.
+
+=back
+
+There are some known shortcomings:
+
+=over 4
+
+=item *
+
+Some NTFS symbolic links may not be followed correctly.
+
+=item *
+
+NTFS junction points that cross filesystems are not followed.
+
+=back
+
+=head1 USING GUESTFISH
+
+L<guestfish(1)> is a more powerful, lower level tool which you can use
+when C<virt-edit> doesn't work.
+
+Using C<virt-edit> is approximately equivalent to doing:
+
+ guestfish --rw -i -d domname edit /file
+
+where C<domname> is the name of the libvirt guest, and C</file> is the
+full path to the file.
+
+The command above uses libguestfs's guest inspection feature and so
+does not work on guests that libguestfs cannot inspect, or on things
+like arbitrary disk images that don't contain guests.  To edit a file
+on a disk image directly, use:
+
+ guestfish --rw -a disk.img -m /dev/sda1 edit /file
+
+where C<disk.img> is the disk image, C</dev/sda1> is the filesystem
+within the disk image to edit, and C</file> is the full path to the
+file.
+
+C<virt-edit> cannot create new files.  Use the guestfish commands
+C<touch>, C<write> or C<upload> instead:
+
+ guestfish --rw -i -d domname touch /newfile
+
+ guestfish --rw -i -d domname write /newfile "new content"
+
+ guestfish --rw -i -d domname upload localfile /newfile
+
+=head1 ENVIRONMENT VARIABLES
+
+=over 4
+
+=item C<EDITOR>
+
+If set, this string is used as the editor.  It may contain arguments,
+eg. C<"emacs -nw">
+
+If not set, C<vi> is used.
+
+=back
+
+=head1 SHELL QUOTING
+
+Libvirt guest names can contain arbitrary characters, some of which
+have meaning to the shell such as C<#> and space.  You may need to
+quote or escape these characters on the command line.  See the shell
+manual page L<sh(1)> for details.
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<guestfish(1)>,
+L<virt-cat(1)>,
+L<virt-copy-in(1)>,
+L<virt-tar-in(1)>,
+L<Sys::Guestfs(3)>,
+L<Sys::Guestfs::Lib(3)>,
+L<Sys::Virt(3)>,
+L<http://libguestfs.org/>,
+L<perl(1)>,
+L<perlre(1)>.
+
+=head1 AUTHOR
+
+Richard W.M. Jones L<http://people.redhat.com/~rjones/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2009-2011 Red Hat Inc.
+
+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.
index 0e064b4..a038432 100755 (executable)
@@ -83,6 +83,14 @@ touch /boot/grub/grub.conf
 # Test files.
 write /etc/test1 "abcdefg"
 write /etc/test2 ""
 # Test files.
 write /etc/test1 "abcdefg"
 write /etc/test2 ""
+upload -<<__end /etc/test3
+a
+b
+c
+d
+e
+f
+__end
 write /bin/test1 "abcdefg"
 write /bin/test2 "zxcvbnm"
 write /bin/test3 "1234567"
 write /bin/test1 "abcdefg"
 write /bin/test2 "zxcvbnm"
 write /bin/test3 "1234567"
index c023ab9..7c0df52 100644 (file)
@@ -78,6 +78,7 @@ df/df.c
 df/domains.c
 df/main.c
 df/output.c
 df/domains.c
 df/main.c
 df/output.c
+edit/virt-edit.c
 fish/alloc.c
 fish/cmds.c
 fish/cmds_gperf.c
 fish/alloc.c
 fish/cmds.c
 fish/cmds_gperf.c
@@ -151,7 +152,6 @@ src/match.c
 src/proto.c
 src/virt.c
 test-tool/test-tool.c
 src/proto.c
 src/virt.c
 test-tool/test-tool.c
-tools/virt-edit.pl
 tools/virt-list-filesystems.pl
 tools/virt-list-partitions.pl
 tools/virt-make-fs.pl
 tools/virt-list-filesystems.pl
 tools/virt-list-partitions.pl
 tools/virt-make-fs.pl
index 5d9d804..915d860 100644 (file)
@@ -2671,6 +2671,10 @@ actions.
 
 L<virt-df(1)> command and documentation.
 
 
 L<virt-df(1)> command and documentation.
 
+=item C<edit>
+
+L<virt-edit(1)> command and documentation.
+
 =item C<examples>
 
 C API example code.
 =item C<examples>
 
 C API example code.
index 6441333..7904f1c 100644 (file)
@@ -18,7 +18,6 @@
 include $(top_srcdir)/subdir-rules.mk
 
 tools = \
 include $(top_srcdir)/subdir-rules.mk
 
 tools = \
-       edit \
        list-filesystems \
        list-partitions \
        make-fs \
        list-filesystems \
        list-partitions \
        make-fs \
@@ -37,10 +36,10 @@ bin_SCRIPTS = $(tools:%=virt-%)
 
 # Manual pages and HTML files for the website.
 
 
 # Manual pages and HTML files for the website.
 
-# XXX Bug in automake?  If you list virt-edit.1 explicitly, then it
+# XXX Bug in automake?  If you list virt-tar.1 explicitly, then it
 # builds and installs the man pages.  However if this is removed,
 # then the man pages are neither built nor installed.
 # builds and installs the man pages.  However if this is removed,
 # then the man pages are neither built nor installed.
-man_MANS = virt-edit.1 $(patsubst %,virt-%.1,$(filter-out edit,$(tools)))
+man_MANS = virt-tar.1 $(patsubst %,virt-%.1,$(filter-out tar,$(tools)))
 
 noinst_DATA = $(tools:%=$(top_builddir)/html/virt-%.1.html)
 
 
 noinst_DATA = $(tools:%=$(top_builddir)/html/virt-%.1.html)
 
diff --git a/tools/virt-edit b/tools/virt-edit
deleted file mode 100755 (executable)
index a004291..0000000
+++ /dev/null
@@ -1,530 +0,0 @@
-#!/usr/bin/perl -w
-# virt-edit
-# Copyright (C) 2009-2011 Red Hat Inc.
-#
-# 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.
-
-use warnings;
-use strict;
-
-use Sys::Guestfs;
-use Sys::Guestfs::Lib qw(open_guest);
-use Pod::Usage;
-use Getopt::Long;
-use File::Temp qw/tempfile/;
-use File::Basename;
-use Locale::TextDomain 'libguestfs';
-
-=encoding utf8
-
-=head1 NAME
-
-virt-edit - Edit a file in a virtual machine
-
-=head1 SYNOPSIS
-
- virt-edit [--options] domname file
-
- virt-edit [--options] disk.img [disk.img ...] file
-
- virt-edit [domname|disk.img] file -e 'expr'
-
-=head1 WARNING
-
-You must I<not> use C<virt-edit> on live virtual machines.  If you do
-this, you risk disk corruption in the VM.  C<virt-edit> tries to stop
-you from doing this, but doesn't catch all cases.
-
-=head1 DESCRIPTION
-
-C<virt-edit> is a command line tool to edit C<file> where C<file>
-exists in the named virtual machine (or disk image).
-
-If you want to just view a file, use L<virt-cat(1)>.
-
-For more complex cases you should look at the L<guestfish(1)> tool
-(see L</USING GUESTFISH> below).
-
-C<virt-edit> cannot be used to create a new file, nor to edit
-multiple files.  L<guestfish(1)> can do that and much more.
-
-=head1 EXAMPLES
-
-Edit the named files interactively:
-
- virt-edit mydomain /boot/grub/grub.conf
-
- virt-edit mydomain /etc/passwd
-
-For Windows guests, some Windows paths are understood:
-
- virt-edit mywindomain 'c:\autoexec.bat'
-
-You can also edit files non-interactively (see
-L</NON-INTERACTIVE EDITING> below).
-To change the init default level to 5:
-
- virt-edit mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'
-
-=head1 OPTIONS
-
-=over 4
-
-=cut
-
-my $help;
-
-=item B<--help>
-
-Display brief help.
-
-=cut
-
-my $version;
-
-=item B<--version>
-
-Display version number and exit.
-
-=cut
-
-my $backup;
-
-=item B<--backup extension> | B<-b extension>
-
-Create a backup of the original file I<in the guest disk image>.
-The backup has the original filename with C<extension> added.
-
-Usually the first character of C<extension> would be a dot C<.>
-so you would write:
-
- virt-edit -b .orig [etc]
-
-By default, no backup file is made.
-
-=cut
-
-my $uri;
-
-=item B<--connect URI> | B<-c URI>
-
-If using libvirt, connect to the given I<URI>.  If omitted, then we
-connect to the default libvirt hypervisor.
-
-If you specify guest block devices directly, then libvirt is not used
-at all.
-
-=cut
-
-my $format;
-
-=item B<--format> raw
-
-Specify the format of disk images given on the command line.  If this
-is omitted then the format is autodetected from the content of the
-disk image.
-
-If disk images are requested from libvirt, then this program asks
-libvirt for this information.  In this case, the value of the format
-parameter is ignored.
-
-If working with untrusted raw-format guest disk images, you should
-ensure the format is always specified.
-
-=cut
-
-my $expr;
-
-=item B<--expr EXPR> | B<-e EXPR>
-
-Instead of launching the external editor, non-interactively
-apply the Perl expression C<EXPR> to each line in the file.
-See L</NON-INTERACTIVE EDITING> below.
-
-Be careful to properly quote the expression to prevent it from
-being altered by the shell.
-
-=back
-
-=cut
-
-GetOptions ("help|?" => \$help,
-            "version" => \$version,
-            "connect|c=s" => \$uri,
-            "format=s" => \$format,
-            "expr|e=s" => \$expr,
-            "backup|b=s" => \$backup,
-    ) or pod2usage (2);
-pod2usage (1) if $help;
-if ($version) {
-    my $g = Sys::Guestfs->new ();
-    my %h = $g->version ();
-    print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
-    exit
-}
-
-pod2usage (__"virt-edit: no image, VM names or filenames to edit given")
-    if @ARGV <= 1;
-
-my $filename = pop @ARGV;
-
-my $g;
-if ($uri) {
-    $g = open_guest (\@ARGV, address => $uri, rw => 1, format => $format);
-} else {
-    $g = open_guest (\@ARGV, rw => 1, format => $format);
-}
-
-$g->launch ();
-
-my @roots = $g->inspect_os ();
-if (@roots == 0) {
-    die __x("{prog}: No operating system could be detected inside this disk image.\n\nThis may be because the file is not a disk image, or is not a virtual machine\nimage, or because the OS type is not understood by libguestfs.\n\nIf you feel this is an error, please file a bug report including as much\ninformation about the disk image as possible.\n",
-            prog => basename ($0));
-}
-if (@roots > 1) {
-    die __x("{prog}: multiboot operating systems are not supported.\n",
-            prog => basename ($0))
-}
-my $root = $roots[0];
-my %fses = $g->inspect_get_mountpoints ($root);
-my @fses = sort { length $a <=> length $b } keys %fses;
-foreach (@fses) {
-    $g->mount_options ("", $fses{$_}, $_);
-}
-
-# Special handling for Windows filenames.
-$filename = windows_path ($g, $root, $filename)
-    if $g->inspect_get_type ($root) eq "windows";
-
-my ($fh, $tempname) = tempfile (UNLINK => 1);
-my $fddev = "/dev/fd/" . fileno ($fh);
-
-# Allow this to fail in case eg. the file does not exist.
-$g->download ($filename, $fddev);
-
-close $fh or die "close: $!";
-
-my $do_upload = $tempname;
-
-if (!defined $expr) {
-    # Interactively edit the file.
-    my $oldctime = (stat ($tempname))[10];
-
-    my $editor = $ENV{EDITOR};
-    $editor ||= "vi";
-    system ("$editor $tempname") == 0
-        or die "edit failed: $editor: $?";
-
-    my $newctime = (stat ($tempname))[10];
-
-    if ($oldctime == $newctime) {
-        $do_upload = undef;
-        print __"File not changed.\n";
-    }
-} else {
-    my ($fh, $tempout) = tempfile (UNLINK => 1);
-
-    # Apply a Perl expression to the lines of the file.
-    open IFILE, $tempname or die "$tempname: $!";
-    my $lineno = 0;
-    while (<IFILE>) {
-        $lineno++;
-        eval $expr;
-        die if $@;
-        print $fh $_ or die "print: $!";
-    }
-    close $fh or die "close: $!";
-
-    $do_upload = $tempout;
-}
-
-if (defined $do_upload) {
-    # Upload to a new file, so if it fails we don't end up with
-    # a partially written file.  Give the new file a completely
-    # random name so we have only a tiny chance of overwriting
-    # some existing file.
-    my $dirname = $filename;
-    $dirname =~ s{/[^/]+$}{/};
-
-    my @chars = ('a'..'z', 'A'..'Z', '0'..'9');
-    my $newname = $dirname;
-    foreach (0..7) {
-        $newname .= $chars[rand @chars];
-    }
-
-    $g->upload ($do_upload, $newname);
-
-    # Backup or overwrite?
-    $g->mv ($filename, "$filename$backup") if defined $backup;
-    $g->mv ($newname, $filename);
-
-    $g->umount_all ();
-    $g->sync ();
-}
-
-undef $g;
-
-=head1 NON-INTERACTIVE EDITING
-
-C<virt-edit> normally calls out to C<$EDITOR> (or vi) so
-the system administrator can interactively edit the file.
-
-There are two ways also to use C<virt-edit> from scripts in order to
-make automated edits to files.  (Note that although you I<can> use
-C<virt-edit> like this, it's less error-prone to write scripts
-directly using the libguestfs API and Augeas for configuration file
-editing.)
-
-The first method is to temporarily set C<$EDITOR> to any script or
-program you want to run.  The script is invoked as C<$EDITOR tmpfile>
-and it should update C<tmpfile> in place however it likes.
-
-The second method is to use the I<-e> parameter of C<virt-edit> to run
-a short Perl snippet in the style of L<sed(1)>.  For example to
-replace all instances of C<foo> with C<bar> in a file:
-
- virt-edit domname filename -e 's/foo/bar/'
-
-The full power of Perl regular expressions can be used (see
-L<perlre(1)>).  For example to delete root's password you could do:
-
- virt-edit domname /etc/passwd -e 's/^root:.*?:/root::/'
-
-What really happens is that the snippet is evaluated as a Perl
-expression for each line of the file.  The line, including the final
-C<\n>, is passed in C<$_> and the expression should update C<$_> or
-leave it unchanged.
-
-To delete a line, set C<$_> to the empty string.  For example, to
-delete the C<apache> user account from the password file you can do:
-
- virt-edit mydomain /etc/passwd -e '$_ = "" if /^apache:/'
-
-To insert a line, prepend or append it to C<$_>.  However appending
-lines to the end of the file is rather difficult this way since there
-is no concept of "last line of the file" - your expression just
-doesn't get called again.  You might want to use the first method
-(setting C<$EDITOR>) if you want to do this.
-
-The variable C<$lineno> contains the current line number.
-As is traditional, the first line in the file is number C<1>.
-
-The return value from the expression is ignored, but the expression
-may call C<die> in order to abort the whole program, leaving the
-original file untouched.
-
-Remember when matching the end of a line that C<$_> may contain the
-final C<\n>, or (for DOS files) C<\r\n>, or if the file does not end
-with a newline then neither of these.  Thus to match or substitute
-some text at the end of a line, use this regular expression:
-
- /some text(\r?\n)?$/
-
-Alternately, use the perl C<chomp> function, being careful not to
-chomp C<$_> itself (since that would remove all newlines from the
-file):
-
- my $m = $_; chomp $m; $m =~ /some text$/
-
-=head1 WINDOWS PATHS
-
-C<virt-edit> has a limited ability to understand Windows drive letters
-and paths (eg. C<E:\foo\bar.txt>).
-
-If and only if the guest is running Windows then:
-
-=over 4
-
-=item *
-
-Drive letter prefixes like C<C:> are resolved against the
-Windows Registry to the correct filesystem.
-
-=item *
-
-Any backslash (C<\>) characters in the path are replaced
-with forward slashes so that libguestfs can process it.
-
-=item *
-
-The path is resolved case insensitively to locate the file
-that should be edited.
-
-=back
-
-There are some known shortcomings:
-
-=over 4
-
-=item *
-
-Some NTFS symbolic links may not be followed correctly.
-
-=item *
-
-NTFS junction points that cross filesystems are not followed.
-
-=back
-
-=cut
-
-sub windows_path
-{
-    my $g = shift;
-    my $root = shift;
-    my $filename = shift;
-
-    # Deal with drive letters.
-    if ($filename =~ /^([a-z]):(.*)/i) {
-        $filename = $2;
-        my $drive_letter = $1;
-
-        # Look up the drive letter in the drive mapping table.  We
-        # have to do a case insensitive comparison, the slow way.
-        my $device;
-        my %drives = $g->inspect_get_drive_mappings ($root);
-        foreach (keys %drives) {
-            if (lc $_ eq lc $drive_letter) {
-                $device = $drives{$_};
-                last;
-            }
-        }
-
-        die __x("virt-edit: drive '{x}:' not found\n", x => $drive_letter)
-            unless defined $device;
-
-        # Unmount current disk and remount $device.
-        $g->umount_all ();
-        $g->mount_options ("", $device, "/");
-    }
-
-    # Replace any backslashes in the rest of the path with
-    # forward slashes.
-    $filename =~ s{\\}{/}g;
-
-    # If the user put \foo on the command line without quoting it
-    # properly, then we'll see that here as a bare path.  Add a more
-    # descriptive error message here.
-    if (substr ($filename, 0, 1) ne "/") {
-        die __x("virt-edit: '{f}' does not start with a / or \\ character.
-If you are using Windows style paths with backslashes like C:\\foo.txt
-then don't forget that you must quote them with single quotes to
-prevent the shell from munging the backslashes.\n",
-                f => $filename)
-    }
-
-    # Case sensitivity.
-    $filename = $g->case_sensitive_path ($filename);
-
-    return $filename;
-}
-
-=head1 USING GUESTFISH
-
-L<guestfish(1)> is a more powerful, lower level tool which you can use
-when C<virt-edit> doesn't work.
-
-Using C<virt-edit> is approximately equivalent to doing:
-
- guestfish --rw -i -d domname edit /file
-
-where C<domname> is the name of the libvirt guest, and C</file> is the
-full path to the file.
-
-The command above uses libguestfs's guest inspection feature and so
-does not work on guests that libguestfs cannot inspect, or on things
-like arbitrary disk images that don't contain guests.  To edit a file
-on a disk image directly, use:
-
- guestfish --rw -a disk.img -m /dev/sda1 edit /file
-
-where C<disk.img> is the disk image, C</dev/sda1> is the filesystem
-within the disk image to edit, and C</file> is the full path to the
-file.
-
-C<virt-edit> cannot create new files.  Use the guestfish commands
-C<touch>, C<write> or C<upload> instead:
-
- guestfish --rw -i -d domname touch /newfile
-
- guestfish --rw -i -d domname write /newfile "new content"
-
- guestfish --rw -i -d domname upload localfile /newfile
-
-C<virt-edit> cannot edit multiple files, but guestfish can
-do it like this:
-
- guestfish --rw -i -d domname edit /file1 : edit /file2
-
-=cut
-
-exit 0;
-
-=head1 ENVIRONMENT VARIABLES
-
-=over 4
-
-=item C<EDITOR>
-
-If set, this string is used as the editor.  It may contain arguments,
-eg. C<"emacs -nw">
-
-If not set, C<vi> is used.
-
-=back
-
-=head1 SHELL QUOTING
-
-Libvirt guest names can contain arbitrary characters, some of which
-have meaning to the shell such as C<#> and space.  You may need to
-quote or escape these characters on the command line.  See the shell
-manual page L<sh(1)> for details.
-
-=head1 SEE ALSO
-
-L<guestfs(3)>,
-L<guestfish(1)>,
-L<virt-cat(1)>,
-L<virt-copy-in(1)>,
-L<virt-tar-in(1)>,
-L<Sys::Guestfs(3)>,
-L<Sys::Guestfs::Lib(3)>,
-L<Sys::Virt(3)>,
-L<http://libguestfs.org/>,
-L<perl(1)>,
-L<perlre(1)>.
-
-=head1 AUTHOR
-
-Richard W.M. Jones L<http://people.redhat.com/~rjones/>
-
-=head1 COPYRIGHT
-
-Copyright (C) 2009-2011 Red Hat Inc.
-
-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.