generator/generator_types.ml

   1 (* libguestfs
   2  * Copyright (C) 2009-2011 Red Hat Inc.
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17  *)
  18
  19 (* Please read generator/README first. *)
  20
  21 (* Types used to describe the API. *)
  22
  23 type style = ret * args * args
  24     (* The [style] is a tuple which describes the return value and
  25      * arguments of a function.
  26      *
  27      * [ret] is the return value, one of the [R*] values below.
  28      *
  29      * The second element is the list of required arguments, a list of
  30      * [argt]s from the list below, eg. [Bool], [String] etc.  Each has
  31      * a name so that for example [Int "foo"] corresponds in the C
  32      * bindings to an [int foo] parameter.
  33      *
  34      * The third element is the list of optional arguments.  These are
  35      * mapped to optional arguments in the language binding, eg. in
  36      * Perl to:
  37      *   $g->fn (required1, required2, opt1 => val, opt2 => val);
  38      * As the name suggests these are optional, and the function can
  39      * tell which optional parameters were supplied by the caller.
  40      *
  41      * Only [Bool], [Int], [Int64], [String] may currently appear in
  42      * the optional argument list (we may permit more types in future).
  43      *
  44      * ABI and API considerations
  45      * --------------------------
  46      *
  47      * The return type and required arguments may not be changed after
  48      * these have been published in a stable version of libguestfs,
  49      * because doing so would break the ABI.
  50      *
  51      * If a published function has one or more optional arguments,
  52      * then the call can be extended without breaking the ABI or API.
  53      * This is in fact the only way to change an existing function.
  54      * There are limitations on this:
  55      *
  56      * (1) you may _only_ add extra elements at the end of the list
  57      * (2) you may _not_ rearrange or rename or remove existing elements
  58      * (3) you may _not_ add optional arguments to a function which did
  59      *     not have any before (since this breaks the C ABI).
  60      *)
  61
  62 and ret =
  63     (* "RErr" as a return value means an int used as a simple error
  64      * indication, ie. 0 or -1.
  65      *)
  66   | RErr
  67
  68     (* "RInt" as a return value means an int which is -1 for error
  69      * or any value >= 0 on success.  Only use this for smallish
  70      * positive ints (0 <= i < 2^30).
  71      *)
  72   | RInt of string
  73
  74     (* "RInt64" is the same as RInt, but is guaranteed to be able
  75      * to return a full 64 bit value, _except_ that -1 means error
  76      * (so -1 cannot be a valid, non-error return value).
  77      *)
  78   | RInt64 of string
  79
  80     (* "RBool" is a bool return value which can be true/false or
  81      * -1 for error.
  82      *)
  83   | RBool of string
  84
  85     (* "RConstString" is a string that refers to a constant value.
  86      * The return value must NOT be NULL (since NULL indicates
  87      * an error).
  88      *
  89      * Try to avoid using this.  In particular you cannot use this
  90      * for values returned from the daemon, because there is no
  91      * thread-safe way to return them in the C API.
  92      *)
  93   | RConstString of string
  94
  95     (* "RConstOptString" is an even more broken version of
  96      * "RConstString".  The returned string may be NULL and there
  97      * is no way to return an error indication.  Avoid using this!
  98      *)
  99   | RConstOptString of string
 100
 101     (* "RString" is a returned string.  It must NOT be NULL, since
 102      * a NULL return indicates an error.  The caller frees this.
 103      *)
 104   | RString of string
 105
 106     (* "RStringList" is a list of strings.  No string in the list
 107      * can be NULL.  The caller frees the strings and the array.
 108      *)
 109   | RStringList of string
 110
 111     (* "RStruct" is a function which returns a single named structure
 112      * or an error indication (in C, a struct, and in other languages
 113      * with varying representations, but usually very efficient).  See
 114      * after the function list below for the structures.
 115      *)
 116   | RStruct of string * string          (* name of retval, name of struct *)
 117
 118     (* "RStructList" is a function which returns either a list/array
 119      * of structures (could be zero-length), or an error indication.
 120      *)
 121   | RStructList of string * string      (* name of retval, name of struct *)
 122
 123     (* Key-value pairs of untyped strings.  Turns into a hashtable or
 124      * dictionary in languages which support it.  DON'T use this as a
 125      * general "bucket" for results.  Prefer a stronger typed return
 126      * value if one is available, or write a custom struct.  Don't use
 127      * this if the list could potentially be very long, since it is
 128      * inefficient.  Keys should be unique.  NULLs are not permitted.
 129      *)
 130   | RHashtable of string
 131
 132     (* "RBufferOut" is handled almost exactly like RString, but
 133      * it allows the string to contain arbitrary 8 bit data including
 134      * ASCII NUL.  In the C API this causes an implicit extra parameter
 135      * to be added of type <size_t *size_r>.  The extra parameter
 136      * returns the actual size of the return buffer in bytes.
 137      *
 138      * Other programming languages support strings with arbitrary 8 bit
 139      * data.
 140      *
 141      * At the RPC layer we have to use the opaque<> type instead of
 142      * string<>.  Returned data is still limited to the max message
 143      * size (ie. ~ 2 MB).
 144      *)
 145   | RBufferOut of string
 146
 147 and args = argt list    (* Function parameters, guestfs handle is implicit. *)
 148
 149 and argt =
 150   | Bool of string      (* boolean *)
 151   | Int of string       (* int (smallish ints, signed, <= 31 bits) *)
 152   | Int64 of string     (* any 64 bit int *)
 153   | String of string    (* const char *name, cannot be NULL *)
 154   | Device of string    (* /dev device name, cannot be NULL *)
 155   | Pathname of string  (* file name, cannot be NULL *)
 156   | Dev_or_Path of string (* /dev device name or Pathname, cannot be NULL *)
 157   | OptString of string (* const char *name, may be NULL *)
 158   | StringList of string(* list of strings (each string cannot be NULL) *)
 159   | DeviceList of string(* list of Device names (each cannot be NULL) *)
 160     (* Opaque buffer which can contain arbitrary 8 bit data.
 161      * In the C API, this is expressed as <const char *, size_t> pair.
 162      * Most other languages have a string type which can contain
 163      * ASCII NUL.  We use whatever type is appropriate for each
 164      * language.
 165      * Buffers are limited by the total message size.  To transfer
 166      * large blocks of data, use FileIn/FileOut parameters instead.
 167      * To return an arbitrary buffer, use RBufferOut.
 168      *)
 169   | BufferIn of string
 170     (* Key material / passphrase.  Eventually we should treat this
 171      * as sensitive and mlock it into physical RAM.  However this
 172      * is highly complex because of all the places that XDR-encoded
 173      * strings can end up.  So currently the only difference from
 174      * 'String' is the way that guestfish requests these parameters
 175      * from the user.
 176      *)
 177   | Key of string
 178     (* These are treated as filenames (simple string parameters) in
 179      * the C API and bindings.  But in the RPC protocol, we transfer
 180      * the actual file content up to or down from the daemon.
 181      * FileIn: local machine -> daemon (in request)
 182      * FileOut: daemon -> local machine (in reply)
 183      * In guestfish (only), the special name "-" means read from
 184      * stdin or write to stdout.
 185      *)
 186   | FileIn of string
 187   | FileOut of string
 188     (* This specifies an opaque pointer that is passed through
 189      * untouched.  Only non-daemon functions are supported.
 190      *
 191      * Pointer ("foo *", "bar") translates to "foo *bar" in the
 192      * C API.  The pointer ("bar") cannot be NULL.
 193      *
 194      * This is less well supported in other language bindings:
 195      * if the pointer type is known then we may be able to produce
 196      * a suitable binding, otherwise this is translated into a 64
 197      * bit int.
 198      *
 199      * Functions with this parameter type are not supported at all
 200      * in guestfish (the function must be declared "NotInFish" else
 201      * you will get an error).  Also the function cannot contain
 202      * tests, although we should fix this in future.
 203      *)
 204   | Pointer of (string * string)
 205
 206 type errcode = [ `CannotReturnError | `ErrorIsMinusOne | `ErrorIsNULL ]
 207
 208 type flags =
 209   | ProtocolLimitWarning  (* display warning about protocol size limits *)
 210   | FishAlias of string   (* provide an alias for this cmd in guestfish *)
 211   | FishOutput of fish_output_t (* how to display output in guestfish *)
 212   | NotInFish             (* do not export via guestfish *)
 213   | NotInDocs             (* do not add this function to documentation *)
 214   | DeprecatedBy of string (* function is deprecated, use .. instead *)
 215   | Optional of string    (* function is part of an optional group *)
 216   | Progress              (* function can generate progress messages *)
 217
 218 and fish_output_t =
 219   | FishOutputOctal       (* for int return, print in octal *)
 220   | FishOutputHexadecimal (* for int return, print in hex *)
 221
 222 (* See guestfs(3)/EXTENDING LIBGUESTFS. *)
 223 type tests = (test_init * test_prereq * test) list
 224 and test =
 225     (* Run the command sequence and just expect nothing to fail. *)
 226   | TestRun of seq
 227
 228     (* Run the command sequence and expect the output of the final
 229      * command to be the string.
 230      *)
 231   | TestOutput of seq * string
 232
 233     (* Run the command sequence and expect the output of the final
 234      * command to be the list of strings.
 235      *)
 236   | TestOutputList of seq * string list
 237
 238     (* Run the command sequence and expect the output of the final
 239      * command to be the list of block devices (could be either
 240      * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
 241      * character of each string).
 242      *)
 243   | TestOutputListOfDevices of seq * string list
 244
 245     (* Run the command sequence and expect the output of the final
 246      * command to be the integer.
 247      *)
 248   | TestOutputInt of seq * int
 249
 250     (* Run the command sequence and expect the output of the final
 251      * command to be <op> <int>, eg. ">=", "1".
 252      *)
 253   | TestOutputIntOp of seq * string * int
 254
 255     (* Run the command sequence and expect the output of the final
 256      * command to be a true value (!= 0 or != NULL).
 257      *)
 258   | TestOutputTrue of seq
 259
 260     (* Run the command sequence and expect the output of the final
 261      * command to be a false value (== 0 or == NULL, but not an error).
 262      *)
 263   | TestOutputFalse of seq
 264
 265     (* Run the command sequence and expect the output of the final
 266      * command to be a list of the given length (but don't care about
 267      * content).
 268      *)
 269   | TestOutputLength of seq * int
 270
 271     (* Run the command sequence and expect the output of the final
 272      * command to be a buffer (RBufferOut), ie. string + size.
 273      *)
 274   | TestOutputBuffer of seq * string
 275
 276     (* Run the command sequence and expect the output of the final
 277      * command to be a structure.
 278      *)
 279   | TestOutputStruct of seq * test_field_compare list
 280
 281     (* Run the command sequence and expect the output of the final
 282      * command to be a string which is the hex MD5 of the content of
 283      * the named file.
 284      *)
 285   | TestOutputFileMD5 of seq * string
 286
 287     (* Run the command sequence and expect the output of the final
 288      * command to be a string which is a block device name (we don't
 289      * check the 5th character of the string, so "/dev/sda" == "/dev/vda").
 290      *)
 291   | TestOutputDevice of seq * string
 292
 293     (* Run the command sequence and expect a hashtable.  Check
 294      * one of more fields in the hashtable against known good
 295      * strings.
 296      *)
 297   | TestOutputHashtable of seq * (string * string) list
 298
 299   (* Run the command sequence and expect the final command (only)
 300    * to fail.
 301    *)
 302   | TestLastFail of seq
 303
 304 and test_field_compare =
 305   | CompareWithInt of string * int
 306   | CompareWithIntOp of string * string * int
 307   | CompareWithString of string * string
 308   | CompareFieldsIntEq of string * string
 309   | CompareFieldsStrEq of string * string
 310
 311 (* Test prerequisites. *)
 312 and test_prereq =
 313     (* Test always runs. *)
 314   | Always
 315
 316     (* Test is currently disabled - eg. it fails, or it tests some
 317      * unimplemented feature.
 318      *)
 319   | Disabled
 320
 321     (* 'string' is some C code (a function body) that should return
 322      * true or false.  The test will run if the code returns true.
 323      *)
 324   | If of string
 325
 326     (* As for 'If' but the test runs _unless_ the code returns true. *)
 327   | Unless of string
 328
 329     (* Run the test only if 'string' is available in the daemon. *)
 330   | IfAvailable of string
 331
 332 (* Some initial scenarios for testing. *)
 333 and test_init =
 334     (* Do nothing, block devices could contain random stuff including
 335      * LVM PVs, and some filesystems might be mounted.  This is usually
 336      * a bad idea.
 337      *)
 338   | InitNone
 339
 340     (* Block devices are empty and no filesystems are mounted. *)
 341   | InitEmpty
 342
 343     (* /dev/sda contains a single partition /dev/sda1, with random
 344      * content.  No LVM.
 345      *)
 346   | InitPartition
 347
 348     (* /dev/sda contains a single partition /dev/sda1, which is formatted
 349      * as ext2, empty [except for lost+found] and mounted on /.
 350      * No LVM.
 351      *
 352      * Note: for testing filesystem operations, it is quicker to use
 353      * InitScratchFS
 354      *)
 355   | InitBasicFS
 356
 357     (* /dev/sda:
 358      *   /dev/sda1 (is a PV):
 359      *     /dev/VG/LV (size 8MB):
 360      *       formatted as ext2, empty [except for lost+found], mounted on /
 361      *
 362      * Note: only use this if you really need a freshly created filesystem
 363      * on LVM.  Normally you should use InitScratchFS instead.
 364      *)
 365   | InitBasicFSonLVM
 366
 367     (* /dev/sdd (the ISO, see images/ directory in source)
 368      * is mounted on /
 369      *)
 370   | InitISOFS
 371
 372     (* /dev/sdb1 (write scratch disk) is mounted on /.  The filesystem
 373      * will be empty.
 374      *
 375      * Note that this filesystem is not recreated between tests, and
 376      * could contain random files and directories from previous tests.
 377      * Therefore it is recommended that you create uniquely named files
 378      * and directories for your tests.
 379      *)
 380   | InitScratchFS
 381
 382 (* Sequence of commands for testing. *)
 383 and seq = cmd list
 384 and cmd = string list
 385
 386 (* Type of an action as declared in Generator_actions module. *)
 387 type action = string * style * int * flags list * tests * string * string
 388
 389 (* Field types for structures. *)
 390 type field =
 391   | FChar                       (* C 'char' (really, a 7 bit byte). *)
 392   | FString                     (* nul-terminated ASCII string, NOT NULL. *)
 393   | FBuffer                     (* opaque buffer of bytes, (char *, int) pair *)
 394   | FUInt32
 395   | FInt32
 396   | FUInt64
 397   | FInt64
 398   | FBytes                      (* Any int measure that counts bytes. *)
 399   | FUUID                       (* 32 bytes long, NOT nul-terminated. *)
 400   | FOptPercent                 (* [0..100], or -1 meaning "not present". *)
 401
 402 (* Used for testing language bindings. *)
 403 type callt =
 404   | CallString of string
 405   | CallOptString of string option
 406   | CallStringList of string list
 407   | CallInt of int
 408   | CallInt64 of int64
 409   | CallBool of bool
 410   | CallBuffer of string