df: Add --uuid option to print guest UUIDs instead of names (RHBZ#646821).

[libguestfs.git] / generator / generator_types.ml

diff --git a/generator/generator_types.ml b/generator/generator_types.ml
index 0ed6f74..262fb20 100644 (file)
--- a/generator/generator_types.ml
+++ b/generator/generator_types.ml
@@ -20,7 +20,45 @@
 
 (* Types used to describe the API. *)
 
 
 (* Types used to describe the API. *)
 

-type style = ret * args
+type style = ret * args * args
+    (* The [style] is a tuple which describes the return value and
+     * arguments of a function.
+     * 
+     * [ret] is the return value, one of the [R*] values below.
+     * 
+     * The second element is the list of required arguments, a list of
+     * [argt]s from the list below, eg. [Bool], [String] etc.  Each has
+     * a name so that for example [Int "foo"] corresponds in the C
+     * bindings to an [int foo] parameter.
+     * 
+     * The third element is the list of optional arguments.  These are
+     * mapped to optional arguments in the language binding, eg. in
+     * Perl to:
+     *   $g->fn (required1, required2, opt1 => val, opt2 => val);
+     * As the name suggests these are optional, and the function can
+     * tell which optional parameters were supplied by the caller.
+     * 
+     * Only [Bool], [Int], [Int64], [String] may currently appear in
+     * the optional argument list (we may permit more types in future).
+     *
+     * ABI and API considerations
+     * --------------------------
+     * 
+     * The return type and required arguments may not be changed after
+     * these have been published in a stable version of libguestfs,
+     * because doing so would break the ABI.
+     * 
+     * If a published function has one or more optional arguments,
+     * then the call can be extended without breaking the ABI or API.
+     * This is in fact the only way to change an existing function.
+     * There are limitations on this:
+     *
+     * (1) you may _only_ add extra elements at the end of the list
+     * (2) you may _not_ rearrange or rename or remove existing elements
+     * (3) you may _not_ add optional arguments to a function which did
+     *     not have any before (since this breaks the C ABI).
+     *)
+

 and ret =
     (* "RErr" as a return value means an int used as a simple error
      * indication, ie. 0 or -1.
 and ret =
     (* "RErr" as a return value means an int used as a simple error
      * indication, ie. 0 or -1.


@@ -108,14 +146,10 @@ and ret =
 
 and args = argt list   (* Function parameters, guestfs handle is implicit. *)
 
 
 and args = argt list   (* Function parameters, guestfs handle is implicit. *)
 

-    (* Note in future we should allow a "variable args" parameter as
-     * the final parameter, to allow commands like
-     *   chmod mode file [file(s)...]
-     * This is not implemented yet, but many commands (such as chmod)
-     * are currently defined with the argument order keeping this future
-     * possibility in mind.
-     *)

 and argt =
 and argt =

+  | Bool of string     (* boolean *)
+  | Int of string      (* int (smallish ints, signed, <= 31 bits) *)
+  | Int64 of string    (* any 64 bit int *)

   | String of string   (* const char *name, cannot be NULL *)
   | Device of string   (* /dev device name, cannot be NULL *)
   | Pathname of string (* file name, cannot be NULL *)
   | String of string   (* const char *name, cannot be NULL *)
   | Device of string   (* /dev device name, cannot be NULL *)
   | Pathname of string (* file name, cannot be NULL *)


@@ -123,19 +157,6 @@ and argt =
   | OptString of string        (* const char *name, may be NULL *)
   | StringList of string(* list of strings (each string cannot be NULL) *)
   | DeviceList of string(* list of Device names (each cannot be NULL) *)
   | OptString of string        (* const char *name, may be NULL *)
   | StringList of string(* list of strings (each string cannot be NULL) *)
   | DeviceList of string(* list of Device names (each cannot be NULL) *)

-  | Bool of string     (* boolean *)
-  | Int of string      (* int (smallish ints, signed, <= 31 bits) *)
-  | Int64 of string    (* any 64 bit int *)
-    (* These are treated as filenames (simple string parameters) in
-     * the C API and bindings.  But in the RPC protocol, we transfer
-     * the actual file content up to or down from the daemon.
-     * FileIn: local machine -> daemon (in request)
-     * FileOut: daemon -> local machine (in reply)
-     * In guestfish (only), the special name "-" means read from
-     * stdin or write to stdout.
-     *)
-  | FileIn of string
-  | FileOut of string

     (* Opaque buffer which can contain arbitrary 8 bit data.
      * In the C API, this is expressed as <const char *, size_t> pair.
      * Most other languages have a string type which can contain
     (* Opaque buffer which can contain arbitrary 8 bit data.
      * In the C API, this is expressed as <const char *, size_t> pair.
      * Most other languages have a string type which can contain


@@ -154,6 +175,16 @@ and argt =
      * from the user.
      *)
   | Key of string
      * from the user.
      *)
   | Key of string

+    (* These are treated as filenames (simple string parameters) in
+     * the C API and bindings.  But in the RPC protocol, we transfer
+     * the actual file content up to or down from the daemon.
+     * FileIn: local machine -> daemon (in request)
+     * FileOut: daemon -> local machine (in reply)
+     * In guestfish (only), the special name "-" means read from
+     * stdin or write to stdout.
+     *)
+  | FileIn of string
+  | FileOut of string

 
 type flags =
   | ProtocolLimitWarning  (* display warning about protocol size limits *)
 
 type flags =
   | ProtocolLimitWarning  (* display warning about protocol size limits *)