guestfs: Reference guestfs-browser architecture in threads documentation.

[libguestfs.git] / src / generator.ml

diff --git a/src/generator.ml b/src/generator.ml
index 742a88c..e5fd335 100755 (executable)
--- a/src/generator.ml
+++ b/src/generator.ml
@@ -307,6 +307,9 @@ and test_prereq =
     (* As for 'If' but the test runs _unless_ the code returns true. *)
   | Unless of string
 
     (* As for 'If' but the test runs _unless_ the code returns true. *)
   | Unless of string
 

+    (* Run the test only if 'string' is available in the daemon. *)
+  | IfAvailable of string
+

 (* Some initial scenarios for testing. *)
 and test_init =
     (* Do nothing, block devices could contain random stuff including
 (* Some initial scenarios for testing. *)
 and test_init =
     (* Do nothing, block devices could contain random stuff including


@@ -545,15 +548,13 @@ handle is closed.  We don't currently have any method to enable
 changes to be committed, although qemu can support this.
 
 This is equivalent to the qemu parameter
 changes to be committed, although qemu can support this.
 
 This is equivalent to the qemu parameter

-C<-drive file=filename,snapshot=on,readonly=on,if=...>.
+C<-drive file=filename,snapshot=on,if=...>.

 
 C<if=...> is set at compile time by the configuration option
 C<./configure --with-drive-if=...>.  In the rare case where you
 might need to change this at run time, use C<guestfs_add_drive_with_if>
 or C<guestfs_add_drive_ro_with_if>.
 
 
 C<if=...> is set at compile time by the configuration option
 C<./configure --with-drive-if=...>.  In the rare case where you
 might need to change this at run time, use C<guestfs_add_drive_with_if>
 or C<guestfs_add_drive_ro_with_if>.
 

-C<readonly=on> is only added where qemu supports this option.
-

 Note that this call checks for the existence of C<filename>.  This
 stops you from specifying other types of drive which are supported
 by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
 Note that this call checks for the existence of C<filename>.  This
 stops you from specifying other types of drive which are supported
 by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use


@@ -572,7 +573,7 @@ The first character of C<param> string must be a C<-> (dash).
 
 C<value> can be NULL.");
 
 
 C<value> can be NULL.");
 

-  ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"],
+  ("set_qemu", (RErr, [OptString "qemu"]), -1, [FishAlias "qemu"],

    [],
    "set the qemu binary",
    "\
    [],
    "set the qemu binary",
    "\


@@ -604,7 +605,7 @@ Return the current qemu binary.
 This is always non-NULL.  If it wasn't set already, then this will
 return the default qemu binary name.");
 
 This is always non-NULL.  If it wasn't set already, then this will
 return the default qemu binary name.");
 

-  ("set_path", (RErr, [String "searchpath"]), -1, [FishAlias "path"],
+  ("set_path", (RErr, [OptString "searchpath"]), -1, [FishAlias "path"],

    [],
    "set the search path",
    "\
    [],
    "set the search path",
    "\


@@ -791,8 +792,9 @@ against a completely different C<libguestfs.so> library.
 
 This call was added in version C<1.0.58>.  In previous
 versions of libguestfs there was no way to get the version
 
 This call was added in version C<1.0.58>.  In previous
 versions of libguestfs there was no way to get the version

-number.  From C code you can use ELF weak linking tricks to find out if
-this symbol exists (if it doesn't, then it's an earlier version).
+number.  From C code you can use dynamic linker functions
+to find out if this symbol exists (if it doesn't, then
+it's an earlier version).

 
 The call returns a structure with four elements.  The first
 three (C<major>, C<minor> and C<release>) are numbers and
 
 The call returns a structure with four elements.  The first
 three (C<major>, C<minor> and C<release>) are numbers and


@@ -803,9 +805,13 @@ used for distro-specific information.
 To construct the original version string:
 C<$major.$minor.$release$extra>
 
 To construct the original version string:
 C<$major.$minor.$release$extra>
 

+See also: L<guestfs(3)/LIBGUESTFS VERSION NUMBERS>.
+

 I<Note:> Don't use this call to test for availability
 I<Note:> Don't use this call to test for availability

-of features.  Distro backports makes this unreliable.  Use
-C<guestfs_available> instead.");
+of features.  In enterprise distributions we backport
+features from later versions into earlier versions,
+making this an unreliable way to test for features.
+Use C<guestfs_available> instead.");

 
   ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"],
    [InitNone, Always, TestOutputTrue (
 
   ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"],
    [InitNone, Always, TestOutputTrue (


@@ -1547,7 +1553,10 @@ C<guestfs_part_init>");
        ["cat"; "/new"]], "\n\n\n");
     InitBasicFS, Always, TestOutput (
       [["write_file"; "/new"; "\n"; "0"];
        ["cat"; "/new"]], "\n\n\n");
     InitBasicFS, Always, TestOutput (
       [["write_file"; "/new"; "\n"; "0"];

-       ["cat"; "/new"]], "\n")],
+       ["cat"; "/new"]], "\n");
+    (* Regression test for RHBZ#597135. *)
+    InitBasicFS, Always, TestLastFail
+      [["write_file"; "/new"; "abc"; "10000"]]],

    "create a file",
    "\
 This call creates a file called C<path>.  The contents of the
    "create a file",
    "\
 This call creates a file called C<path>.  The contents of the


@@ -2319,7 +2328,18 @@ See also: C<guestfs_scrub_device>.");
    "install GRUB",
    "\
 This command installs GRUB (the Grand Unified Bootloader) on
    "install GRUB",
    "\
 This command installs GRUB (the Grand Unified Bootloader) on

-C<device>, with the root directory being C<root>.");
+C<device>, with the root directory being C<root>.
+
+Note: If grub-install reports the error
+\"No suitable drive was found in the generated device map.\"
+it may be that you need to create a C</boot/grub/device.map>
+file first that contains the mapping between grub device names
+and Linux device names.  It is usually sufficient to create
+a file containing:
+
+ (hd0) /dev/vda
+
+replacing C</dev/vda> with the name of the installation device.");

 
   ("cp", (RErr, [Pathname "src"; Pathname "dest"]), 87, [],
    [InitBasicFS, Always, TestOutput (
 
   ("cp", (RErr, [Pathname "src"; Pathname "dest"]), 87, [],
    [InitBasicFS, Always, TestOutput (


@@ -2442,12 +2462,41 @@ the list of printable strings found.");
    "print the printable strings in a file",
    "\
 This is like the C<guestfs_strings> command, but allows you to
    "print the printable strings in a file",
    "\
 This is like the C<guestfs_strings> command, but allows you to

-specify the encoding.
+specify the encoding of strings that are looked for in
+the source file C<path>.
+
+Allowed encodings are:
+
+=over 4
+
+=item s
+
+Single 7-bit-byte characters like ASCII and the ASCII-compatible
+parts of ISO-8859-X (this is what C<guestfs_strings> uses).
+
+=item S
+
+Single 8-bit-byte characters.
+
+=item b
+
+16-bit big endian strings such as those encoded in
+UTF-16BE or UCS-2BE.

 
 

-See the L<strings(1)> manpage for the full list of encodings.
+=item l (lower case letter L)

 
 

-Commonly useful encodings are C<l> (lower case L) which will
-show strings inside Windows/x86 files.
+16-bit little endian such as UTF-16LE and UCS-2LE.
+This is useful for examining binaries in Windows guests.
+
+=item B
+
+32-bit big endian such as UCS-4BE.
+
+=item L
+
+32-bit little endian such as UCS-4LE.
+
+=back

 
 The returned strings are transcoded to UTF-8.");
 
 
 The returned strings are transcoded to UTF-8.");
 


@@ -2596,9 +2645,9 @@ is lost.");
 
   ("resize2fs", (RErr, [Device "device"]), 106, [],
    [], (* lvresize tests this *)
 
   ("resize2fs", (RErr, [Device "device"]), 106, [],
    [], (* lvresize tests this *)

-   "resize an ext2/ext3 filesystem",
+   "resize an ext2, ext3 or ext4 filesystem",

    "\
    "\

-This resizes an ext2 or ext3 filesystem to match the size of
+This resizes an ext2, ext3 or ext4 filesystem to match the size of

 the underlying device.
 
 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
 the underlying device.
 
 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>


@@ -3111,7 +3160,7 @@ Unknown file type
 
 =item '?'
 
 
 =item '?'
 

-The L<readdir(3)> returned a C<d_type> field with an
+The L<readdir(3)> call returned a C<d_type> field with an

 unexpected value
 
 =back
 unexpected value
 
 =back


@@ -3255,7 +3304,20 @@ for full details.");
 
   ("read_file", (RBufferOut "content", [Pathname "path"]), 150, [ProtocolLimitWarning],
    [InitISOFS, Always, TestOutputBuffer (
 
   ("read_file", (RBufferOut "content", [Pathname "path"]), 150, [ProtocolLimitWarning],
    [InitISOFS, Always, TestOutputBuffer (

-      [["read_file"; "/known-4"]], "abc\ndef\nghi")],
+      [["read_file"; "/known-4"]], "abc\ndef\nghi");
+    (* Test various near large, large and too large files (RHBZ#589039). *)
+    InitBasicFS, Always, TestLastFail (
+      [["touch"; "/a"];
+       ["truncate_size"; "/a"; "4194303"]; (* GUESTFS_MESSAGE_MAX - 1 *)
+       ["read_file"; "/a"]]);
+    InitBasicFS, Always, TestLastFail (
+      [["touch"; "/a"];
+       ["truncate_size"; "/a"; "4194304"]; (* GUESTFS_MESSAGE_MAX *)
+       ["read_file"; "/a"]]);
+    InitBasicFS, Always, TestLastFail (
+      [["touch"; "/a"];
+       ["truncate_size"; "/a"; "41943040"]; (* GUESTFS_MESSAGE_MAX * 10 *)
+       ["read_file"; "/a"]])],

    "read a file",
    "\
 This calls returns the contents of the file C<path> as a
    "read a file",
    "\
 This calls returns the contents of the file C<path> as a


@@ -3740,8 +3802,8 @@ was built (see C<appliance/kmod.whitelist.in> in the source).");
     )],
    "echo arguments back to the client",
    "\
     )],
    "echo arguments back to the client",
    "\

-This command concatenate the list of C<words> passed with single spaces between
-them and returns the resulting string.
+This command concatenates the list of C<words> passed with single spaces
+between them and returns the resulting string.

 
 You can use this command to test the connection through to the daemon.
 
 
 You can use this command to test the connection through to the daemon.
 


@@ -3843,12 +3905,13 @@ See also C<guestfs_realpath>.");
       [["vfs_type"; "/dev/sda1"]], "ext2")],
    "get the Linux VFS type corresponding to a mounted device",
    "\
       [["vfs_type"; "/dev/sda1"]], "ext2")],
    "get the Linux VFS type corresponding to a mounted device",
    "\

-This command gets the block device type corresponding to
-a mounted device called C<device>.
+This command gets the filesystem type corresponding to
+the filesystem on C<device>.

 
 

-Usually the result is the name of the Linux VFS module that
-is used to mount this device (probably determined automatically
-if you used the C<guestfs_mount> call).");
+For most filesystems, the result is the name of the Linux
+VFS module which would be used to mount this filesystem
+if you mounted it without specifying the filesystem type.
+For example a string such as C<ext3> or C<ntfs>.");

 
   ("truncate", (RErr, [Pathname "path"]), 199, [],
    [InitBasicFS, Always, TestOutputStruct (
 
   ("truncate", (RErr, [Pathname "path"]), 199, [],
    [InitBasicFS, Always, TestOutputStruct (


@@ -3868,8 +3931,13 @@ file must exist already.");
    "truncate a file to a particular size",
    "\
 This command truncates C<path> to size C<size> bytes.  The file
    "truncate a file to a particular size",
    "\
 This command truncates C<path> to size C<size> bytes.  The file

-must exist already.  If the file is smaller than C<size> then
-the file is extended to the required size with null bytes.");
+must exist already.
+
+If the current file size is less than C<size> then
+the file is extended to the required size with zero bytes.
+This creates a sparse file (ie. disk blocks are not allocated
+for the file until you write to it).  To create a non-sparse
+file of zeroes, use C<guestfs_fallocate64> instead.");

 
   ("utimens", (RErr, [Pathname "path"; Int64 "atsecs"; Int64 "atnsecs"; Int64 "mtsecs"; Int64 "mtnsecs"]), 201, [],
    [InitBasicFS, Always, TestOutputStruct (
 
   ("utimens", (RErr, [Pathname "path"; Int64 "atsecs"; Int64 "atnsecs"; Int64 "mtsecs"; Int64 "mtnsecs"]), 201, [],
    [InitBasicFS, Always, TestOutputStruct (


@@ -3979,7 +4047,7 @@ C<names> is the list of files from this directory.
 
 On return you get a list of strings, with a one-to-one
 correspondence to the C<names> list.  Each string is the
 
 On return you get a list of strings, with a one-to-one
 correspondence to the C<names> list.  Each string is the

-value of the symbol link.
+value of the symbolic link.

 
 If the C<readlink(2)> operation fails on any name, then
 the corresponding result string is the empty string C<\"\">.
 
 If the C<readlink(2)> operation fails on any name, then
 the corresponding result string is the empty string C<\"\">.


@@ -5168,7 +5236,7 @@ let rec generate_actions_pod () =
 The string is owned by the guest handle and must I<not> be freed.\n\n"
          | RConstOptString _ ->
              pr "This function returns a string which may be NULL.
 The string is owned by the guest handle and must I<not> be freed.\n\n"
          | RConstOptString _ ->
              pr "This function returns a string which may be NULL.

-There is way to return an error from this function.
+There is no way to return an error from this function.

 The string is owned by the guest handle and must I<not> be freed.\n\n"
          | RString _ ->
              pr "This function returns a string, or NULL on error.
 The string is owned by the guest handle and must I<not> be freed.\n\n"
          | RString _ ->
              pr "This function returns a string, or NULL on error.


@@ -5273,7 +5341,7 @@ and generate_xdr () =
   generate_header CStyle LGPLv2plus;
 
   (* This has to be defined to get around a limitation in Sun's rpcgen. *)
   generate_header CStyle LGPLv2plus;
 
   (* This has to be defined to get around a limitation in Sun's rpcgen. *)

-  pr "typedef string str<>;\n";
+  pr "typedef string guestfs_str<>;\n";

   pr "\n";
 
   (* Internal structures. *)
   pr "\n";
 
   (* Internal structures. *)


@@ -5308,8 +5376,8 @@ and generate_xdr () =
              function
              | Pathname n | Device n | Dev_or_Path n | String n ->
                  pr "  string %s<>;\n" n
              function
              | Pathname n | Device n | Dev_or_Path n | String n ->
                  pr "  string %s<>;\n" n

-             | OptString n -> pr "  str *%s;\n" n
-             | StringList n | DeviceList n -> pr "  str %s<>;\n" n
+             | OptString n -> pr "  guestfs_str *%s;\n" n
+             | StringList n | DeviceList n -> pr "  guestfs_str %s<>;\n" n

              | Bool n -> pr "  bool %s;\n" n
              | Int n -> pr "  int %s;\n" n
              | Int64 n -> pr "  hyper %s;\n" n
              | Bool n -> pr "  bool %s;\n" n
              | Int n -> pr "  int %s;\n" n
              | Int64 n -> pr "  hyper %s;\n" n


@@ -5339,7 +5407,7 @@ and generate_xdr () =
            pr "};\n\n"
        | RStringList n ->
            pr "struct %s_ret {\n" name;
            pr "};\n\n"
        | RStringList n ->
            pr "struct %s_ret {\n" name;

-           pr "  str %s<>;\n" n;
+           pr "  guestfs_str %s<>;\n" n;

            pr "};\n\n"
        | RStruct (n, typ) ->
            pr "struct %s_ret {\n" name;
            pr "};\n\n"
        | RStruct (n, typ) ->
            pr "struct %s_ret {\n" name;


@@ -5351,7 +5419,7 @@ and generate_xdr () =
            pr "};\n\n"
        | RHashtable n ->
            pr "struct %s_ret {\n" name;
            pr "};\n\n"
        | RHashtable n ->
            pr "struct %s_ret {\n" name;

-           pr "  str %s<>;\n" n;
+           pr "  guestfs_str %s<>;\n" n;

            pr "};\n\n"
        | RBufferOut n ->
            pr "struct %s_ret {\n" name;
            pr "};\n\n"
        | RBufferOut n ->
            pr "struct %s_ret {\n" name;


@@ -5575,7 +5643,7 @@ check_state (guestfs_h *g, const char *caller)
                    | StringList _ | DeviceList _ -> true
                    | _ -> false) (snd style) in
     if needs_i then (
                    | StringList _ | DeviceList _ -> true
                    | _ -> false) (snd style) in
     if needs_i then (

-      pr "    int i;\n";
+      pr "    size_t i;\n";

       pr "\n"
     );
 
       pr "\n"
     );
 


@@ -5884,6 +5952,8 @@ and generate_linker_script () =
      *)
     "guestfs_safe_calloc";
     "guestfs_safe_malloc";
      *)
     "guestfs_safe_calloc";
     "guestfs_safe_malloc";

+    "guestfs_safe_strdup";
+    "guestfs_safe_memdup";

   ] in
   let functions =
     List.map (fun (name, _, _, _, _, _, _) -> "guestfs_" ^ name)
   ] in
   let functions =
     List.map (fun (name, _, _, _, _, _, _) -> "guestfs_" ^ name)


@@ -6004,9 +6074,12 @@ and generate_daemon_actions () =
              | DeviceList n ->
                  pr_list_handling_code n;
                  pr "  /* Ensure that each is a device,\n";
              | DeviceList n ->
                  pr_list_handling_code n;
                  pr "  /* Ensure that each is a device,\n";

-                 pr "   * and perform device name translation. */\n";
-                 pr "  { int pvi; for (pvi = 0; physvols[pvi] != NULL; ++pvi)\n";
-                 pr "    RESOLVE_DEVICE (physvols[pvi], goto done);\n";
+                 pr "   * and perform device name translation.\n";
+                 pr "   */\n";
+                 pr "  {\n";
+                 pr "    size_t i;\n";
+                 pr "    for (i = 0; %s[i] != NULL; ++i)\n" n;
+                 pr "      RESOLVE_DEVICE (%s[i], goto done);\n" n;

                  pr "  }\n";
              | Bool n -> pr "  %s = args.%s;\n" n n
              | Int n -> pr "  %s = args.%s;\n" n n
                  pr "  }\n";
              | Bool n -> pr "  %s = args.%s;\n" n n
              | Int n -> pr "  %s = args.%s;\n" n n


@@ -6151,7 +6224,7 @@ and generate_daemon_actions () =
         pr "static int lvm_tokenize_%s (char *str, guestfs_int_lvm_%s *r)\n" typ typ;
         pr "{\n";
         pr "  char *tok, *p, *next;\n";
         pr "static int lvm_tokenize_%s (char *str, guestfs_int_lvm_%s *r)\n" typ typ;
         pr "{\n";
         pr "  char *tok, *p, *next;\n";

-        pr "  int i, j;\n";
+        pr "  size_t i, j;\n";

         pr "\n";
         (*
           pr "  fprintf (stderr, \"%%s: <<%%s>>\\n\", __func__, str);\n";
         pr "\n";
         (*
           pr "  fprintf (stderr, \"%%s: <<%%s>>\\n\", __func__, str);\n";


@@ -6376,7 +6449,7 @@ static void print_error (guestfs_h *g, void *data, const char *msg)
 /* FIXME: nearly identical code appears in fish.c */
 static void print_strings (char *const *argv)
 {
 /* FIXME: nearly identical code appears in fish.c */
 static void print_strings (char *const *argv)
 {

-  int argc;
+  size_t argc;

 
   for (argc = 0; argv[argc] != NULL; ++argc)
     printf (\"\\t%%s\\n\", argv[argc]);
 
   for (argc = 0; argv[argc] != NULL; ++argc)
     printf (\"\\t%%s\\n\", argv[argc]);


@@ -6385,13 +6458,26 @@ static void print_strings (char *const *argv)
 /*
 static void print_table (char const *const *argv)
 {
 /*
 static void print_table (char const *const *argv)
 {

-  int i;
+  size_t i;

 
   for (i = 0; argv[i] != NULL; i += 2)
     printf (\"%%s: %%s\\n\", argv[i], argv[i+1]);
 }
 */
 
 
   for (i = 0; argv[i] != NULL; i += 2)
     printf (\"%%s: %%s\\n\", argv[i], argv[i+1]);
 }
 */
 

+static int
+is_available (const char *group)
+{
+  const char *groups[] = { group, NULL };
+  int r;
+
+  suppress_error = 1;
+  r = guestfs_available (g, (char **) groups);
+  suppress_error = 0;
+
+  return r == 0;
+}
+

 ";
 
   (* Generate a list of commands which are not tested anywhere. *)
 ";
 
   (* Generate a list of commands which are not tested anywhere. *)


@@ -6403,7 +6489,7 @@ static void print_table (char const *const *argv)
     fun (_, _, _, _, tests, _, _) ->
       let tests = filter_map (
         function
     fun (_, _, _, _, tests, _, _) ->
       let tests = filter_map (
         function

-        | (_, (Always|If _|Unless _), test) -> Some test
+        | (_, (Always|If _|Unless _|IfAvailable _), test) -> Some test

         | (_, Disabled, _) -> None
       ) tests in
       let seq = List.concat (List.map seq_of_test tests) in
         | (_, Disabled, _) -> None
       ) tests in
       let seq = List.concat (List.map seq_of_test tests) in


@@ -6609,7 +6695,7 @@ static int %s_skip (void)
 " test_name name (String.uppercase test_name) (String.uppercase name);
 
   (match prereq with
 " test_name name (String.uppercase test_name) (String.uppercase name);
 
   (match prereq with

-   | Disabled | Always -> ()
+   | Disabled | Always | IfAvailable _ -> ()

    | If code | Unless code ->
        pr "static int %s_prereq (void)\n" test_name;
        pr "{\n";
    | If code | Unless code ->
        pr "static int %s_prereq (void)\n" test_name;
        pr "{\n";


@@ -6634,16 +6720,9 @@ static int %s (void)
   List.iter (
     function
     | Optional group ->
   List.iter (
     function
     | Optional group ->

-        pr "  {\n";
-        pr "    const char *groups[] = { \"%s\", NULL };\n" group;
-        pr "    int r;\n";
-        pr "    suppress_error = 1;\n";
-        pr "    r = guestfs_available (g, (char **) groups);\n";
-        pr "    suppress_error = 0;\n";
-        pr "    if (r == -1) {\n";
-        pr "      printf (\"        %%s skipped (reason: group %%s not available in daemon)\\n\", \"%s\", groups[0]);\n" test_name;
-        pr "      return 0;\n";
-        pr "    }\n";
+        pr "  if (!is_available (\"%s\")) {\n" group;
+        pr "    printf (\"        %%s skipped (reason: group %%s not available in daemon)\\n\", \"%s\", \"%s\");\n" test_name group;
+        pr "    return 0;\n";

         pr "  }\n";
     | _ -> ()
   ) flags;
         pr "  }\n";
     | _ -> ()
   ) flags;


@@ -6665,6 +6744,13 @@ static int %s (void)
        pr "  }\n";
        pr "\n";
        generate_one_test_body name i test_name init test;
        pr "  }\n";
        pr "\n";
        generate_one_test_body name i test_name init test;

+   | IfAvailable group ->
+       pr "  if (!is_available (\"%s\")) {\n" group;
+       pr "    printf (\"        %%s skipped (reason: %%s not available)\\n\", \"%s\", \"%s\");\n" test_name group;
+       pr "    return 0;\n";
+       pr "  }\n";
+       pr "\n";
+       generate_one_test_body name i test_name init test;

    | Always ->
        generate_one_test_body name i test_name init test
   );
    | Always ->
        generate_one_test_body name i test_name init test
   );


@@ -7006,7 +7092,7 @@ and generate_test_command_call ?(expect_error = false) ?test test_name cmd =
         | RString _ -> pr "    char *r;\n"; "NULL"
         | RStringList _ | RHashtable _ ->
             pr "    char **r;\n";
         | RString _ -> pr "    char *r;\n"; "NULL"
         | RStringList _ | RHashtable _ ->
             pr "    char **r;\n";

-            pr "    int i;\n";
+            pr "    size_t i;\n";

             "NULL"
         | RStruct (_, typ) ->
             pr "    struct guestfs_%s *r;\n" typ; "NULL"
             "NULL"
         | RStruct (_, typ) ->
             pr "    struct guestfs_%s *r;\n" typ; "NULL"


@@ -7135,7 +7221,7 @@ and generate_fish_cmds () =
   pr "\n";
 
   (* display_command function, which implements guestfish -h cmd *)
   pr "\n";
 
   (* display_command function, which implements guestfish -h cmd *)

-  pr "void display_command (const char *cmd)\n";
+  pr "int display_command (const char *cmd)\n";

   pr "{\n";
   List.iter (
     fun (name, style, _, flags, _, shortdesc, longdesc) ->
   pr "{\n";
   List.iter (
     fun (name, style, _, flags, _, shortdesc, longdesc) ->


@@ -7183,15 +7269,17 @@ and generate_fish_cmds () =
         pr " || STRCASEEQ (cmd, \"%s\")" name2;
       if name <> alias then
         pr " || STRCASEEQ (cmd, \"%s\")" alias;
         pr " || STRCASEEQ (cmd, \"%s\")" name2;
       if name <> alias then
         pr " || STRCASEEQ (cmd, \"%s\")" alias;

-      pr ")\n";
+      pr ") {\n";

       pr "    pod2text (\"%s\", _(\"%s\"), %S);\n"
         name2 shortdesc
         ("=head1 SYNOPSIS\n\n " ^ synopsis ^ "\n\n" ^
          "=head1 DESCRIPTION\n\n" ^
          longdesc ^ warnings ^ describe_alias);
       pr "    pod2text (\"%s\", _(\"%s\"), %S);\n"
         name2 shortdesc
         ("=head1 SYNOPSIS\n\n " ^ synopsis ^ "\n\n" ^
          "=head1 DESCRIPTION\n\n" ^
          longdesc ^ warnings ^ describe_alias);

+      pr "    return 0;\n";
+      pr "  }\n";

       pr "  else\n"
   ) all_functions;
       pr "  else\n"
   ) all_functions;

-  pr "    display_builtin_command (cmd);\n";
+  pr "    return display_builtin_command (cmd);\n";

   pr "}\n";
   pr "\n";
 
   pr "}\n";
   pr "\n";
 


@@ -7400,9 +7488,10 @@ and generate_fish_cmds () =
 
       List.iter (
         function
 
       List.iter (
         function

-        | Device name | String name
-        | OptString name | FileIn name | FileOut name | Bool name
-        | Int name | Int64 name -> ()
+        | Device _ | String _
+        | OptString _ | Bool _
+        | Int _ | Int64 _
+        | FileIn _ | FileOut _ -> ()

         | Pathname name | Dev_or_Path name ->
             pr "  free (%s);\n" name
         | StringList name | DeviceList name ->
         | Pathname name | Dev_or_Path name ->
             pr "  free (%s);\n" name
         | StringList name | DeviceList name ->


@@ -7550,7 +7639,7 @@ static const char *const commands[] = {
 static char *
 generator (const char *text, int state)
 {
 static char *
 generator (const char *text, int state)
 {

-  static int index, len;
+  static size_t index, len;

   const char *name;
 
   if (!state) {
   const char *name;
 
   if (!state) {


@@ -7834,7 +7923,7 @@ and generate_ocaml_c () =
 #include <caml/mlvalues.h>
 #include <caml/signals.h>
 
 #include <caml/mlvalues.h>
 #include <caml/signals.h>
 

-#include <guestfs.h>
+#include \"guestfs.h\"

 
 #include \"guestfs_c.h\"
 
 
 #include \"guestfs_c.h\"
 


@@ -7847,7 +7936,7 @@ copy_table (char * const * argv)
 {
   CAMLparam0 ();
   CAMLlocal5 (rv, pairv, kv, vv, cons);
 {
   CAMLparam0 ();
   CAMLlocal5 (rv, pairv, kv, vv, cons);

-  int i;
+  size_t i;

 
   rv = Val_int (0);
   for (i = 0; argv[i] != NULL; i += 2) {
 
   rv = Val_int (0);
   for (i = 0; argv[i] != NULL; i += 2) {


@@ -8002,11 +8091,12 @@ copy_table (char * const * argv)
         | String n
         | FileIn n
         | FileOut n ->
         | String n
         | FileIn n
         | FileOut n ->

-            pr "  const char *%s = String_val (%sv);\n" n n
+            (* Copy strings in case the GC moves them: RHBZ#604691 *)
+            pr "  char *%s = guestfs_safe_strdup (g, String_val (%sv));\n" n n

         | OptString n ->
         | OptString n ->

-            pr "  const char *%s =\n" n;
-            pr "    %sv != Val_int (0) ? String_val (Field (%sv, 0)) : NULL;\n"
-              n n
+            pr "  char *%s =\n" n;
+            pr "    %sv != Val_int (0) ?" n;
+            pr "      guestfs_safe_strdup (g, String_val (Field (%sv, 0))) : NULL;\n" n

         | StringList n | DeviceList n ->
             pr "  char **%s = ocaml_guestfs_strings_val (g, %sv);\n" n n
         | Bool n ->
         | StringList n | DeviceList n ->
             pr "  char **%s = ocaml_guestfs_strings_val (g, %sv);\n" n n
         | Bool n ->


@@ -8026,7 +8116,7 @@ copy_table (char * const * argv)
             pr "  const char *r;\n"; "NULL"
         | RString _ -> pr "  char *r;\n"; "NULL"
         | RStringList _ ->
             pr "  const char *r;\n"; "NULL"
         | RString _ -> pr "  char *r;\n"; "NULL"
         | RStringList _ ->

-            pr "  int i;\n";
+            pr "  size_t i;\n";

             pr "  char **r;\n";
             "NULL"
         | RStruct (_, typ) ->
             pr "  char **r;\n";
             "NULL"
         | RStruct (_, typ) ->


@@ -8034,7 +8124,7 @@ copy_table (char * const * argv)
         | RStructList (_, typ) ->
             pr "  struct guestfs_%s_list *r;\n" typ; "NULL"
         | RHashtable _ ->
         | RStructList (_, typ) ->
             pr "  struct guestfs_%s_list *r;\n" typ; "NULL"
         | RHashtable _ ->

-            pr "  int i;\n";
+            pr "  size_t i;\n";

             pr "  char **r;\n";
             "NULL"
         | RBufferOut _ ->
             pr "  char **r;\n";
             "NULL"
         | RBufferOut _ ->


@@ -8049,13 +8139,15 @@ copy_table (char * const * argv)
       pr ";\n";
       pr "  caml_leave_blocking_section ();\n";
 
       pr ";\n";
       pr "  caml_leave_blocking_section ();\n";
 

+      (* Free strings if we copied them above. *)

       List.iter (
         function
       List.iter (
         function

+        | Pathname n | Device n | Dev_or_Path n | String n | OptString n
+        | FileIn n | FileOut n ->
+            pr "  free (%s);\n" n

         | StringList n | DeviceList n ->
             pr "  ocaml_guestfs_free_strings (%s);\n" n;
         | StringList n | DeviceList n ->
             pr "  ocaml_guestfs_free_strings (%s);\n" n;

-        | Pathname _ | Device _ | Dev_or_Path _ | String _ | OptString _
-        | Bool _ | Int _ | Int64 _
-        | FileIn _ | FileOut _ -> ()
+        | Bool _ | Int _ | Int64 _ -> ()

       ) (snd style);
 
       pr "  if (r == %s)\n" error_code;
       ) (snd style);
 
       pr "  if (r == %s)\n" error_code;


@@ -8394,7 +8486,7 @@ DESTROY (g)
        | RStringList n | RHashtable n ->
            pr "PREINIT:\n";
            pr "      char **%s;\n" n;
        | RStringList n | RHashtable n ->
            pr "PREINIT:\n";
            pr "      char **%s;\n" n;

-           pr "      int i, n;\n";
+           pr "      size_t i, n;\n";

            pr " PPCODE:\n";
            pr "      %s = guestfs_%s " n name;
            generate_c_call_args ~handle:"g" style;
            pr " PPCODE:\n";
            pr "      %s = guestfs_%s " n name;
            generate_c_call_args ~handle:"g" style;


@@ -8438,7 +8530,7 @@ DESTROY (g)
 and generate_perl_struct_list_code typ cols name style n do_cleanups =
   pr "PREINIT:\n";
   pr "      struct guestfs_%s_list *%s;\n" typ n;
 and generate_perl_struct_list_code typ cols name style n do_cleanups =
   pr "PREINIT:\n";
   pr "      struct guestfs_%s_list *%s;\n" typ n;

-  pr "      int i;\n";
+  pr "      size_t i;\n";

   pr "      HV *hv;\n";
   pr " PPCODE:\n";
   pr "      %s = guestfs_%s " n name;
   pr "      HV *hv;\n";
   pr " PPCODE:\n";
   pr "      %s = guestfs_%s " n name;


@@ -8637,6 +8729,37 @@ sub new {
 
 =back
 
 
 =back
 

+=head1 AVAILABILITY
+
+From time to time we add new libguestfs APIs.  Also some libguestfs
+APIs won't be available in all builds of libguestfs (the Fedora
+build is full-featured, but other builds may disable features).
+How do you test whether the APIs that your Perl program needs are
+available in the version of C<Sys::Guestfs> that you are using?
+
+To test if a particular function is available in the C<Sys::Guestfs>
+class, use the ordinary Perl UNIVERSAL method C<can(METHOD)>
+(see L<perlobj(1)>).  For example:
+
+ use Sys::Guestfs;
+ if (defined (Sys::Guestfs->can (\"set_verbose\"))) {
+   print \"\\$h->set_verbose is available\\n\";
+ }
+
+To test if particular features are supported by the current
+build, use the L</available> method like the example below.  Note
+that the appliance must be launched first.
+
+ $h->available ( [\"augeas\"] );
+
+Since the L</available> method croaks if the feature is not supported,
+you might also want to wrap this in an eval and return a boolean.
+In fact this has already been done for you: use
+L<Sys::Guestfs::Lib(3)/feature_available>.
+
+For further discussion on this topic, refer to
+L<guestfs(3)/AVAILABILITY>.
+

 =head1 COPYRIGHT
 
 Copyright (C) %s Red Hat Inc.
 =head1 COPYRIGHT
 
 Copyright (C) %s Red Hat Inc.


@@ -8692,6 +8815,12 @@ and generate_python_c () =
   pr "\
 #include <Python.h>
 
   pr "\
 #include <Python.h>
 

+#if PY_VERSION_HEX < 0x02050000
+typedef int Py_ssize_t;
+#define PY_SSIZE_T_MAX INT_MAX
+#define PY_SSIZE_T_MIN INT_MIN
+#endif
+

 #include <stdio.h>
 #include <stdlib.h>
 #include <assert.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <assert.h>


@@ -8723,7 +8852,7 @@ put_handle (guestfs_h *g)
 static char **
 get_string_list (PyObject *obj)
 {
 static char **
 get_string_list (PyObject *obj)
 {

-  int i, len;
+  size_t i, len;

   char **r;
 
   assert (obj);
   char **r;
 
   assert (obj);


@@ -8733,7 +8862,12 @@ get_string_list (PyObject *obj)
     return NULL;
   }
 
     return NULL;
   }
 

-  len = PyList_Size (obj);
+  Py_ssize_t slen = PyList_Size (obj);
+  if (slen == -1) {
+    PyErr_SetString (PyExc_RuntimeError, \"get_string_list: PyList_Size failure\");
+    return NULL;
+  }
+  len = (size_t) slen;

   r = malloc (sizeof (char *) * (len+1));
   if (r == NULL) {
     PyErr_SetString (PyExc_RuntimeError, \"get_string_list: out of memory\");
   r = malloc (sizeof (char *) * (len+1));
   if (r == NULL) {
     PyErr_SetString (PyExc_RuntimeError, \"get_string_list: out of memory\");


@@ -8831,7 +8965,7 @@ py_guestfs_close (PyObject *self, PyObject *args)
     pr "put_%s_list (struct guestfs_%s_list *%ss)\n" typ typ typ;
     pr "{\n";
     pr "  PyObject *list;\n";
     pr "put_%s_list (struct guestfs_%s_list *%ss)\n" typ typ typ;
     pr "{\n";
     pr "  PyObject *list;\n";

-    pr "  int i;\n";
+    pr "  size_t i;\n";

     pr "\n";
     pr "  list = PyList_New (%ss->len);\n" typ;
     pr "  for (i = 0; i < %ss->len; ++i)\n" typ;
     pr "\n";
     pr "  list = PyList_New (%ss->len);\n" typ;
     pr "  for (i = 0; i < %ss->len; ++i)\n" typ;


@@ -9314,7 +9448,7 @@ static VALUE ruby_guestfs_close (VALUE gv)
             pr "  char **%s;\n" n;
             pr "  Check_Type (%sv, T_ARRAY);\n" n;
             pr "  {\n";
             pr "  char **%s;\n" n;
             pr "  Check_Type (%sv, T_ARRAY);\n" n;
             pr "  {\n";

-            pr "    int i, len;\n";
+            pr "    size_t i, len;\n";

             pr "    len = RARRAY_LEN (%sv);\n" n;
             pr "    %s = guestfs_safe_malloc (g, sizeof (char *) * (len+1));\n"
               n;
             pr "    len = RARRAY_LEN (%sv);\n" n;
             pr "    %s = guestfs_safe_malloc (g, sizeof (char *) * (len+1));\n"
               n;


@@ -9385,7 +9519,7 @@ static VALUE ruby_guestfs_close (VALUE gv)
            pr "  free (r);\n";
            pr "  return rv;\n";
        | RStringList _ ->
            pr "  free (r);\n";
            pr "  return rv;\n";
        | RStringList _ ->

-           pr "  int i, len = 0;\n";
+           pr "  size_t i, len = 0;\n";

            pr "  for (i = 0; r[i] != NULL; ++i) len++;\n";
            pr "  VALUE rv = rb_ary_new2 (len);\n";
            pr "  for (i = 0; r[i] != NULL; ++i) {\n";
            pr "  for (i = 0; r[i] != NULL; ++i) len++;\n";
            pr "  VALUE rv = rb_ary_new2 (len);\n";
            pr "  for (i = 0; r[i] != NULL; ++i) {\n";


@@ -9402,7 +9536,7 @@ static VALUE ruby_guestfs_close (VALUE gv)
            generate_ruby_struct_list_code typ cols
        | RHashtable _ ->
            pr "  VALUE rv = rb_hash_new ();\n";
            generate_ruby_struct_list_code typ cols
        | RHashtable _ ->
            pr "  VALUE rv = rb_hash_new ();\n";

-           pr "  int i;\n";
+           pr "  size_t i;\n";

            pr "  for (i = 0; r[i] != NULL; i+=2) {\n";
            pr "    rb_hash_aset (rv, rb_str_new2 (r[i]), rb_str_new2 (r[i+1]));\n";
            pr "    free (r[i]);\n";
            pr "  for (i = 0; r[i] != NULL; i+=2) {\n";
            pr "    rb_hash_aset (rv, rb_str_new2 (r[i]), rb_str_new2 (r[i+1]));\n";
            pr "    free (r[i]);\n";


@@ -9471,7 +9605,7 @@ and generate_ruby_struct_code typ cols =
 (* Ruby code to return a struct list. *)
 and generate_ruby_struct_list_code typ cols =
   pr "  VALUE rv = rb_ary_new2 (r->len);\n";
 (* Ruby code to return a struct list. *)
 and generate_ruby_struct_list_code typ cols =
   pr "  VALUE rv = rb_ary_new2 (r->len);\n";

-  pr "  int i;\n";
+  pr "  size_t i;\n";

   pr "  for (i = 0; i < r->len; ++i) {\n";
   pr "    VALUE hv = rb_hash_new ();\n";
   List.iter (
   pr "  for (i = 0; i < r->len; ++i) {\n";
   pr "    VALUE hv = rb_hash_new ();\n";
   List.iter (


@@ -9871,7 +10005,7 @@ Java_com_redhat_et_libguestfs_GuestFS__1close
                        | DeviceList _ -> true
                        | _ -> false) (snd style) in
       if needs_i then
                        | DeviceList _ -> true
                        | _ -> false) (snd style) in
       if needs_i then

-        pr "  int i;\n";
+        pr "  size_t i;\n";

 
       pr "\n";
 
 
       pr "\n";
 


@@ -10509,7 +10643,7 @@ namespace Guestfs
            pr "      return r != 0 ? true : false;\n"
        | RHashtable _ ->
            pr "      Hashtable rr = new Hashtable ();\n";
            pr "      return r != 0 ? true : false;\n"
        | RHashtable _ ->
            pr "      Hashtable rr = new Hashtable ();\n";

-           pr "      for (int i = 0; i < r.Length; i += 2)\n";
+           pr "      for (size_t i = 0; i < r.Length; i += 2)\n";

            pr "        rr.Add (r[i], r[i+1]);\n";
            pr "      return rr;\n"
        | RInt _ | RInt64 _ | RConstString _ | RConstOptString _
            pr "        rr.Add (r[i], r[i+1]);\n";
            pr "      return rr;\n"
        | RInt _ | RInt64 _ | RConstString _ | RConstOptString _


@@ -10546,7 +10680,7 @@ and generate_bindtests () =
 static void
 print_strings (char *const *argv)
 {
 static void
 print_strings (char *const *argv)
 {

-  int argc;
+  size_t argc;

 
   printf (\"[\");
   for (argc = 0; argv[argc] != NULL; ++argc) {
 
   printf (\"[\");
   for (argc = 0; argv[argc] != NULL; ++argc) {