New APIs: guestfs_create_flags, guestfs_parse_environment,

guestfs_parse_environment_list.

Add a new function for creating a handle:

 guestfs_h *guestfs_create_flags (unsigned flags [, ...]);

This variant lets you supply flags and extra arguments, although extra
arguments are not used at the moment.

Of particular interest is the ability to separate the creation of the
handle from the parsing of environment variables like
LIBGUESTFS_DEBUG.  guestfs_create does both together, which prevents
us from propagating errors from parsing environment variables back to
the caller (guestfs_create has always printed any errors on stderr and
then just ignored them).

If you are interested in these errors, you can now write:

 g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
 if (!g)
   exit (EXIT_FAILURE);
 r = guestfs_parse_environment (g);
 if (!r)
   exit (EXIT_FAILURE);

Also you can *omit* the call to guestfs_parse_environment, which
creates a handle unaffected by the environment (which was not possible
before).

This commit also includes new (backwards compatible) changes to the
OCaml, Perl, Python, Ruby and Java constructors that let you use the
flags.

7 files changed, 123 insertions, 24 deletions

diff --git a/generator/actions.ml b/generator/actions.ml
index ac8e354a..dc712349 100644
--- a/generator/actions.ml
+++ b/generator/actions.ml
@@ -2480,6 +2480,39 @@ call this function to pass the answer back to libvirt.
 
 See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." };
 
+  { defaults with
+    name = "parse_environment";
+    style = RErr, [], [];
+    tests = [];
+    shortdesc = "parse the environment and set handle flags accordingly";
+    longdesc = "\
+Parse the program's environment and set flags in the handle
+accordingly.  For example if C<LIBGUESTFS_DEBUG=1> then the
+'verbose' flag is set in the handle.
+
+I<Most programs do not need to call this>.  It is done implicitly
+when you call C<guestfs_create>.
+
+See L<guestfs(3)/ENVIRONMENT VARIABLES> for a list of environment
+variables that can affect libguestfs handles.  See also
+L<guestfs(3)/guestfs_create_flags>, and
+C<guestfs_parse_environment_list>." };
+
+  { defaults with
+    name = "parse_environment_list";
+    style = RErr, [StringList "environment"], [];
+    tests = [];
+    shortdesc = "parse the environment and set handle flags accordingly";
+    longdesc = "\
+Parse the list of strings in the argument C<environment>
+and set flags in the handle accordingly.
+For example if C<LIBGUESTFS_DEBUG=1> is a string in the list,
+then the 'verbose' flag is set in the handle.
+
+This is the same as C<guestfs_parse_environment> except that
+it parses an explicit list of strings instead of the program's
+environment." };
+
 ]
 
 (* daemon_functions are any functions which cause some action
diff --git a/generator/c.ml b/generator/c.ml
index e159d8fa..ac8fd5ee 100644
--- a/generator/c.ml
+++ b/generator/c.ml
@@ -416,6 +416,9 @@ typedef struct guestfs_h guestfs_h;
 
 /* Connection management. */
 extern GUESTFS_DLL_PUBLIC guestfs_h *guestfs_create (void);
+extern GUESTFS_DLL_PUBLIC guestfs_h *guestfs_create_flags (unsigned flags, ...);
+#define GUESTFS_CREATE_NO_ENVIRONMENT   (1 << 0)
+#define GUESTFS_CREATE_NO_CLOSE_ON_EXIT (1 << 1)
 extern GUESTFS_DLL_PUBLIC void guestfs_close (guestfs_h *g);
 
 /* Error handling. */
@@ -1586,6 +1589,7 @@ and generate_linker_script () =
 
   let globals = [
     "guestfs_create";
+    "guestfs_create_flags";
     "guestfs_close";
     "guestfs_delete_event_callback";
     "guestfs_first_private";
diff --git a/generator/java.ml b/generator/java.ml
index f3b9f5f3..1e06c62d 100644
--- a/generator/java.ml
+++ b/generator/java.ml
@@ -56,15 +56,39 @@ public class GuestFS {
   long g;
 
   /**
+   * Create a libguestfs handle, setting flags.
+   *
+   * @throws LibGuestFSException
+   */
+  public GuestFS (Map<String, Object> optargs) throws LibGuestFSException
+  {
+    int flags = 0;
+
+    /* Unpack optional args. */
+    Object _optobj;
+    _optobj = null;
+    if (optargs != null)
+      _optobj = optargs.get (\"environment\");
+    if (_optobj != null && !((Boolean) _optobj).booleanValue())
+      flags |= 1;
+    if (optargs != null)
+      _optobj = optargs.get (\"close_on_exit\");
+    if (_optobj != null && !((Boolean) _optobj).booleanValue())
+      flags |= 2;
+
+    g = _create (flags);
+  }
+
+  /**
    * Create a libguestfs handle.
    *
    * @throws LibGuestFSException
    */
   public GuestFS () throws LibGuestFSException
   {
-    g = _create ();
+    g = _create (0);
   }
-  private native long _create () throws LibGuestFSException;
+  private native long _create (int flags) throws LibGuestFSException;
 
   /**
    * Close a libguestfs handle.
@@ -409,12 +433,12 @@ throw_exception (JNIEnv *env, const char *msg)
 }
 
 JNIEXPORT jlong JNICALL
-Java_com_redhat_et_libguestfs_GuestFS__1create
-  (JNIEnv *env, jobject obj)
+Java_com_redhat_et_libguestfs_GuestFS__1create (JNIEnv *env,
+                                                jobject obj_unused, jint flags)
 {
   guestfs_h *g;
 
-  g = guestfs_create ();
+  g = guestfs_create_flags ((int) flags);
   if (g == NULL) {
     throw_exception (env, \"GuestFS.create: failed to allocate handle\");
     return 0;
diff --git a/generator/ocaml.ml b/generator/ocaml.ml
index b04eb5fe..84210490 100644
--- a/generator/ocaml.ml
+++ b/generator/ocaml.ml
@@ -62,8 +62,14 @@ exception Handle_closed of string
     after calling {!close} on it.  The string is the name of
     the function. *)
 
-val create : unit -> t
-(** Create a {!t} handle. *)
+val create : ?environment:bool -> ?close_on_exit:bool -> unit -> t
+(** Create a {!t} handle.
+
+    [?environment] defaults to [true].  If set to false, it sets
+    the [GUESTFS_CREATE_NO_ENVIRONMENT] flag.
+
+    [?close_on_exit] defaults to [true].  If set to false, it sets
+    the [GUESTFS_CREATE_NO_CLOSE_ON_EXIT] flag. *)
 
 val close : t -> unit
 (** Close the {!t} handle and free up all resources used
@@ -171,7 +177,7 @@ val user_cancel : t -> unit
     For example [g#]{{!guestfs.get_verbose}get_verbose} [()]
     calls the method, whereas [g#get_verbose] is a function. *)
 
-class guestfs : unit -> object
+class guestfs : ?environment:bool -> ?close_on_exit:bool -> unit -> object
   method close : unit -> unit
   method set_event_callback : event_callback -> event list -> event_handle
   method delete_event_callback : event_handle -> unit
@@ -211,7 +217,8 @@ type t
 exception Error of string
 exception Handle_closed of string
 
-external create : unit -> t = \"ocaml_guestfs_create\"
+external create : ?environment:bool -> ?close_on_exit:bool -> unit -> t =
+  \"ocaml_guestfs_create\"
 external close : t -> unit = \"ocaml_guestfs_close\"
 
 type event =
@@ -265,8 +272,8 @@ let () =
 
   (* OO API. *)
   pr "
-class guestfs () =
-  let g = create () in
+class guestfs ?environment ?close_on_exit () =
+  let g = create ?environment ?close_on_exit () in
   object (self)
     method close () = close g
     method set_event_callback = set_event_callback g
diff --git a/generator/perl.ml b/generator/perl.ml
index 0bd36a15..7e78ca75 100644
--- a/generator/perl.ml
+++ b/generator/perl.ml
@@ -211,9 +211,10 @@ MODULE = Sys::Guestfs  PACKAGE = Sys::Guestfs
 PROTOTYPES: ENABLE
 
 guestfs_h *
-_create ()
+_create (flags)
+      unsigned flags;
    CODE:
-      RETVAL = guestfs_create ();
+      RETVAL = guestfs_create_flags (flags);
       if (!RETVAL)
         croak (\"could not create guestfs handle\");
       guestfs_set_error_handler (RETVAL, NULL, NULL);
@@ -713,18 +714,29 @@ XSLoader::load ('Sys::Guestfs');
 
   (* Methods. *)
   pr "\
-=item $g = Sys::Guestfs->new ();
+=item $g = Sys::Guestfs->new ([environment => 0,] [close_on_exit => 0]);
 
 Create a new guestfs handle.
 
+If the optional argument C<environment> is false, then
+the C<GUESTFS_CREATE_NO_ENVIRONMENT> flag is set.
+
+If the optional argument C<close_on_exit> is false, then
+the C<GUESTFS_CREATE_NO_CLOSE_ON_EXIT> flag is set.
+
 =cut
 
 sub new {
   my $proto = shift;
   my $class = ref ($proto) || $proto;
+  my %%flags = @_;
+
+  my $flags = 0;
+  $flags |= 1 if exists $flags{environment} && !$flags{environment};
+  $flags |= 2 if exists $flags{close_on_exit} && !$flags{close_on_exit};
 
-  my $g = Sys::Guestfs::_create ();
-  my $self = { _g => $g };
+  my $g = Sys::Guestfs::_create ($flags);
+  my $self = { _g => $g, _flags => $flags };
   bless $self, $class;
   return $self;
 }
@@ -1013,10 +1025,11 @@ L<guestfs(3)/AVAILABILITY>.
 =head1 STORING DATA IN THE HANDLE
 
 The handle returned from L</new> is a hash reference.  The hash
-normally contains a single element:
+normally contains some elements:
 
  {
-   _g => [private data used by libguestfs]
+   _g => [private data used by libguestfs],
+   _flags => [flags provided when creating the handle]
  }
 
 Callers can add other elements to this hash to store data for their own
diff --git a/generator/python.ml b/generator/python.ml
index b4bc3cee..aa1ce8e9 100644
--- a/generator/python.ml
+++ b/generator/python.ml
@@ -645,9 +645,12 @@ class ClosedHandle(ValueError):
 class GuestFS:
     \"\"\"Instances of this class are libguestfs API handles.\"\"\"
 
-    def __init__ (self):
+    def __init__ (self, environment=True, close_on_exit=True):
         \"\"\"Create a new libguestfs handle.\"\"\"
-        self._o = libguestfsmod.create ()
+        flags = 0
+        if not environment: flags |= 1
+        if not close_on_exit: flags |= 2
+        self._o = libguestfsmod.create (flags)
 
     def __del__ (self):
         if self._o:
diff --git a/generator/ruby.ml b/generator/ruby.ml
index f3b8912d..6cc17fc2 100644
--- a/generator/ruby.ml
+++ b/generator/ruby.ml
@@ -126,7 +126,7 @@ ruby_guestfs_free (void *gvp)
 
 /*
  * call-seq:
- *   Guestfs::Guestfs.new() -> Guestfs::Guestfs
+ *   Guestfs::Guestfs.new([{:environment => false, :close_on_exit => false}]) -> Guestfs::Guestfs
  *
  * Call
  * +guestfs_create+[http://libguestfs.org/guestfs.3.html#guestfs_create]
@@ -134,11 +134,26 @@ ruby_guestfs_free (void *gvp)
  * Ruby as an instance of the Guestfs::Guestfs class.
  */
 static VALUE
-ruby_guestfs_create (VALUE m)
+ruby_guestfs_create (int argc, VALUE *argv, VALUE m)
 {
   guestfs_h *g;
 
-  g = guestfs_create ();
+  if (argc > 1)
+    rb_raise (rb_eArgError, \"expecting 0 or 1 arguments\");
+
+  volatile VALUE optargsv = argc == 1 ? argv[0] : rb_hash_new ();
+  Check_Type (optargsv, T_HASH);
+
+  unsigned flags = 0;
+  volatile VALUE v;
+  v = rb_hash_lookup (optargsv, ID2SYM (rb_intern (\"environment\")));
+  if (v != Qnil && !RTEST (v))
+    flags |= GUESTFS_CREATE_NO_ENVIRONMENT;
+  v = rb_hash_lookup (optargsv, ID2SYM (rb_intern (\"close_on_exit\")));
+  if (v != Qnil && !RTEST (v))
+    flags |= GUESTFS_CREATE_NO_CLOSE_ON_EXIT;
+
+  g = guestfs_create_flags (flags);
   if (!g)
     rb_raise (e_Error, \"failed to create guestfs handle\");
 
@@ -663,7 +678,7 @@ void Init__guestfs ()
   rb_define_alloc_func (c_guestfs, ruby_guestfs_create);
 #endif
 
-  rb_define_module_function (m_guestfs, \"create\", ruby_guestfs_create, 0);
+  rb_define_module_function (m_guestfs, \"create\", ruby_guestfs_create, -1);
   rb_define_method (c_guestfs, \"close\", ruby_guestfs_close, 0);
   rb_define_method (c_guestfs, \"set_event_callback\",
                     ruby_set_event_callback, 2);