generator/generator_types.ml

   1 (* libguestfs
   2  * Copyright (C) 2009-2010 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
  24 and ret =
  25     (* "RErr" as a return value means an int used as a simple error
  26      * indication, ie. 0 or -1.
  27      *)
  28   | RErr
  29
  30     (* "RInt" as a return value means an int which is -1 for error
  31      * or any value >= 0 on success.  Only use this for smallish
  32      * positive ints (0 <= i < 2^30).
  33      *)
  34   | RInt of string
  35
  36     (* "RInt64" is the same as RInt, but is guaranteed to be able
  37      * to return a full 64 bit value, _except_ that -1 means error
  38      * (so -1 cannot be a valid, non-error return value).
  39      *)
  40   | RInt64 of string
  41
  42     (* "RBool" is a bool return value which can be true/false or
  43      * -1 for error.
  44      *)
  45   | RBool of string
  46
  47     (* "RConstString" is a string that refers to a constant value.
  48      * The return value must NOT be NULL (since NULL indicates
  49      * an error).
  50      *
  51      * Try to avoid using this.  In particular you cannot use this
  52      * for values returned from the daemon, because there is no
  53      * thread-safe way to return them in the C API.
  54      *)
  55   | RConstString of string
  56
  57     (* "RConstOptString" is an even more broken version of
  58      * "RConstString".  The returned string may be NULL and there
  59      * is no way to return an error indication.  Avoid using this!
  60      *)
  61   | RConstOptString of string
  62
  63     (* "RString" is a returned string.  It must NOT be NULL, since
  64      * a NULL return indicates an error.  The caller frees this.
  65      *)
  66   | RString of string
  67
  68     (* "RStringList" is a list of strings.  No string in the list
  69      * can be NULL.  The caller frees the strings and the array.
  70      *)
  71   | RStringList of string
  72
  73     (* "RStruct" is a function which returns a single named structure
  74      * or an error indication (in C, a struct, and in other languages
  75      * with varying representations, but usually very efficient).  See
  76      * after the function list below for the structures.
  77      *)
  78   | RStruct of string * string          (* name of retval, name of struct *)
  79
  80     (* "RStructList" is a function which returns either a list/array
  81      * of structures (could be zero-length), or an error indication.
  82      *)
  83   | RStructList of string * string      (* name of retval, name of struct *)
  84
  85     (* Key-value pairs of untyped strings.  Turns into a hashtable or
  86      * dictionary in languages which support it.  DON'T use this as a
  87      * general "bucket" for results.  Prefer a stronger typed return
  88      * value if one is available, or write a custom struct.  Don't use
  89      * this if the list could potentially be very long, since it is
  90      * inefficient.  Keys should be unique.  NULLs are not permitted.
  91      *)
  92   | RHashtable of string
  93
  94     (* "RBufferOut" is handled almost exactly like RString, but
  95      * it allows the string to contain arbitrary 8 bit data including
  96      * ASCII NUL.  In the C API this causes an implicit extra parameter
  97      * to be added of type <size_t *size_r>.  The extra parameter
  98      * returns the actual size of the return buffer in bytes.
  99      *
 100      * Other programming languages support strings with arbitrary 8 bit
 101      * data.
 102      *
 103      * At the RPC layer we have to use the opaque<> type instead of
 104      * string<>.  Returned data is still limited to the max message
 105      * size (ie. ~ 2 MB).
 106      *)
 107   | RBufferOut of string
 108
 109 and args = argt list    (* Function parameters, guestfs handle is implicit. *)
 110
 111     (* Note in future we should allow a "variable args" parameter as
 112      * the final parameter, to allow commands like
 113      *   chmod mode file [file(s)...]
 114      * This is not implemented yet, but many commands (such as chmod)
 115      * are currently defined with the argument order keeping this future
 116      * possibility in mind.
 117      *)
 118 and argt =
 119   | String of string    (* const char *name, cannot be NULL *)
 120   | Device of string    (* /dev device name, cannot be NULL *)
 121   | Pathname of string  (* file name, cannot be NULL *)
 122   | Dev_or_Path of string (* /dev device name or Pathname, cannot be NULL *)
 123   | OptString of string (* const char *name, may be NULL *)
 124   | StringList of string(* list of strings (each string cannot be NULL) *)
 125   | DeviceList of string(* list of Device names (each cannot be NULL) *)
 126   | Bool of string      (* boolean *)
 127   | Int of string       (* int (smallish ints, signed, <= 31 bits) *)
 128   | Int64 of string     (* any 64 bit int *)
 129     (* These are treated as filenames (simple string parameters) in
 130      * the C API and bindings.  But in the RPC protocol, we transfer
 131      * the actual file content up to or down from the daemon.
 132      * FileIn: local machine -> daemon (in request)
 133      * FileOut: daemon -> local machine (in reply)
 134      * In guestfish (only), the special name "-" means read from
 135      * stdin or write to stdout.
 136      *)
 137   | FileIn of string
 138   | FileOut of string
 139     (* Opaque buffer which can contain arbitrary 8 bit data.
 140      * In the C API, this is expressed as <const char *, size_t> pair.
 141      * Most other languages have a string type which can contain
 142      * ASCII NUL.  We use whatever type is appropriate for each
 143      * language.
 144      * Buffers are limited by the total message size.  To transfer
 145      * large blocks of data, use FileIn/FileOut parameters instead.
 146      * To return an arbitrary buffer, use RBufferOut.
 147      *)
 148   | BufferIn of string
 149     (* Key material / passphrase.  Eventually we should treat this
 150      * as sensitive and mlock it into physical RAM.  However this
 151      * is highly complex because of all the places that XDR-encoded
 152      * strings can end up.  So currently the only difference from
 153      * 'String' is the way that guestfish requests these parameters
 154      * from the user.
 155      *)
 156   | Key of string
 157
 158 type flags =
 159   | ProtocolLimitWarning  (* display warning about protocol size limits *)
 160   | DangerWillRobinson    (* flags particularly dangerous commands *)
 161   | FishAlias of string   (* provide an alias for this cmd in guestfish *)
 162   | FishOutput of fish_output_t (* how to display output in guestfish *)
 163   | NotInFish             (* do not export via guestfish *)
 164   | NotInDocs             (* do not add this function to documentation *)
 165   | DeprecatedBy of string (* function is deprecated, use .. instead *)
 166   | Optional of string    (* function is part of an optional group *)
 167   | Progress              (* function can generate progress messages *)
 168
 169 and fish_output_t =
 170   | FishOutputOctal       (* for int return, print in octal *)
 171   | FishOutputHexadecimal (* for int return, print in hex *)
 172
 173 (* You can supply zero or as many tests as you want per API call.
 174  *
 175  * Note that the test environment has 3 block devices, of size 500MB,
 176  * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and
 177  * a fourth ISO block device with some known files on it (/dev/sdd).
 178  *
 179  * Note for partitioning purposes, the 500MB device has 1015 cylinders.
 180  * Number of cylinders was 63 for IDE emulated disks with precisely
 181  * the same size.  How exactly this is calculated is a mystery.
 182  *
 183  * The ISO block device (/dev/sdd) comes from images/test.iso.
 184  *
 185  * To be able to run the tests in a reasonable amount of time,
 186  * the virtual machine and block devices are reused between tests.
 187  * So don't try testing kill_subprocess :-x
 188  *
 189  * Between each test we blockdev-setrw, umount-all, lvm-remove-all.
 190  *
 191  * Don't assume anything about the previous contents of the block
 192  * devices.  Use 'Init*' to create some initial scenarios.
 193  *
 194  * You can add a prerequisite clause to any individual test.  This
 195  * is a run-time check, which, if it fails, causes the test to be
 196  * skipped.  Useful if testing a command which might not work on
 197  * all variations of libguestfs builds.  A test that has prerequisite
 198  * of 'Always' is run unconditionally.
 199  *
 200  * In addition, packagers can skip individual tests by setting the
 201  * environment variables:     eg:
 202  *   SKIP_TEST_<CMD>_<NUM>=1  SKIP_TEST_COMMAND_3=1  (skips test #3 of command)
 203  *   SKIP_TEST_<CMD>=1        SKIP_TEST_ZEROFREE=1   (skips all zerofree tests)
 204  *)
 205 type tests = (test_init * test_prereq * test) list
 206 and test =
 207     (* Run the command sequence and just expect nothing to fail. *)
 208   | TestRun of seq
 209
 210     (* Run the command sequence and expect the output of the final
 211      * command to be the string.
 212      *)
 213   | TestOutput of seq * string
 214
 215     (* Run the command sequence and expect the output of the final
 216      * command to be the list of strings.
 217      *)
 218   | TestOutputList of seq * string list
 219
 220     (* Run the command sequence and expect the output of the final
 221      * command to be the list of block devices (could be either
 222      * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
 223      * character of each string).
 224      *)
 225   | TestOutputListOfDevices of seq * string list
 226
 227     (* Run the command sequence and expect the output of the final
 228      * command to be the integer.
 229      *)
 230   | TestOutputInt of seq * int
 231
 232     (* Run the command sequence and expect the output of the final
 233      * command to be <op> <int>, eg. ">=", "1".
 234      *)
 235   | TestOutputIntOp of seq * string * int
 236
 237     (* Run the command sequence and expect the output of the final
 238      * command to be a true value (!= 0 or != NULL).
 239      *)
 240   | TestOutputTrue of seq
 241
 242     (* Run the command sequence and expect the output of the final
 243      * command to be a false value (== 0 or == NULL, but not an error).
 244      *)
 245   | TestOutputFalse of seq
 246
 247     (* Run the command sequence and expect the output of the final
 248      * command to be a list of the given length (but don't care about
 249      * content).
 250      *)
 251   | TestOutputLength of seq * int
 252
 253     (* Run the command sequence and expect the output of the final
 254      * command to be a buffer (RBufferOut), ie. string + size.
 255      *)
 256   | TestOutputBuffer of seq * string
 257
 258     (* Run the command sequence and expect the output of the final
 259      * command to be a structure.
 260      *)
 261   | TestOutputStruct of seq * test_field_compare list
 262
 263     (* Run the command sequence and expect the output of the final
 264      * command to be a string which is the hex MD5 of the content of
 265      * the named file.
 266      *)
 267   | TestOutputFileMD5 of seq * string
 268
 269     (* Run the command sequence and expect the output of the final
 270      * command to be a string which is a block device name (we don't
 271      * check the 5th character of the string, so "/dev/sda" == "/dev/vda").
 272      *)
 273   | TestOutputDevice of seq * string
 274
 275   (* Run the command sequence and expect the final command (only)
 276    * to fail.
 277    *)
 278   | TestLastFail of seq
 279
 280 and test_field_compare =
 281   | CompareWithInt of string * int
 282   | CompareWithIntOp of string * string * int
 283   | CompareWithString of string * string
 284   | CompareFieldsIntEq of string * string
 285   | CompareFieldsStrEq of string * string
 286
 287 (* Test prerequisites. *)
 288 and test_prereq =
 289     (* Test always runs. *)
 290   | Always
 291
 292     (* Test is currently disabled - eg. it fails, or it tests some
 293      * unimplemented feature.
 294      *)
 295   | Disabled
 296
 297     (* 'string' is some C code (a function body) that should return
 298      * true or false.  The test will run if the code returns true.
 299      *)
 300   | If of string
 301
 302     (* As for 'If' but the test runs _unless_ the code returns true. *)
 303   | Unless of string
 304
 305     (* Run the test only if 'string' is available in the daemon. *)
 306   | IfAvailable of string
 307
 308 (* Some initial scenarios for testing. *)
 309 and test_init =
 310     (* Do nothing, block devices could contain random stuff including
 311      * LVM PVs, and some filesystems might be mounted.  This is usually
 312      * a bad idea.
 313      *)
 314   | InitNone
 315
 316     (* Block devices are empty and no filesystems are mounted. *)
 317   | InitEmpty
 318
 319     (* /dev/sda contains a single partition /dev/sda1, with random
 320      * content.  /dev/sdb and /dev/sdc may have random content.
 321      * No LVM.
 322      *)
 323   | InitPartition
 324
 325     (* /dev/sda contains a single partition /dev/sda1, which is formatted
 326      * as ext2, empty [except for lost+found] and mounted on /.
 327      * /dev/sdb and /dev/sdc may have random content.
 328      * No LVM.
 329      *)
 330   | InitBasicFS
 331
 332     (* /dev/sda:
 333      *   /dev/sda1 (is a PV):
 334      *     /dev/VG/LV (size 8MB):
 335      *       formatted as ext2, empty [except for lost+found], mounted on /
 336      * /dev/sdb and /dev/sdc may have random content.
 337      *)
 338   | InitBasicFSonLVM
 339
 340     (* /dev/sdd (the ISO, see images/ directory in source)
 341      * is mounted on /
 342      *)
 343   | InitISOFS
 344
 345 (* Sequence of commands for testing. *)
 346 and seq = cmd list
 347 and cmd = string list
 348
 349 (* Type of an action as declared in Generator_actions module. *)
 350 type action = string * style * int * flags list * tests * string * string
 351
 352 (* Field types for structures. *)
 353 type field =
 354   | FChar                       (* C 'char' (really, a 7 bit byte). *)
 355   | FString                     (* nul-terminated ASCII string, NOT NULL. *)
 356   | FBuffer                     (* opaque buffer of bytes, (char *, int) pair *)
 357   | FUInt32
 358   | FInt32
 359   | FUInt64
 360   | FInt64
 361   | FBytes                      (* Any int measure that counts bytes. *)
 362   | FUUID                       (* 32 bytes long, NOT nul-terminated. *)
 363   | FOptPercent                 (* [0..100], or -1 meaning "not present". *)
 364
 365 (* Used for testing language bindings. *)
 366 type callt =
 367   | CallString of string
 368   | CallOptString of string option
 369   | CallStringList of string list
 370   | CallInt of int
 371   | CallInt64 of int64
 372   | CallBool of bool
 373   | CallBuffer of string