Add 'version' call to get true library version number.

[libguestfs.git] / src / generator.ml

diff --git a/src/generator.ml b/src/generator.ml
index bc5b805..0904afc 100755 (executable)
--- a/src/generator.ml
+++ b/src/generator.ml
@@ -636,6 +636,36 @@ qemu subprocess, then this will return an error.
 
 This is an internal call used for debugging and testing.");
 
+  ("version", (RStruct ("version", "version"), []), -1, [],
+   [InitBasicFS, Always, TestOutputStruct (
+      [["version"]], [CompareWithInt ("major", 1)])],
+   "get the library version number",
+   "\
+Return the libguestfs version number that the program is linked
+against.
+
+Note that because of dynamic linking this is not necessarily
+the version of libguestfs that you compiled against.  You can
+compile the program, and then at runtime dynamically link
+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
+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).
+
+The call returns a structure with four elements.  The first
+three (C<major>, C<minor> and C<release>) are numbers and
+correspond to the usual version triplet.  The fourth element
+(C<extra>) is a string and is normally empty, but may be
+used for distro-specific information.
+
+To construct the original version string:
+C<$major.$minor.$release$extra>
+
+I<Note:> Don't use this call to test for availability
+of features.  Distro backports makes this unreliable.");
+
 ]
 
 (* daemon_functions are any functions which cause some action
@@ -2928,6 +2958,14 @@ let structs = [
     "ftyp", FChar;
     "name", FString;
   ];
+
+  (* Version numbers. *)
+  "version", [
+    "major", FInt64;
+    "minor", FInt64;
+    "release", FInt64;
+    "extra", FString;
+  ];
 ] (* end of structs *)
 
 (* Ugh, Java has to be different ..
@@ -2940,7 +2978,8 @@ let java_structs = [
   "lvm_lv", "LV";
   "stat", "Stat";
   "statvfs", "StatVFS";
-  "dirent", "Dirent"
+  "dirent", "Dirent";
+  "version", "Version";
 ]
 
 (* Used for testing language bindings. *)
@@ -6048,30 +6087,33 @@ and generate_perl_struct_code typ cols name style n do_cleanups =
   do_cleanups ();
   pr "      if (%s == NULL)\n" n;
   pr "        croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
-  pr "      EXTEND (SP, %d);\n" (List.length cols);
+  pr "      EXTEND (SP, 2 * %d);\n" (List.length cols);
   List.iter (
-    function
-    | name, FString ->
-       pr "      PUSHs (sv_2mortal (newSVpv (%s->%s, 0)));\n"
-         n name
-    | name, FUUID ->
-       pr "      PUSHs (sv_2mortal (newSVpv (%s->%s, 32)));\n"
-         n name
-    | name, (FBytes|FUInt64) ->
-       pr "      PUSHs (sv_2mortal (my_newSVull (%s->%s)));\n"
-         n name
-    | name, FInt64 ->
-       pr "      PUSHs (sv_2mortal (my_newSVll (%s->%s)));\n"
-         n name
-    | name, (FInt32|FUInt32) ->
-       pr "      PUSHs (sv_2mortal (newSVnv (%s->%s)));\n"
-         n name
-    | name, FChar ->
-       pr "      PUSHs (sv_2mortal (newSVpv (&%s->%s, 1)));\n"
-         n name
-    | name, FOptPercent ->
-       pr "      PUSHs (sv_2mortal (newSVnv (%s->%s)));\n"
-         n name
+    fun ((name, _) as col) ->
+      pr "      PUSHs (sv_2mortal (newSVpv (\"%s\", 0)));\n" name;
+
+      match col with
+      | name, FString ->
+         pr "      PUSHs (sv_2mortal (newSVpv (%s->%s, 0)));\n"
+           n name
+      | name, FUUID ->
+         pr "      PUSHs (sv_2mortal (newSVpv (%s->%s, 32)));\n"
+           n name
+      | name, (FBytes|FUInt64) ->
+         pr "      PUSHs (sv_2mortal (my_newSVull (%s->%s)));\n"
+           n name
+      | name, FInt64 ->
+         pr "      PUSHs (sv_2mortal (my_newSVll (%s->%s)));\n"
+           n name
+      | name, (FInt32|FUInt32) ->
+         pr "      PUSHs (sv_2mortal (newSVnv (%s->%s)));\n"
+           n name
+      | name, FChar ->
+         pr "      PUSHs (sv_2mortal (newSVpv (&%s->%s, 1)));\n"
+           n name
+      | name, FOptPercent ->
+         pr "      PUSHs (sv_2mortal (newSVnv (%s->%s)));\n"
+           n name
   ) cols;
   pr "      free (%s);\n" n
 
@@ -6120,6 +6162,10 @@ Libguestfs provides ways to enumerate guest storage (eg. partitions,
 LVs, what filesystem is in each LV, etc.).  It can also run commands
 in the context of the guest.  Also you can access filesystems over FTP.
 
+See also L<Sys::Guestfs::Lib(3)> for a set of useful library
+functions for using libguestfs from Perl, including integration
+with libvirt.
+
 =head1 ERRORS
 
 All errors turn into calls to C<croak> (see L<Carp(3)>).
@@ -6191,7 +6237,10 @@ Please see the file COPYING.LIB for the full license.
 
 =head1 SEE ALSO
 
-L<guestfs(3)>, L<guestfish(1)>.
+L<guestfs(3)>,
+L<guestfish(1)>,
+L<http://libguestfs.org>,
+L<Sys::Guestfs::Lib(3)>.
 
 =cut
 "