src/generator.ml

   1 #!/usr/bin/env ocaml
   2 (* libguestfs
   3  * Copyright (C) 2009 Red Hat Inc.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  18  *)
  19
  20 (* This script generates a large amount of code and documentation for
  21  * all the daemon actions.
  22  *
  23  * To add a new action there are only two files you need to change,
  24  * this one to describe the interface (see the big table below), and
  25  * daemon/<somefile>.c to write the implementation.
  26  *
  27  * After editing this file, run it (./src/generator.ml) to regenerate
  28  * all the output files.
  29  *
  30  * IMPORTANT: This script should NOT print any warnings.  If it prints
  31  * warnings, you should treat them as errors.
  32  * [Need to add -warn-error to ocaml command line]
  33  *)
  34
  35 #load "unix.cma";;
  36 #load "str.cma";;
  37
  38 open Printf
  39
  40 type style = ret * args
  41 and ret =
  42     (* "RErr" as a return value means an int used as a simple error
  43      * indication, ie. 0 or -1.
  44      *)
  45   | RErr
  46     (* "RInt" as a return value means an int which is -1 for error
  47      * or any value >= 0 on success.  Only use this for smallish
  48      * positive ints (0 <= i < 2^30).
  49      *)
  50   | RInt of string
  51     (* "RInt64" is the same as RInt, but is guaranteed to be able
  52      * to return a full 64 bit value, _except_ that -1 means error
  53      * (so -1 cannot be a valid, non-error return value).
  54      *)
  55   | RInt64 of string
  56     (* "RBool" is a bool return value which can be true/false or
  57      * -1 for error.
  58      *)
  59   | RBool of string
  60     (* "RConstString" is a string that refers to a constant value.
  61      * Try to avoid using this.  In particular you cannot use this
  62      * for values returned from the daemon, because there is no
  63      * thread-safe way to return them in the C API.
  64      *)
  65   | RConstString of string
  66     (* "RString" and "RStringList" are caller-frees. *)
  67   | RString of string
  68   | RStringList of string
  69     (* "RStruct" is a function which returns a single named structure
  70      * or an error indication (in C, a struct, and in other languages
  71      * with varying representations, but usually very efficient).  See
  72      * after the function list below for the structures.
  73      *)
  74   | RStruct of string * string          (* name of retval, name of struct *)
  75     (* "RStructList" is a function which returns either a list/array
  76      * of structures (could be zero-length), or an error indication.
  77      *)
  78   | RStructList of string * string      (* name of retval, name of struct *)
  79     (* Key-value pairs of untyped strings.  Turns into a hashtable or
  80      * dictionary in languages which support it.  DON'T use this as a
  81      * general "bucket" for results.  Prefer a stronger typed return
  82      * value if one is available, or write a custom struct.  Don't use
  83      * this if the list could potentially be very long, since it is
  84      * inefficient.  Keys should be unique.  NULLs are not permitted.
  85      *)
  86   | RHashtable of string
  87 (* Not implemented:
  88     (* "RBufferOut" is handled almost exactly like RString, but
  89      * it allows the string to contain arbitrary 8 bit data including
  90      * ASCII NUL.  In the C API this causes an implicit extra parameter
  91      * to be added of type <size_t *size_r>.  Other programming languages
  92      * support strings with arbitrary 8 bit data.  At the RPC layer
  93      * we have to use the opaque<> type instead of string<>.
  94      *)
  95   | RBufferOut of string
  96 *)
  97
  98 and args = argt list    (* Function parameters, guestfs handle is implicit. *)
  99
 100     (* Note in future we should allow a "variable args" parameter as
 101      * the final parameter, to allow commands like
 102      *   chmod mode file [file(s)...]
 103      * This is not implemented yet, but many commands (such as chmod)
 104      * are currently defined with the argument order keeping this future
 105      * possibility in mind.
 106      *)
 107 and argt =
 108   | String of string    (* const char *name, cannot be NULL *)
 109   | OptString of string (* const char *name, may be NULL *)
 110   | StringList of string(* list of strings (each string cannot be NULL) *)
 111   | Bool of string      (* boolean *)
 112   | Int of string       (* int (smallish ints, signed, <= 31 bits) *)
 113     (* These are treated as filenames (simple string parameters) in
 114      * the C API and bindings.  But in the RPC protocol, we transfer
 115      * the actual file content up to or down from the daemon.
 116      * FileIn: local machine -> daemon (in request)
 117      * FileOut: daemon -> local machine (in reply)
 118      * In guestfish (only), the special name "-" means read from
 119      * stdin or write to stdout.
 120      *)
 121   | FileIn of string
 122   | FileOut of string
 123 (* Not implemented:
 124     (* Opaque buffer which can contain arbitrary 8 bit data.
 125      * In the C API, this is expressed as <char *, int> pair.
 126      * Most other languages have a string type which can contain
 127      * ASCII NUL.  We use whatever type is appropriate for each
 128      * language.
 129      * Buffers are limited by the total message size.  To transfer
 130      * large blocks of data, use FileIn/FileOut parameters instead.
 131      * To return an arbitrary buffer, use RBufferOut.
 132      *)
 133   | BufferIn of string
 134 *)
 135
 136 type flags =
 137   | ProtocolLimitWarning  (* display warning about protocol size limits *)
 138   | DangerWillRobinson    (* flags particularly dangerous commands *)
 139   | FishAlias of string   (* provide an alias for this cmd in guestfish *)
 140   | FishAction of string  (* call this function in guestfish *)
 141   | NotInFish             (* do not export via guestfish *)
 142   | NotInDocs             (* do not add this function to documentation *)
 143
 144 let protocol_limit_warning =
 145   "Because of the message protocol, there is a transfer limit
 146 of somewhere between 2MB and 4MB.  To transfer large files you should use
 147 FTP."
 148
 149 let danger_will_robinson =
 150   "B<This command is dangerous.  Without careful use you
 151 can easily destroy all your data>."
 152
 153 (* You can supply zero or as many tests as you want per API call.
 154  *
 155  * Note that the test environment has 3 block devices, of size 500MB,
 156  * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and
 157  * a fourth squashfs block device with some known files on it (/dev/sdd).
 158  *
 159  * Note for partitioning purposes, the 500MB device has 1015 cylinders.
 160  * Number of cylinders was 63 for IDE emulated disks with precisely
 161  * the same size.  How exactly this is calculated is a mystery.
 162  *
 163  * The squashfs block device (/dev/sdd) comes from images/test.sqsh.
 164  *
 165  * To be able to run the tests in a reasonable amount of time,
 166  * the virtual machine and block devices are reused between tests.
 167  * So don't try testing kill_subprocess :-x
 168  *
 169  * Between each test we blockdev-setrw, umount-all, lvm-remove-all.
 170  *
 171  * Don't assume anything about the previous contents of the block
 172  * devices.  Use 'Init*' to create some initial scenarios.
 173  *
 174  * You can add a prerequisite clause to any individual test.  This
 175  * is a run-time check, which, if it fails, causes the test to be
 176  * skipped.  Useful if testing a command which might not work on
 177  * all variations of libguestfs builds.  A test that has prerequisite
 178  * of 'Always' is run unconditionally.
 179  *
 180  * In addition, packagers can skip individual tests by setting the
 181  * environment variables:     eg:
 182  *   SKIP_TEST_<CMD>_<NUM>=1  SKIP_TEST_COMMAND_3=1  (skips test #3 of command)
 183  *   SKIP_TEST_<CMD>=1        SKIP_TEST_ZEROFREE=1   (skips all zerofree tests)
 184  *)
 185 type tests = (test_init * test_prereq * test) list
 186 and test =
 187     (* Run the command sequence and just expect nothing to fail. *)
 188   | TestRun of seq
 189     (* Run the command sequence and expect the output of the final
 190      * command to be the string.
 191      *)
 192   | TestOutput of seq * string
 193     (* Run the command sequence and expect the output of the final
 194      * command to be the list of strings.
 195      *)
 196   | TestOutputList of seq * string list
 197     (* Run the command sequence and expect the output of the final
 198      * command to be the list of block devices (could be either
 199      * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
 200      * character of each string).
 201      *)
 202   | TestOutputListOfDevices of seq * string list
 203     (* Run the command sequence and expect the output of the final
 204      * command to be the integer.
 205      *)
 206   | TestOutputInt of seq * int
 207     (* Run the command sequence and expect the output of the final
 208      * command to be a true value (!= 0 or != NULL).
 209      *)
 210   | TestOutputTrue of seq
 211     (* Run the command sequence and expect the output of the final
 212      * command to be a false value (== 0 or == NULL, but not an error).
 213      *)
 214   | TestOutputFalse of seq
 215     (* Run the command sequence and expect the output of the final
 216      * command to be a list of the given length (but don't care about
 217      * content).
 218      *)
 219   | TestOutputLength of seq * int
 220     (* Run the command sequence and expect the output of the final
 221      * command to be a structure.
 222      *)
 223   | TestOutputStruct of seq * test_field_compare list
 224     (* Run the command sequence and expect the final command (only)
 225      * to fail.
 226      *)
 227   | TestLastFail of seq
 228
 229 and test_field_compare =
 230   | CompareWithInt of string * int
 231   | CompareWithString of string * string
 232   | CompareFieldsIntEq of string * string
 233   | CompareFieldsStrEq of string * string
 234
 235 (* Test prerequisites. *)
 236 and test_prereq =
 237     (* Test always runs. *)
 238   | Always
 239     (* Test is currently disabled - eg. it fails, or it tests some
 240      * unimplemented feature.
 241      *)
 242   | Disabled
 243     (* 'string' is some C code (a function body) that should return
 244      * true or false.  The test will run if the code returns true.
 245      *)
 246   | If of string
 247     (* As for 'If' but the test runs _unless_ the code returns true. *)
 248   | Unless of string
 249
 250 (* Some initial scenarios for testing. *)
 251 and test_init =
 252     (* Do nothing, block devices could contain random stuff including
 253      * LVM PVs, and some filesystems might be mounted.  This is usually
 254      * a bad idea.
 255      *)
 256   | InitNone
 257     (* Block devices are empty and no filesystems are mounted. *)
 258   | InitEmpty
 259     (* /dev/sda contains a single partition /dev/sda1, which is formatted
 260      * as ext2, empty [except for lost+found] and mounted on /.
 261      * /dev/sdb and /dev/sdc may have random content.
 262      * No LVM.
 263      *)
 264   | InitBasicFS
 265     (* /dev/sda:
 266      *   /dev/sda1 (is a PV):
 267      *     /dev/VG/LV (size 8MB):
 268      *       formatted as ext2, empty [except for lost+found], mounted on /
 269      * /dev/sdb and /dev/sdc may have random content.
 270      *)
 271   | InitBasicFSonLVM
 272
 273 (* Sequence of commands for testing. *)
 274 and seq = cmd list
 275 and cmd = string list
 276
 277 (* Note about long descriptions: When referring to another
 278  * action, use the format C<guestfs_other> (ie. the full name of
 279  * the C function).  This will be replaced as appropriate in other
 280  * language bindings.
 281  *
 282  * Apart from that, long descriptions are just perldoc paragraphs.
 283  *)
 284
 285 (* These test functions are used in the language binding tests. *)
 286
 287 let test_all_args = [
 288   String "str";
 289   OptString "optstr";
 290   StringList "strlist";
 291   Bool "b";
 292   Int "integer";
 293   FileIn "filein";
 294   FileOut "fileout";
 295 ]
 296
 297 let test_all_rets = [
 298   (* except for RErr, which is tested thoroughly elsewhere *)
 299   "test0rint",         RInt "valout";
 300   "test0rint64",       RInt64 "valout";
 301   "test0rbool",        RBool "valout";
 302   "test0rconststring", RConstString "valout";
 303   "test0rstring",      RString "valout";
 304   "test0rstringlist",  RStringList "valout";
 305   "test0rstruct",      RStruct ("valout", "lvm_pv");
 306   "test0rstructlist",  RStructList ("valout", "lvm_pv");
 307   "test0rhashtable",   RHashtable "valout";
 308 ]
 309
 310 let test_functions = [
 311   ("test0", (RErr, test_all_args), -1, [NotInFish; NotInDocs],
 312    [],
 313    "internal test function - do not use",
 314    "\
 315 This is an internal test function which is used to test whether
 316 the automatically generated bindings can handle every possible
 317 parameter type correctly.
 318
 319 It echos the contents of each parameter to stdout.
 320
 321 You probably don't want to call this function.");
 322 ] @ List.flatten (
 323   List.map (
 324     fun (name, ret) ->
 325       [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs],
 326         [],
 327         "internal test function - do not use",
 328         "\
 329 This is an internal test function which is used to test whether
 330 the automatically generated bindings can handle every possible
 331 return type correctly.
 332
 333 It converts string C<val> to the return type.
 334
 335 You probably don't want to call this function.");
 336        (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs],
 337         [],
 338         "internal test function - do not use",
 339         "\
 340 This is an internal test function which is used to test whether
 341 the automatically generated bindings can handle every possible
 342 return type correctly.
 343
 344 This function always returns an error.
 345
 346 You probably don't want to call this function.")]
 347   ) test_all_rets
 348 )
 349
 350 (* non_daemon_functions are any functions which don't get processed
 351  * in the daemon, eg. functions for setting and getting local
 352  * configuration values.
 353  *)
 354
 355 let non_daemon_functions = test_functions @ [
 356   ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"],
 357    [],
 358    "launch the qemu subprocess",
 359    "\
 360 Internally libguestfs is implemented by running a virtual machine
 361 using L<qemu(1)>.
 362
 363 You should call this after configuring the handle
 364 (eg. adding drives) but before performing any actions.");
 365
 366   ("wait_ready", (RErr, []), -1, [NotInFish],
 367    [],
 368    "wait until the qemu subprocess launches",
 369    "\
 370 Internally libguestfs is implemented by running a virtual machine
 371 using L<qemu(1)>.
 372
 373 You should call this after C<guestfs_launch> to wait for the launch
 374 to complete.");
 375
 376   ("kill_subprocess", (RErr, []), -1, [],
 377    [],
 378    "kill the qemu subprocess",
 379    "\
 380 This kills the qemu subprocess.  You should never need to call this.");
 381
 382   ("add_drive", (RErr, [String "filename"]), -1, [FishAlias "add"],
 383    [],
 384    "add an image to examine or modify",
 385    "\
 386 This function adds a virtual machine disk image C<filename> to the
 387 guest.  The first time you call this function, the disk appears as IDE
 388 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
 389 so on.
 390
 391 You don't necessarily need to be root when using libguestfs.  However
 392 you obviously do need sufficient permissions to access the filename
 393 for whatever operations you want to perform (ie. read access if you
 394 just want to read the image or write access if you want to modify the
 395 image).
 396
 397 This is equivalent to the qemu parameter
 398 C<-drive file=filename,cache=off,if=...>.
 399
 400 Note that this call checks for the existence of C<filename>.  This
 401 stops you from specifying other types of drive which are supported
 402 by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
 403 the general C<guestfs_config> call instead.");
 404
 405   ("add_cdrom", (RErr, [String "filename"]), -1, [FishAlias "cdrom"],
 406    [],
 407    "add a CD-ROM disk image to examine",
 408    "\
 409 This function adds a virtual CD-ROM disk image to the guest.
 410
 411 This is equivalent to the qemu parameter C<-cdrom filename>.
 412
 413 Note that this call checks for the existence of C<filename>.  This
 414 stops you from specifying other types of drive which are supported
 415 by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
 416 the general C<guestfs_config> call instead.");
 417
 418   ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"],
 419    [],
 420    "add a drive in snapshot mode (read-only)",
 421    "\
 422 This adds a drive in snapshot mode, making it effectively
 423 read-only.
 424
 425 Note that writes to the device are allowed, and will be seen for
 426 the duration of the guestfs handle, but they are written
 427 to a temporary file which is discarded as soon as the guestfs
 428 handle is closed.  We don't currently have any method to enable
 429 changes to be committed, although qemu can support this.
 430
 431 This is equivalent to the qemu parameter
 432 C<-drive file=filename,snapshot=on,if=...>.
 433
 434 Note that this call checks for the existence of C<filename>.  This
 435 stops you from specifying other types of drive which are supported
 436 by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
 437 the general C<guestfs_config> call instead.");
 438
 439   ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"]), -1, [],
 440    [],
 441    "add qemu parameters",
 442    "\
 443 This can be used to add arbitrary qemu command line parameters
 444 of the form C<-param value>.  Actually it's not quite arbitrary - we
 445 prevent you from setting some parameters which would interfere with
 446 parameters that we use.
 447
 448 The first character of C<param> string must be a C<-> (dash).
 449
 450 C<value> can be NULL.");
 451
 452   ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"],
 453    [],
 454    "set the qemu binary",
 455    "\
 456 Set the qemu binary that we will use.
 457
 458 The default is chosen when the library was compiled by the
 459 configure script.
 460
 461 You can also override this by setting the C<LIBGUESTFS_QEMU>
 462 environment variable.
 463
 464 Setting C<qemu> to C<NULL> restores the default qemu binary.");
 465
 466   ("get_qemu", (RConstString "qemu", []), -1, [],
 467    [],
 468    "get the qemu binary",
 469    "\
 470 Return the current qemu binary.
 471
 472 This is always non-NULL.  If it wasn't set already, then this will
 473 return the default qemu binary name.");
 474
 475   ("set_path", (RErr, [String "path"]), -1, [FishAlias "path"],
 476    [],
 477    "set the search path",
 478    "\
 479 Set the path that libguestfs searches for kernel and initrd.img.
 480
 481 The default is C<$libdir/guestfs> unless overridden by setting
 482 C<LIBGUESTFS_PATH> environment variable.
 483
 484 Setting C<path> to C<NULL> restores the default path.");
 485
 486   ("get_path", (RConstString "path", []), -1, [],
 487    [],
 488    "get the search path",
 489    "\
 490 Return the current search path.
 491
 492 This is always non-NULL.  If it wasn't set already, then this will
 493 return the default path.");
 494
 495   ("set_append", (RErr, [String "append"]), -1, [FishAlias "append"],
 496    [],
 497    "add options to kernel command line",
 498    "\
 499 This function is used to add additional options to the
 500 guest kernel command line.
 501
 502 The default is C<NULL> unless overridden by setting
 503 C<LIBGUESTFS_APPEND> environment variable.
 504
 505 Setting C<append> to C<NULL> means I<no> additional options
 506 are passed (libguestfs always adds a few of its own).");
 507
 508   ("get_append", (RConstString "append", []), -1, [],
 509    [],
 510    "get the additional kernel options",
 511    "\
 512 Return the additional kernel options which are added to the
 513 guest kernel command line.
 514
 515 If C<NULL> then no options are added.");
 516
 517   ("set_autosync", (RErr, [Bool "autosync"]), -1, [FishAlias "autosync"],
 518    [],
 519    "set autosync mode",
 520    "\
 521 If C<autosync> is true, this enables autosync.  Libguestfs will make a
 522 best effort attempt to run C<guestfs_umount_all> followed by
 523 C<guestfs_sync> when the handle is closed
 524 (also if the program exits without closing handles).
 525
 526 This is disabled by default (except in guestfish where it is
 527 enabled by default).");
 528
 529   ("get_autosync", (RBool "autosync", []), -1, [],
 530    [],
 531    "get autosync mode",
 532    "\
 533 Get the autosync flag.");
 534
 535   ("set_verbose", (RErr, [Bool "verbose"]), -1, [FishAlias "verbose"],
 536    [],
 537    "set verbose mode",
 538    "\
 539 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
 540
 541 Verbose messages are disabled unless the environment variable
 542 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
 543
 544   ("get_verbose", (RBool "verbose", []), -1, [],
 545    [],
 546    "get verbose mode",
 547    "\
 548 This returns the verbose messages flag.");
 549
 550   ("is_ready", (RBool "ready", []), -1, [],
 551    [],
 552    "is ready to accept commands",
 553    "\
 554 This returns true iff this handle is ready to accept commands
 555 (in the C<READY> state).
 556
 557 For more information on states, see L<guestfs(3)>.");
 558
 559   ("is_config", (RBool "config", []), -1, [],
 560    [],
 561    "is in configuration state",
 562    "\
 563 This returns true iff this handle is being configured
 564 (in the C<CONFIG> state).
 565
 566 For more information on states, see L<guestfs(3)>.");
 567
 568   ("is_launching", (RBool "launching", []), -1, [],
 569    [],
 570    "is launching subprocess",
 571    "\
 572 This returns true iff this handle is launching the subprocess
 573 (in the C<LAUNCHING> state).
 574
 575 For more information on states, see L<guestfs(3)>.");
 576
 577   ("is_busy", (RBool "busy", []), -1, [],
 578    [],
 579    "is busy processing a command",
 580    "\
 581 This returns true iff this handle is busy processing a command
 582 (in the C<BUSY> state).
 583
 584 For more information on states, see L<guestfs(3)>.");
 585
 586   ("get_state", (RInt "state", []), -1, [],
 587    [],
 588    "get the current state",
 589    "\
 590 This returns the current state as an opaque integer.  This is
 591 only useful for printing debug and internal error messages.
 592
 593 For more information on states, see L<guestfs(3)>.");
 594
 595   ("set_busy", (RErr, []), -1, [NotInFish],
 596    [],
 597    "set state to busy",
 598    "\
 599 This sets the state to C<BUSY>.  This is only used when implementing
 600 actions using the low-level API.
 601
 602 For more information on states, see L<guestfs(3)>.");
 603
 604   ("set_ready", (RErr, []), -1, [NotInFish],
 605    [],
 606    "set state to ready",
 607    "\
 608 This sets the state to C<READY>.  This is only used when implementing
 609 actions using the low-level API.
 610
 611 For more information on states, see L<guestfs(3)>.");
 612
 613   ("end_busy", (RErr, []), -1, [NotInFish],
 614    [],
 615    "leave the busy state",
 616    "\
 617 This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
 618 state as is.  This is only used when implementing
 619 actions using the low-level API.
 620
 621 For more information on states, see L<guestfs(3)>.");
 622
 623   ("set_memsize", (RErr, [Int "memsize"]), -1, [FishAlias "memsize"],
 624    [],
 625    "set memory allocated to the qemu subprocess",
 626    "\
 627 This sets the memory size in megabytes allocated to the
 628 qemu subprocess.  This only has any effect if called before
 629 C<guestfs_launch>.
 630
 631 You can also change this by setting the environment
 632 variable C<LIBGUESTFS_MEMSIZE> before the handle is
 633 created.
 634
 635 For more information on the architecture of libguestfs,
 636 see L<guestfs(3)>.");
 637
 638   ("get_memsize", (RInt "memsize", []), -1, [],
 639    [],
 640    "get memory allocated to the qemu subprocess",
 641    "\
 642 This gets the memory size in megabytes allocated to the
 643 qemu subprocess.
 644
 645 If C<guestfs_set_memsize> was not called
 646 on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
 647 then this returns the compiled-in default value for memsize.
 648
 649 For more information on the architecture of libguestfs,
 650 see L<guestfs(3)>.");
 651
 652   ("get_pid", (RInt "pid", []), -1, [FishAlias "pid"],
 653    [],
 654    "get PID of qemu subprocess",
 655    "\
 656 Return the process ID of the qemu subprocess.  If there is no
 657 qemu subprocess, then this will return an error.
 658
 659 This is an internal call used for debugging and testing.");
 660
 661   ("version", (RStruct ("version", "version"), []), -1, [],
 662    [InitNone, Always, TestOutputStruct (
 663       [["version"]], [CompareWithInt ("major", 1)])],
 664    "get the library version number",
 665    "\
 666 Return the libguestfs version number that the program is linked
 667 against.
 668
 669 Note that because of dynamic linking this is not necessarily
 670 the version of libguestfs that you compiled against.  You can
 671 compile the program, and then at runtime dynamically link
 672 against a completely different C<libguestfs.so> library.
 673
 674 This call was added in version C<1.0.58>.  In previous
 675 versions of libguestfs there was no way to get the version
 676 number.  From C code you can use ELF weak linking tricks to find out if
 677 this symbol exists (if it doesn't, then it's an earlier version).
 678
 679 The call returns a structure with four elements.  The first
 680 three (C<major>, C<minor> and C<release>) are numbers and
 681 correspond to the usual version triplet.  The fourth element
 682 (C<extra>) is a string and is normally empty, but may be
 683 used for distro-specific information.
 684
 685 To construct the original version string:
 686 C<$major.$minor.$release$extra>
 687
 688 I<Note:> Don't use this call to test for availability
 689 of features.  Distro backports makes this unreliable.");
 690
 691 ]
 692
 693 (* daemon_functions are any functions which cause some action
 694  * to take place in the daemon.
 695  *)
 696
 697 let daemon_functions = [
 698   ("mount", (RErr, [String "device"; String "mountpoint"]), 1, [],
 699    [InitEmpty, Always, TestOutput (
 700       [["sfdiskM"; "/dev/sda"; ","];
 701        ["mkfs"; "ext2"; "/dev/sda1"];
 702        ["mount"; "/dev/sda1"; "/"];
 703        ["write_file"; "/new"; "new file contents"; "0"];
 704        ["cat"; "/new"]], "new file contents")],
 705    "mount a guest disk at a position in the filesystem",
 706    "\
 707 Mount a guest disk at a position in the filesystem.  Block devices
 708 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
 709 the guest.  If those block devices contain partitions, they will have
 710 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
 711 names can be used.
 712
 713 The rules are the same as for L<mount(2)>:  A filesystem must
 714 first be mounted on C</> before others can be mounted.  Other
 715 filesystems can only be mounted on directories which already
 716 exist.
 717
 718 The mounted filesystem is writable, if we have sufficient permissions
 719 on the underlying device.
 720
 721 The filesystem options C<sync> and C<noatime> are set with this
 722 call, in order to improve reliability.");
 723
 724   ("sync", (RErr, []), 2, [],
 725    [ InitEmpty, Always, TestRun [["sync"]]],
 726    "sync disks, writes are flushed through to the disk image",
 727    "\
 728 This syncs the disk, so that any writes are flushed through to the
 729 underlying disk image.
 730
 731 You should always call this if you have modified a disk image, before
 732 closing the handle.");
 733
 734   ("touch", (RErr, [String "path"]), 3, [],
 735    [InitBasicFS, Always, TestOutputTrue (
 736       [["touch"; "/new"];
 737        ["exists"; "/new"]])],
 738    "update file timestamps or create a new file",
 739    "\
 740 Touch acts like the L<touch(1)> command.  It can be used to
 741 update the timestamps on a file, or, if the file does not exist,
 742 to create a new zero-length file.");
 743
 744   ("cat", (RString "content", [String "path"]), 4, [ProtocolLimitWarning],
 745    [InitBasicFS, Always, TestOutput (
 746       [["write_file"; "/new"; "new file contents"; "0"];
 747        ["cat"; "/new"]], "new file contents")],
 748    "list the contents of a file",
 749    "\
 750 Return the contents of the file named C<path>.
 751
 752 Note that this function cannot correctly handle binary files
 753 (specifically, files containing C<\\0> character which is treated
 754 as end of string).  For those you need to use the C<guestfs_download>
 755 function which has a more complex interface.");
 756
 757   ("ll", (RString "listing", [String "directory"]), 5, [],
 758    [], (* XXX Tricky to test because it depends on the exact format
 759         * of the 'ls -l' command, which changes between F10 and F11.
 760         *)
 761    "list the files in a directory (long format)",
 762    "\
 763 List the files in C<directory> (relative to the root directory,
 764 there is no cwd) in the format of 'ls -la'.
 765
 766 This command is mostly useful for interactive sessions.  It
 767 is I<not> intended that you try to parse the output string.");
 768
 769   ("ls", (RStringList "listing", [String "directory"]), 6, [],
 770    [InitBasicFS, Always, TestOutputList (
 771       [["touch"; "/new"];
 772        ["touch"; "/newer"];
 773        ["touch"; "/newest"];
 774        ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])],
 775    "list the files in a directory",
 776    "\
 777 List the files in C<directory> (relative to the root directory,
 778 there is no cwd).  The '.' and '..' entries are not returned, but
 779 hidden files are shown.
 780
 781 This command is mostly useful for interactive sessions.  Programs
 782 should probably use C<guestfs_readdir> instead.");
 783
 784   ("list_devices", (RStringList "devices", []), 7, [],
 785    [InitEmpty, Always, TestOutputListOfDevices (
 786       [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
 787    "list the block devices",
 788    "\
 789 List all the block devices.
 790
 791 The full block device names are returned, eg. C</dev/sda>");
 792
 793   ("list_partitions", (RStringList "partitions", []), 8, [],
 794    [InitBasicFS, Always, TestOutputListOfDevices (
 795       [["list_partitions"]], ["/dev/sda1"]);
 796     InitEmpty, Always, TestOutputListOfDevices (
 797       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
 798        ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
 799    "list the partitions",
 800    "\
 801 List all the partitions detected on all block devices.
 802
 803 The full partition device names are returned, eg. C</dev/sda1>
 804
 805 This does not return logical volumes.  For that you will need to
 806 call C<guestfs_lvs>.");
 807
 808   ("pvs", (RStringList "physvols", []), 9, [],
 809    [InitBasicFSonLVM, Always, TestOutputListOfDevices (
 810       [["pvs"]], ["/dev/sda1"]);
 811     InitEmpty, Always, TestOutputListOfDevices (
 812       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
 813        ["pvcreate"; "/dev/sda1"];
 814        ["pvcreate"; "/dev/sda2"];
 815        ["pvcreate"; "/dev/sda3"];
 816        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
 817    "list the LVM physical volumes (PVs)",
 818    "\
 819 List all the physical volumes detected.  This is the equivalent
 820 of the L<pvs(8)> command.
 821
 822 This returns a list of just the device names that contain
 823 PVs (eg. C</dev/sda2>).
 824
 825 See also C<guestfs_pvs_full>.");
 826
 827   ("vgs", (RStringList "volgroups", []), 10, [],
 828    [InitBasicFSonLVM, Always, TestOutputList (
 829       [["vgs"]], ["VG"]);
 830     InitEmpty, Always, TestOutputList (
 831       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
 832        ["pvcreate"; "/dev/sda1"];
 833        ["pvcreate"; "/dev/sda2"];
 834        ["pvcreate"; "/dev/sda3"];
 835        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
 836        ["vgcreate"; "VG2"; "/dev/sda3"];
 837        ["vgs"]], ["VG1"; "VG2"])],
 838    "list the LVM volume groups (VGs)",
 839    "\
 840 List all the volumes groups detected.  This is the equivalent
 841 of the L<vgs(8)> command.
 842
 843 This returns a list of just the volume group names that were
 844 detected (eg. C<VolGroup00>).
 845
 846 See also C<guestfs_vgs_full>.");
 847
 848   ("lvs", (RStringList "logvols", []), 11, [],
 849    [InitBasicFSonLVM, Always, TestOutputList (
 850       [["lvs"]], ["/dev/VG/LV"]);
 851     InitEmpty, Always, TestOutputList (
 852       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
 853        ["pvcreate"; "/dev/sda1"];
 854        ["pvcreate"; "/dev/sda2"];
 855        ["pvcreate"; "/dev/sda3"];
 856        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
 857        ["vgcreate"; "VG2"; "/dev/sda3"];
 858        ["lvcreate"; "LV1"; "VG1"; "50"];
 859        ["lvcreate"; "LV2"; "VG1"; "50"];
 860        ["lvcreate"; "LV3"; "VG2"; "50"];
 861        ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
 862    "list the LVM logical volumes (LVs)",
 863    "\
 864 List all the logical volumes detected.  This is the equivalent
 865 of the L<lvs(8)> command.
 866
 867 This returns a list of the logical volume device names
 868 (eg. C</dev/VolGroup00/LogVol00>).
 869
 870 See also C<guestfs_lvs_full>.");
 871
 872   ("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 12, [],
 873    [], (* XXX how to test? *)
 874    "list the LVM physical volumes (PVs)",
 875    "\
 876 List all the physical volumes detected.  This is the equivalent
 877 of the L<pvs(8)> command.  The \"full\" version includes all fields.");
 878
 879   ("vgs_full", (RStructList ("volgroups", "lvm_vg"), []), 13, [],
 880    [], (* XXX how to test? *)
 881    "list the LVM volume groups (VGs)",
 882    "\
 883 List all the volumes groups detected.  This is the equivalent
 884 of the L<vgs(8)> command.  The \"full\" version includes all fields.");
 885
 886   ("lvs_full", (RStructList ("logvols", "lvm_lv"), []), 14, [],
 887    [], (* XXX how to test? *)
 888    "list the LVM logical volumes (LVs)",
 889    "\
 890 List all the logical volumes detected.  This is the equivalent
 891 of the L<lvs(8)> command.  The \"full\" version includes all fields.");
 892
 893   ("read_lines", (RStringList "lines", [String "path"]), 15, [],
 894    [InitBasicFS, Always, TestOutputList (
 895       [["write_file"; "/new"; "line1\r\nline2\nline3"; "0"];
 896        ["read_lines"; "/new"]], ["line1"; "line2"; "line3"]);
 897     InitBasicFS, Always, TestOutputList (
 898       [["write_file"; "/new"; ""; "0"];
 899        ["read_lines"; "/new"]], [])],
 900    "read file as lines",
 901    "\
 902 Return the contents of the file named C<path>.
 903
 904 The file contents are returned as a list of lines.  Trailing
 905 C<LF> and C<CRLF> character sequences are I<not> returned.
 906
 907 Note that this function cannot correctly handle binary files
 908 (specifically, files containing C<\\0> character which is treated
 909 as end of line).  For those you need to use the C<guestfs_read_file>
 910 function which has a more complex interface.");
 911
 912   ("aug_init", (RErr, [String "root"; Int "flags"]), 16, [],
 913    [], (* XXX Augeas code needs tests. *)
 914    "create a new Augeas handle",
 915    "\
 916 Create a new Augeas handle for editing configuration files.
 917 If there was any previous Augeas handle associated with this
 918 guestfs session, then it is closed.
 919
 920 You must call this before using any other C<guestfs_aug_*>
 921 commands.
 922
 923 C<root> is the filesystem root.  C<root> must not be NULL,
 924 use C</> instead.
 925
 926 The flags are the same as the flags defined in
 927 E<lt>augeas.hE<gt>, the logical I<or> of the following
 928 integers:
 929
 930 =over 4
 931
 932 =item C<AUG_SAVE_BACKUP> = 1
 933
 934 Keep the original file with a C<.augsave> extension.
 935
 936 =item C<AUG_SAVE_NEWFILE> = 2
 937
 938 Save changes into a file with extension C<.augnew>, and
 939 do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
 940
 941 =item C<AUG_TYPE_CHECK> = 4
 942
 943 Typecheck lenses (can be expensive).
 944
 945 =item C<AUG_NO_STDINC> = 8
 946
 947 Do not use standard load path for modules.
 948
 949 =item C<AUG_SAVE_NOOP> = 16
 950
 951 Make save a no-op, just record what would have been changed.
 952
 953 =item C<AUG_NO_LOAD> = 32
 954
 955 Do not load the tree in C<guestfs_aug_init>.
 956
 957 =back
 958
 959 To close the handle, you can call C<guestfs_aug_close>.
 960
 961 To find out more about Augeas, see L<http://augeas.net/>.");
 962
 963   ("aug_close", (RErr, []), 26, [],
 964    [], (* XXX Augeas code needs tests. *)
 965    "close the current Augeas handle",
 966    "\
 967 Close the current Augeas handle and free up any resources
 968 used by it.  After calling this, you have to call
 969 C<guestfs_aug_init> again before you can use any other
 970 Augeas functions.");
 971
 972   ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [],
 973    [], (* XXX Augeas code needs tests. *)
 974    "define an Augeas variable",
 975    "\
 976 Defines an Augeas variable C<name> whose value is the result
 977 of evaluating C<expr>.  If C<expr> is NULL, then C<name> is
 978 undefined.
 979
 980 On success this returns the number of nodes in C<expr>, or
 981 C<0> if C<expr> evaluates to something which is not a nodeset.");
 982
 983   ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"]), 18, [],
 984    [], (* XXX Augeas code needs tests. *)
 985    "define an Augeas node",
 986    "\
 987 Defines a variable C<name> whose value is the result of
 988 evaluating C<expr>.
 989
 990 If C<expr> evaluates to an empty nodeset, a node is created,
 991 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
 992 C<name> will be the nodeset containing that single node.
 993
 994 On success this returns a pair containing the
 995 number of nodes in the nodeset, and a boolean flag
 996 if a node was created.");
 997
 998   ("aug_get", (RString "val", [String "path"]), 19, [],
 999    [], (* XXX Augeas code needs tests. *)
1000    "look up the value of an Augeas path",
1001    "\
1002 Look up the value associated with C<path>.  If C<path>
1003 matches exactly one node, the C<value> is returned.");
1004
1005   ("aug_set", (RErr, [String "path"; String "val"]), 20, [],
1006    [], (* XXX Augeas code needs tests. *)
1007    "set Augeas path to value",
1008    "\
1009 Set the value associated with C<path> to C<value>.");
1010
1011   ("aug_insert", (RErr, [String "path"; String "label"; Bool "before"]), 21, [],
1012    [], (* XXX Augeas code needs tests. *)
1013    "insert a sibling Augeas node",
1014    "\
1015 Create a new sibling C<label> for C<path>, inserting it into
1016 the tree before or after C<path> (depending on the boolean
1017 flag C<before>).
1018
1019 C<path> must match exactly one existing node in the tree, and
1020 C<label> must be a label, ie. not contain C</>, C<*> or end
1021 with a bracketed index C<[N]>.");
1022
1023   ("aug_rm", (RInt "nrnodes", [String "path"]), 22, [],
1024    [], (* XXX Augeas code needs tests. *)
1025    "remove an Augeas path",
1026    "\
1027 Remove C<path> and all of its children.
1028
1029 On success this returns the number of entries which were removed.");
1030
1031   ("aug_mv", (RErr, [String "src"; String "dest"]), 23, [],
1032    [], (* XXX Augeas code needs tests. *)
1033    "move Augeas node",
1034    "\
1035 Move the node C<src> to C<dest>.  C<src> must match exactly
1036 one node.  C<dest> is overwritten if it exists.");
1037
1038   ("aug_match", (RStringList "matches", [String "path"]), 24, [],
1039    [], (* XXX Augeas code needs tests. *)
1040    "return Augeas nodes which match path",
1041    "\
1042 Returns a list of paths which match the path expression C<path>.
1043 The returned paths are sufficiently qualified so that they match
1044 exactly one node in the current tree.");
1045
1046   ("aug_save", (RErr, []), 25, [],
1047    [], (* XXX Augeas code needs tests. *)
1048    "write all pending Augeas changes to disk",
1049    "\
1050 This writes all pending changes to disk.
1051
1052 The flags which were passed to C<guestfs_aug_init> affect exactly
1053 how files are saved.");
1054
1055   ("aug_load", (RErr, []), 27, [],
1056    [], (* XXX Augeas code needs tests. *)
1057    "load files into the tree",
1058    "\
1059 Load files into the tree.
1060
1061 See C<aug_load> in the Augeas documentation for the full gory
1062 details.");
1063
1064   ("aug_ls", (RStringList "matches", [String "path"]), 28, [],
1065    [], (* XXX Augeas code needs tests. *)
1066    "list Augeas nodes under a path",
1067    "\
1068 This is just a shortcut for listing C<guestfs_aug_match>
1069 C<path/*> and sorting the resulting nodes into alphabetical order.");
1070
1071   ("rm", (RErr, [String "path"]), 29, [],
1072    [InitBasicFS, Always, TestRun
1073       [["touch"; "/new"];
1074        ["rm"; "/new"]];
1075     InitBasicFS, Always, TestLastFail
1076       [["rm"; "/new"]];
1077     InitBasicFS, Always, TestLastFail
1078       [["mkdir"; "/new"];
1079        ["rm"; "/new"]]],
1080    "remove a file",
1081    "\
1082 Remove the single file C<path>.");
1083
1084   ("rmdir", (RErr, [String "path"]), 30, [],
1085    [InitBasicFS, Always, TestRun
1086       [["mkdir"; "/new"];
1087        ["rmdir"; "/new"]];
1088     InitBasicFS, Always, TestLastFail
1089       [["rmdir"; "/new"]];
1090     InitBasicFS, Always, TestLastFail
1091       [["touch"; "/new"];
1092        ["rmdir"; "/new"]]],
1093    "remove a directory",
1094    "\
1095 Remove the single directory C<path>.");
1096
1097   ("rm_rf", (RErr, [String "path"]), 31, [],
1098    [InitBasicFS, Always, TestOutputFalse
1099       [["mkdir"; "/new"];
1100        ["mkdir"; "/new/foo"];
1101        ["touch"; "/new/foo/bar"];
1102        ["rm_rf"; "/new"];
1103        ["exists"; "/new"]]],
1104    "remove a file or directory recursively",
1105    "\
1106 Remove the file or directory C<path>, recursively removing the
1107 contents if its a directory.  This is like the C<rm -rf> shell
1108 command.");
1109
1110   ("mkdir", (RErr, [String "path"]), 32, [],
1111    [InitBasicFS, Always, TestOutputTrue
1112       [["mkdir"; "/new"];
1113        ["is_dir"; "/new"]];
1114     InitBasicFS, Always, TestLastFail
1115       [["mkdir"; "/new/foo/bar"]]],
1116    "create a directory",
1117    "\
1118 Create a directory named C<path>.");
1119
1120   ("mkdir_p", (RErr, [String "path"]), 33, [],
1121    [InitBasicFS, Always, TestOutputTrue
1122       [["mkdir_p"; "/new/foo/bar"];
1123        ["is_dir"; "/new/foo/bar"]];
1124     InitBasicFS, Always, TestOutputTrue
1125       [["mkdir_p"; "/new/foo/bar"];
1126        ["is_dir"; "/new/foo"]];
1127     InitBasicFS, Always, TestOutputTrue
1128       [["mkdir_p"; "/new/foo/bar"];
1129        ["is_dir"; "/new"]];
1130     (* Regression tests for RHBZ#503133: *)
1131     InitBasicFS, Always, TestRun
1132       [["mkdir"; "/new"];
1133        ["mkdir_p"; "/new"]];
1134     InitBasicFS, Always, TestLastFail
1135       [["touch"; "/new"];
1136        ["mkdir_p"; "/new"]]],
1137    "create a directory and parents",
1138    "\
1139 Create a directory named C<path>, creating any parent directories
1140 as necessary.  This is like the C<mkdir -p> shell command.");
1141
1142   ("chmod", (RErr, [Int "mode"; String "path"]), 34, [],
1143    [], (* XXX Need stat command to test *)
1144    "change file mode",
1145    "\
1146 Change the mode (permissions) of C<path> to C<mode>.  Only
1147 numeric modes are supported.");
1148
1149   ("chown", (RErr, [Int "owner"; Int "group"; String "path"]), 35, [],
1150    [], (* XXX Need stat command to test *)
1151    "change file owner and group",
1152    "\
1153 Change the file owner to C<owner> and group to C<group>.
1154
1155 Only numeric uid and gid are supported.  If you want to use
1156 names, you will need to locate and parse the password file
1157 yourself (Augeas support makes this relatively easy).");
1158
1159   ("exists", (RBool "existsflag", [String "path"]), 36, [],
1160    [InitBasicFS, Always, TestOutputTrue (
1161       [["touch"; "/new"];
1162        ["exists"; "/new"]]);
1163     InitBasicFS, Always, TestOutputTrue (
1164       [["mkdir"; "/new"];
1165        ["exists"; "/new"]])],
1166    "test if file or directory exists",
1167    "\
1168 This returns C<true> if and only if there is a file, directory
1169 (or anything) with the given C<path> name.
1170
1171 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
1172
1173   ("is_file", (RBool "fileflag", [String "path"]), 37, [],
1174    [InitBasicFS, Always, TestOutputTrue (
1175       [["touch"; "/new"];
1176        ["is_file"; "/new"]]);
1177     InitBasicFS, Always, TestOutputFalse (
1178       [["mkdir"; "/new"];
1179        ["is_file"; "/new"]])],
1180    "test if file exists",
1181    "\
1182 This returns C<true> if and only if there is a file
1183 with the given C<path> name.  Note that it returns false for
1184 other objects like directories.
1185
1186 See also C<guestfs_stat>.");
1187
1188   ("is_dir", (RBool "dirflag", [String "path"]), 38, [],
1189    [InitBasicFS, Always, TestOutputFalse (
1190       [["touch"; "/new"];
1191        ["is_dir"; "/new"]]);
1192     InitBasicFS, Always, TestOutputTrue (
1193       [["mkdir"; "/new"];
1194        ["is_dir"; "/new"]])],
1195    "test if file exists",
1196    "\
1197 This returns C<true> if and only if there is a directory
1198 with the given C<path> name.  Note that it returns false for
1199 other objects like files.
1200
1201 See also C<guestfs_stat>.");
1202
1203   ("pvcreate", (RErr, [String "device"]), 39, [],
1204    [InitEmpty, Always, TestOutputListOfDevices (
1205       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1206        ["pvcreate"; "/dev/sda1"];
1207        ["pvcreate"; "/dev/sda2"];
1208        ["pvcreate"; "/dev/sda3"];
1209        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1210    "create an LVM physical volume",
1211    "\
1212 This creates an LVM physical volume on the named C<device>,
1213 where C<device> should usually be a partition name such
1214 as C</dev/sda1>.");
1215
1216   ("vgcreate", (RErr, [String "volgroup"; StringList "physvols"]), 40, [],
1217    [InitEmpty, Always, TestOutputList (
1218       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1219        ["pvcreate"; "/dev/sda1"];
1220        ["pvcreate"; "/dev/sda2"];
1221        ["pvcreate"; "/dev/sda3"];
1222        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1223        ["vgcreate"; "VG2"; "/dev/sda3"];
1224        ["vgs"]], ["VG1"; "VG2"])],
1225    "create an LVM volume group",
1226    "\
1227 This creates an LVM volume group called C<volgroup>
1228 from the non-empty list of physical volumes C<physvols>.");
1229
1230   ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"]), 41, [],
1231    [InitEmpty, Always, TestOutputList (
1232       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1233        ["pvcreate"; "/dev/sda1"];
1234        ["pvcreate"; "/dev/sda2"];
1235        ["pvcreate"; "/dev/sda3"];
1236        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1237        ["vgcreate"; "VG2"; "/dev/sda3"];
1238        ["lvcreate"; "LV1"; "VG1"; "50"];
1239        ["lvcreate"; "LV2"; "VG1"; "50"];
1240        ["lvcreate"; "LV3"; "VG2"; "50"];
1241        ["lvcreate"; "LV4"; "VG2"; "50"];
1242        ["lvcreate"; "LV5"; "VG2"; "50"];
1243        ["lvs"]],
1244       ["/dev/VG1/LV1"; "/dev/VG1/LV2";
1245        "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
1246    "create an LVM volume group",
1247    "\
1248 This creates an LVM volume group called C<logvol>
1249 on the volume group C<volgroup>, with C<size> megabytes.");
1250
1251   ("mkfs", (RErr, [String "fstype"; String "device"]), 42, [],
1252    [InitEmpty, Always, TestOutput (
1253       [["sfdiskM"; "/dev/sda"; ","];
1254        ["mkfs"; "ext2"; "/dev/sda1"];
1255        ["mount"; "/dev/sda1"; "/"];
1256        ["write_file"; "/new"; "new file contents"; "0"];
1257        ["cat"; "/new"]], "new file contents")],
1258    "make a filesystem",
1259    "\
1260 This creates a filesystem on C<device> (usually a partition
1261 or LVM logical volume).  The filesystem type is C<fstype>, for
1262 example C<ext3>.");
1263
1264   ("sfdisk", (RErr, [String "device";
1265                      Int "cyls"; Int "heads"; Int "sectors";
1266                      StringList "lines"]), 43, [DangerWillRobinson],
1267    [],
1268    "create partitions on a block device",
1269    "\
1270 This is a direct interface to the L<sfdisk(8)> program for creating
1271 partitions on block devices.
1272
1273 C<device> should be a block device, for example C</dev/sda>.
1274
1275 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1276 and sectors on the device, which are passed directly to sfdisk as
1277 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
1278 of these, then the corresponding parameter is omitted.  Usually for
1279 'large' disks, you can just pass C<0> for these, but for small
1280 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1281 out the right geometry and you will need to tell it.
1282
1283 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
1284 information refer to the L<sfdisk(8)> manpage.
1285
1286 To create a single partition occupying the whole disk, you would
1287 pass C<lines> as a single element list, when the single element being
1288 the string C<,> (comma).
1289
1290 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>");
1291
1292   ("write_file", (RErr, [String "path"; String "content"; Int "size"]), 44, [ProtocolLimitWarning],
1293    [InitBasicFS, Always, TestOutput (
1294       [["write_file"; "/new"; "new file contents"; "0"];
1295        ["cat"; "/new"]], "new file contents");
1296     InitBasicFS, Always, TestOutput (
1297       [["write_file"; "/new"; "\nnew file contents\n"; "0"];
1298        ["cat"; "/new"]], "\nnew file contents\n");
1299     InitBasicFS, Always, TestOutput (
1300       [["write_file"; "/new"; "\n\n"; "0"];
1301        ["cat"; "/new"]], "\n\n");
1302     InitBasicFS, Always, TestOutput (
1303       [["write_file"; "/new"; ""; "0"];
1304        ["cat"; "/new"]], "");
1305     InitBasicFS, Always, TestOutput (
1306       [["write_file"; "/new"; "\n\n\n"; "0"];
1307        ["cat"; "/new"]], "\n\n\n");
1308     InitBasicFS, Always, TestOutput (
1309       [["write_file"; "/new"; "\n"; "0"];
1310        ["cat"; "/new"]], "\n")],
1311    "create a file",
1312    "\
1313 This call creates a file called C<path>.  The contents of the
1314 file is the string C<content> (which can contain any 8 bit data),
1315 with length C<size>.
1316
1317 As a special case, if C<size> is C<0>
1318 then the length is calculated using C<strlen> (so in this case
1319 the content cannot contain embedded ASCII NULs).
1320
1321 I<NB.> Owing to a bug, writing content containing ASCII NUL
1322 characters does I<not> work, even if the length is specified.
1323 We hope to resolve this bug in a future version.  In the meantime
1324 use C<guestfs_upload>.");
1325
1326   ("umount", (RErr, [String "pathordevice"]), 45, [FishAlias "unmount"],
1327    [InitEmpty, Always, TestOutputListOfDevices (
1328       [["sfdiskM"; "/dev/sda"; ","];
1329        ["mkfs"; "ext2"; "/dev/sda1"];
1330        ["mount"; "/dev/sda1"; "/"];
1331        ["mounts"]], ["/dev/sda1"]);
1332     InitEmpty, Always, TestOutputList (
1333       [["sfdiskM"; "/dev/sda"; ","];
1334        ["mkfs"; "ext2"; "/dev/sda1"];
1335        ["mount"; "/dev/sda1"; "/"];
1336        ["umount"; "/"];
1337        ["mounts"]], [])],
1338    "unmount a filesystem",
1339    "\
1340 This unmounts the given filesystem.  The filesystem may be
1341 specified either by its mountpoint (path) or the device which
1342 contains the filesystem.");
1343
1344   ("mounts", (RStringList "devices", []), 46, [],
1345    [InitBasicFS, Always, TestOutputListOfDevices (
1346       [["mounts"]], ["/dev/sda1"])],
1347    "show mounted filesystems",
1348    "\
1349 This returns the list of currently mounted filesystems.  It returns
1350 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1351
1352 Some internal mounts are not shown.");
1353
1354   ("umount_all", (RErr, []), 47, [FishAlias "unmount-all"],
1355    [InitBasicFS, Always, TestOutputList (
1356       [["umount_all"];
1357        ["mounts"]], []);
1358     (* check that umount_all can unmount nested mounts correctly: *)
1359     InitEmpty, Always, TestOutputList (
1360       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1361        ["mkfs"; "ext2"; "/dev/sda1"];
1362        ["mkfs"; "ext2"; "/dev/sda2"];
1363        ["mkfs"; "ext2"; "/dev/sda3"];
1364        ["mount"; "/dev/sda1"; "/"];
1365        ["mkdir"; "/mp1"];
1366        ["mount"; "/dev/sda2"; "/mp1"];
1367        ["mkdir"; "/mp1/mp2"];
1368        ["mount"; "/dev/sda3"; "/mp1/mp2"];
1369        ["mkdir"; "/mp1/mp2/mp3"];
1370        ["umount_all"];
1371        ["mounts"]], [])],
1372    "unmount all filesystems",
1373    "\
1374 This unmounts all mounted filesystems.
1375
1376 Some internal mounts are not unmounted by this call.");
1377
1378   ("lvm_remove_all", (RErr, []), 48, [DangerWillRobinson],
1379    [],
1380    "remove all LVM LVs, VGs and PVs",
1381    "\
1382 This command removes all LVM logical volumes, volume groups
1383 and physical volumes.");
1384
1385   ("file", (RString "description", [String "path"]), 49, [],
1386    [InitBasicFS, Always, TestOutput (
1387       [["touch"; "/new"];
1388        ["file"; "/new"]], "empty");
1389     InitBasicFS, Always, TestOutput (
1390       [["write_file"; "/new"; "some content\n"; "0"];
1391        ["file"; "/new"]], "ASCII text");
1392     InitBasicFS, Always, TestLastFail (
1393       [["file"; "/nofile"]])],
1394    "determine file type",
1395    "\
1396 This call uses the standard L<file(1)> command to determine
1397 the type or contents of the file.  This also works on devices,
1398 for example to find out whether a partition contains a filesystem.
1399
1400 The exact command which runs is C<file -bsL path>.  Note in
1401 particular that the filename is not prepended to the output
1402 (the C<-b> option).");
1403
1404   ("command", (RString "output", [StringList "arguments"]), 50, [ProtocolLimitWarning],
1405    [InitBasicFS, Always, TestOutput (
1406       [["upload"; "test-command"; "/test-command"];
1407        ["chmod"; "0o755"; "/test-command"];
1408        ["command"; "/test-command 1"]], "Result1");
1409     InitBasicFS, Always, TestOutput (
1410       [["upload"; "test-command"; "/test-command"];
1411        ["chmod"; "0o755"; "/test-command"];
1412        ["command"; "/test-command 2"]], "Result2\n");
1413     InitBasicFS, Always, TestOutput (
1414       [["upload"; "test-command"; "/test-command"];
1415        ["chmod"; "0o755"; "/test-command"];
1416        ["command"; "/test-command 3"]], "\nResult3");
1417     InitBasicFS, Always, TestOutput (
1418       [["upload"; "test-command"; "/test-command"];
1419        ["chmod"; "0o755"; "/test-command"];
1420        ["command"; "/test-command 4"]], "\nResult4\n");
1421     InitBasicFS, Always, TestOutput (
1422       [["upload"; "test-command"; "/test-command"];
1423        ["chmod"; "0o755"; "/test-command"];
1424        ["command"; "/test-command 5"]], "\nResult5\n\n");
1425     InitBasicFS, Always, TestOutput (
1426       [["upload"; "test-command"; "/test-command"];
1427        ["chmod"; "0o755"; "/test-command"];
1428        ["command"; "/test-command 6"]], "\n\nResult6\n\n");
1429     InitBasicFS, Always, TestOutput (
1430       [["upload"; "test-command"; "/test-command"];
1431        ["chmod"; "0o755"; "/test-command"];
1432        ["command"; "/test-command 7"]], "");
1433     InitBasicFS, Always, TestOutput (
1434       [["upload"; "test-command"; "/test-command"];
1435        ["chmod"; "0o755"; "/test-command"];
1436        ["command"; "/test-command 8"]], "\n");
1437     InitBasicFS, Always, TestOutput (
1438       [["upload"; "test-command"; "/test-command"];
1439        ["chmod"; "0o755"; "/test-command"];
1440        ["command"; "/test-command 9"]], "\n\n");
1441     InitBasicFS, Always, TestOutput (
1442       [["upload"; "test-command"; "/test-command"];
1443        ["chmod"; "0o755"; "/test-command"];
1444        ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n");
1445     InitBasicFS, Always, TestOutput (
1446       [["upload"; "test-command"; "/test-command"];
1447        ["chmod"; "0o755"; "/test-command"];
1448        ["command"; "/test-command 11"]], "Result11-1\nResult11-2");
1449     InitBasicFS, Always, TestLastFail (
1450       [["upload"; "test-command"; "/test-command"];
1451        ["chmod"; "0o755"; "/test-command"];
1452        ["command"; "/test-command"]])],
1453    "run a command from the guest filesystem",
1454    "\
1455 This call runs a command from the guest filesystem.  The
1456 filesystem must be mounted, and must contain a compatible
1457 operating system (ie. something Linux, with the same
1458 or compatible processor architecture).
1459
1460 The single parameter is an argv-style list of arguments.
1461 The first element is the name of the program to run.
1462 Subsequent elements are parameters.  The list must be
1463 non-empty (ie. must contain a program name).  Note that
1464 the command runs directly, and is I<not> invoked via
1465 the shell (see C<guestfs_sh>).
1466
1467 The return value is anything printed to I<stdout> by
1468 the command.
1469
1470 If the command returns a non-zero exit status, then
1471 this function returns an error message.  The error message
1472 string is the content of I<stderr> from the command.
1473
1474 The C<$PATH> environment variable will contain at least
1475 C</usr/bin> and C</bin>.  If you require a program from
1476 another location, you should provide the full path in the
1477 first parameter.
1478
1479 Shared libraries and data files required by the program
1480 must be available on filesystems which are mounted in the
1481 correct places.  It is the caller's responsibility to ensure
1482 all filesystems that are needed are mounted at the right
1483 locations.");
1484
1485   ("command_lines", (RStringList "lines", [StringList "arguments"]), 51, [ProtocolLimitWarning],
1486    [InitBasicFS, Always, TestOutputList (
1487       [["upload"; "test-command"; "/test-command"];
1488        ["chmod"; "0o755"; "/test-command"];
1489        ["command_lines"; "/test-command 1"]], ["Result1"]);
1490     InitBasicFS, Always, TestOutputList (
1491       [["upload"; "test-command"; "/test-command"];
1492        ["chmod"; "0o755"; "/test-command"];
1493        ["command_lines"; "/test-command 2"]], ["Result2"]);
1494     InitBasicFS, Always, TestOutputList (
1495       [["upload"; "test-command"; "/test-command"];
1496        ["chmod"; "0o755"; "/test-command"];
1497        ["command_lines"; "/test-command 3"]], ["";"Result3"]);
1498     InitBasicFS, Always, TestOutputList (
1499       [["upload"; "test-command"; "/test-command"];
1500        ["chmod"; "0o755"; "/test-command"];
1501        ["command_lines"; "/test-command 4"]], ["";"Result4"]);
1502     InitBasicFS, Always, TestOutputList (
1503       [["upload"; "test-command"; "/test-command"];
1504        ["chmod"; "0o755"; "/test-command"];
1505        ["command_lines"; "/test-command 5"]], ["";"Result5";""]);
1506     InitBasicFS, Always, TestOutputList (
1507       [["upload"; "test-command"; "/test-command"];
1508        ["chmod"; "0o755"; "/test-command"];
1509        ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]);
1510     InitBasicFS, Always, TestOutputList (
1511       [["upload"; "test-command"; "/test-command"];
1512        ["chmod"; "0o755"; "/test-command"];
1513        ["command_lines"; "/test-command 7"]], []);
1514     InitBasicFS, Always, TestOutputList (
1515       [["upload"; "test-command"; "/test-command"];
1516        ["chmod"; "0o755"; "/test-command"];
1517        ["command_lines"; "/test-command 8"]], [""]);
1518     InitBasicFS, Always, TestOutputList (
1519       [["upload"; "test-command"; "/test-command"];
1520        ["chmod"; "0o755"; "/test-command"];
1521        ["command_lines"; "/test-command 9"]], ["";""]);
1522     InitBasicFS, Always, TestOutputList (
1523       [["upload"; "test-command"; "/test-command"];
1524        ["chmod"; "0o755"; "/test-command"];
1525        ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]);
1526     InitBasicFS, Always, TestOutputList (
1527       [["upload"; "test-command"; "/test-command"];
1528        ["chmod"; "0o755"; "/test-command"];
1529        ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])],
1530    "run a command, returning lines",
1531    "\
1532 This is the same as C<guestfs_command>, but splits the
1533 result into a list of lines.
1534
1535 See also: C<guestfs_sh_lines>");
1536
1537   ("stat", (RStruct ("statbuf", "stat"), [String "path"]), 52, [],
1538    [InitBasicFS, Always, TestOutputStruct (
1539       [["touch"; "/new"];
1540        ["stat"; "/new"]], [CompareWithInt ("size", 0)])],
1541    "get file information",
1542    "\
1543 Returns file information for the given C<path>.
1544
1545 This is the same as the C<stat(2)> system call.");
1546
1547   ("lstat", (RStruct ("statbuf", "stat"), [String "path"]), 53, [],
1548    [InitBasicFS, Always, TestOutputStruct (
1549       [["touch"; "/new"];
1550        ["lstat"; "/new"]], [CompareWithInt ("size", 0)])],
1551    "get file information for a symbolic link",
1552    "\
1553 Returns file information for the given C<path>.
1554
1555 This is the same as C<guestfs_stat> except that if C<path>
1556 is a symbolic link, then the link is stat-ed, not the file it
1557 refers to.
1558
1559 This is the same as the C<lstat(2)> system call.");
1560
1561   ("statvfs", (RStruct ("statbuf", "statvfs"), [String "path"]), 54, [],
1562    [InitBasicFS, Always, TestOutputStruct (
1563       [["statvfs"; "/"]], [CompareWithInt ("namemax", 255);
1564                            CompareWithInt ("bsize", 1024)])],
1565    "get file system statistics",
1566    "\
1567 Returns file system statistics for any mounted file system.
1568 C<path> should be a file or directory in the mounted file system
1569 (typically it is the mount point itself, but it doesn't need to be).
1570
1571 This is the same as the C<statvfs(2)> system call.");
1572
1573   ("tune2fs_l", (RHashtable "superblock", [String "device"]), 55, [],
1574    [], (* XXX test *)
1575    "get ext2/ext3/ext4 superblock details",
1576    "\
1577 This returns the contents of the ext2, ext3 or ext4 filesystem
1578 superblock on C<device>.
1579
1580 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
1581 manpage for more details.  The list of fields returned isn't
1582 clearly defined, and depends on both the version of C<tune2fs>
1583 that libguestfs was built against, and the filesystem itself.");
1584
1585   ("blockdev_setro", (RErr, [String "device"]), 56, [],
1586    [InitEmpty, Always, TestOutputTrue (
1587       [["blockdev_setro"; "/dev/sda"];
1588        ["blockdev_getro"; "/dev/sda"]])],
1589    "set block device to read-only",
1590    "\
1591 Sets the block device named C<device> to read-only.
1592
1593 This uses the L<blockdev(8)> command.");
1594
1595   ("blockdev_setrw", (RErr, [String "device"]), 57, [],
1596    [InitEmpty, Always, TestOutputFalse (
1597       [["blockdev_setrw"; "/dev/sda"];
1598        ["blockdev_getro"; "/dev/sda"]])],
1599    "set block device to read-write",
1600    "\
1601 Sets the block device named C<device> to read-write.
1602
1603 This uses the L<blockdev(8)> command.");
1604
1605   ("blockdev_getro", (RBool "ro", [String "device"]), 58, [],
1606    [InitEmpty, Always, TestOutputTrue (
1607       [["blockdev_setro"; "/dev/sda"];
1608        ["blockdev_getro"; "/dev/sda"]])],
1609    "is block device set to read-only",
1610    "\
1611 Returns a boolean indicating if the block device is read-only
1612 (true if read-only, false if not).
1613
1614 This uses the L<blockdev(8)> command.");
1615
1616   ("blockdev_getss", (RInt "sectorsize", [String "device"]), 59, [],
1617    [InitEmpty, Always, TestOutputInt (
1618       [["blockdev_getss"; "/dev/sda"]], 512)],
1619    "get sectorsize of block device",
1620    "\
1621 This returns the size of sectors on a block device.
1622 Usually 512, but can be larger for modern devices.
1623
1624 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
1625 for that).
1626
1627 This uses the L<blockdev(8)> command.");
1628
1629   ("blockdev_getbsz", (RInt "blocksize", [String "device"]), 60, [],
1630    [InitEmpty, Always, TestOutputInt (
1631       [["blockdev_getbsz"; "/dev/sda"]], 4096)],
1632    "get blocksize of block device",
1633    "\
1634 This returns the block size of a device.
1635
1636 (Note this is different from both I<size in blocks> and
1637 I<filesystem block size>).
1638
1639 This uses the L<blockdev(8)> command.");
1640
1641   ("blockdev_setbsz", (RErr, [String "device"; Int "blocksize"]), 61, [],
1642    [], (* XXX test *)
1643    "set blocksize of block device",
1644    "\
1645 This sets the block size of a device.
1646
1647 (Note this is different from both I<size in blocks> and
1648 I<filesystem block size>).
1649
1650 This uses the L<blockdev(8)> command.");
1651
1652   ("blockdev_getsz", (RInt64 "sizeinsectors", [String "device"]), 62, [],
1653    [InitEmpty, Always, TestOutputInt (
1654       [["blockdev_getsz"; "/dev/sda"]], 1024000)],
1655    "get total size of device in 512-byte sectors",
1656    "\
1657 This returns the size of the device in units of 512-byte sectors
1658 (even if the sectorsize isn't 512 bytes ... weird).
1659
1660 See also C<guestfs_blockdev_getss> for the real sector size of
1661 the device, and C<guestfs_blockdev_getsize64> for the more
1662 useful I<size in bytes>.
1663
1664 This uses the L<blockdev(8)> command.");
1665
1666   ("blockdev_getsize64", (RInt64 "sizeinbytes", [String "device"]), 63, [],
1667    [InitEmpty, Always, TestOutputInt (
1668       [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
1669    "get total size of device in bytes",
1670    "\
1671 This returns the size of the device in bytes.
1672
1673 See also C<guestfs_blockdev_getsz>.
1674
1675 This uses the L<blockdev(8)> command.");
1676
1677   ("blockdev_flushbufs", (RErr, [String "device"]), 64, [],
1678    [InitEmpty, Always, TestRun
1679       [["blockdev_flushbufs"; "/dev/sda"]]],
1680    "flush device buffers",
1681    "\
1682 This tells the kernel to flush internal buffers associated
1683 with C<device>.
1684
1685 This uses the L<blockdev(8)> command.");
1686
1687   ("blockdev_rereadpt", (RErr, [String "device"]), 65, [],
1688    [InitEmpty, Always, TestRun
1689       [["blockdev_rereadpt"; "/dev/sda"]]],
1690    "reread partition table",
1691    "\
1692 Reread the partition table on C<device>.
1693
1694 This uses the L<blockdev(8)> command.");
1695
1696   ("upload", (RErr, [FileIn "filename"; String "remotefilename"]), 66, [],
1697    [InitBasicFS, Always, TestOutput (
1698       (* Pick a file from cwd which isn't likely to change. *)
1699     [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1700      ["checksum"; "md5"; "/COPYING.LIB"]], "e3eda01d9815f8d24aae2dbd89b68b06")],
1701    "upload a file from the local machine",
1702    "\
1703 Upload local file C<filename> to C<remotefilename> on the
1704 filesystem.
1705
1706 C<filename> can also be a named pipe.
1707
1708 See also C<guestfs_download>.");
1709
1710   ("download", (RErr, [String "remotefilename"; FileOut "filename"]), 67, [],
1711    [InitBasicFS, Always, TestOutput (
1712       (* Pick a file from cwd which isn't likely to change. *)
1713     [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1714      ["download"; "/COPYING.LIB"; "testdownload.tmp"];
1715      ["upload"; "testdownload.tmp"; "/upload"];
1716      ["checksum"; "md5"; "/upload"]], "e3eda01d9815f8d24aae2dbd89b68b06")],
1717    "download a file to the local machine",
1718    "\
1719 Download file C<remotefilename> and save it as C<filename>
1720 on the local machine.
1721
1722 C<filename> can also be a named pipe.
1723
1724 See also C<guestfs_upload>, C<guestfs_cat>.");
1725
1726   ("checksum", (RString "checksum", [String "csumtype"; String "path"]), 68, [],
1727    [InitBasicFS, Always, TestOutput (
1728       [["write_file"; "/new"; "test\n"; "0"];
1729        ["checksum"; "crc"; "/new"]], "935282863");
1730     InitBasicFS, Always, TestLastFail (
1731       [["checksum"; "crc"; "/new"]]);
1732     InitBasicFS, Always, TestOutput (
1733       [["write_file"; "/new"; "test\n"; "0"];
1734        ["checksum"; "md5"; "/new"]], "d8e8fca2dc0f896fd7cb4cb0031ba249");
1735     InitBasicFS, Always, TestOutput (
1736       [["write_file"; "/new"; "test\n"; "0"];
1737        ["checksum"; "sha1"; "/new"]], "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83");
1738     InitBasicFS, Always, TestOutput (
1739       [["write_file"; "/new"; "test\n"; "0"];
1740        ["checksum"; "sha224"; "/new"]], "52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec");
1741     InitBasicFS, Always, TestOutput (
1742       [["write_file"; "/new"; "test\n"; "0"];
1743        ["checksum"; "sha256"; "/new"]], "f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2");
1744     InitBasicFS, Always, TestOutput (
1745       [["write_file"; "/new"; "test\n"; "0"];
1746        ["checksum"; "sha384"; "/new"]], "109bb6b5b6d5547c1ce03c7a8bd7d8f80c1cb0957f50c4f7fda04692079917e4f9cad52b878f3d8234e1a170b154b72d");
1747     InitBasicFS, Always, TestOutput (
1748       [["write_file"; "/new"; "test\n"; "0"];
1749        ["checksum"; "sha512"; "/new"]], "0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123");
1750     InitBasicFS, Always, TestOutput (
1751       (* RHEL 5 thinks this is an HFS+ filesystem unless we give
1752        * the type explicitly.
1753        *)
1754       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
1755        ["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c")],
1756    "compute MD5, SHAx or CRC checksum of file",
1757    "\
1758 This call computes the MD5, SHAx or CRC checksum of the
1759 file named C<path>.
1760
1761 The type of checksum to compute is given by the C<csumtype>
1762 parameter which must have one of the following values:
1763
1764 =over 4
1765
1766 =item C<crc>
1767
1768 Compute the cyclic redundancy check (CRC) specified by POSIX
1769 for the C<cksum> command.
1770
1771 =item C<md5>
1772
1773 Compute the MD5 hash (using the C<md5sum> program).
1774
1775 =item C<sha1>
1776
1777 Compute the SHA1 hash (using the C<sha1sum> program).
1778
1779 =item C<sha224>
1780
1781 Compute the SHA224 hash (using the C<sha224sum> program).
1782
1783 =item C<sha256>
1784
1785 Compute the SHA256 hash (using the C<sha256sum> program).
1786
1787 =item C<sha384>
1788
1789 Compute the SHA384 hash (using the C<sha384sum> program).
1790
1791 =item C<sha512>
1792
1793 Compute the SHA512 hash (using the C<sha512sum> program).
1794
1795 =back
1796
1797 The checksum is returned as a printable string.");
1798
1799   ("tar_in", (RErr, [FileIn "tarfile"; String "directory"]), 69, [],
1800    [InitBasicFS, Always, TestOutput (
1801       [["tar_in"; "../images/helloworld.tar"; "/"];
1802        ["cat"; "/hello"]], "hello\n")],
1803    "unpack tarfile to directory",
1804    "\
1805 This command uploads and unpacks local file C<tarfile> (an
1806 I<uncompressed> tar file) into C<directory>.
1807
1808 To upload a compressed tarball, use C<guestfs_tgz_in>.");
1809
1810   ("tar_out", (RErr, [String "directory"; FileOut "tarfile"]), 70, [],
1811    [],
1812    "pack directory into tarfile",
1813    "\
1814 This command packs the contents of C<directory> and downloads
1815 it to local file C<tarfile>.
1816
1817 To download a compressed tarball, use C<guestfs_tgz_out>.");
1818
1819   ("tgz_in", (RErr, [FileIn "tarball"; String "directory"]), 71, [],
1820    [InitBasicFS, Always, TestOutput (
1821       [["tgz_in"; "../images/helloworld.tar.gz"; "/"];
1822        ["cat"; "/hello"]], "hello\n")],
1823    "unpack compressed tarball to directory",
1824    "\
1825 This command uploads and unpacks local file C<tarball> (a
1826 I<gzip compressed> tar file) into C<directory>.
1827
1828 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
1829
1830   ("tgz_out", (RErr, [String "directory"; FileOut "tarball"]), 72, [],
1831    [],
1832    "pack directory into compressed tarball",
1833    "\
1834 This command packs the contents of C<directory> and downloads
1835 it to local file C<tarball>.
1836
1837 To download an uncompressed tarball, use C<guestfs_tar_out>.");
1838
1839   ("mount_ro", (RErr, [String "device"; String "mountpoint"]), 73, [],
1840    [InitBasicFS, Always, TestLastFail (
1841       [["umount"; "/"];
1842        ["mount_ro"; "/dev/sda1"; "/"];
1843        ["touch"; "/new"]]);
1844     InitBasicFS, Always, TestOutput (
1845       [["write_file"; "/new"; "data"; "0"];
1846        ["umount"; "/"];
1847        ["mount_ro"; "/dev/sda1"; "/"];
1848        ["cat"; "/new"]], "data")],
1849    "mount a guest disk, read-only",
1850    "\
1851 This is the same as the C<guestfs_mount> command, but it
1852 mounts the filesystem with the read-only (I<-o ro>) flag.");
1853
1854   ("mount_options", (RErr, [String "options"; String "device"; String "mountpoint"]), 74, [],
1855    [],
1856    "mount a guest disk with mount options",
1857    "\
1858 This is the same as the C<guestfs_mount> command, but it
1859 allows you to set the mount options as for the
1860 L<mount(8)> I<-o> flag.");
1861
1862   ("mount_vfs", (RErr, [String "options"; String "vfstype"; String "device"; String "mountpoint"]), 75, [],
1863    [],
1864    "mount a guest disk with mount options and vfstype",
1865    "\
1866 This is the same as the C<guestfs_mount> command, but it
1867 allows you to set both the mount options and the vfstype
1868 as for the L<mount(8)> I<-o> and I<-t> flags.");
1869
1870   ("debug", (RString "result", [String "subcmd"; StringList "extraargs"]), 76, [],
1871    [],
1872    "debugging and internals",
1873    "\
1874 The C<guestfs_debug> command exposes some internals of
1875 C<guestfsd> (the guestfs daemon) that runs inside the
1876 qemu subprocess.
1877
1878 There is no comprehensive help for this command.  You have
1879 to look at the file C<daemon/debug.c> in the libguestfs source
1880 to find out what you can do.");
1881
1882   ("lvremove", (RErr, [String "device"]), 77, [],
1883    [InitEmpty, Always, TestOutputList (
1884       [["sfdiskM"; "/dev/sda"; ","];
1885        ["pvcreate"; "/dev/sda1"];
1886        ["vgcreate"; "VG"; "/dev/sda1"];
1887        ["lvcreate"; "LV1"; "VG"; "50"];
1888        ["lvcreate"; "LV2"; "VG"; "50"];
1889        ["lvremove"; "/dev/VG/LV1"];
1890        ["lvs"]], ["/dev/VG/LV2"]);
1891     InitEmpty, Always, TestOutputList (
1892       [["sfdiskM"; "/dev/sda"; ","];
1893        ["pvcreate"; "/dev/sda1"];
1894        ["vgcreate"; "VG"; "/dev/sda1"];
1895        ["lvcreate"; "LV1"; "VG"; "50"];
1896        ["lvcreate"; "LV2"; "VG"; "50"];
1897        ["lvremove"; "/dev/VG"];
1898        ["lvs"]], []);
1899     InitEmpty, Always, TestOutputList (
1900       [["sfdiskM"; "/dev/sda"; ","];
1901        ["pvcreate"; "/dev/sda1"];
1902        ["vgcreate"; "VG"; "/dev/sda1"];
1903        ["lvcreate"; "LV1"; "VG"; "50"];
1904        ["lvcreate"; "LV2"; "VG"; "50"];
1905        ["lvremove"; "/dev/VG"];
1906        ["vgs"]], ["VG"])],
1907    "remove an LVM logical volume",
1908    "\
1909 Remove an LVM logical volume C<device>, where C<device> is
1910 the path to the LV, such as C</dev/VG/LV>.
1911
1912 You can also remove all LVs in a volume group by specifying
1913 the VG name, C</dev/VG>.");
1914
1915   ("vgremove", (RErr, [String "vgname"]), 78, [],
1916    [InitEmpty, Always, TestOutputList (
1917       [["sfdiskM"; "/dev/sda"; ","];
1918        ["pvcreate"; "/dev/sda1"];
1919        ["vgcreate"; "VG"; "/dev/sda1"];
1920        ["lvcreate"; "LV1"; "VG"; "50"];
1921        ["lvcreate"; "LV2"; "VG"; "50"];
1922        ["vgremove"; "VG"];
1923        ["lvs"]], []);
1924     InitEmpty, Always, TestOutputList (
1925       [["sfdiskM"; "/dev/sda"; ","];
1926        ["pvcreate"; "/dev/sda1"];
1927        ["vgcreate"; "VG"; "/dev/sda1"];
1928        ["lvcreate"; "LV1"; "VG"; "50"];
1929        ["lvcreate"; "LV2"; "VG"; "50"];
1930        ["vgremove"; "VG"];
1931        ["vgs"]], [])],
1932    "remove an LVM volume group",
1933    "\
1934 Remove an LVM volume group C<vgname>, (for example C<VG>).
1935
1936 This also forcibly removes all logical volumes in the volume
1937 group (if any).");
1938
1939   ("pvremove", (RErr, [String "device"]), 79, [],
1940    [InitEmpty, Always, TestOutputListOfDevices (
1941       [["sfdiskM"; "/dev/sda"; ","];
1942        ["pvcreate"; "/dev/sda1"];
1943        ["vgcreate"; "VG"; "/dev/sda1"];
1944        ["lvcreate"; "LV1"; "VG"; "50"];
1945        ["lvcreate"; "LV2"; "VG"; "50"];
1946        ["vgremove"; "VG"];
1947        ["pvremove"; "/dev/sda1"];
1948        ["lvs"]], []);
1949     InitEmpty, Always, TestOutputListOfDevices (
1950       [["sfdiskM"; "/dev/sda"; ","];
1951        ["pvcreate"; "/dev/sda1"];
1952        ["vgcreate"; "VG"; "/dev/sda1"];
1953        ["lvcreate"; "LV1"; "VG"; "50"];
1954        ["lvcreate"; "LV2"; "VG"; "50"];
1955        ["vgremove"; "VG"];
1956        ["pvremove"; "/dev/sda1"];
1957        ["vgs"]], []);
1958     InitEmpty, Always, TestOutputListOfDevices (
1959       [["sfdiskM"; "/dev/sda"; ","];
1960        ["pvcreate"; "/dev/sda1"];
1961        ["vgcreate"; "VG"; "/dev/sda1"];
1962        ["lvcreate"; "LV1"; "VG"; "50"];
1963        ["lvcreate"; "LV2"; "VG"; "50"];
1964        ["vgremove"; "VG"];
1965        ["pvremove"; "/dev/sda1"];
1966        ["pvs"]], [])],
1967    "remove an LVM physical volume",
1968    "\
1969 This wipes a physical volume C<device> so that LVM will no longer
1970 recognise it.
1971
1972 The implementation uses the C<pvremove> command which refuses to
1973 wipe physical volumes that contain any volume groups, so you have
1974 to remove those first.");
1975
1976   ("set_e2label", (RErr, [String "device"; String "label"]), 80, [],
1977    [InitBasicFS, Always, TestOutput (
1978       [["set_e2label"; "/dev/sda1"; "testlabel"];
1979        ["get_e2label"; "/dev/sda1"]], "testlabel")],
1980    "set the ext2/3/4 filesystem label",
1981    "\
1982 This sets the ext2/3/4 filesystem label of the filesystem on
1983 C<device> to C<label>.  Filesystem labels are limited to
1984 16 characters.
1985
1986 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
1987 to return the existing label on a filesystem.");
1988
1989   ("get_e2label", (RString "label", [String "device"]), 81, [],
1990    [],
1991    "get the ext2/3/4 filesystem label",
1992    "\
1993 This returns the ext2/3/4 filesystem label of the filesystem on
1994 C<device>.");
1995
1996   ("set_e2uuid", (RErr, [String "device"; String "uuid"]), 82, [],
1997    [InitBasicFS, Always, TestOutput (
1998       [["set_e2uuid"; "/dev/sda1"; "a3a61220-882b-4f61-89f4-cf24dcc7297d"];
1999        ["get_e2uuid"; "/dev/sda1"]], "a3a61220-882b-4f61-89f4-cf24dcc7297d");
2000     InitBasicFS, Always, TestOutput (
2001       [["set_e2uuid"; "/dev/sda1"; "clear"];
2002        ["get_e2uuid"; "/dev/sda1"]], "");
2003     (* We can't predict what UUIDs will be, so just check the commands run. *)
2004     InitBasicFS, Always, TestRun (
2005       [["set_e2uuid"; "/dev/sda1"; "random"]]);
2006     InitBasicFS, Always, TestRun (
2007       [["set_e2uuid"; "/dev/sda1"; "time"]])],
2008    "set the ext2/3/4 filesystem UUID",
2009    "\
2010 This sets the ext2/3/4 filesystem UUID of the filesystem on
2011 C<device> to C<uuid>.  The format of the UUID and alternatives
2012 such as C<clear>, C<random> and C<time> are described in the
2013 L<tune2fs(8)> manpage.
2014
2015 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
2016 to return the existing UUID of a filesystem.");
2017
2018   ("get_e2uuid", (RString "uuid", [String "device"]), 83, [],
2019    [],
2020    "get the ext2/3/4 filesystem UUID",
2021    "\
2022 This returns the ext2/3/4 filesystem UUID of the filesystem on
2023 C<device>.");
2024
2025   ("fsck", (RInt "status", [String "fstype"; String "device"]), 84, [],
2026    [InitBasicFS, Always, TestOutputInt (
2027       [["umount"; "/dev/sda1"];
2028        ["fsck"; "ext2"; "/dev/sda1"]], 0);
2029     InitBasicFS, Always, TestOutputInt (
2030       [["umount"; "/dev/sda1"];
2031        ["zero"; "/dev/sda1"];
2032        ["fsck"; "ext2"; "/dev/sda1"]], 8)],
2033    "run the filesystem checker",
2034    "\
2035 This runs the filesystem checker (fsck) on C<device> which
2036 should have filesystem type C<fstype>.
2037
2038 The returned integer is the status.  See L<fsck(8)> for the
2039 list of status codes from C<fsck>.
2040
2041 Notes:
2042
2043 =over 4
2044
2045 =item *
2046
2047 Multiple status codes can be summed together.
2048
2049 =item *
2050
2051 A non-zero return code can mean \"success\", for example if
2052 errors have been corrected on the filesystem.
2053
2054 =item *
2055
2056 Checking or repairing NTFS volumes is not supported
2057 (by linux-ntfs).
2058
2059 =back
2060
2061 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
2062
2063   ("zero", (RErr, [String "device"]), 85, [],
2064    [InitBasicFS, Always, TestOutput (
2065       [["umount"; "/dev/sda1"];
2066        ["zero"; "/dev/sda1"];
2067        ["file"; "/dev/sda1"]], "data")],
2068    "write zeroes to the device",
2069    "\
2070 This command writes zeroes over the first few blocks of C<device>.
2071
2072 How many blocks are zeroed isn't specified (but it's I<not> enough
2073 to securely wipe the device).  It should be sufficient to remove
2074 any partition tables, filesystem superblocks and so on.
2075
2076 See also: C<guestfs_scrub_device>.");
2077
2078   ("grub_install", (RErr, [String "root"; String "device"]), 86, [],
2079    (* Test disabled because grub-install incompatible with virtio-blk driver.
2080     * See also: https://bugzilla.redhat.com/show_bug.cgi?id=479760
2081     *)
2082    [InitBasicFS, Disabled, TestOutputTrue (
2083       [["grub_install"; "/"; "/dev/sda1"];
2084        ["is_dir"; "/boot"]])],
2085    "install GRUB",
2086    "\
2087 This command installs GRUB (the Grand Unified Bootloader) on
2088 C<device>, with the root directory being C<root>.");
2089
2090   ("cp", (RErr, [String "src"; String "dest"]), 87, [],
2091    [InitBasicFS, Always, TestOutput (
2092       [["write_file"; "/old"; "file content"; "0"];
2093        ["cp"; "/old"; "/new"];
2094        ["cat"; "/new"]], "file content");
2095     InitBasicFS, Always, TestOutputTrue (
2096       [["write_file"; "/old"; "file content"; "0"];
2097        ["cp"; "/old"; "/new"];
2098        ["is_file"; "/old"]]);
2099     InitBasicFS, Always, TestOutput (
2100       [["write_file"; "/old"; "file content"; "0"];
2101        ["mkdir"; "/dir"];
2102        ["cp"; "/old"; "/dir/new"];
2103        ["cat"; "/dir/new"]], "file content")],
2104    "copy a file",
2105    "\
2106 This copies a file from C<src> to C<dest> where C<dest> is
2107 either a destination filename or destination directory.");
2108
2109   ("cp_a", (RErr, [String "src"; String "dest"]), 88, [],
2110    [InitBasicFS, Always, TestOutput (
2111       [["mkdir"; "/olddir"];
2112        ["mkdir"; "/newdir"];
2113        ["write_file"; "/olddir/file"; "file content"; "0"];
2114        ["cp_a"; "/olddir"; "/newdir"];
2115        ["cat"; "/newdir/olddir/file"]], "file content")],
2116    "copy a file or directory recursively",
2117    "\
2118 This copies a file or directory from C<src> to C<dest>
2119 recursively using the C<cp -a> command.");
2120
2121   ("mv", (RErr, [String "src"; String "dest"]), 89, [],
2122    [InitBasicFS, Always, TestOutput (
2123       [["write_file"; "/old"; "file content"; "0"];
2124        ["mv"; "/old"; "/new"];
2125        ["cat"; "/new"]], "file content");
2126     InitBasicFS, Always, TestOutputFalse (
2127       [["write_file"; "/old"; "file content"; "0"];
2128        ["mv"; "/old"; "/new"];
2129        ["is_file"; "/old"]])],
2130    "move a file",
2131    "\
2132 This moves a file from C<src> to C<dest> where C<dest> is
2133 either a destination filename or destination directory.");
2134
2135   ("drop_caches", (RErr, [Int "whattodrop"]), 90, [],
2136    [InitEmpty, Always, TestRun (
2137       [["drop_caches"; "3"]])],
2138    "drop kernel page cache, dentries and inodes",
2139    "\
2140 This instructs the guest kernel to drop its page cache,
2141 and/or dentries and inode caches.  The parameter C<whattodrop>
2142 tells the kernel what precisely to drop, see
2143 L<http://linux-mm.org/Drop_Caches>
2144
2145 Setting C<whattodrop> to 3 should drop everything.
2146
2147 This automatically calls L<sync(2)> before the operation,
2148 so that the maximum guest memory is freed.");
2149
2150   ("dmesg", (RString "kmsgs", []), 91, [],
2151    [InitEmpty, Always, TestRun (
2152       [["dmesg"]])],
2153    "return kernel messages",
2154    "\
2155 This returns the kernel messages (C<dmesg> output) from
2156 the guest kernel.  This is sometimes useful for extended
2157 debugging of problems.
2158
2159 Another way to get the same information is to enable
2160 verbose messages with C<guestfs_set_verbose> or by setting
2161 the environment variable C<LIBGUESTFS_DEBUG=1> before
2162 running the program.");
2163
2164   ("ping_daemon", (RErr, []), 92, [],
2165    [InitEmpty, Always, TestRun (
2166       [["ping_daemon"]])],
2167    "ping the guest daemon",
2168    "\
2169 This is a test probe into the guestfs daemon running inside
2170 the qemu subprocess.  Calling this function checks that the
2171 daemon responds to the ping message, without affecting the daemon
2172 or attached block device(s) in any other way.");
2173
2174   ("equal", (RBool "equality", [String "file1"; String "file2"]), 93, [],
2175    [InitBasicFS, Always, TestOutputTrue (
2176       [["write_file"; "/file1"; "contents of a file"; "0"];
2177        ["cp"; "/file1"; "/file2"];
2178        ["equal"; "/file1"; "/file2"]]);
2179     InitBasicFS, Always, TestOutputFalse (
2180       [["write_file"; "/file1"; "contents of a file"; "0"];
2181        ["write_file"; "/file2"; "contents of another file"; "0"];
2182        ["equal"; "/file1"; "/file2"]]);
2183     InitBasicFS, Always, TestLastFail (
2184       [["equal"; "/file1"; "/file2"]])],
2185    "test if two files have equal contents",
2186    "\
2187 This compares the two files C<file1> and C<file2> and returns
2188 true if their content is exactly equal, or false otherwise.
2189
2190 The external L<cmp(1)> program is used for the comparison.");
2191
2192   ("strings", (RStringList "stringsout", [String "path"]), 94, [ProtocolLimitWarning],
2193    [InitBasicFS, Always, TestOutputList (
2194       [["write_file"; "/new"; "hello\nworld\n"; "0"];
2195        ["strings"; "/new"]], ["hello"; "world"]);
2196     InitBasicFS, Always, TestOutputList (
2197       [["touch"; "/new"];
2198        ["strings"; "/new"]], [])],
2199    "print the printable strings in a file",
2200    "\
2201 This runs the L<strings(1)> command on a file and returns
2202 the list of printable strings found.");
2203
2204   ("strings_e", (RStringList "stringsout", [String "encoding"; String "path"]), 95, [ProtocolLimitWarning],
2205    [InitBasicFS, Always, TestOutputList (
2206       [["write_file"; "/new"; "hello\nworld\n"; "0"];
2207        ["strings_e"; "b"; "/new"]], []);
2208     InitBasicFS, Disabled, TestOutputList (
2209       [["write_file"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"; "24"];
2210        ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2211    "print the printable strings in a file",
2212    "\
2213 This is like the C<guestfs_strings> command, but allows you to
2214 specify the encoding.
2215
2216 See the L<strings(1)> manpage for the full list of encodings.
2217
2218 Commonly useful encodings are C<l> (lower case L) which will
2219 show strings inside Windows/x86 files.
2220
2221 The returned strings are transcoded to UTF-8.");
2222
2223   ("hexdump", (RString "dump", [String "path"]), 96, [ProtocolLimitWarning],
2224    [InitBasicFS, Always, TestOutput (
2225       [["write_file"; "/new"; "hello\nworld\n"; "12"];
2226        ["hexdump"; "/new"]], "00000000  68 65 6c 6c 6f 0a 77 6f  72 6c 64 0a              |hello.world.|\n0000000c\n");
2227     (* Test for RHBZ#501888c2 regression which caused large hexdump
2228      * commands to segfault.
2229      *)
2230     InitBasicFS, Always, TestRun (
2231       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2232        ["hexdump"; "/100krandom"]])],
2233    "dump a file in hexadecimal",
2234    "\
2235 This runs C<hexdump -C> on the given C<path>.  The result is
2236 the human-readable, canonical hex dump of the file.");
2237
2238   ("zerofree", (RErr, [String "device"]), 97, [],
2239    [InitNone, Always, TestOutput (
2240       [["sfdiskM"; "/dev/sda"; ","];
2241        ["mkfs"; "ext3"; "/dev/sda1"];
2242        ["mount"; "/dev/sda1"; "/"];
2243        ["write_file"; "/new"; "test file"; "0"];
2244        ["umount"; "/dev/sda1"];
2245        ["zerofree"; "/dev/sda1"];
2246        ["mount"; "/dev/sda1"; "/"];
2247        ["cat"; "/new"]], "test file")],
2248    "zero unused inodes and disk blocks on ext2/3 filesystem",
2249    "\
2250 This runs the I<zerofree> program on C<device>.  This program
2251 claims to zero unused inodes and disk blocks on an ext2/3
2252 filesystem, thus making it possible to compress the filesystem
2253 more effectively.
2254
2255 You should B<not> run this program if the filesystem is
2256 mounted.
2257
2258 It is possible that using this program can damage the filesystem
2259 or data on the filesystem.");
2260
2261   ("pvresize", (RErr, [String "device"]), 98, [],
2262    [],
2263    "resize an LVM physical volume",
2264    "\
2265 This resizes (expands or shrinks) an existing LVM physical
2266 volume to match the new size of the underlying device.");
2267
2268   ("sfdisk_N", (RErr, [String "device"; Int "partnum";
2269                        Int "cyls"; Int "heads"; Int "sectors";
2270                        String "line"]), 99, [DangerWillRobinson],
2271    [],
2272    "modify a single partition on a block device",
2273    "\
2274 This runs L<sfdisk(8)> option to modify just the single
2275 partition C<n> (note: C<n> counts from 1).
2276
2277 For other parameters, see C<guestfs_sfdisk>.  You should usually
2278 pass C<0> for the cyls/heads/sectors parameters.");
2279
2280   ("sfdisk_l", (RString "partitions", [String "device"]), 100, [],
2281    [],
2282    "display the partition table",
2283    "\
2284 This displays the partition table on C<device>, in the
2285 human-readable output of the L<sfdisk(8)> command.  It is
2286 not intended to be parsed.");
2287
2288   ("sfdisk_kernel_geometry", (RString "partitions", [String "device"]), 101, [],
2289    [],
2290    "display the kernel geometry",
2291    "\
2292 This displays the kernel's idea of the geometry of C<device>.
2293
2294 The result is in human-readable format, and not designed to
2295 be parsed.");
2296
2297   ("sfdisk_disk_geometry", (RString "partitions", [String "device"]), 102, [],
2298    [],
2299    "display the disk geometry from the partition table",
2300    "\
2301 This displays the disk geometry of C<device> read from the
2302 partition table.  Especially in the case where the underlying
2303 block device has been resized, this can be different from the
2304 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2305
2306 The result is in human-readable format, and not designed to
2307 be parsed.");
2308
2309   ("vg_activate_all", (RErr, [Bool "activate"]), 103, [],
2310    [],
2311    "activate or deactivate all volume groups",
2312    "\
2313 This command activates or (if C<activate> is false) deactivates
2314 all logical volumes in all volume groups.
2315 If activated, then they are made known to the
2316 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2317 then those devices disappear.
2318
2319 This command is the same as running C<vgchange -a y|n>");
2320
2321   ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"]), 104, [],
2322    [],
2323    "activate or deactivate some volume groups",
2324    "\
2325 This command activates or (if C<activate> is false) deactivates
2326 all logical volumes in the listed volume groups C<volgroups>.
2327 If activated, then they are made known to the
2328 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2329 then those devices disappear.
2330
2331 This command is the same as running C<vgchange -a y|n volgroups...>
2332
2333 Note that if C<volgroups> is an empty list then B<all> volume groups
2334 are activated or deactivated.");
2335
2336   ("lvresize", (RErr, [String "device"; Int "mbytes"]), 105, [],
2337    [InitNone, Always, TestOutput (
2338     [["sfdiskM"; "/dev/sda"; ","];
2339      ["pvcreate"; "/dev/sda1"];
2340      ["vgcreate"; "VG"; "/dev/sda1"];
2341      ["lvcreate"; "LV"; "VG"; "10"];
2342      ["mkfs"; "ext2"; "/dev/VG/LV"];
2343      ["mount"; "/dev/VG/LV"; "/"];
2344      ["write_file"; "/new"; "test content"; "0"];
2345      ["umount"; "/"];
2346      ["lvresize"; "/dev/VG/LV"; "20"];
2347      ["e2fsck_f"; "/dev/VG/LV"];
2348      ["resize2fs"; "/dev/VG/LV"];
2349      ["mount"; "/dev/VG/LV"; "/"];
2350      ["cat"; "/new"]], "test content")],
2351    "resize an LVM logical volume",
2352    "\
2353 This resizes (expands or shrinks) an existing LVM logical
2354 volume to C<mbytes>.  When reducing, data in the reduced part
2355 is lost.");
2356
2357   ("resize2fs", (RErr, [String "device"]), 106, [],
2358    [], (* lvresize tests this *)
2359    "resize an ext2/ext3 filesystem",
2360    "\
2361 This resizes an ext2 or ext3 filesystem to match the size of
2362 the underlying device.
2363
2364 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2365 on the C<device> before calling this command.  For unknown reasons
2366 C<resize2fs> sometimes gives an error about this and sometimes not.
2367 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2368 calling this function.");
2369
2370   ("find", (RStringList "names", [String "directory"]), 107, [],
2371    [InitBasicFS, Always, TestOutputList (
2372       [["find"; "/"]], ["lost+found"]);
2373     InitBasicFS, Always, TestOutputList (
2374       [["touch"; "/a"];
2375        ["mkdir"; "/b"];
2376        ["touch"; "/b/c"];
2377        ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2378     InitBasicFS, Always, TestOutputList (
2379       [["mkdir_p"; "/a/b/c"];
2380        ["touch"; "/a/b/c/d"];
2381        ["find"; "/a/b/"]], ["c"; "c/d"])],
2382    "find all files and directories",
2383    "\
2384 This command lists out all files and directories, recursively,
2385 starting at C<directory>.  It is essentially equivalent to
2386 running the shell command C<find directory -print> but some
2387 post-processing happens on the output, described below.
2388
2389 This returns a list of strings I<without any prefix>.  Thus
2390 if the directory structure was:
2391
2392  /tmp/a
2393  /tmp/b
2394  /tmp/c/d
2395
2396 then the returned list from C<guestfs_find> C</tmp> would be
2397 4 elements:
2398
2399  a
2400  b
2401  c
2402  c/d
2403
2404 If C<directory> is not a directory, then this command returns
2405 an error.
2406
2407 The returned list is sorted.");
2408
2409   ("e2fsck_f", (RErr, [String "device"]), 108, [],
2410    [], (* lvresize tests this *)
2411    "check an ext2/ext3 filesystem",
2412    "\
2413 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2414 filesystem checker on C<device>, noninteractively (C<-p>),
2415 even if the filesystem appears to be clean (C<-f>).
2416
2417 This command is only needed because of C<guestfs_resize2fs>
2418 (q.v.).  Normally you should use C<guestfs_fsck>.");
2419
2420   ("sleep", (RErr, [Int "secs"]), 109, [],
2421    [InitNone, Always, TestRun (
2422     [["sleep"; "1"]])],
2423    "sleep for some seconds",
2424    "\
2425 Sleep for C<secs> seconds.");
2426
2427   ("ntfs_3g_probe", (RInt "status", [Bool "rw"; String "device"]), 110, [],
2428    [InitNone, Always, TestOutputInt (
2429       [["sfdiskM"; "/dev/sda"; ","];
2430        ["mkfs"; "ntfs"; "/dev/sda1"];
2431        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2432     InitNone, Always, TestOutputInt (
2433       [["sfdiskM"; "/dev/sda"; ","];
2434        ["mkfs"; "ext2"; "/dev/sda1"];
2435        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2436    "probe NTFS volume",
2437    "\
2438 This command runs the L<ntfs-3g.probe(8)> command which probes
2439 an NTFS C<device> for mountability.  (Not all NTFS volumes can
2440 be mounted read-write, and some cannot be mounted at all).
2441
2442 C<rw> is a boolean flag.  Set it to true if you want to test
2443 if the volume can be mounted read-write.  Set it to false if
2444 you want to test if the volume can be mounted read-only.
2445
2446 The return value is an integer which C<0> if the operation
2447 would succeed, or some non-zero value documented in the
2448 L<ntfs-3g.probe(8)> manual page.");
2449
2450   ("sh", (RString "output", [String "command"]), 111, [],
2451    [], (* XXX needs tests *)
2452    "run a command via the shell",
2453    "\
2454 This call runs a command from the guest filesystem via the
2455 guest's C</bin/sh>.
2456
2457 This is like C<guestfs_command>, but passes the command to:
2458
2459  /bin/sh -c \"command\"
2460
2461 Depending on the guest's shell, this usually results in
2462 wildcards being expanded, shell expressions being interpolated
2463 and so on.
2464
2465 All the provisos about C<guestfs_command> apply to this call.");
2466
2467   ("sh_lines", (RStringList "lines", [String "command"]), 112, [],
2468    [], (* XXX needs tests *)
2469    "run a command via the shell returning lines",
2470    "\
2471 This is the same as C<guestfs_sh>, but splits the result
2472 into a list of lines.
2473
2474 See also: C<guestfs_command_lines>");
2475
2476   ("glob_expand", (RStringList "paths", [String "pattern"]), 113, [],
2477    [InitBasicFS, Always, TestOutputList (
2478       [["mkdir_p"; "/a/b/c"];
2479        ["touch"; "/a/b/c/d"];
2480        ["touch"; "/a/b/c/e"];
2481        ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2482     InitBasicFS, Always, TestOutputList (
2483       [["mkdir_p"; "/a/b/c"];
2484        ["touch"; "/a/b/c/d"];
2485        ["touch"; "/a/b/c/e"];
2486        ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2487     InitBasicFS, Always, TestOutputList (
2488       [["mkdir_p"; "/a/b/c"];
2489        ["touch"; "/a/b/c/d"];
2490        ["touch"; "/a/b/c/e"];
2491        ["glob_expand"; "/a/*/x/*"]], [])],
2492    "expand a wildcard path",
2493    "\
2494 This command searches for all the pathnames matching
2495 C<pattern> according to the wildcard expansion rules
2496 used by the shell.
2497
2498 If no paths match, then this returns an empty list
2499 (note: not an error).
2500
2501 It is just a wrapper around the C L<glob(3)> function
2502 with flags C<GLOB_MARK|GLOB_BRACE>.
2503 See that manual page for more details.");
2504
2505   ("scrub_device", (RErr, [String "device"]), 114, [DangerWillRobinson],
2506    [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *)
2507       [["scrub_device"; "/dev/sdc"]])],
2508    "scrub (securely wipe) a device",
2509    "\
2510 This command writes patterns over C<device> to make data retrieval
2511 more difficult.
2512
2513 It is an interface to the L<scrub(1)> program.  See that
2514 manual page for more details.");
2515
2516   ("scrub_file", (RErr, [String "file"]), 115, [],
2517    [InitBasicFS, Always, TestRun (
2518       [["write_file"; "/file"; "content"; "0"];
2519        ["scrub_file"; "/file"]])],
2520    "scrub (securely wipe) a file",
2521    "\
2522 This command writes patterns over a file to make data retrieval
2523 more difficult.
2524
2525 The file is I<removed> after scrubbing.
2526
2527 It is an interface to the L<scrub(1)> program.  See that
2528 manual page for more details.");
2529
2530   ("scrub_freespace", (RErr, [String "dir"]), 116, [],
2531    [], (* XXX needs testing *)
2532    "scrub (securely wipe) free space",
2533    "\
2534 This command creates the directory C<dir> and then fills it
2535 with files until the filesystem is full, and scrubs the files
2536 as for C<guestfs_scrub_file>, and deletes them.
2537 The intention is to scrub any free space on the partition
2538 containing C<dir>.
2539
2540 It is an interface to the L<scrub(1)> program.  See that
2541 manual page for more details.");
2542
2543   ("mkdtemp", (RString "dir", [String "template"]), 117, [],
2544    [InitBasicFS, Always, TestRun (
2545       [["mkdir"; "/tmp"];
2546        ["mkdtemp"; "/tmp/tmpXXXXXX"]])],
2547    "create a temporary directory",
2548    "\
2549 This command creates a temporary directory.  The
2550 C<template> parameter should be a full pathname for the
2551 temporary directory name with the final six characters being
2552 \"XXXXXX\".
2553
2554 For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
2555 the second one being suitable for Windows filesystems.
2556
2557 The name of the temporary directory that was created
2558 is returned.
2559
2560 The temporary directory is created with mode 0700
2561 and is owned by root.
2562
2563 The caller is responsible for deleting the temporary
2564 directory and its contents after use.
2565
2566 See also: L<mkdtemp(3)>");
2567
2568   ("wc_l", (RInt "lines", [String "path"]), 118, [],
2569    [InitBasicFS, Always, TestOutputInt (
2570       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2571        ["wc_l"; "/10klines"]], 10000)],
2572    "count lines in a file",
2573    "\
2574 This command counts the lines in a file, using the
2575 C<wc -l> external command.");
2576
2577   ("wc_w", (RInt "words", [String "path"]), 119, [],
2578    [InitBasicFS, Always, TestOutputInt (
2579       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2580        ["wc_w"; "/10klines"]], 10000)],
2581    "count words in a file",
2582    "\
2583 This command counts the words in a file, using the
2584 C<wc -w> external command.");
2585
2586   ("wc_c", (RInt "chars", [String "path"]), 120, [],
2587    [InitBasicFS, Always, TestOutputInt (
2588       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2589        ["wc_c"; "/100kallspaces"]], 102400)],
2590    "count characters in a file",
2591    "\
2592 This command counts the characters in a file, using the
2593 C<wc -c> external command.");
2594
2595   ("head", (RStringList "lines", [String "path"]), 121, [ProtocolLimitWarning],
2596    [InitBasicFS, Always, TestOutputList (
2597       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2598        ["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])],
2599    "return first 10 lines of a file",
2600    "\
2601 This command returns up to the first 10 lines of a file as
2602 a list of strings.");
2603
2604   ("head_n", (RStringList "lines", [Int "nrlines"; String "path"]), 122, [ProtocolLimitWarning],
2605    [InitBasicFS, Always, TestOutputList (
2606       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2607        ["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
2608     InitBasicFS, Always, TestOutputList (
2609       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2610        ["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
2611     InitBasicFS, Always, TestOutputList (
2612       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2613        ["head_n"; "0"; "/10klines"]], [])],
2614    "return first N lines of a file",
2615    "\
2616 If the parameter C<nrlines> is a positive number, this returns the first
2617 C<nrlines> lines of the file C<path>.
2618
2619 If the parameter C<nrlines> is a negative number, this returns lines
2620 from the file C<path>, excluding the last C<nrlines> lines.
2621
2622 If the parameter C<nrlines> is zero, this returns an empty list.");
2623
2624   ("tail", (RStringList "lines", [String "path"]), 123, [ProtocolLimitWarning],
2625    [InitBasicFS, Always, TestOutputList (
2626       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2627        ["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])],
2628    "return last 10 lines of a file",
2629    "\
2630 This command returns up to the last 10 lines of a file as
2631 a list of strings.");
2632
2633   ("tail_n", (RStringList "lines", [Int "nrlines"; String "path"]), 124, [ProtocolLimitWarning],
2634    [InitBasicFS, Always, TestOutputList (
2635       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2636        ["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
2637     InitBasicFS, Always, TestOutputList (
2638       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2639        ["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
2640     InitBasicFS, Always, TestOutputList (
2641       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2642        ["tail_n"; "0"; "/10klines"]], [])],
2643    "return last N lines of a file",
2644    "\
2645 If the parameter C<nrlines> is a positive number, this returns the last
2646 C<nrlines> lines of the file C<path>.
2647
2648 If the parameter C<nrlines> is a negative number, this returns lines
2649 from the file C<path>, starting with the C<-nrlines>th line.
2650
2651 If the parameter C<nrlines> is zero, this returns an empty list.");
2652
2653   ("df", (RString "output", []), 125, [],
2654    [], (* XXX Tricky to test because it depends on the exact format
2655         * of the 'df' command and other imponderables.
2656         *)
2657    "report file system disk space usage",
2658    "\
2659 This command runs the C<df> command to report disk space used.
2660
2661 This command is mostly useful for interactive sessions.  It
2662 is I<not> intended that you try to parse the output string.
2663 Use C<statvfs> from programs.");
2664
2665   ("df_h", (RString "output", []), 126, [],
2666    [], (* XXX Tricky to test because it depends on the exact format
2667         * of the 'df' command and other imponderables.
2668         *)
2669    "report file system disk space usage (human readable)",
2670    "\
2671 This command runs the C<df -h> command to report disk space used
2672 in human-readable format.
2673
2674 This command is mostly useful for interactive sessions.  It
2675 is I<not> intended that you try to parse the output string.
2676 Use C<statvfs> from programs.");
2677
2678   ("du", (RInt64 "sizekb", [String "path"]), 127, [],
2679    [InitBasicFS, Always, TestOutputInt (
2680       [["mkdir"; "/p"];
2681        ["du"; "/p"]], 1 (* ie. 1 block, so depends on ext3 blocksize *))],
2682    "estimate file space usage",
2683    "\
2684 This command runs the C<du -s> command to estimate file space
2685 usage for C<path>.
2686
2687 C<path> can be a file or a directory.  If C<path> is a directory
2688 then the estimate includes the contents of the directory and all
2689 subdirectories (recursively).
2690
2691 The result is the estimated size in I<kilobytes>
2692 (ie. units of 1024 bytes).");
2693
2694   ("initrd_list", (RStringList "filenames", [String "path"]), 128, [],
2695    [InitBasicFS, Always, TestOutputList (
2696       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2697        ["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3"])],
2698    "list files in an initrd",
2699    "\
2700 This command lists out files contained in an initrd.
2701
2702 The files are listed without any initial C</> character.  The
2703 files are listed in the order they appear (not necessarily
2704 alphabetical).  Directory names are listed as separate items.
2705
2706 Old Linux kernels (2.4 and earlier) used a compressed ext2
2707 filesystem as initrd.  We I<only> support the newer initramfs
2708 format (compressed cpio files).");
2709
2710   ("mount_loop", (RErr, [String "file"; String "mountpoint"]), 129, [],
2711    [],
2712    "mount a file using the loop device",
2713    "\
2714 This command lets you mount C<file> (a filesystem image
2715 in a file) on a mount point.  It is entirely equivalent to
2716 the command C<mount -o loop file mountpoint>.");
2717
2718   ("mkswap", (RErr, [String "device"]), 130, [],
2719    [InitEmpty, Always, TestRun (
2720       [["sfdiskM"; "/dev/sda"; ","];
2721        ["mkswap"; "/dev/sda1"]])],
2722    "create a swap partition",
2723    "\
2724 Create a swap partition on C<device>.");
2725
2726   ("mkswap_L", (RErr, [String "label"; String "device"]), 131, [],
2727    [InitEmpty, Always, TestRun (
2728       [["sfdiskM"; "/dev/sda"; ","];
2729        ["mkswap_L"; "hello"; "/dev/sda1"]])],
2730    "create a swap partition with a label",
2731    "\
2732 Create a swap partition on C<device> with label C<label>.");
2733
2734   ("mkswap_U", (RErr, [String "uuid"; String "device"]), 132, [],
2735    [InitEmpty, Always, TestRun (
2736       [["sfdiskM"; "/dev/sda"; ","];
2737        ["mkswap_U"; "a3a61220-882b-4f61-89f4-cf24dcc7297d"; "/dev/sda1"]])],
2738    "create a swap partition with an explicit UUID",
2739    "\
2740 Create a swap partition on C<device> with UUID C<uuid>.");
2741
2742   ("mknod", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; String "path"]), 133, [],
2743    [InitBasicFS, Always, TestOutputStruct (
2744       [["mknod"; "0o10777"; "0"; "0"; "/node"];
2745        (* NB: default umask 022 means 0777 -> 0755 in these tests *)
2746        ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)]);
2747     InitBasicFS, Always, TestOutputStruct (
2748       [["mknod"; "0o60777"; "66"; "99"; "/node"];
2749        ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
2750    "make block, character or FIFO devices",
2751    "\
2752 This call creates block or character special devices, or
2753 named pipes (FIFOs).
2754
2755 The C<mode> parameter should be the mode, using the standard
2756 constants.  C<devmajor> and C<devminor> are the
2757 device major and minor numbers, only used when creating block
2758 and character special devices.");
2759
2760   ("mkfifo", (RErr, [Int "mode"; String "path"]), 134, [],
2761    [InitBasicFS, Always, TestOutputStruct (
2762       [["mkfifo"; "0o777"; "/node"];
2763        ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)])],
2764    "make FIFO (named pipe)",
2765    "\
2766 This call creates a FIFO (named pipe) called C<path> with
2767 mode C<mode>.  It is just a convenient wrapper around
2768 C<guestfs_mknod>.");
2769
2770   ("mknod_b", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; String "path"]), 135, [],
2771    [InitBasicFS, Always, TestOutputStruct (
2772       [["mknod_b"; "0o777"; "99"; "66"; "/node"];
2773        ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
2774    "make block device node",
2775    "\
2776 This call creates a block device node called C<path> with
2777 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
2778 It is just a convenient wrapper around C<guestfs_mknod>.");
2779
2780   ("mknod_c", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; String "path"]), 136, [],
2781    [InitBasicFS, Always, TestOutputStruct (
2782       [["mknod_c"; "0o777"; "99"; "66"; "/node"];
2783        ["stat"; "/node"]], [CompareWithInt ("mode", 0o20755)])],
2784    "make char device node",
2785    "\
2786 This call creates a char device node called C<path> with
2787 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
2788 It is just a convenient wrapper around C<guestfs_mknod>.");
2789
2790   ("umask", (RInt "oldmask", [Int "mask"]), 137, [],
2791    [], (* XXX umask is one of those stateful things that we should
2792         * reset between each test.
2793         *)
2794    "set file mode creation mask (umask)",
2795    "\
2796 This function sets the mask used for creating new files and
2797 device nodes to C<mask & 0777>.
2798
2799 Typical umask values would be C<022> which creates new files
2800 with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and
2801 C<002> which creates new files with permissions like
2802 \"-rw-rw-r--\" or \"-rwxrwxr-x\".
2803
2804 The default umask is C<022>.  This is important because it
2805 means that directories and device nodes will be created with
2806 C<0644> or C<0755> mode even if you specify C<0777>.
2807
2808 See also L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
2809
2810 This call returns the previous umask.");
2811
2812   ("readdir", (RStructList ("entries", "dirent"), [String "dir"]), 138, [],
2813    [],
2814    "read directories entries",
2815    "\
2816 This returns the list of directory entries in directory C<dir>.
2817
2818 All entries in the directory are returned, including C<.> and
2819 C<..>.  The entries are I<not> sorted, but returned in the same
2820 order as the underlying filesystem.
2821
2822 This function is primarily intended for use by programs.  To
2823 get a simple list of names, use C<guestfs_ls>.  To get a printable
2824 directory for human consumption, use C<guestfs_ll>.");
2825
2826   ("sfdiskM", (RErr, [String "device"; StringList "lines"]), 139, [DangerWillRobinson],
2827    [],
2828    "create partitions on a block device",
2829    "\
2830 This is a simplified interface to the C<guestfs_sfdisk>
2831 command, where partition sizes are specified in megabytes
2832 only (rounded to the nearest cylinder) and you don't need
2833 to specify the cyls, heads and sectors parameters which
2834 were rarely if ever used anyway.
2835
2836 See also C<guestfs_sfdisk> and the L<sfdisk(8)> manpage.");
2837
2838 ]
2839
2840 let all_functions = non_daemon_functions @ daemon_functions
2841
2842 (* In some places we want the functions to be displayed sorted
2843  * alphabetically, so this is useful:
2844  *)
2845 let all_functions_sorted =
2846   List.sort (fun (n1,_,_,_,_,_,_) (n2,_,_,_,_,_,_) ->
2847                compare n1 n2) all_functions
2848
2849 (* Field types for structures. *)
2850 type field =
2851   | FChar                       (* C 'char' (really, a 7 bit byte). *)
2852   | FString                     (* nul-terminated ASCII string. *)
2853   | FUInt32
2854   | FInt32
2855   | FUInt64
2856   | FInt64
2857   | FBytes                      (* Any int measure that counts bytes. *)
2858   | FUUID                       (* 32 bytes long, NOT nul-terminated. *)
2859   | FOptPercent                 (* [0..100], or -1 meaning "not present". *)
2860
2861 (* Because we generate extra parsing code for LVM command line tools,
2862  * we have to pull out the LVM columns separately here.
2863  *)
2864 let lvm_pv_cols = [
2865   "pv_name", FString;
2866   "pv_uuid", FUUID;
2867   "pv_fmt", FString;
2868   "pv_size", FBytes;
2869   "dev_size", FBytes;
2870   "pv_free", FBytes;
2871   "pv_used", FBytes;
2872   "pv_attr", FString (* XXX *);
2873   "pv_pe_count", FInt64;
2874   "pv_pe_alloc_count", FInt64;
2875   "pv_tags", FString;
2876   "pe_start", FBytes;
2877   "pv_mda_count", FInt64;
2878   "pv_mda_free", FBytes;
2879   (* Not in Fedora 10:
2880      "pv_mda_size", FBytes;
2881   *)
2882 ]
2883 let lvm_vg_cols = [
2884   "vg_name", FString;
2885   "vg_uuid", FUUID;
2886   "vg_fmt", FString;
2887   "vg_attr", FString (* XXX *);
2888   "vg_size", FBytes;
2889   "vg_free", FBytes;
2890   "vg_sysid", FString;
2891   "vg_extent_size", FBytes;
2892   "vg_extent_count", FInt64;
2893   "vg_free_count", FInt64;
2894   "max_lv", FInt64;
2895   "max_pv", FInt64;
2896   "pv_count", FInt64;
2897   "lv_count", FInt64;
2898   "snap_count", FInt64;
2899   "vg_seqno", FInt64;
2900   "vg_tags", FString;
2901   "vg_mda_count", FInt64;
2902   "vg_mda_free", FBytes;
2903   (* Not in Fedora 10:
2904      "vg_mda_size", FBytes;
2905   *)
2906 ]
2907 let lvm_lv_cols = [
2908   "lv_name", FString;
2909   "lv_uuid", FUUID;
2910   "lv_attr", FString (* XXX *);
2911   "lv_major", FInt64;
2912   "lv_minor", FInt64;
2913   "lv_kernel_major", FInt64;
2914   "lv_kernel_minor", FInt64;
2915   "lv_size", FBytes;
2916   "seg_count", FInt64;
2917   "origin", FString;
2918   "snap_percent", FOptPercent;
2919   "copy_percent", FOptPercent;
2920   "move_pv", FString;
2921   "lv_tags", FString;
2922   "mirror_log", FString;
2923   "modules", FString;
2924 ]
2925
2926 (* Names and fields in all structures (in RStruct and RStructList)
2927  * that we support.
2928  *)
2929 let structs = [
2930   (* The old RIntBool return type, only ever used for aug_defnode.  Do
2931    * not use this struct in any new code.
2932    *)
2933   "int_bool", [
2934     "i", FInt32;                (* for historical compatibility *)
2935     "b", FInt32;                (* for historical compatibility *)
2936   ];
2937
2938   (* LVM PVs, VGs, LVs. *)
2939   "lvm_pv", lvm_pv_cols;
2940   "lvm_vg", lvm_vg_cols;
2941   "lvm_lv", lvm_lv_cols;
2942
2943   (* Column names and types from stat structures.
2944    * NB. Can't use things like 'st_atime' because glibc header files
2945    * define some of these as macros.  Ugh.
2946    *)
2947   "stat", [
2948     "dev", FInt64;
2949     "ino", FInt64;
2950     "mode", FInt64;
2951     "nlink", FInt64;
2952     "uid", FInt64;
2953     "gid", FInt64;
2954     "rdev", FInt64;
2955     "size", FInt64;
2956     "blksize", FInt64;
2957     "blocks", FInt64;
2958     "atime", FInt64;
2959     "mtime", FInt64;
2960     "ctime", FInt64;
2961   ];
2962   "statvfs", [
2963     "bsize", FInt64;
2964     "frsize", FInt64;
2965     "blocks", FInt64;
2966     "bfree", FInt64;
2967     "bavail", FInt64;
2968     "files", FInt64;
2969     "ffree", FInt64;
2970     "favail", FInt64;
2971     "fsid", FInt64;
2972     "flag", FInt64;
2973     "namemax", FInt64;
2974   ];
2975
2976   (* Column names in dirent structure. *)
2977   "dirent", [
2978     "ino", FInt64;
2979     (* 'b' 'c' 'd' 'f' (FIFO) 'l' 'r' (regular file) 's' 'u' '?' *)
2980     "ftyp", FChar;
2981     "name", FString;
2982   ];
2983
2984   (* Version numbers. *)
2985   "version", [
2986     "major", FInt64;
2987     "minor", FInt64;
2988     "release", FInt64;
2989     "extra", FString;
2990   ];
2991 ] (* end of structs *)
2992
2993 (* Ugh, Java has to be different ..
2994  * These names are also used by the Haskell bindings.
2995  *)
2996 let java_structs = [
2997   "int_bool", "IntBool";
2998   "lvm_pv", "PV";
2999   "lvm_vg", "VG";
3000   "lvm_lv", "LV";
3001   "stat", "Stat";
3002   "statvfs", "StatVFS";
3003   "dirent", "Dirent";
3004   "version", "Version";
3005 ]
3006
3007 (* Used for testing language bindings. *)
3008 type callt =
3009   | CallString of string
3010   | CallOptString of string option
3011   | CallStringList of string list
3012   | CallInt of int
3013   | CallBool of bool
3014
3015 (* Used to memoize the result of pod2text. *)
3016 let pod2text_memo_filename = "src/.pod2text.data"
3017 let pod2text_memo : ((int * string * string), string list) Hashtbl.t =
3018   try
3019     let chan = open_in pod2text_memo_filename in
3020     let v = input_value chan in
3021     close_in chan;
3022     v
3023   with
3024     _ -> Hashtbl.create 13
3025
3026 (* Useful functions.
3027  * Note we don't want to use any external OCaml libraries which
3028  * makes this a bit harder than it should be.
3029  *)
3030 let failwithf fs = ksprintf failwith fs
3031
3032 let replace_char s c1 c2 =
3033   let s2 = String.copy s in
3034   let r = ref false in
3035   for i = 0 to String.length s2 - 1 do
3036     if String.unsafe_get s2 i = c1 then (
3037       String.unsafe_set s2 i c2;
3038       r := true
3039     )
3040   done;
3041   if not !r then s else s2
3042
3043 let isspace c =
3044   c = ' '
3045   (* || c = '\f' *) || c = '\n' || c = '\r' || c = '\t' (* || c = '\v' *)
3046
3047 let triml ?(test = isspace) str =
3048   let i = ref 0 in
3049   let n = ref (String.length str) in
3050   while !n > 0 && test str.[!i]; do
3051     decr n;
3052     incr i
3053   done;
3054   if !i = 0 then str
3055   else String.sub str !i !n
3056
3057 let trimr ?(test = isspace) str =
3058   let n = ref (String.length str) in
3059   while !n > 0 && test str.[!n-1]; do
3060     decr n
3061   done;
3062   if !n = String.length str then str
3063   else String.sub str 0 !n
3064
3065 let trim ?(test = isspace) str =
3066   trimr ~test (triml ~test str)
3067
3068 let rec find s sub =
3069   let len = String.length s in
3070   let sublen = String.length sub in
3071   let rec loop i =
3072     if i <= len-sublen then (
3073       let rec loop2 j =
3074         if j < sublen then (
3075           if s.[i+j] = sub.[j] then loop2 (j+1)
3076           else -1
3077         ) else
3078           i (* found *)
3079       in
3080       let r = loop2 0 in
3081       if r = -1 then loop (i+1) else r
3082     ) else
3083       -1 (* not found *)
3084   in
3085   loop 0
3086
3087 let rec replace_str s s1 s2 =
3088   let len = String.length s in
3089   let sublen = String.length s1 in
3090   let i = find s s1 in
3091   if i = -1 then s
3092   else (
3093     let s' = String.sub s 0 i in
3094     let s'' = String.sub s (i+sublen) (len-i-sublen) in
3095     s' ^ s2 ^ replace_str s'' s1 s2
3096   )
3097
3098 let rec string_split sep str =
3099   let len = String.length str in
3100   let seplen = String.length sep in
3101   let i = find str sep in
3102   if i = -1 then [str]
3103   else (
3104     let s' = String.sub str 0 i in
3105     let s'' = String.sub str (i+seplen) (len-i-seplen) in
3106     s' :: string_split sep s''
3107   )
3108
3109 let files_equal n1 n2 =
3110   let cmd = sprintf "cmp -s %s %s" (Filename.quote n1) (Filename.quote n2) in
3111   match Sys.command cmd with
3112   | 0 -> true
3113   | 1 -> false
3114   | i -> failwithf "%s: failed with error code %d" cmd i
3115
3116 let rec find_map f = function
3117   | [] -> raise Not_found
3118   | x :: xs ->
3119       match f x with
3120       | Some y -> y
3121       | None -> find_map f xs
3122
3123 let iteri f xs =
3124   let rec loop i = function
3125     | [] -> ()
3126     | x :: xs -> f i x; loop (i+1) xs
3127   in
3128   loop 0 xs
3129
3130 let mapi f xs =
3131   let rec loop i = function
3132     | [] -> []
3133     | x :: xs -> let r = f i x in r :: loop (i+1) xs
3134   in
3135   loop 0 xs
3136
3137 let name_of_argt = function
3138   | String n | OptString n | StringList n | Bool n | Int n
3139   | FileIn n | FileOut n -> n
3140
3141 let java_name_of_struct typ =
3142   try List.assoc typ java_structs
3143   with Not_found ->
3144     failwithf
3145       "java_name_of_struct: no java_structs entry corresponding to %s" typ
3146
3147 let cols_of_struct typ =
3148   try List.assoc typ structs
3149   with Not_found ->
3150     failwithf "cols_of_struct: unknown struct %s" typ
3151
3152 let seq_of_test = function
3153   | TestRun s | TestOutput (s, _) | TestOutputList (s, _)
3154   | TestOutputListOfDevices (s, _)
3155   | TestOutputInt (s, _) | TestOutputTrue s | TestOutputFalse s
3156   | TestOutputLength (s, _) | TestOutputStruct (s, _)
3157   | TestLastFail s -> s
3158
3159 (* Check function names etc. for consistency. *)
3160 let check_functions () =
3161   let contains_uppercase str =
3162     let len = String.length str in
3163     let rec loop i =
3164       if i >= len then false
3165       else (
3166         let c = str.[i] in
3167         if c >= 'A' && c <= 'Z' then true
3168         else loop (i+1)
3169       )
3170     in
3171     loop 0
3172   in
3173
3174   (* Check function names. *)
3175   List.iter (
3176     fun (name, _, _, _, _, _, _) ->
3177       if String.length name >= 7 && String.sub name 0 7 = "guestfs" then
3178         failwithf "function name %s does not need 'guestfs' prefix" name;
3179       if name = "" then
3180         failwithf "function name is empty";
3181       if name.[0] < 'a' || name.[0] > 'z' then
3182         failwithf "function name %s must start with lowercase a-z" name;
3183       if String.contains name '-' then
3184         failwithf "function name %s should not contain '-', use '_' instead."
3185           name
3186   ) all_functions;
3187
3188   (* Check function parameter/return names. *)
3189   List.iter (
3190     fun (name, style, _, _, _, _, _) ->
3191       let check_arg_ret_name n =
3192         if contains_uppercase n then
3193           failwithf "%s param/ret %s should not contain uppercase chars"
3194             name n;
3195         if String.contains n '-' || String.contains n '_' then
3196           failwithf "%s param/ret %s should not contain '-' or '_'"
3197             name n;
3198         if n = "value" then
3199           failwithf "%s has a param/ret called 'value', which causes conflicts in the OCaml bindings, use something like 'val' or a more descriptive name" name;
3200         if n = "int" || n = "char" || n = "short" || n = "long" then
3201           failwithf "%s has a param/ret which conflicts with a C type (eg. 'int', 'char' etc.)" name;
3202         if n = "i" || n = "n" then
3203           failwithf "%s has a param/ret called 'i' or 'n', which will cause some conflicts in the generated code" name;
3204         if n = "argv" || n = "args" then
3205           failwithf "%s has a param/ret called 'argv' or 'args', which will cause some conflicts in the generated code" name
3206       in
3207
3208       (match fst style with
3209        | RErr -> ()
3210        | RInt n | RInt64 n | RBool n | RConstString n | RString n
3211        | RStringList n | RStruct (n, _) | RStructList (n, _)
3212        | RHashtable n ->
3213            check_arg_ret_name n
3214       );
3215       List.iter (fun arg -> check_arg_ret_name (name_of_argt arg)) (snd style)
3216   ) all_functions;
3217
3218   (* Check short descriptions. *)
3219   List.iter (
3220     fun (name, _, _, _, _, shortdesc, _) ->
3221       if shortdesc.[0] <> Char.lowercase shortdesc.[0] then
3222         failwithf "short description of %s should begin with lowercase." name;
3223       let c = shortdesc.[String.length shortdesc-1] in
3224       if c = '\n' || c = '.' then
3225         failwithf "short description of %s should not end with . or \\n." name
3226   ) all_functions;
3227
3228   (* Check long dscriptions. *)
3229   List.iter (
3230     fun (name, _, _, _, _, _, longdesc) ->
3231       if longdesc.[String.length longdesc-1] = '\n' then
3232         failwithf "long description of %s should not end with \\n." name
3233   ) all_functions;
3234
3235   (* Check proc_nrs. *)
3236   List.iter (
3237     fun (name, _, proc_nr, _, _, _, _) ->
3238       if proc_nr <= 0 then
3239         failwithf "daemon function %s should have proc_nr > 0" name
3240   ) daemon_functions;
3241
3242   List.iter (
3243     fun (name, _, proc_nr, _, _, _, _) ->
3244       if proc_nr <> -1 then
3245         failwithf "non-daemon function %s should have proc_nr -1" name
3246   ) non_daemon_functions;
3247
3248   let proc_nrs =
3249     List.map (fun (name, _, proc_nr, _, _, _, _) -> name, proc_nr)
3250       daemon_functions in
3251   let proc_nrs =
3252     List.sort (fun (_,nr1) (_,nr2) -> compare nr1 nr2) proc_nrs in
3253   let rec loop = function
3254     | [] -> ()
3255     | [_] -> ()
3256     | (name1,nr1) :: ((name2,nr2) :: _ as rest) when nr1 < nr2 ->
3257         loop rest
3258     | (name1,nr1) :: (name2,nr2) :: _ ->
3259         failwithf "%s and %s have conflicting procedure numbers (%d, %d)"
3260           name1 name2 nr1 nr2
3261   in
3262   loop proc_nrs;
3263
3264   (* Check tests. *)
3265   List.iter (
3266     function
3267       (* Ignore functions that have no tests.  We generate a
3268        * warning when the user does 'make check' instead.
3269        *)
3270     | name, _, _, _, [], _, _ -> ()
3271     | name, _, _, _, tests, _, _ ->
3272         let funcs =
3273           List.map (
3274             fun (_, _, test) ->
3275               match seq_of_test test with
3276               | [] ->
3277                   failwithf "%s has a test containing an empty sequence" name
3278               | cmds -> List.map List.hd cmds
3279           ) tests in
3280         let funcs = List.flatten funcs in
3281
3282         let tested = List.mem name funcs in
3283
3284         if not tested then
3285           failwithf "function %s has tests but does not test itself" name
3286   ) all_functions
3287
3288 (* 'pr' prints to the current output file. *)
3289 let chan = ref stdout
3290 let pr fs = ksprintf (output_string !chan) fs
3291
3292 (* Generate a header block in a number of standard styles. *)
3293 type comment_style = CStyle | HashStyle | OCamlStyle | HaskellStyle
3294 type license = GPLv2 | LGPLv2
3295
3296 let generate_header comment license =
3297   let c = match comment with
3298     | CStyle ->     pr "/* "; " *"
3299     | HashStyle ->  pr "# ";  "#"
3300     | OCamlStyle -> pr "(* "; " *"
3301     | HaskellStyle -> pr "{- "; "  " in
3302   pr "libguestfs generated file\n";
3303   pr "%s WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.\n" c;
3304   pr "%s ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.\n" c;
3305   pr "%s\n" c;
3306   pr "%s Copyright (C) 2009 Red Hat Inc.\n" c;
3307   pr "%s\n" c;
3308   (match license with
3309    | GPLv2 ->
3310        pr "%s This program is free software; you can redistribute it and/or modify\n" c;
3311        pr "%s it under the terms of the GNU General Public License as published by\n" c;
3312        pr "%s the Free Software Foundation; either version 2 of the License, or\n" c;
3313        pr "%s (at your option) any later version.\n" c;
3314        pr "%s\n" c;
3315        pr "%s This program is distributed in the hope that it will be useful,\n" c;
3316        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
3317        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n" c;
3318        pr "%s GNU General Public License for more details.\n" c;
3319        pr "%s\n" c;
3320        pr "%s You should have received a copy of the GNU General Public License along\n" c;
3321        pr "%s with this program; if not, write to the Free Software Foundation, Inc.,\n" c;
3322        pr "%s 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n" c;
3323
3324    | LGPLv2 ->
3325        pr "%s This library is free software; you can redistribute it and/or\n" c;
3326        pr "%s modify it under the terms of the GNU Lesser General Public\n" c;
3327        pr "%s License as published by the Free Software Foundation; either\n" c;
3328        pr "%s version 2 of the License, or (at your option) any later version.\n" c;
3329        pr "%s\n" c;
3330        pr "%s This library is distributed in the hope that it will be useful,\n" c;
3331        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
3332        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\n" c;
3333        pr "%s Lesser General Public License for more details.\n" c;
3334        pr "%s\n" c;
3335        pr "%s You should have received a copy of the GNU Lesser General Public\n" c;
3336        pr "%s License along with this library; if not, write to the Free Software\n" c;
3337        pr "%s Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA\n" c;
3338   );
3339   (match comment with
3340    | CStyle -> pr " */\n"
3341    | HashStyle -> ()
3342    | OCamlStyle -> pr " *)\n"
3343    | HaskellStyle -> pr "-}\n"
3344   );
3345   pr "\n"
3346
3347 (* Start of main code generation functions below this line. *)
3348
3349 (* Generate the pod documentation for the C API. *)
3350 let rec generate_actions_pod () =
3351   List.iter (
3352     fun (shortname, style, _, flags, _, _, longdesc) ->
3353       if not (List.mem NotInDocs flags) then (
3354         let name = "guestfs_" ^ shortname in
3355         pr "=head2 %s\n\n" name;
3356         pr " ";
3357         generate_prototype ~extern:false ~handle:"handle" name style;
3358         pr "\n\n";
3359         pr "%s\n\n" longdesc;
3360         (match fst style with
3361          | RErr ->
3362              pr "This function returns 0 on success or -1 on error.\n\n"
3363          | RInt _ ->
3364              pr "On error this function returns -1.\n\n"
3365          | RInt64 _ ->
3366              pr "On error this function returns -1.\n\n"
3367          | RBool _ ->
3368              pr "This function returns a C truth value on success or -1 on error.\n\n"
3369          | RConstString _ ->
3370              pr "This function returns a string, or NULL on error.
3371 The string is owned by the guest handle and must I<not> be freed.\n\n"
3372          | RString _ ->
3373              pr "This function returns a string, or NULL on error.
3374 I<The caller must free the returned string after use>.\n\n"
3375          | RStringList _ ->
3376              pr "This function returns a NULL-terminated array of strings
3377 (like L<environ(3)>), or NULL if there was an error.
3378 I<The caller must free the strings and the array after use>.\n\n"
3379          | RStruct (_, typ) ->
3380              pr "This function returns a C<struct guestfs_%s *>,
3381 or NULL if there was an error.
3382 I<The caller must call C<guestfs_free_%s> after use>.\n\n" typ typ
3383          | RStructList (_, typ) ->
3384              pr "This function returns a C<struct guestfs_%s_list *>
3385 (see E<lt>guestfs-structs.hE<gt>),
3386 or NULL if there was an error.
3387 I<The caller must call C<guestfs_free_%s_list> after use>.\n\n" typ typ
3388          | RHashtable _ ->
3389              pr "This function returns a NULL-terminated array of
3390 strings, or NULL if there was an error.
3391 The array of strings will always have length C<2n+1>, where
3392 C<n> keys and values alternate, followed by the trailing NULL entry.
3393 I<The caller must free the strings and the array after use>.\n\n"
3394         );
3395         if List.mem ProtocolLimitWarning flags then
3396           pr "%s\n\n" protocol_limit_warning;
3397         if List.mem DangerWillRobinson flags then
3398           pr "%s\n\n" danger_will_robinson
3399       )
3400   ) all_functions_sorted
3401
3402 and generate_structs_pod () =
3403   (* Structs documentation. *)
3404   List.iter (
3405     fun (typ, cols) ->
3406       pr "=head2 guestfs_%s\n" typ;
3407       pr "\n";
3408       pr " struct guestfs_%s {\n" typ;
3409       List.iter (
3410         function
3411         | name, FChar -> pr "   char %s;\n" name
3412         | name, FUInt32 -> pr "   uint32_t %s;\n" name
3413         | name, FInt32 -> pr "   int32_t %s;\n" name
3414         | name, (FUInt64|FBytes) -> pr "   uint64_t %s;\n" name
3415         | name, FInt64 -> pr "   int64_t %s;\n" name
3416         | name, FString -> pr "   char *%s;\n" name
3417         | name, FUUID ->
3418             pr "   /* The next field is NOT nul-terminated, be careful when printing it: */\n";
3419             pr "   char %s[32];\n" name
3420         | name, FOptPercent ->
3421             pr "   /* The next field is [0..100] or -1 meaning 'not present': */\n";
3422             pr "   float %s;\n" name
3423       ) cols;
3424       pr " };\n";
3425       pr " \n";
3426       pr " struct guestfs_%s_list {\n" typ;
3427       pr "   uint32_t len; /* Number of elements in list. */\n";
3428       pr "   struct guestfs_%s *val; /* Elements. */\n" typ;
3429       pr " };\n";
3430       pr " \n";
3431       pr " void guestfs_free_%s (struct guestfs_free_%s *);\n" typ typ;
3432       pr " void guestfs_free_%s_list (struct guestfs_free_%s_list *);\n"
3433         typ typ;
3434       pr "\n"
3435   ) structs
3436
3437 (* Generate the protocol (XDR) file, 'guestfs_protocol.x' and
3438  * indirectly 'guestfs_protocol.h' and 'guestfs_protocol.c'.
3439  *
3440  * We have to use an underscore instead of a dash because otherwise
3441  * rpcgen generates incorrect code.
3442  *
3443  * This header is NOT exported to clients, but see also generate_structs_h.
3444  *)
3445 and generate_xdr () =
3446   generate_header CStyle LGPLv2;
3447
3448   (* This has to be defined to get around a limitation in Sun's rpcgen. *)
3449   pr "typedef string str<>;\n";
3450   pr "\n";
3451
3452   (* Internal structures. *)
3453   List.iter (
3454     function
3455     | typ, cols ->
3456         pr "struct guestfs_int_%s {\n" typ;
3457         List.iter (function
3458                    | name, FChar -> pr "  char %s;\n" name
3459                    | name, FString -> pr "  string %s<>;\n" name
3460                    | name, FUUID -> pr "  opaque %s[32];\n" name
3461                    | name, (FInt32|FUInt32) -> pr "  int %s;\n" name
3462                    | name, (FInt64|FUInt64|FBytes) -> pr "  hyper %s;\n" name
3463                    | name, FOptPercent -> pr "  float %s;\n" name
3464                   ) cols;
3465         pr "};\n";
3466         pr "\n";
3467         pr "typedef struct guestfs_int_%s guestfs_int_%s_list<>;\n" typ typ;
3468         pr "\n";
3469   ) structs;
3470
3471   List.iter (
3472     fun (shortname, style, _, _, _, _, _) ->
3473       let name = "guestfs_" ^ shortname in
3474
3475       (match snd style with
3476        | [] -> ()
3477        | args ->
3478            pr "struct %s_args {\n" name;
3479            List.iter (
3480              function
3481              | String n -> pr "  string %s<>;\n" n
3482              | OptString n -> pr "  str *%s;\n" n
3483              | StringList n -> pr "  str %s<>;\n" n
3484              | Bool n -> pr "  bool %s;\n" n
3485              | Int n -> pr "  int %s;\n" n
3486              | FileIn _ | FileOut _ -> ()
3487            ) args;
3488            pr "};\n\n"
3489       );
3490       (match fst style with
3491        | RErr -> ()
3492        | RInt n ->
3493            pr "struct %s_ret {\n" name;
3494            pr "  int %s;\n" n;
3495            pr "};\n\n"
3496        | RInt64 n ->
3497            pr "struct %s_ret {\n" name;
3498            pr "  hyper %s;\n" n;
3499            pr "};\n\n"
3500        | RBool n ->
3501            pr "struct %s_ret {\n" name;
3502            pr "  bool %s;\n" n;
3503            pr "};\n\n"
3504        | RConstString _ ->
3505            failwithf "RConstString cannot be returned from a daemon function"
3506        | RString n ->
3507            pr "struct %s_ret {\n" name;
3508            pr "  string %s<>;\n" n;
3509            pr "};\n\n"
3510        | RStringList n ->
3511            pr "struct %s_ret {\n" name;
3512            pr "  str %s<>;\n" n;
3513            pr "};\n\n"
3514        | RStruct (n, typ) ->
3515            pr "struct %s_ret {\n" name;
3516            pr "  guestfs_int_%s %s;\n" typ n;
3517            pr "};\n\n"
3518        | RStructList (n, typ) ->
3519            pr "struct %s_ret {\n" name;
3520            pr "  guestfs_int_%s_list %s;\n" typ n;
3521            pr "};\n\n"
3522        | RHashtable n ->
3523            pr "struct %s_ret {\n" name;
3524            pr "  str %s<>;\n" n;
3525            pr "};\n\n"
3526       );
3527   ) daemon_functions;
3528
3529   (* Table of procedure numbers. *)
3530   pr "enum guestfs_procedure {\n";
3531   List.iter (
3532     fun (shortname, _, proc_nr, _, _, _, _) ->
3533       pr "  GUESTFS_PROC_%s = %d,\n" (String.uppercase shortname) proc_nr
3534   ) daemon_functions;
3535   pr "  GUESTFS_PROC_NR_PROCS\n";
3536   pr "};\n";
3537   pr "\n";
3538
3539   (* Having to choose a maximum message size is annoying for several
3540    * reasons (it limits what we can do in the API), but it (a) makes
3541    * the protocol a lot simpler, and (b) provides a bound on the size
3542    * of the daemon which operates in limited memory space.  For large
3543    * file transfers you should use FTP.
3544    *)
3545   pr "const GUESTFS_MESSAGE_MAX = %d;\n" (4 * 1024 * 1024);
3546   pr "\n";
3547
3548   (* Message header, etc. *)
3549   pr "\
3550 /* The communication protocol is now documented in the guestfs(3)
3551  * manpage.
3552  */
3553
3554 const GUESTFS_PROGRAM = 0x2000F5F5;
3555 const GUESTFS_PROTOCOL_VERSION = 1;
3556
3557 /* These constants must be larger than any possible message length. */
3558 const GUESTFS_LAUNCH_FLAG = 0xf5f55ff5;
3559 const GUESTFS_CANCEL_FLAG = 0xffffeeee;
3560
3561 enum guestfs_message_direction {
3562   GUESTFS_DIRECTION_CALL = 0,        /* client -> daemon */
3563   GUESTFS_DIRECTION_REPLY = 1        /* daemon -> client */
3564 };
3565
3566 enum guestfs_message_status {
3567   GUESTFS_STATUS_OK = 0,
3568   GUESTFS_STATUS_ERROR = 1
3569 };
3570
3571 const GUESTFS_ERROR_LEN = 256;
3572
3573 struct guestfs_message_error {
3574   string error_message<GUESTFS_ERROR_LEN>;
3575 };
3576
3577 struct guestfs_message_header {
3578   unsigned prog;                     /* GUESTFS_PROGRAM */
3579   unsigned vers;                     /* GUESTFS_PROTOCOL_VERSION */
3580   guestfs_procedure proc;            /* GUESTFS_PROC_x */
3581   guestfs_message_direction direction;
3582   unsigned serial;                   /* message serial number */
3583   guestfs_message_status status;
3584 };
3585
3586 const GUESTFS_MAX_CHUNK_SIZE = 8192;
3587
3588 struct guestfs_chunk {
3589   int cancel;                        /* if non-zero, transfer is cancelled */
3590   /* data size is 0 bytes if the transfer has finished successfully */
3591   opaque data<GUESTFS_MAX_CHUNK_SIZE>;
3592 };
3593 "
3594
3595 (* Generate the guestfs-structs.h file. *)
3596 and generate_structs_h () =
3597   generate_header CStyle LGPLv2;
3598
3599   (* This is a public exported header file containing various
3600    * structures.  The structures are carefully written to have
3601    * exactly the same in-memory format as the XDR structures that
3602    * we use on the wire to the daemon.  The reason for creating
3603    * copies of these structures here is just so we don't have to
3604    * export the whole of guestfs_protocol.h (which includes much
3605    * unrelated and XDR-dependent stuff that we don't want to be
3606    * public, or required by clients).
3607    *
3608    * To reiterate, we will pass these structures to and from the
3609    * client with a simple assignment or memcpy, so the format
3610    * must be identical to what rpcgen / the RFC defines.
3611    *)
3612
3613   (* Public structures. *)
3614   List.iter (
3615     fun (typ, cols) ->
3616       pr "struct guestfs_%s {\n" typ;
3617       List.iter (
3618         function
3619         | name, FChar -> pr "  char %s;\n" name
3620         | name, FString -> pr "  char *%s;\n" name
3621         | name, FUUID -> pr "  char %s[32]; /* this is NOT nul-terminated, be careful when printing */\n" name
3622         | name, FUInt32 -> pr "  uint32_t %s;\n" name
3623         | name, FInt32 -> pr "  int32_t %s;\n" name
3624         | name, (FUInt64|FBytes) -> pr "  uint64_t %s;\n" name
3625         | name, FInt64 -> pr "  int64_t %s;\n" name
3626         | name, FOptPercent -> pr "  float %s; /* [0..100] or -1 */\n" name
3627       ) cols;
3628       pr "};\n";
3629       pr "\n";
3630       pr "struct guestfs_%s_list {\n" typ;
3631       pr "  uint32_t len;\n";
3632       pr "  struct guestfs_%s *val;\n" typ;
3633       pr "};\n";
3634       pr "\n";
3635       pr "extern void guestfs_free_%s (struct guestfs_%s *);\n" typ typ;
3636       pr "extern void guestfs_free_%s_list (struct guestfs_%s_list *);\n" typ typ;
3637       pr "\n"
3638   ) structs
3639
3640 (* Generate the guestfs-actions.h file. *)
3641 and generate_actions_h () =
3642   generate_header CStyle LGPLv2;
3643   List.iter (
3644     fun (shortname, style, _, _, _, _, _) ->
3645       let name = "guestfs_" ^ shortname in
3646       generate_prototype ~single_line:true ~newline:true ~handle:"handle"
3647         name style
3648   ) all_functions
3649
3650 (* Generate the client-side dispatch stubs. *)
3651 and generate_client_actions () =
3652   generate_header CStyle LGPLv2;
3653
3654   pr "\
3655 #include <stdio.h>
3656 #include <stdlib.h>
3657
3658 #include \"guestfs.h\"
3659 #include \"guestfs_protocol.h\"
3660
3661 #define error guestfs_error
3662 #define perrorf guestfs_perrorf
3663 #define safe_malloc guestfs_safe_malloc
3664 #define safe_realloc guestfs_safe_realloc
3665 #define safe_strdup guestfs_safe_strdup
3666 #define safe_memdup guestfs_safe_memdup
3667
3668 /* Check the return message from a call for validity. */
3669 static int
3670 check_reply_header (guestfs_h *g,
3671                     const struct guestfs_message_header *hdr,
3672                     int proc_nr, int serial)
3673 {
3674   if (hdr->prog != GUESTFS_PROGRAM) {
3675     error (g, \"wrong program (%%d/%%d)\", hdr->prog, GUESTFS_PROGRAM);
3676     return -1;
3677   }
3678   if (hdr->vers != GUESTFS_PROTOCOL_VERSION) {
3679     error (g, \"wrong protocol version (%%d/%%d)\",
3680            hdr->vers, GUESTFS_PROTOCOL_VERSION);
3681     return -1;
3682   }
3683   if (hdr->direction != GUESTFS_DIRECTION_REPLY) {
3684     error (g, \"unexpected message direction (%%d/%%d)\",
3685            hdr->direction, GUESTFS_DIRECTION_REPLY);
3686     return -1;
3687   }
3688   if (hdr->proc != proc_nr) {
3689     error (g, \"unexpected procedure number (%%d/%%d)\", hdr->proc, proc_nr);
3690     return -1;
3691   }
3692   if (hdr->serial != serial) {
3693     error (g, \"unexpected serial (%%d/%%d)\", hdr->serial, serial);
3694     return -1;
3695   }
3696
3697   return 0;
3698 }
3699
3700 /* Check we are in the right state to run a high-level action. */
3701 static int
3702 check_state (guestfs_h *g, const char *caller)
3703 {
3704   if (!guestfs_is_ready (g)) {
3705     if (guestfs_is_config (g))
3706       error (g, \"%%s: call launch() before using this function\",
3707         caller);
3708     else if (guestfs_is_launching (g))
3709       error (g, \"%%s: call wait_ready() before using this function\",
3710         caller);
3711     else
3712       error (g, \"%%s called from the wrong state, %%d != READY\",
3713         caller, guestfs_get_state (g));
3714     return -1;
3715   }
3716   return 0;
3717 }
3718
3719 ";
3720
3721   (* Client-side stubs for each function. *)
3722   List.iter (
3723     fun (shortname, style, _, _, _, _, _) ->
3724       let name = "guestfs_" ^ shortname in
3725
3726       (* Generate the context struct which stores the high-level
3727        * state between callback functions.
3728        *)
3729       pr "struct %s_ctx {\n" shortname;
3730       pr "  /* This flag is set by the callbacks, so we know we've done\n";
3731       pr "   * the callbacks as expected, and in the right sequence.\n";
3732       pr "   * 0 = not called, 1 = reply_cb called.\n";
3733       pr "   */\n";
3734       pr "  int cb_sequence;\n";
3735       pr "  struct guestfs_message_header hdr;\n";
3736       pr "  struct guestfs_message_error err;\n";
3737       (match fst style with
3738        | RErr -> ()
3739        | RConstString _ ->
3740            failwithf "RConstString cannot be returned from a daemon function"
3741        | RInt _ | RInt64 _
3742        | RBool _ | RString _ | RStringList _
3743        | RStruct _ | RStructList _
3744        | RHashtable _ ->
3745            pr "  struct %s_ret ret;\n" name
3746       );
3747       pr "};\n";
3748       pr "\n";
3749
3750       (* Generate the reply callback function. *)
3751       pr "static void %s_reply_cb (guestfs_h *g, void *data, XDR *xdr)\n" shortname;
3752       pr "{\n";
3753       pr "  guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3754       pr "  struct %s_ctx *ctx = (struct %s_ctx *) data;\n" shortname shortname;
3755       pr "\n";
3756       pr "  /* This should definitely not happen. */\n";
3757       pr "  if (ctx->cb_sequence != 0) {\n";
3758       pr "    ctx->cb_sequence = 9999;\n";
3759       pr "    error (g, \"%%s: internal error: reply callback called twice\", \"%s\");\n" name;
3760       pr "    return;\n";
3761       pr "  }\n";
3762       pr "\n";
3763       pr "  ml->main_loop_quit (ml, g);\n";
3764       pr "\n";
3765       pr "  if (!xdr_guestfs_message_header (xdr, &ctx->hdr)) {\n";
3766       pr "    error (g, \"%%s: failed to parse reply header\", \"%s\");\n" name;
3767       pr "    return;\n";
3768       pr "  }\n";
3769       pr "  if (ctx->hdr.status == GUESTFS_STATUS_ERROR) {\n";
3770       pr "    if (!xdr_guestfs_message_error (xdr, &ctx->err)) {\n";
3771       pr "      error (g, \"%%s: failed to parse reply error\", \"%s\");\n"
3772         name;
3773       pr "      return;\n";
3774       pr "    }\n";
3775       pr "    goto done;\n";
3776       pr "  }\n";
3777
3778       (match fst style with
3779        | RErr -> ()
3780        | RConstString _ ->
3781            failwithf "RConstString cannot be returned from a daemon function"
3782        | RInt _ | RInt64 _
3783        | RBool _ | RString _ | RStringList _
3784        | RStruct _ | RStructList _
3785        | RHashtable _ ->
3786            pr "  if (!xdr_%s_ret (xdr, &ctx->ret)) {\n" name;
3787            pr "    error (g, \"%%s: failed to parse reply\", \"%s\");\n" name;
3788            pr "    return;\n";
3789            pr "  }\n";
3790       );
3791
3792       pr " done:\n";
3793       pr "  ctx->cb_sequence = 1;\n";
3794       pr "}\n\n";
3795
3796       (* Generate the action stub. *)
3797       generate_prototype ~extern:false ~semicolon:false ~newline:true
3798         ~handle:"g" name style;
3799
3800       let error_code =
3801         match fst style with
3802         | RErr | RInt _ | RInt64 _ | RBool _ -> "-1"
3803         | RConstString _ ->
3804             failwithf "RConstString cannot be returned from a daemon function"
3805         | RString _ | RStringList _
3806         | RStruct _ | RStructList _
3807         | RHashtable _ ->
3808             "NULL" in
3809
3810       pr "{\n";
3811
3812       (match snd style with
3813        | [] -> ()
3814        | _ -> pr "  struct %s_args args;\n" name
3815       );
3816
3817       pr "  struct %s_ctx ctx;\n" shortname;
3818       pr "  guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3819       pr "  int serial;\n";
3820       pr "\n";
3821       pr "  if (check_state (g, \"%s\") == -1) return %s;\n" name error_code;
3822       pr "  guestfs_set_busy (g);\n";
3823       pr "\n";
3824       pr "  memset (&ctx, 0, sizeof ctx);\n";
3825       pr "\n";
3826
3827       (* Send the main header and arguments. *)
3828       (match snd style with
3829        | [] ->
3830            pr "  serial = guestfs__send_sync (g, GUESTFS_PROC_%s, NULL, NULL);\n"
3831              (String.uppercase shortname)
3832        | args ->
3833            List.iter (
3834              function
3835              | String n ->
3836                  pr "  args.%s = (char *) %s;\n" n n
3837              | OptString n ->
3838                  pr "  args.%s = %s ? (char **) &%s : NULL;\n" n n n
3839              | StringList n ->
3840                  pr "  args.%s.%s_val = (char **) %s;\n" n n n;
3841                  pr "  for (args.%s.%s_len = 0; %s[args.%s.%s_len]; args.%s.%s_len++) ;\n" n n n n n n n;
3842              | Bool n ->
3843                  pr "  args.%s = %s;\n" n n
3844              | Int n ->
3845                  pr "  args.%s = %s;\n" n n
3846              | FileIn _ | FileOut _ -> ()
3847            ) args;
3848            pr "  serial = guestfs__send_sync (g, GUESTFS_PROC_%s,\n"
3849              (String.uppercase shortname);
3850            pr "        (xdrproc_t) xdr_%s_args, (char *) &args);\n"
3851              name;
3852       );
3853       pr "  if (serial == -1) {\n";
3854       pr "    guestfs_end_busy (g);\n";
3855       pr "    return %s;\n" error_code;
3856       pr "  }\n";
3857       pr "\n";
3858
3859       (* Send any additional files (FileIn) requested. *)
3860       let need_read_reply_label = ref false in
3861       List.iter (
3862         function
3863         | FileIn n ->
3864             pr "  {\n";
3865             pr "    int r;\n";
3866             pr "\n";
3867             pr "    r = guestfs__send_file_sync (g, %s);\n" n;
3868             pr "    if (r == -1) {\n";
3869             pr "      guestfs_end_busy (g);\n";
3870             pr "      return %s;\n" error_code;
3871             pr "    }\n";
3872             pr "    if (r == -2) /* daemon cancelled */\n";
3873             pr "      goto read_reply;\n";
3874             need_read_reply_label := true;
3875             pr "  }\n";
3876             pr "\n";
3877         | _ -> ()
3878       ) (snd style);
3879
3880       (* Wait for the reply from the remote end. *)
3881       if !need_read_reply_label then pr " read_reply:\n";
3882       pr "  guestfs__switch_to_receiving (g);\n";
3883       pr "  ctx.cb_sequence = 0;\n";
3884       pr "  guestfs_set_reply_callback (g, %s_reply_cb, &ctx);\n" shortname;
3885       pr "  (void) ml->main_loop_run (ml, g);\n";
3886       pr "  guestfs_set_reply_callback (g, NULL, NULL);\n";
3887       pr "  if (ctx.cb_sequence != 1) {\n";
3888       pr "    error (g, \"%%s reply failed, see earlier error messages\", \"%s\");\n" name;
3889       pr "    guestfs_end_busy (g);\n";
3890       pr "    return %s;\n" error_code;
3891       pr "  }\n";
3892       pr "\n";
3893
3894       pr "  if (check_reply_header (g, &ctx.hdr, GUESTFS_PROC_%s, serial) == -1) {\n"
3895         (String.uppercase shortname);
3896       pr "    guestfs_end_busy (g);\n";
3897       pr "    return %s;\n" error_code;
3898       pr "  }\n";
3899       pr "\n";
3900
3901       pr "  if (ctx.hdr.status == GUESTFS_STATUS_ERROR) {\n";
3902       pr "    error (g, \"%%s\", ctx.err.error_message);\n";
3903       pr "    free (ctx.err.error_message);\n";
3904       pr "    guestfs_end_busy (g);\n";
3905       pr "    return %s;\n" error_code;
3906       pr "  }\n";
3907       pr "\n";
3908
3909       (* Expecting to receive further files (FileOut)? *)
3910       List.iter (
3911         function
3912         | FileOut n ->
3913             pr "  if (guestfs__receive_file_sync (g, %s) == -1) {\n" n;
3914             pr "    guestfs_end_busy (g);\n";
3915             pr "    return %s;\n" error_code;
3916             pr "  }\n";
3917             pr "\n";
3918         | _ -> ()
3919       ) (snd style);
3920
3921       pr "  guestfs_end_busy (g);\n";
3922
3923       (match fst style with
3924        | RErr -> pr "  return 0;\n"
3925        | RInt n | RInt64 n | RBool n ->
3926            pr "  return ctx.ret.%s;\n" n
3927        | RConstString _ ->
3928            failwithf "RConstString cannot be returned from a daemon function"
3929        | RString n ->
3930            pr "  return ctx.ret.%s; /* caller will free */\n" n
3931        | RStringList n | RHashtable n ->
3932            pr "  /* caller will free this, but we need to add a NULL entry */\n";
3933            pr "  ctx.ret.%s.%s_val =\n" n n;
3934            pr "    safe_realloc (g, ctx.ret.%s.%s_val,\n" n n;
3935            pr "                  sizeof (char *) * (ctx.ret.%s.%s_len + 1));\n"
3936              n n;
3937            pr "  ctx.ret.%s.%s_val[ctx.ret.%s.%s_len] = NULL;\n" n n n n;
3938            pr "  return ctx.ret.%s.%s_val;\n" n n
3939        | RStruct (n, _) ->
3940            pr "  /* caller will free this */\n";
3941            pr "  return safe_memdup (g, &ctx.ret.%s, sizeof (ctx.ret.%s));\n" n n
3942        | RStructList (n, _) ->
3943            pr "  /* caller will free this */\n";
3944            pr "  return safe_memdup (g, &ctx.ret.%s, sizeof (ctx.ret.%s));\n" n n
3945       );
3946
3947       pr "}\n\n"
3948   ) daemon_functions;
3949
3950   (* Functions to free structures. *)
3951   pr "/* Structure-freeing functions.  These rely on the fact that the\n";
3952   pr " * structure format is identical to the XDR format.  See note in\n";
3953   pr " * generator.ml.\n";
3954   pr " */\n";
3955   pr "\n";
3956
3957   List.iter (
3958     fun (typ, _) ->
3959       pr "void\n";
3960       pr "guestfs_free_%s (struct guestfs_%s *x)\n" typ typ;
3961       pr "{\n";
3962       pr "  xdr_free ((xdrproc_t) xdr_guestfs_int_%s, (char *) x);\n" typ;
3963       pr "  free (x);\n";
3964       pr "}\n";
3965       pr "\n";
3966
3967       pr "void\n";
3968       pr "guestfs_free_%s_list (struct guestfs_%s_list *x)\n" typ typ;
3969       pr "{\n";
3970       pr "  xdr_free ((xdrproc_t) xdr_guestfs_int_%s_list, (char *) x);\n" typ;
3971       pr "  free (x);\n";
3972       pr "}\n";
3973       pr "\n";
3974
3975   ) structs;
3976
3977 (* Generate daemon/actions.h. *)
3978 and generate_daemon_actions_h () =
3979   generate_header CStyle GPLv2;
3980
3981   pr "#include \"../src/guestfs_protocol.h\"\n";
3982   pr "\n";
3983
3984   List.iter (
3985     fun (name, style, _, _, _, _, _) ->
3986       generate_prototype
3987         ~single_line:true ~newline:true ~in_daemon:true ~prefix:"do_"
3988         name style;
3989   ) daemon_functions
3990
3991 (* Generate the server-side stubs. *)
3992 and generate_daemon_actions () =
3993   generate_header CStyle GPLv2;
3994
3995   pr "#include <config.h>\n";
3996   pr "\n";
3997   pr "#include <stdio.h>\n";
3998   pr "#include <stdlib.h>\n";
3999   pr "#include <string.h>\n";
4000   pr "#include <inttypes.h>\n";
4001   pr "#include <ctype.h>\n";
4002   pr "#include <rpc/types.h>\n";
4003   pr "#include <rpc/xdr.h>\n";
4004   pr "\n";
4005   pr "#include \"daemon.h\"\n";
4006   pr "#include \"../src/guestfs_protocol.h\"\n";
4007   pr "#include \"actions.h\"\n";
4008   pr "\n";
4009
4010   List.iter (
4011     fun (name, style, _, _, _, _, _) ->
4012       (* Generate server-side stubs. *)
4013       pr "static void %s_stub (XDR *xdr_in)\n" name;
4014       pr "{\n";
4015       let error_code =
4016         match fst style with
4017         | RErr | RInt _ -> pr "  int r;\n"; "-1"
4018         | RInt64 _ -> pr "  int64_t r;\n"; "-1"
4019         | RBool _ -> pr "  int r;\n"; "-1"
4020         | RConstString _ ->
4021             failwithf "RConstString cannot be returned from a daemon function"
4022         | RString _ -> pr "  char *r;\n"; "NULL"
4023         | RStringList _ | RHashtable _ -> pr "  char **r;\n"; "NULL"
4024         | RStruct (_, typ) -> pr "  guestfs_int_%s *r;\n" typ; "NULL"
4025         | RStructList (_, typ) -> pr "  guestfs_int_%s_list *r;\n" typ; "NULL" in
4026
4027       (match snd style with
4028        | [] -> ()
4029        | args ->
4030            pr "  struct guestfs_%s_args args;\n" name;
4031            List.iter (
4032              function
4033                (* Note we allow the string to be writable, in order to
4034                 * allow device name translation.  This is safe because
4035                 * we can modify the string (passed from RPC).
4036                 *)
4037              | String n
4038              | OptString n -> pr "  char *%s;\n" n
4039              | StringList n -> pr "  char **%s;\n" n
4040              | Bool n -> pr "  int %s;\n" n
4041              | Int n -> pr "  int %s;\n" n
4042              | FileIn _ | FileOut _ -> ()
4043            ) args
4044       );
4045       pr "\n";
4046
4047       (match snd style with
4048        | [] -> ()
4049        | args ->
4050            pr "  memset (&args, 0, sizeof args);\n";
4051            pr "\n";
4052            pr "  if (!xdr_guestfs_%s_args (xdr_in, &args)) {\n" name;
4053            pr "    reply_with_error (\"%%s: daemon failed to decode procedure arguments\", \"%s\");\n" name;
4054            pr "    return;\n";
4055            pr "  }\n";
4056            List.iter (
4057              function
4058              | String n -> pr "  %s = args.%s;\n" n n
4059              | OptString n -> pr "  %s = args.%s ? *args.%s : NULL;\n" n n n
4060              | StringList n ->
4061                  pr "  %s = realloc (args.%s.%s_val,\n" n n n;
4062                  pr "                sizeof (char *) * (args.%s.%s_len+1));\n" n n;
4063                  pr "  if (%s == NULL) {\n" n;
4064                  pr "    reply_with_perror (\"realloc\");\n";
4065                  pr "    goto done;\n";
4066                  pr "  }\n";
4067                  pr "  %s[args.%s.%s_len] = NULL;\n" n n n;
4068                  pr "  args.%s.%s_val = %s;\n" n n n;
4069              | Bool n -> pr "  %s = args.%s;\n" n n
4070              | Int n -> pr "  %s = args.%s;\n" n n
4071              | FileIn _ | FileOut _ -> ()
4072            ) args;
4073            pr "\n"
4074       );
4075
4076       (* Don't want to call the impl with any FileIn or FileOut
4077        * parameters, since these go "outside" the RPC protocol.
4078        *)
4079       let argsnofile =
4080         List.filter (function FileIn _ | FileOut _ -> false | _ -> true)
4081           (snd style) in
4082       pr "  r = do_%s " name;
4083       generate_call_args argsnofile;
4084       pr ";\n";
4085
4086       pr "  if (r == %s)\n" error_code;
4087       pr "    /* do_%s has already called reply_with_error */\n" name;
4088       pr "    goto done;\n";
4089       pr "\n";
4090
4091       (* If there are any FileOut parameters, then the impl must
4092        * send its own reply.
4093        *)
4094       let no_reply =
4095         List.exists (function FileOut _ -> true | _ -> false) (snd style) in
4096       if no_reply then
4097         pr "  /* do_%s has already sent a reply */\n" name
4098       else (
4099         match fst style with
4100         | RErr -> pr "  reply (NULL, NULL);\n"
4101         | RInt n | RInt64 n | RBool n ->
4102             pr "  struct guestfs_%s_ret ret;\n" name;
4103             pr "  ret.%s = r;\n" n;
4104             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
4105               name
4106         | RConstString _ ->
4107             failwithf "RConstString cannot be returned from a daemon function"
4108         | RString n ->
4109             pr "  struct guestfs_%s_ret ret;\n" name;
4110             pr "  ret.%s = r;\n" n;
4111             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
4112               name;
4113             pr "  free (r);\n"
4114         | RStringList n | RHashtable n ->
4115             pr "  struct guestfs_%s_ret ret;\n" name;
4116             pr "  ret.%s.%s_len = count_strings (r);\n" n n;
4117             pr "  ret.%s.%s_val = r;\n" n n;
4118             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
4119               name;
4120             pr "  free_strings (r);\n"
4121         | RStruct (n, _) ->
4122             pr "  struct guestfs_%s_ret ret;\n" name;
4123             pr "  ret.%s = *r;\n" n;
4124             pr "  reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
4125               name;
4126             pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
4127               name
4128         | RStructList (n, _) ->
4129             pr "  struct guestfs_%s_ret ret;\n" name;
4130             pr "  ret.%s = *r;\n" n;
4131             pr "  reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
4132               name;
4133             pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
4134               name
4135       );
4136
4137       (* Free the args. *)
4138       (match snd style with
4139        | [] ->
4140            pr "done: ;\n";
4141        | _ ->
4142            pr "done:\n";
4143            pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_args, (char *) &args);\n"
4144              name
4145       );
4146
4147       pr "}\n\n";
4148   ) daemon_functions;
4149
4150   (* Dispatch function. *)
4151   pr "void dispatch_incoming_message (XDR *xdr_in)\n";
4152   pr "{\n";
4153   pr "  switch (proc_nr) {\n";
4154
4155   List.iter (
4156     fun (name, style, _, _, _, _, _) ->
4157       pr "    case GUESTFS_PROC_%s:\n" (String.uppercase name);
4158       pr "      %s_stub (xdr_in);\n" name;
4159       pr "      break;\n"
4160   ) daemon_functions;
4161
4162   pr "    default:\n";
4163   pr "      reply_with_error (\"dispatch_incoming_message: unknown procedure number %%d, set LIBGUESTFS_PATH to point to the matching libguestfs appliance directory\", proc_nr);\n";
4164   pr "  }\n";
4165   pr "}\n";
4166   pr "\n";
4167
4168   (* LVM columns and tokenization functions. *)
4169   (* XXX This generates crap code.  We should rethink how we
4170    * do this parsing.
4171    *)
4172   List.iter (
4173     function
4174     | typ, cols ->
4175         pr "static const char *lvm_%s_cols = \"%s\";\n"
4176           typ (String.concat "," (List.map fst cols));
4177         pr "\n";
4178
4179         pr "static int lvm_tokenize_%s (char *str, guestfs_int_lvm_%s *r)\n" typ typ;
4180         pr "{\n";
4181         pr "  char *tok, *p, *next;\n";
4182         pr "  int i, j;\n";
4183         pr "\n";
4184         (*
4185           pr "  fprintf (stderr, \"%%s: <<%%s>>\\n\", __func__, str);\n";
4186           pr "\n";
4187         *)
4188         pr "  if (!str) {\n";
4189         pr "    fprintf (stderr, \"%%s: failed: passed a NULL string\\n\", __func__);\n";
4190         pr "    return -1;\n";
4191         pr "  }\n";
4192         pr "  if (!*str || isspace (*str)) {\n";
4193         pr "    fprintf (stderr, \"%%s: failed: passed a empty string or one beginning with whitespace\\n\", __func__);\n";
4194         pr "    return -1;\n";
4195         pr "  }\n";
4196         pr "  tok = str;\n";
4197         List.iter (
4198           fun (name, coltype) ->
4199             pr "  if (!tok) {\n";
4200             pr "    fprintf (stderr, \"%%s: failed: string finished early, around token %%s\\n\", __func__, \"%s\");\n" name;
4201             pr "    return -1;\n";
4202             pr "  }\n";
4203             pr "  p = strchrnul (tok, ',');\n";
4204             pr "  if (*p) next = p+1; else next = NULL;\n";
4205             pr "  *p = '\\0';\n";
4206             (match coltype with
4207              | FString ->
4208                  pr "  r->%s = strdup (tok);\n" name;
4209                  pr "  if (r->%s == NULL) {\n" name;
4210                  pr "    perror (\"strdup\");\n";
4211                  pr "    return -1;\n";
4212                  pr "  }\n"
4213              | FUUID ->
4214                  pr "  for (i = j = 0; i < 32; ++j) {\n";
4215                  pr "    if (tok[j] == '\\0') {\n";
4216                  pr "      fprintf (stderr, \"%%s: failed to parse UUID from '%%s'\\n\", __func__, tok);\n";
4217                  pr "      return -1;\n";
4218                  pr "    } else if (tok[j] != '-')\n";
4219                  pr "      r->%s[i++] = tok[j];\n" name;
4220                  pr "  }\n";
4221              | FBytes ->
4222                  pr "  if (sscanf (tok, \"%%\"SCNu64, &r->%s) != 1) {\n" name;
4223                  pr "    fprintf (stderr, \"%%s: failed to parse size '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
4224                  pr "    return -1;\n";
4225                  pr "  }\n";
4226              | FInt64 ->
4227                  pr "  if (sscanf (tok, \"%%\"SCNi64, &r->%s) != 1) {\n" name;
4228                  pr "    fprintf (stderr, \"%%s: failed to parse int '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
4229                  pr "    return -1;\n";
4230                  pr "  }\n";
4231              | FOptPercent ->
4232                  pr "  if (tok[0] == '\\0')\n";
4233                  pr "    r->%s = -1;\n" name;
4234                  pr "  else if (sscanf (tok, \"%%f\", &r->%s) != 1) {\n" name;
4235                  pr "    fprintf (stderr, \"%%s: failed to parse float '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
4236                  pr "    return -1;\n";
4237                  pr "  }\n";
4238              | FInt32 | FUInt32 | FUInt64 | FChar ->
4239                  assert false (* can never be an LVM column *)
4240             );
4241             pr "  tok = next;\n";
4242         ) cols;
4243
4244         pr "  if (tok != NULL) {\n";
4245         pr "    fprintf (stderr, \"%%s: failed: extra tokens at end of string\\n\", __func__);\n";
4246         pr "    return -1;\n";
4247         pr "  }\n";
4248         pr "  return 0;\n";
4249         pr "}\n";
4250         pr "\n";
4251
4252         pr "guestfs_int_lvm_%s_list *\n" typ;
4253         pr "parse_command_line_%ss (void)\n" typ;
4254         pr "{\n";
4255         pr "  char *out, *err;\n";
4256         pr "  char *p, *pend;\n";
4257         pr "  int r, i;\n";
4258         pr "  guestfs_int_lvm_%s_list *ret;\n" typ;
4259         pr "  void *newp;\n";
4260         pr "\n";
4261         pr "  ret = malloc (sizeof *ret);\n";
4262         pr "  if (!ret) {\n";
4263         pr "    reply_with_perror (\"malloc\");\n";
4264         pr "    return NULL;\n";
4265         pr "  }\n";
4266         pr "\n";
4267         pr "  ret->guestfs_int_lvm_%s_list_len = 0;\n" typ;
4268         pr "  ret->guestfs_int_lvm_%s_list_val = NULL;\n" typ;
4269         pr "\n";
4270         pr "  r = command (&out, &err,\n";
4271         pr "           \"/sbin/lvm\", \"%ss\",\n" typ;
4272         pr "           \"-o\", lvm_%s_cols, \"--unbuffered\", \"--noheadings\",\n" typ;
4273         pr "           \"--nosuffix\", \"--separator\", \",\", \"--units\", \"b\", NULL);\n";
4274         pr "  if (r == -1) {\n";
4275         pr "    reply_with_error (\"%%s\", err);\n";
4276         pr "    free (out);\n";
4277         pr "    free (err);\n";
4278         pr "    free (ret);\n";
4279         pr "    return NULL;\n";
4280         pr "  }\n";
4281         pr "\n";
4282         pr "  free (err);\n";
4283         pr "\n";
4284         pr "  /* Tokenize each line of the output. */\n";
4285         pr "  p = out;\n";
4286         pr "  i = 0;\n";
4287         pr "  while (p) {\n";
4288         pr "    pend = strchr (p, '\\n');       /* Get the next line of output. */\n";
4289         pr "    if (pend) {\n";
4290         pr "      *pend = '\\0';\n";
4291         pr "      pend++;\n";
4292         pr "    }\n";
4293         pr "\n";
4294         pr "    while (*p && isspace (*p))      /* Skip any leading whitespace. */\n";
4295         pr "      p++;\n";
4296         pr "\n";
4297         pr "    if (!*p) {                      /* Empty line?  Skip it. */\n";
4298         pr "      p = pend;\n";
4299         pr "      continue;\n";
4300         pr "    }\n";
4301         pr "\n";
4302         pr "    /* Allocate some space to store this next entry. */\n";
4303         pr "    newp = realloc (ret->guestfs_int_lvm_%s_list_val,\n" typ;
4304         pr "                sizeof (guestfs_int_lvm_%s) * (i+1));\n" typ;
4305         pr "    if (newp == NULL) {\n";
4306         pr "      reply_with_perror (\"realloc\");\n";
4307         pr "      free (ret->guestfs_int_lvm_%s_list_val);\n" typ;
4308         pr "      free (ret);\n";
4309         pr "      free (out);\n";
4310         pr "      return NULL;\n";
4311         pr "    }\n";
4312         pr "    ret->guestfs_int_lvm_%s_list_val = newp;\n" typ;
4313         pr "\n";
4314         pr "    /* Tokenize the next entry. */\n";
4315         pr "    r = lvm_tokenize_%s (p, &ret->guestfs_int_lvm_%s_list_val[i]);\n" typ typ;
4316         pr "    if (r == -1) {\n";
4317         pr "      reply_with_error (\"failed to parse output of '%ss' command\");\n" typ;
4318         pr "      free (ret->guestfs_int_lvm_%s_list_val);\n" typ;
4319         pr "      free (ret);\n";
4320         pr "      free (out);\n";
4321         pr "      return NULL;\n";
4322         pr "    }\n";
4323         pr "\n";
4324         pr "    ++i;\n";
4325         pr "    p = pend;\n";
4326         pr "  }\n";
4327         pr "\n";
4328         pr "  ret->guestfs_int_lvm_%s_list_len = i;\n" typ;
4329         pr "\n";
4330         pr "  free (out);\n";
4331         pr "  return ret;\n";
4332         pr "}\n"
4333
4334   ) ["pv", lvm_pv_cols; "vg", lvm_vg_cols; "lv", lvm_lv_cols]
4335
4336 (* Generate a list of function names, for debugging in the daemon.. *)
4337 and generate_daemon_names () =
4338   generate_header CStyle GPLv2;
4339
4340   pr "#include <config.h>\n";
4341   pr "\n";
4342   pr "#include \"daemon.h\"\n";
4343   pr "\n";
4344
4345   pr "/* This array is indexed by proc_nr.  See guestfs_protocol.x. */\n";
4346   pr "const char *function_names[] = {\n";
4347   List.iter (
4348     fun (name, _, proc_nr, _, _, _, _) -> pr "  [%d] = \"%s\",\n" proc_nr name
4349   ) daemon_functions;
4350   pr "};\n";
4351
4352 (* Generate the tests. *)
4353 and generate_tests () =
4354   generate_header CStyle GPLv2;
4355
4356   pr "\
4357 #include <stdio.h>
4358 #include <stdlib.h>
4359 #include <string.h>
4360 #include <unistd.h>
4361 #include <sys/types.h>
4362 #include <fcntl.h>
4363
4364 #include \"guestfs.h\"
4365
4366 static guestfs_h *g;
4367 static int suppress_error = 0;
4368
4369 static void print_error (guestfs_h *g, void *data, const char *msg)
4370 {
4371   if (!suppress_error)
4372     fprintf (stderr, \"%%s\\n\", msg);
4373 }
4374
4375 static void print_strings (char * const * const argv)
4376 {
4377   int argc;
4378
4379   for (argc = 0; argv[argc] != NULL; ++argc)
4380     printf (\"\\t%%s\\n\", argv[argc]);
4381 }
4382
4383 /*
4384 static void print_table (char * const * const argv)
4385 {
4386   int i;
4387
4388   for (i = 0; argv[i] != NULL; i += 2)
4389     printf (\"%%s: %%s\\n\", argv[i], argv[i+1]);
4390 }
4391 */
4392
4393 static void no_test_warnings (void)
4394 {
4395 ";
4396
4397   List.iter (
4398     function
4399     | name, _, _, _, [], _, _ ->
4400         pr "  fprintf (stderr, \"warning: \\\"guestfs_%s\\\" has no tests\\n\");\n" name
4401     | name, _, _, _, tests, _, _ -> ()
4402   ) all_functions;
4403
4404   pr "}\n";
4405   pr "\n";
4406
4407   (* Generate the actual tests.  Note that we generate the tests
4408    * in reverse order, deliberately, so that (in general) the
4409    * newest tests run first.  This makes it quicker and easier to
4410    * debug them.
4411    *)
4412   let test_names =
4413     List.map (
4414       fun (name, _, _, _, tests, _, _) ->
4415         mapi (generate_one_test name) tests
4416     ) (List.rev all_functions) in
4417   let test_names = List.concat test_names in
4418   let nr_tests = List.length test_names in
4419
4420   pr "\
4421 int main (int argc, char *argv[])
4422 {
4423   char c = 0;
4424   int failed = 0;
4425   const char *filename;
4426   int fd;
4427   int nr_tests, test_num = 0;
4428
4429   setbuf (stdout, NULL);
4430
4431   no_test_warnings ();
4432
4433   g = guestfs_create ();
4434   if (g == NULL) {
4435     printf (\"guestfs_create FAILED\\n\");
4436     exit (1);
4437   }
4438
4439   guestfs_set_error_handler (g, print_error, NULL);
4440
4441   guestfs_set_path (g, \"../appliance\");
4442
4443   filename = \"test1.img\";
4444   fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
4445   if (fd == -1) {
4446     perror (filename);
4447     exit (1);
4448   }
4449   if (lseek (fd, %d, SEEK_SET) == -1) {
4450     perror (\"lseek\");
4451     close (fd);
4452     unlink (filename);
4453     exit (1);
4454   }
4455   if (write (fd, &c, 1) == -1) {
4456     perror (\"write\");
4457     close (fd);
4458     unlink (filename);
4459     exit (1);
4460   }
4461   if (close (fd) == -1) {
4462     perror (filename);
4463     unlink (filename);
4464     exit (1);
4465   }
4466   if (guestfs_add_drive (g, filename) == -1) {
4467     printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
4468     exit (1);
4469   }
4470
4471   filename = \"test2.img\";
4472   fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
4473   if (fd == -1) {
4474     perror (filename);
4475     exit (1);
4476   }
4477   if (lseek (fd, %d, SEEK_SET) == -1) {
4478     perror (\"lseek\");
4479     close (fd);
4480     unlink (filename);
4481     exit (1);
4482   }
4483   if (write (fd, &c, 1) == -1) {
4484     perror (\"write\");
4485     close (fd);
4486     unlink (filename);
4487     exit (1);
4488   }
4489   if (close (fd) == -1) {
4490     perror (filename);
4491     unlink (filename);
4492     exit (1);
4493   }
4494   if (guestfs_add_drive (g, filename) == -1) {
4495     printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
4496     exit (1);
4497   }
4498
4499   filename = \"test3.img\";
4500   fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
4501   if (fd == -1) {
4502     perror (filename);
4503     exit (1);
4504   }
4505   if (lseek (fd, %d, SEEK_SET) == -1) {
4506     perror (\"lseek\");
4507     close (fd);
4508     unlink (filename);
4509     exit (1);
4510   }
4511   if (write (fd, &c, 1) == -1) {
4512     perror (\"write\");
4513     close (fd);
4514     unlink (filename);
4515     exit (1);
4516   }
4517   if (close (fd) == -1) {
4518     perror (filename);
4519     unlink (filename);
4520     exit (1);
4521   }
4522   if (guestfs_add_drive (g, filename) == -1) {
4523     printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
4524     exit (1);
4525   }
4526
4527   if (guestfs_add_drive_ro (g, \"../images/test.sqsh\") == -1) {
4528     printf (\"guestfs_add_drive_ro ../images/test.sqsh FAILED\\n\");
4529     exit (1);
4530   }
4531
4532   if (guestfs_launch (g) == -1) {
4533     printf (\"guestfs_launch FAILED\\n\");
4534     exit (1);
4535   }
4536
4537   /* Set a timeout in case qemu hangs during launch (RHBZ#505329). */
4538   alarm (600);
4539
4540   if (guestfs_wait_ready (g) == -1) {
4541     printf (\"guestfs_wait_ready FAILED\\n\");
4542     exit (1);
4543   }
4544
4545   /* Cancel previous alarm. */
4546   alarm (0);
4547
4548   nr_tests = %d;
4549
4550 " (500 * 1024 * 1024) (50 * 1024 * 1024) (10 * 1024 * 1024) nr_tests;
4551
4552   iteri (
4553     fun i test_name ->
4554       pr "  test_num++;\n";
4555       pr "  printf (\"%%3d/%%3d %s\\n\", test_num, nr_tests);\n" test_name;
4556       pr "  if (%s () == -1) {\n" test_name;
4557       pr "    printf (\"%s FAILED\\n\");\n" test_name;
4558       pr "    failed++;\n";
4559       pr "  }\n";
4560   ) test_names;
4561   pr "\n";
4562
4563   pr "  guestfs_close (g);\n";
4564   pr "  unlink (\"test1.img\");\n";
4565   pr "  unlink (\"test2.img\");\n";
4566   pr "  unlink (\"test3.img\");\n";
4567   pr "\n";
4568
4569   pr "  if (failed > 0) {\n";
4570   pr "    printf (\"***** %%d / %%d tests FAILED *****\\n\", failed, nr_tests);\n";
4571   pr "    exit (1);\n";
4572   pr "  }\n";
4573   pr "\n";
4574
4575   pr "  exit (0);\n";
4576   pr "}\n"
4577
4578 and generate_one_test name i (init, prereq, test) =
4579   let test_name = sprintf "test_%s_%d" name i in
4580
4581   pr "\
4582 static int %s_skip (void)
4583 {
4584   const char *str;
4585
4586   str = getenv (\"TEST_ONLY\");
4587   if (str)
4588     return strstr (str, \"%s\") == NULL;
4589   str = getenv (\"SKIP_%s\");
4590   if (str && strcmp (str, \"1\") == 0) return 1;
4591   str = getenv (\"SKIP_TEST_%s\");
4592   if (str && strcmp (str, \"1\") == 0) return 1;
4593   return 0;
4594 }
4595
4596 " test_name name (String.uppercase test_name) (String.uppercase name);
4597
4598   (match prereq with
4599    | Disabled | Always -> ()
4600    | If code | Unless code ->
4601        pr "static int %s_prereq (void)\n" test_name;
4602        pr "{\n";
4603        pr "  %s\n" code;
4604        pr "}\n";
4605        pr "\n";
4606   );
4607
4608   pr "\
4609 static int %s (void)
4610 {
4611   if (%s_skip ()) {
4612     printf (\"        %%s skipped (reason: environment variable set)\\n\", \"%s\");
4613     return 0;
4614   }
4615
4616 " test_name test_name test_name;
4617
4618   (match prereq with
4619    | Disabled ->
4620        pr "  printf (\"        %%s skipped (reason: test disabled in generator)\\n\", \"%s\");\n" test_name
4621    | If _ ->
4622        pr "  if (! %s_prereq ()) {\n" test_name;
4623        pr "    printf (\"        %%s skipped (reason: test prerequisite)\\n\", \"%s\");\n" test_name;
4624        pr "    return 0;\n";
4625        pr "  }\n";
4626        pr "\n";
4627        generate_one_test_body name i test_name init test;
4628    | Unless _ ->
4629        pr "  if (%s_prereq ()) {\n" test_name;
4630        pr "    printf (\"        %%s skipped (reason: test prerequisite)\\n\", \"%s\");\n" test_name;
4631        pr "    return 0;\n";
4632        pr "  }\n";
4633        pr "\n";
4634        generate_one_test_body name i test_name init test;
4635    | Always ->
4636        generate_one_test_body name i test_name init test
4637   );
4638
4639   pr "  return 0;\n";
4640   pr "}\n";
4641   pr "\n";
4642   test_name
4643
4644 and generate_one_test_body name i test_name init test =
4645   (match init with
4646    | InitNone (* XXX at some point, InitNone and InitEmpty became
4647                * folded together as the same thing.  Really we should
4648                * make InitNone do nothing at all, but the tests may
4649                * need to be checked to make sure this is OK.
4650                *)
4651    | InitEmpty ->
4652        pr "  /* InitNone|InitEmpty for %s */\n" test_name;
4653        List.iter (generate_test_command_call test_name)
4654          [["blockdev_setrw"; "/dev/sda"];
4655           ["umount_all"];
4656           ["lvm_remove_all"]]
4657    | InitBasicFS ->
4658        pr "  /* InitBasicFS for %s: create ext2 on /dev/sda1 */\n" test_name;
4659        List.iter (generate_test_command_call test_name)
4660          [["blockdev_setrw"; "/dev/sda"];
4661           ["umount_all"];
4662           ["lvm_remove_all"];
4663           ["sfdiskM"; "/dev/sda"; ","];
4664           ["mkfs"; "ext2"; "/dev/sda1"];
4665           ["mount"; "/dev/sda1"; "/"]]
4666    | InitBasicFSonLVM ->
4667        pr "  /* InitBasicFSonLVM for %s: create ext2 on /dev/VG/LV */\n"
4668          test_name;
4669        List.iter (generate_test_command_call test_name)
4670          [["blockdev_setrw"; "/dev/sda"];
4671           ["umount_all"];
4672           ["lvm_remove_all"];
4673           ["sfdiskM"; "/dev/sda"; ","];
4674           ["pvcreate"; "/dev/sda1"];
4675           ["vgcreate"; "VG"; "/dev/sda1"];
4676           ["lvcreate"; "LV"; "VG"; "8"];
4677           ["mkfs"; "ext2"; "/dev/VG/LV"];
4678           ["mount"; "/dev/VG/LV"; "/"]]
4679   );
4680
4681   let get_seq_last = function
4682     | [] ->
4683         failwithf "%s: you cannot use [] (empty list) when expecting a command"
4684           test_name
4685     | seq ->
4686         let seq = List.rev seq in
4687         List.rev (List.tl seq), List.hd seq
4688   in
4689
4690   match test with
4691   | TestRun seq ->
4692       pr "  /* TestRun for %s (%d) */\n" name i;
4693       List.iter (generate_test_command_call test_name) seq
4694   | TestOutput (seq, expected) ->
4695       pr "  /* TestOutput for %s (%d) */\n" name i;
4696       pr "  const char *expected = \"%s\";\n" (c_quote expected);
4697       let seq, last = get_seq_last seq in
4698       let test () =
4699         pr "    if (strcmp (r, expected) != 0) {\n";
4700         pr "      fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r);\n" test_name;
4701         pr "      return -1;\n";
4702         pr "    }\n"
4703       in
4704       List.iter (generate_test_command_call test_name) seq;
4705       generate_test_command_call ~test test_name last
4706   | TestOutputList (seq, expected) ->
4707       pr "  /* TestOutputList for %s (%d) */\n" name i;
4708       let seq, last = get_seq_last seq in
4709       let test () =
4710         iteri (
4711           fun i str ->
4712             pr "    if (!r[%d]) {\n" i;
4713             pr "      fprintf (stderr, \"%s: short list returned from command\\n\");\n" test_name;
4714             pr "      print_strings (r);\n";
4715             pr "      return -1;\n";
4716             pr "    }\n";
4717             pr "    {\n";
4718             pr "      const char *expected = \"%s\";\n" (c_quote str);
4719             pr "      if (strcmp (r[%d], expected) != 0) {\n" i;
4720             pr "        fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r[%d]);\n" test_name i;
4721             pr "        return -1;\n";
4722             pr "      }\n";
4723             pr "    }\n"
4724         ) expected;
4725         pr "    if (r[%d] != NULL) {\n" (List.length expected);
4726         pr "      fprintf (stderr, \"%s: extra elements returned from command\\n\");\n"
4727           test_name;
4728         pr "      print_strings (r);\n";
4729         pr "      return -1;\n";
4730         pr "    }\n"
4731       in
4732       List.iter (generate_test_command_call test_name) seq;
4733       generate_test_command_call ~test test_name last
4734   | TestOutputListOfDevices (seq, expected) ->
4735       pr "  /* TestOutputListOfDevices for %s (%d) */\n" name i;
4736       let seq, last = get_seq_last seq in
4737       let test () =
4738         iteri (
4739           fun i str ->
4740             pr "    if (!r[%d]) {\n" i;
4741             pr "      fprintf (stderr, \"%s: short list returned from command\\n\");\n" test_name;
4742             pr "      print_strings (r);\n";
4743             pr "      return -1;\n";
4744             pr "    }\n";
4745             pr "    {\n";
4746             pr "      const char *expected = \"%s\";\n" (c_quote str);
4747             pr "      r[%d][5] = 's';\n" i;
4748             pr "      if (strcmp (r[%d], expected) != 0) {\n" i;
4749             pr "        fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r[%d]);\n" test_name i;
4750             pr "        return -1;\n";
4751             pr "      }\n";
4752             pr "    }\n"
4753         ) expected;
4754         pr "    if (r[%d] != NULL) {\n" (List.length expected);
4755         pr "      fprintf (stderr, \"%s: extra elements returned from command\\n\");\n"
4756           test_name;
4757         pr "      print_strings (r);\n";
4758         pr "      return -1;\n";
4759         pr "    }\n"
4760       in
4761       List.iter (generate_test_command_call test_name) seq;
4762       generate_test_command_call ~test test_name last
4763   | TestOutputInt (seq, expected) ->
4764       pr "  /* TestOutputInt for %s (%d) */\n" name i;
4765       let seq, last = get_seq_last seq in
4766       let test () =
4767         pr "    if (r != %d) {\n" expected;
4768         pr "      fprintf (stderr, \"%s: expected %d but got %%d\\n\","
4769           test_name expected;
4770         pr "               (int) r);\n";
4771         pr "      return -1;\n";
4772         pr "    }\n"
4773       in
4774       List.iter (generate_test_command_call test_name) seq;
4775       generate_test_command_call ~test test_name last
4776   | TestOutputTrue seq ->
4777       pr "  /* TestOutputTrue for %s (%d) */\n" name i;
4778       let seq, last = get_seq_last seq in
4779       let test () =
4780         pr "    if (!r) {\n";
4781         pr "      fprintf (stderr, \"%s: expected true, got false\\n\");\n"
4782           test_name;
4783         pr "      return -1;\n";
4784         pr "    }\n"
4785       in
4786       List.iter (generate_test_command_call test_name) seq;
4787       generate_test_command_call ~test test_name last
4788   | TestOutputFalse seq ->
4789       pr "  /* TestOutputFalse for %s (%d) */\n" name i;
4790       let seq, last = get_seq_last seq in
4791       let test () =
4792         pr "    if (r) {\n";
4793         pr "      fprintf (stderr, \"%s: expected false, got true\\n\");\n"
4794           test_name;
4795         pr "      return -1;\n";
4796         pr "    }\n"
4797       in
4798       List.iter (generate_test_command_call test_name) seq;
4799       generate_test_command_call ~test test_name last
4800   | TestOutputLength (seq, expected) ->
4801       pr "  /* TestOutputLength for %s (%d) */\n" name i;
4802       let seq, last = get_seq_last seq in
4803       let test () =
4804         pr "    int j;\n";
4805         pr "    for (j = 0; j < %d; ++j)\n" expected;
4806         pr "      if (r[j] == NULL) {\n";
4807         pr "        fprintf (stderr, \"%s: short list returned\\n\");\n"
4808           test_name;
4809         pr "        print_strings (r);\n";
4810         pr "        return -1;\n";
4811         pr "      }\n";
4812         pr "    if (r[j] != NULL) {\n";
4813         pr "      fprintf (stderr, \"%s: long list returned\\n\");\n"
4814           test_name;
4815         pr "      print_strings (r);\n";
4816         pr "      return -1;\n";
4817         pr "    }\n"
4818       in
4819       List.iter (generate_test_command_call test_name) seq;
4820       generate_test_command_call ~test test_name last
4821   | TestOutputStruct (seq, checks) ->
4822       pr "  /* TestOutputStruct for %s (%d) */\n" name i;
4823       let seq, last = get_seq_last seq in
4824       let test () =
4825         List.iter (
4826           function
4827           | CompareWithInt (field, expected) ->
4828               pr "    if (r->%s != %d) {\n" field expected;
4829               pr "      fprintf (stderr, \"%s: %s was %%d, expected %d\\n\",\n"
4830                 test_name field expected;
4831               pr "               (int) r->%s);\n" field;
4832               pr "      return -1;\n";
4833               pr "    }\n"
4834           | CompareWithString (field, expected) ->
4835               pr "    if (strcmp (r->%s, \"%s\") != 0) {\n" field expected;
4836               pr "      fprintf (stderr, \"%s: %s was \"%%s\", expected \"%s\"\\n\",\n"
4837                 test_name field expected;
4838               pr "               r->%s);\n" field;
4839               pr "      return -1;\n";
4840               pr "    }\n"
4841           | CompareFieldsIntEq (field1, field2) ->
4842               pr "    if (r->%s != r->%s) {\n" field1 field2;
4843               pr "      fprintf (stderr, \"%s: %s (%%d) <> %s (%%d)\\n\",\n"
4844                 test_name field1 field2;
4845               pr "               (int) r->%s, (int) r->%s);\n" field1 field2;
4846               pr "      return -1;\n";
4847               pr "    }\n"
4848           | CompareFieldsStrEq (field1, field2) ->
4849               pr "    if (strcmp (r->%s, r->%s) != 0) {\n" field1 field2;
4850               pr "      fprintf (stderr, \"%s: %s (\"%%s\") <> %s (\"%%s\")\\n\",\n"
4851                 test_name field1 field2;
4852               pr "               r->%s, r->%s);\n" field1 field2;
4853               pr "      return -1;\n";
4854               pr "    }\n"
4855         ) checks
4856       in
4857       List.iter (generate_test_command_call test_name) seq;
4858       generate_test_command_call ~test test_name last
4859   | TestLastFail seq ->
4860       pr "  /* TestLastFail for %s (%d) */\n" name i;
4861       let seq, last = get_seq_last seq in
4862       List.iter (generate_test_command_call test_name) seq;
4863       generate_test_command_call test_name ~expect_error:true last
4864
4865 (* Generate the code to run a command, leaving the result in 'r'.
4866  * If you expect to get an error then you should set expect_error:true.
4867  *)
4868 and generate_test_command_call ?(expect_error = false) ?test test_name cmd =
4869   match cmd with
4870   | [] -> assert false
4871   | name :: args ->
4872       (* Look up the command to find out what args/ret it has. *)
4873       let style =
4874         try
4875           let _, style, _, _, _, _, _ =
4876             List.find (fun (n, _, _, _, _, _, _) -> n = name) all_functions in
4877           style
4878         with Not_found ->
4879           failwithf "%s: in test, command %s was not found" test_name name in
4880
4881       if List.length (snd style) <> List.length args then
4882         failwithf "%s: in test, wrong number of args given to %s"
4883           test_name name;
4884
4885       pr "  {\n";
4886
4887       List.iter (
4888         function
4889         | OptString n, "NULL" -> ()
4890         | String n, arg
4891         | OptString n, arg ->
4892             pr "    const char *%s = \"%s\";\n" n (c_quote arg);
4893         | Int _, _
4894         | Bool _, _
4895         | FileIn _, _ | FileOut _, _ -> ()
4896         | StringList n, arg ->
4897             let strs = string_split " " arg in
4898             iteri (
4899               fun i str ->
4900                 pr "    const char *%s_%d = \"%s\";\n" n i (c_quote str);
4901             ) strs;
4902             pr "    const char *%s[] = {\n" n;
4903             iteri (
4904               fun i _ -> pr "      %s_%d,\n" n i
4905             ) strs;
4906             pr "      NULL\n";
4907             pr "    };\n";
4908       ) (List.combine (snd style) args);
4909
4910       let error_code =
4911         match fst style with
4912         | RErr | RInt _ | RBool _ -> pr "    int r;\n"; "-1"
4913         | RInt64 _ -> pr "    int64_t r;\n"; "-1"
4914         | RConstString _ -> pr "    const char *r;\n"; "NULL"
4915         | RString _ -> pr "    char *r;\n"; "NULL"
4916         | RStringList _ | RHashtable _ ->
4917             pr "    char **r;\n";
4918             pr "    int i;\n";
4919             "NULL"
4920         | RStruct (_, typ) ->
4921             pr "    struct guestfs_%s *r;\n" typ; "NULL"
4922         | RStructList (_, typ) ->
4923             pr "    struct guestfs_%s_list *r;\n" typ; "NULL" in
4924
4925       pr "    suppress_error = %d;\n" (if expect_error then 1 else 0);
4926       pr "    r = guestfs_%s (g" name;
4927
4928       (* Generate the parameters. *)
4929       List.iter (
4930         function
4931         | OptString _, "NULL" -> pr ", NULL"
4932         | String n, _
4933         | OptString n, _ ->
4934             pr ", %s" n
4935         | FileIn _, arg | FileOut _, arg ->
4936             pr ", \"%s\"" (c_quote arg)
4937         | StringList n, _ ->
4938             pr ", %s" n
4939         | Int _, arg ->
4940             let i =
4941               try int_of_string arg
4942               with Failure "int_of_string" ->
4943                 failwithf "%s: expecting an int, but got '%s'" test_name arg in
4944             pr ", %d" i
4945         | Bool _, arg ->
4946             let b = bool_of_string arg in pr ", %d" (if b then 1 else 0)
4947       ) (List.combine (snd style) args);
4948
4949       pr ");\n";
4950       if not expect_error then
4951         pr "    if (r == %s)\n" error_code
4952       else
4953         pr "    if (r != %s)\n" error_code;
4954       pr "      return -1;\n";
4955
4956       (* Insert the test code. *)
4957       (match test with
4958        | None -> ()
4959        | Some f -> f ()
4960       );
4961
4962       (match fst style with
4963        | RErr | RInt _ | RInt64 _ | RBool _ | RConstString _ -> ()
4964        | RString _ -> pr "    free (r);\n"
4965        | RStringList _ | RHashtable _ ->
4966            pr "    for (i = 0; r[i] != NULL; ++i)\n";
4967            pr "      free (r[i]);\n";
4968            pr "    free (r);\n"
4969        | RStruct (_, typ) ->
4970            pr "    guestfs_free_%s (r);\n" typ
4971        | RStructList (_, typ) ->
4972            pr "    guestfs_free_%s_list (r);\n" typ
4973       );
4974
4975       pr "  }\n"
4976
4977 and c_quote str =
4978   let str = replace_str str "\r" "\\r" in
4979   let str = replace_str str "\n" "\\n" in
4980   let str = replace_str str "\t" "\\t" in
4981   let str = replace_str str "\000" "\\0" in
4982   str
4983
4984 (* Generate a lot of different functions for guestfish. *)
4985 and generate_fish_cmds () =
4986   generate_header CStyle GPLv2;
4987
4988   let all_functions =
4989     List.filter (
4990       fun (_, _, _, flags, _, _, _) -> not (List.mem NotInFish flags)
4991     ) all_functions in
4992   let all_functions_sorted =
4993     List.filter (
4994       fun (_, _, _, flags, _, _, _) -> not (List.mem NotInFish flags)
4995     ) all_functions_sorted in
4996
4997   pr "#include <stdio.h>\n";
4998   pr "#include <stdlib.h>\n";
4999   pr "#include <string.h>\n";
5000   pr "#include <inttypes.h>\n";
5001   pr "\n";
5002   pr "#include <guestfs.h>\n";
5003   pr "#include \"fish.h\"\n";
5004   pr "\n";
5005
5006   (* list_commands function, which implements guestfish -h *)
5007   pr "void list_commands (void)\n";
5008   pr "{\n";
5009   pr "  printf (\"    %%-16s     %%s\\n\", \"Command\", \"Description\");\n";
5010   pr "  list_builtin_commands ();\n";
5011   List.iter (
5012     fun (name, _, _, flags, _, shortdesc, _) ->
5013       let name = replace_char name '_' '-' in
5014       pr "  printf (\"%%-20s %%s\\n\", \"%s\", \"%s\");\n"
5015         name shortdesc
5016   ) all_functions_sorted;
5017   pr "  printf (\"    Use -h <cmd> / help <cmd> to show detailed help for a command.\\n\");\n";
5018   pr "}\n";
5019   pr "\n";
5020
5021   (* display_command function, which implements guestfish -h cmd *)
5022   pr "void display_command (const char *cmd)\n";
5023   pr "{\n";
5024   List.iter (
5025     fun (name, style, _, flags, _, shortdesc, longdesc) ->
5026       let name2 = replace_char name '_' '-' in
5027       let alias =
5028         try find_map (function FishAlias n -> Some n | _ -> None) flags
5029         with Not_found -> name in
5030       let longdesc = replace_str longdesc "C<guestfs_" "C<" in
5031       let synopsis =
5032         match snd style with
5033         | [] -> name2
5034         | args ->
5035             sprintf "%s <%s>"
5036               name2 (String.concat "> <" (List.map name_of_argt args)) in
5037
5038       let warnings =
5039         if List.mem ProtocolLimitWarning flags then
5040           ("\n\n" ^ protocol_limit_warning)
5041         else "" in
5042
5043       (* For DangerWillRobinson commands, we should probably have
5044        * guestfish prompt before allowing you to use them (especially
5045        * in interactive mode). XXX
5046        *)
5047       let warnings =
5048         warnings ^
5049           if List.mem DangerWillRobinson flags then
5050             ("\n\n" ^ danger_will_robinson)
5051           else "" in
5052
5053       let describe_alias =
5054         if name <> alias then
5055           sprintf "\n\nYou can use '%s' as an alias for this command." alias
5056         else "" in
5057
5058       pr "  if (";
5059       pr "strcasecmp (cmd, \"%s\") == 0" name;
5060       if name <> name2 then
5061         pr " || strcasecmp (cmd, \"%s\") == 0" name2;
5062       if name <> alias then
5063         pr " || strcasecmp (cmd, \"%s\") == 0" alias;
5064       pr ")\n";
5065       pr "    pod2text (\"%s - %s\", %S);\n"
5066         name2 shortdesc
5067         (" " ^ synopsis ^ "\n\n" ^ longdesc ^ warnings ^ describe_alias);
5068       pr "  else\n"
5069   ) all_functions;
5070   pr "    display_builtin_command (cmd);\n";
5071   pr "}\n";
5072   pr "\n";
5073
5074   (* print_* functions *)
5075   List.iter (
5076     fun (typ, cols) ->
5077       let needs_i =
5078         List.exists (function (_, FUUID) -> true | _ -> false) cols in
5079
5080       pr "static void print_%s (struct guestfs_%s *%s)\n" typ typ typ;
5081       pr "{\n";
5082       if needs_i then (
5083         pr "  int i;\n";
5084         pr "\n"
5085       );
5086       List.iter (
5087         function
5088         | name, FString ->
5089             pr "  printf (\"%s: %%s\\n\", %s->%s);\n" name typ name
5090         | name, FUUID ->
5091             pr "  printf (\"%s: \");\n" name;
5092             pr "  for (i = 0; i < 32; ++i)\n";
5093             pr "    printf (\"%%c\", %s->%s[i]);\n" typ name;
5094             pr "  printf (\"\\n\");\n"
5095         | name, (FUInt64|FBytes) ->
5096             pr "  printf (\"%s: %%\" PRIu64 \"\\n\", %s->%s);\n" name typ name
5097         | name, FInt64 ->
5098             pr "  printf (\"%s: %%\" PRIi64 \"\\n\", %s->%s);\n" name typ name
5099         | name, FUInt32 ->
5100             pr "  printf (\"%s: %%\" PRIu32 \"\\n\", %s->%s);\n" name typ name
5101         | name, FInt32 ->
5102             pr "  printf (\"%s: %%\" PRIi32 \"\\n\", %s->%s);\n" name typ name
5103         | name, FChar ->
5104             pr "  printf (\"%s: %%c\\n\", %s->%s);\n" name typ name
5105         | name, FOptPercent ->
5106             pr "  if (%s->%s >= 0) printf (\"%s: %%g %%%%\\n\", %s->%s);\n"
5107               typ name name typ name;
5108             pr "  else printf (\"%s: \\n\");\n" name
5109       ) cols;
5110       pr "}\n";
5111       pr "\n";
5112       pr "static void print_%s_list (struct guestfs_%s_list *%ss)\n"
5113         typ typ typ;
5114       pr "{\n";
5115       pr "  int i;\n";
5116       pr "\n";
5117       pr "  for (i = 0; i < %ss->len; ++i)\n" typ;
5118       pr "    print_%s (&%ss->val[i]);\n" typ typ;
5119       pr "}\n";
5120       pr "\n";
5121   ) structs;
5122
5123   (* run_<action> actions *)
5124   List.iter (
5125     fun (name, style, _, flags, _, _, _) ->
5126       pr "static int run_%s (const char *cmd, int argc, char *argv[])\n" name;
5127       pr "{\n";
5128       (match fst style with
5129        | RErr
5130        | RInt _
5131        | RBool _ -> pr "  int r;\n"
5132        | RInt64 _ -> pr "  int64_t r;\n"
5133        | RConstString _ -> pr "  const char *r;\n"
5134        | RString _ -> pr "  char *r;\n"
5135        | RStringList _ | RHashtable _ -> pr "  char **r;\n"
5136        | RStruct (_, typ) -> pr "  struct guestfs_%s *r;\n" typ
5137        | RStructList (_, typ) -> pr "  struct guestfs_%s_list *r;\n" typ
5138       );
5139       List.iter (
5140         function
5141         | String n
5142         | OptString n
5143         | FileIn n
5144         | FileOut n -> pr "  const char *%s;\n" n
5145         | StringList n -> pr "  char **%s;\n" n
5146         | Bool n -> pr "  int %s;\n" n
5147         | Int n -> pr "  int %s;\n" n
5148       ) (snd style);
5149
5150       (* Check and convert parameters. *)
5151       let argc_expected = List.length (snd style) in
5152       pr "  if (argc != %d) {\n" argc_expected;
5153       pr "    fprintf (stderr, \"%%s should have %d parameter(s)\\n\", cmd);\n"
5154         argc_expected;
5155       pr "    fprintf (stderr, \"type 'help %%s' for help on %%s\\n\", cmd, cmd);\n";
5156       pr "    return -1;\n";
5157       pr "  }\n";
5158       iteri (
5159         fun i ->
5160           function
5161           | String name -> pr "  %s = argv[%d];\n" name i
5162           | OptString name ->
5163               pr "  %s = strcmp (argv[%d], \"\") != 0 ? argv[%d] : NULL;\n"
5164                 name i i
5165           | FileIn name ->
5166               pr "  %s = strcmp (argv[%d], \"-\") != 0 ? argv[%d] : \"/dev/stdin\";\n"
5167                 name i i
5168           | FileOut name ->
5169               pr "  %s = strcmp (argv[%d], \"-\") != 0 ? argv[%d] : \"/dev/stdout\";\n"
5170                 name i i
5171           | StringList name ->
5172               pr "  %s = parse_string_list (argv[%d]);\n" name i
5173           | Bool name ->
5174               pr "  %s = is_true (argv[%d]) ? 1 : 0;\n" name i
5175           | Int name ->
5176               pr "  %s = atoi (argv[%d]);\n" name i
5177       ) (snd style);
5178
5179       (* Call C API function. *)
5180       let fn =
5181         try find_map (function FishAction n -> Some n | _ -> None) flags
5182         with Not_found -> sprintf "guestfs_%s" name in
5183       pr "  r = %s " fn;
5184       generate_call_args ~handle:"g" (snd style);
5185       pr ";\n";
5186
5187       (* Check return value for errors and display command results. *)
5188       (match fst style with
5189        | RErr -> pr "  return r;\n"
5190        | RInt _ ->
5191            pr "  if (r == -1) return -1;\n";
5192            pr "  printf (\"%%d\\n\", r);\n";
5193            pr "  return 0;\n"
5194        | RInt64 _ ->
5195            pr "  if (r == -1) return -1;\n";
5196            pr "  printf (\"%%\" PRIi64 \"\\n\", r);\n";
5197            pr "  return 0;\n"
5198        | RBool _ ->
5199            pr "  if (r == -1) return -1;\n";
5200            pr "  if (r) printf (\"true\\n\"); else printf (\"false\\n\");\n";
5201            pr "  return 0;\n"
5202        | RConstString _ ->
5203            pr "  if (r == NULL) return -1;\n";
5204            pr "  printf (\"%%s\\n\", r);\n";
5205            pr "  return 0;\n"
5206        | RString _ ->
5207            pr "  if (r == NULL) return -1;\n";
5208            pr "  printf (\"%%s\\n\", r);\n";
5209            pr "  free (r);\n";
5210            pr "  return 0;\n"
5211        | RStringList _ ->
5212            pr "  if (r == NULL) return -1;\n";
5213            pr "  print_strings (r);\n";
5214            pr "  free_strings (r);\n";
5215            pr "  return 0;\n"
5216        | RStruct (_, typ) ->
5217            pr "  if (r == NULL) return -1;\n";
5218            pr "  print_%s (r);\n" typ;
5219            pr "  guestfs_free_%s (r);\n" typ;
5220            pr "  return 0;\n"
5221        | RStructList (_, typ) ->
5222            pr "  if (r == NULL) return -1;\n";
5223            pr "  print_%s_list (r);\n" typ;
5224            pr "  guestfs_free_%s_list (r);\n" typ;
5225            pr "  return 0;\n"
5226        | RHashtable _ ->
5227            pr "  if (r == NULL) return -1;\n";
5228            pr "  print_table (r);\n";
5229            pr "  free_strings (r);\n";
5230            pr "  return 0;\n"
5231       );
5232       pr "}\n";
5233       pr "\n"
5234   ) all_functions;
5235
5236   (* run_action function *)
5237   pr "int run_action (const char *cmd, int argc, char *argv[])\n";
5238   pr "{\n";
5239   List.iter (
5240     fun (name, _, _, flags, _, _, _) ->
5241       let name2 = replace_char name '_' '-' in
5242       let alias =
5243         try find_map (function FishAlias n -> Some n | _ -> None) flags
5244         with Not_found -> name in
5245       pr "  if (";
5246       pr "strcasecmp (cmd, \"%s\") == 0" name;
5247       if name <> name2 then
5248         pr " || strcasecmp (cmd, \"%s\") == 0" name2;
5249       if name <> alias then
5250         pr " || strcasecmp (cmd, \"%s\") == 0" alias;
5251       pr ")\n";
5252       pr "    return run_%s (cmd, argc, argv);\n" name;
5253       pr "  else\n";
5254   ) all_functions;
5255   pr "    {\n";
5256   pr "      fprintf (stderr, \"%%s: unknown command\\n\", cmd);\n";
5257   pr "      return -1;\n";
5258   pr "    }\n";
5259   pr "  return 0;\n";
5260   pr "}\n";
5261   pr "\n"
5262
5263 (* Readline completion for guestfish. *)
5264 and generate_fish_completion () =
5265   generate_header CStyle GPLv2;
5266
5267   let all_functions =
5268     List.filter (
5269       fun (_, _, _, flags, _, _, _) -> not (List.mem NotInFish flags)
5270     ) all_functions in
5271
5272   pr "\
5273 #include <config.h>
5274
5275 #include <stdio.h>
5276 #include <stdlib.h>
5277 #include <string.h>
5278
5279 #ifdef HAVE_LIBREADLINE
5280 #include <readline/readline.h>
5281 #endif
5282
5283 #include \"fish.h\"
5284
5285 #ifdef HAVE_LIBREADLINE
5286
5287 static const char *const commands[] = {
5288   BUILTIN_COMMANDS_FOR_COMPLETION,
5289 ";
5290
5291   (* Get the commands, including the aliases.  They don't need to be
5292    * sorted - the generator() function just does a dumb linear search.
5293    *)
5294   let commands =
5295     List.map (
5296       fun (name, _, _, flags, _, _, _) ->
5297         let name2 = replace_char name '_' '-' in
5298         let alias =
5299           try find_map (function FishAlias n -> Some n | _ -> None) flags
5300           with Not_found -> name in
5301
5302         if name <> alias then [name2; alias] else [name2]
5303     ) all_functions in
5304   let commands = List.flatten commands in
5305
5306   List.iter (pr "  \"%s\",\n") commands;
5307
5308   pr "  NULL
5309 };
5310
5311 static char *
5312 generator (const char *text, int state)
5313 {
5314   static int index, len;
5315   const char *name;
5316
5317   if (!state) {
5318     index = 0;
5319     len = strlen (text);
5320   }
5321
5322   rl_attempted_completion_over = 1;
5323
5324   while ((name = commands[index]) != NULL) {
5325     index++;
5326     if (strncasecmp (name, text, len) == 0)
5327       return strdup (name);
5328   }
5329
5330   return NULL;
5331 }
5332
5333 #endif /* HAVE_LIBREADLINE */
5334
5335 char **do_completion (const char *text, int start, int end)
5336 {
5337   char **matches = NULL;
5338
5339 #ifdef HAVE_LIBREADLINE
5340   rl_completion_append_character = ' ';
5341
5342   if (start == 0)
5343     matches = rl_completion_matches (text, generator);
5344   else if (complete_dest_paths)
5345     matches = rl_completion_matches (text, complete_dest_paths_generator);
5346 #endif
5347
5348   return matches;
5349 }
5350 ";
5351
5352 (* Generate the POD documentation for guestfish. *)
5353 and generate_fish_actions_pod () =
5354   let all_functions_sorted =
5355     List.filter (
5356       fun (_, _, _, flags, _, _, _) ->
5357         not (List.mem NotInFish flags || List.mem NotInDocs flags)
5358     ) all_functions_sorted in
5359
5360   let rex = Str.regexp "C<guestfs_\\([^>]+\\)>" in
5361
5362   List.iter (
5363     fun (name, style, _, flags, _, _, longdesc) ->
5364       let longdesc =
5365         Str.global_substitute rex (
5366           fun s ->
5367             let sub =
5368               try Str.matched_group 1 s
5369               with Not_found ->
5370                 failwithf "error substituting C<guestfs_...> in longdesc of function %s" name in
5371             "C<" ^ replace_char sub '_' '-' ^ ">"
5372         ) longdesc in
5373       let name = replace_char name '_' '-' in
5374       let alias =
5375         try find_map (function FishAlias n -> Some n | _ -> None) flags
5376         with Not_found -> name in
5377
5378       pr "=head2 %s" name;
5379       if name <> alias then
5380         pr " | %s" alias;
5381       pr "\n";
5382       pr "\n";
5383       pr " %s" name;
5384       List.iter (
5385         function
5386         | String n -> pr " %s" n
5387         | OptString n -> pr " %s" n
5388         | StringList n -> pr " '%s ...'" n
5389         | Bool _ -> pr " true|false"
5390         | Int n -> pr " %s" n
5391         | FileIn n | FileOut n -> pr " (%s|-)" n
5392       ) (snd style);
5393       pr "\n";
5394       pr "\n";
5395       pr "%s\n\n" longdesc;
5396
5397       if List.exists (function FileIn _ | FileOut _ -> true
5398                       | _ -> false) (snd style) then
5399         pr "Use C<-> instead of a filename to read/write from stdin/stdout.\n\n";
5400
5401       if List.mem ProtocolLimitWarning flags then
5402         pr "%s\n\n" protocol_limit_warning;
5403
5404       if List.mem DangerWillRobinson flags then
5405         pr "%s\n\n" danger_will_robinson
5406   ) all_functions_sorted
5407
5408 (* Generate a C function prototype. *)
5409 and generate_prototype ?(extern = true) ?(static = false) ?(semicolon = true)
5410     ?(single_line = false) ?(newline = false) ?(in_daemon = false)
5411     ?(prefix = "")
5412     ?handle name style =
5413   if extern then pr "extern ";
5414   if static then pr "static ";
5415   (match fst style with
5416    | RErr -> pr "int "
5417    | RInt _ -> pr "int "
5418    | RInt64 _ -> pr "int64_t "
5419    | RBool _ -> pr "int "
5420    | RConstString _ -> pr "const char *"
5421    | RString _ -> pr "char *"
5422    | RStringList _ | RHashtable _ -> pr "char **"
5423    | RStruct (_, typ) ->
5424        if not in_daemon then pr "struct guestfs_%s *" typ
5425        else pr "guestfs_int_%s *" typ
5426    | RStructList (_, typ) ->
5427        if not in_daemon then pr "struct guestfs_%s_list *" typ
5428        else pr "guestfs_int_%s_list *" typ
5429   );
5430   pr "%s%s (" prefix name;
5431   if handle = None && List.length (snd style) = 0 then
5432     pr "void"
5433   else (
5434     let comma = ref false in
5435     (match handle with
5436      | None -> ()
5437      | Some handle -> pr "guestfs_h *%s" handle; comma := true
5438     );
5439     let next () =
5440       if !comma then (
5441         if single_line then pr ", " else pr ",\n\t\t"
5442       );
5443       comma := true
5444     in
5445     List.iter (
5446       function
5447       | String n
5448       | OptString n ->
5449           next ();
5450           if not in_daemon then pr "const char *%s" n
5451           else pr "char *%s" n
5452       | StringList n ->
5453           next ();
5454           if not in_daemon then pr "char * const* const %s" n
5455           else pr "char **%s" n
5456       | Bool n -> next (); pr "int %s" n
5457       | Int n -> next (); pr "int %s" n
5458       | FileIn n
5459       | FileOut n ->
5460           if not in_daemon then (next (); pr "const char *%s" n)
5461     ) (snd style);
5462   );
5463   pr ")";
5464   if semicolon then pr ";";
5465   if newline then pr "\n"
5466
5467 (* Generate C call arguments, eg "(handle, foo, bar)" *)
5468 and generate_call_args ?handle args =
5469   pr "(";
5470   let comma = ref false in
5471   (match handle with
5472    | None -> ()
5473    | Some handle -> pr "%s" handle; comma := true
5474   );
5475   List.iter (
5476     fun arg ->
5477       if !comma then pr ", ";
5478       comma := true;
5479       pr "%s" (name_of_argt arg)
5480   ) args;
5481   pr ")"
5482
5483 (* Generate the OCaml bindings interface. *)
5484 and generate_ocaml_mli () =
5485   generate_header OCamlStyle LGPLv2;
5486
5487   pr "\
5488 (** For API documentation you should refer to the C API
5489     in the guestfs(3) manual page.  The OCaml API uses almost
5490     exactly the same calls. *)
5491
5492 type t
5493 (** A [guestfs_h] handle. *)
5494
5495 exception Error of string
5496 (** This exception is raised when there is an error. *)
5497
5498 val create : unit -> t
5499
5500 val close : t -> unit
5501 (** Handles are closed by the garbage collector when they become
5502     unreferenced, but callers can also call this in order to
5503     provide predictable cleanup. *)
5504
5505 ";
5506   generate_ocaml_structure_decls ();
5507
5508   (* The actions. *)
5509   List.iter (
5510     fun (name, style, _, _, _, shortdesc, _) ->
5511       generate_ocaml_prototype name style;
5512       pr "(** %s *)\n" shortdesc;
5513       pr "\n"
5514   ) all_functions
5515
5516 (* Generate the OCaml bindings implementation. *)
5517 and generate_ocaml_ml () =
5518   generate_header OCamlStyle LGPLv2;
5519
5520   pr "\
5521 type t
5522 exception Error of string
5523 external create : unit -> t = \"ocaml_guestfs_create\"
5524 external close : t -> unit = \"ocaml_guestfs_close\"
5525
5526 let () =
5527   Callback.register_exception \"ocaml_guestfs_error\" (Error \"\")
5528
5529 ";
5530
5531   generate_ocaml_structure_decls ();
5532
5533   (* The actions. *)
5534   List.iter (
5535     fun (name, style, _, _, _, shortdesc, _) ->
5536       generate_ocaml_prototype ~is_external:true name style;
5537   ) all_functions
5538
5539 (* Generate the OCaml bindings C implementation. *)
5540 and generate_ocaml_c () =
5541   generate_header CStyle LGPLv2;
5542
5543   pr "\
5544 #include <stdio.h>
5545 #include <stdlib.h>
5546 #include <string.h>
5547
5548 #include <caml/config.h>
5549 #include <caml/alloc.h>
5550 #include <caml/callback.h>
5551 #include <caml/fail.h>
5552 #include <caml/memory.h>
5553 #include <caml/mlvalues.h>
5554 #include <caml/signals.h>
5555
5556 #include <guestfs.h>
5557
5558 #include \"guestfs_c.h\"
5559
5560 /* Copy a hashtable of string pairs into an assoc-list.  We return
5561  * the list in reverse order, but hashtables aren't supposed to be
5562  * ordered anyway.
5563  */
5564 static CAMLprim value
5565 copy_table (char * const * argv)
5566 {
5567   CAMLparam0 ();
5568   CAMLlocal5 (rv, pairv, kv, vv, cons);
5569   int i;
5570
5571   rv = Val_int (0);
5572   for (i = 0; argv[i] != NULL; i += 2) {
5573     kv = caml_copy_string (argv[i]);
5574     vv = caml_copy_string (argv[i+1]);
5575     pairv = caml_alloc (2, 0);
5576     Store_field (pairv, 0, kv);
5577     Store_field (pairv, 1, vv);
5578     cons = caml_alloc (2, 0);
5579     Store_field (cons, 1, rv);
5580     rv = cons;
5581     Store_field (cons, 0, pairv);
5582   }
5583
5584   CAMLreturn (rv);
5585 }
5586
5587 ";
5588
5589   (* Struct copy functions. *)
5590   List.iter (
5591     fun (typ, cols) ->
5592       let has_optpercent_col =
5593         List.exists (function (_, FOptPercent) -> true | _ -> false) cols in
5594
5595       pr "static CAMLprim value\n";
5596       pr "copy_%s (const struct guestfs_%s *%s)\n" typ typ typ;
5597       pr "{\n";
5598       pr "  CAMLparam0 ();\n";
5599       if has_optpercent_col then
5600         pr "  CAMLlocal3 (rv, v, v2);\n"
5601       else
5602         pr "  CAMLlocal2 (rv, v);\n";
5603       pr "\n";
5604       pr "  rv = caml_alloc (%d, 0);\n" (List.length cols);
5605       iteri (
5606         fun i col ->
5607           (match col with
5608            | name, FString ->
5609                pr "  v = caml_copy_string (%s->%s);\n" typ name
5610            | name, FUUID ->
5611                pr "  v = caml_alloc_string (32);\n";
5612                pr "  memcpy (String_val (v), %s->%s, 32);\n" typ name
5613            | name, (FBytes|FInt64|FUInt64) ->
5614                pr "  v = caml_copy_int64 (%s->%s);\n" typ name
5615            | name, (FInt32|FUInt32) ->
5616                pr "  v = caml_copy_int32 (%s->%s);\n" typ name
5617            | name, FOptPercent ->
5618                pr "  if (%s->%s >= 0) { /* Some %s */\n" typ name name;
5619                pr "    v2 = caml_copy_double (%s->%s);\n" typ name;
5620                pr "    v = caml_alloc (1, 0);\n";
5621                pr "    Store_field (v, 0, v2);\n";
5622                pr "  } else /* None */\n";
5623                pr "    v = Val_int (0);\n";
5624            | name, FChar ->
5625                pr "  v = Val_int (%s->%s);\n" typ name
5626           );
5627           pr "  Store_field (rv, %d, v);\n" i
5628       ) cols;
5629       pr "  CAMLreturn (rv);\n";
5630       pr "}\n";
5631       pr "\n";
5632
5633       pr "static CAMLprim value\n";
5634       pr "copy_%s_list (const struct guestfs_%s_list *%ss)\n"
5635         typ typ typ;
5636       pr "{\n";
5637       pr "  CAMLparam0 ();\n";
5638       pr "  CAMLlocal2 (rv, v);\n";
5639       pr "  int i;\n";
5640       pr "\n";
5641       pr "  if (%ss->len == 0)\n" typ;
5642       pr "    CAMLreturn (Atom (0));\n";
5643       pr "  else {\n";
5644       pr "    rv = caml_alloc (%ss->len, 0);\n" typ;
5645       pr "    for (i = 0; i < %ss->len; ++i) {\n" typ;
5646       pr "      v = copy_%s (&%ss->val[i]);\n" typ typ;
5647       pr "      caml_modify (&Field (rv, i), v);\n";
5648       pr "    }\n";
5649       pr "    CAMLreturn (rv);\n";
5650       pr "  }\n";
5651       pr "}\n";
5652       pr "\n";
5653   ) structs;
5654
5655   (* The wrappers. *)
5656   List.iter (
5657     fun (name, style, _, _, _, _, _) ->
5658       let params =
5659         "gv" :: List.map (fun arg -> name_of_argt arg ^ "v") (snd style) in
5660
5661       pr "CAMLprim value\n";
5662       pr "ocaml_guestfs_%s (value %s" name (List.hd params);
5663       List.iter (pr ", value %s") (List.tl params);
5664       pr ")\n";
5665       pr "{\n";
5666
5667       (match params with
5668        | [p1; p2; p3; p4; p5] ->
5669            pr "  CAMLparam5 (%s);\n" (String.concat ", " params)
5670        | p1 :: p2 :: p3 :: p4 :: p5 :: rest ->
5671            pr "  CAMLparam5 (%s);\n" (String.concat ", " [p1; p2; p3; p4; p5]);
5672            pr "  CAMLxparam%d (%s);\n"
5673              (List.length rest) (String.concat ", " rest)
5674        | ps ->
5675            pr "  CAMLparam%d (%s);\n" (List.length ps) (String.concat ", " ps)
5676       );
5677       pr "  CAMLlocal1 (rv);\n";
5678       pr "\n";
5679
5680       pr "  guestfs_h *g = Guestfs_val (gv);\n";
5681       pr "  if (g == NULL)\n";
5682       pr "    caml_failwith (\"%s: used handle after closing it\");\n" name;
5683       pr "\n";
5684
5685       List.iter (
5686         function
5687         | String n
5688         | FileIn n
5689         | FileOut n ->
5690             pr "  const char *%s = String_val (%sv);\n" n n
5691         | OptString n ->
5692             pr "  const char *%s =\n" n;
5693             pr "    %sv != Val_int (0) ? String_val (Field (%sv, 0)) : NULL;\n"
5694               n n
5695         | StringList n ->
5696             pr "  char **%s = ocaml_guestfs_strings_val (g, %sv);\n" n n
5697         | Bool n ->
5698             pr "  int %s = Bool_val (%sv);\n" n n
5699         | Int n ->
5700             pr "  int %s = Int_val (%sv);\n" n n
5701       ) (snd style);
5702       let error_code =
5703         match fst style with
5704         | RErr -> pr "  int r;\n"; "-1"
5705         | RInt _ -> pr "  int r;\n"; "-1"
5706         | RInt64 _ -> pr "  int64_t r;\n"; "-1"
5707         | RBool _ -> pr "  int r;\n"; "-1"
5708         | RConstString _ -> pr "  const char *r;\n"; "NULL"
5709         | RString _ -> pr "  char *r;\n"; "NULL"
5710         | RStringList _ ->
5711             pr "  int i;\n";
5712             pr "  char **r;\n";
5713             "NULL"
5714         | RStruct (_, typ) ->
5715             pr "  struct guestfs_%s *r;\n" typ; "NULL"
5716         | RStructList (_, typ) ->
5717             pr "  struct guestfs_%s_list *r;\n" typ; "NULL"
5718         | RHashtable _ ->
5719             pr "  int i;\n";
5720             pr "  char **r;\n";
5721             "NULL" in
5722       pr "\n";
5723
5724       pr "  caml_enter_blocking_section ();\n";
5725       pr "  r = guestfs_%s " name;
5726       generate_call_args ~handle:"g" (snd style);
5727       pr ";\n";
5728       pr "  caml_leave_blocking_section ();\n";
5729
5730       List.iter (
5731         function
5732         | StringList n ->
5733             pr "  ocaml_guestfs_free_strings (%s);\n" n;
5734         | String _ | OptString _ | Bool _ | Int _ | FileIn _ | FileOut _ -> ()
5735       ) (snd style);
5736
5737       pr "  if (r == %s)\n" error_code;
5738       pr "    ocaml_guestfs_raise_error (g, \"%s\");\n" name;
5739       pr "\n";
5740
5741       (match fst style with
5742        | RErr -> pr "  rv = Val_unit;\n"
5743        | RInt _ -> pr "  rv = Val_int (r);\n"
5744        | RInt64 _ ->
5745            pr "  rv = caml_copy_int64 (r);\n"
5746        | RBool _ -> pr "  rv = Val_bool (r);\n"
5747        | RConstString _ -> pr "  rv = caml_copy_string (r);\n"
5748        | RString _ ->
5749            pr "  rv = caml_copy_string (r);\n";
5750            pr "  free (r);\n"
5751        | RStringList _ ->
5752            pr "  rv = caml_copy_string_array ((const char **) r);\n";
5753            pr "  for (i = 0; r[i] != NULL; ++i) free (r[i]);\n";
5754            pr "  free (r);\n"
5755        | RStruct (_, typ) ->
5756            pr "  rv = copy_%s (r);\n" typ;
5757            pr "  guestfs_free_%s (r);\n" typ;
5758        | RStructList (_, typ) ->
5759            pr "  rv = copy_%s_list (r);\n" typ;
5760            pr "  guestfs_free_%s_list (r);\n" typ;
5761        | RHashtable _ ->
5762            pr "  rv = copy_table (r);\n";
5763            pr "  for (i = 0; r[i] != NULL; ++i) free (r[i]);\n";
5764            pr "  free (r);\n";
5765       );
5766
5767       pr "  CAMLreturn (rv);\n";
5768       pr "}\n";
5769       pr "\n";
5770
5771       if List.length params > 5 then (
5772         pr "CAMLprim value\n";
5773         pr "ocaml_guestfs_%s_byte (value *argv, int argn)\n" name;
5774         pr "{\n";
5775         pr "  return ocaml_guestfs_%s (argv[0]" name;
5776         iteri (fun i _ -> pr ", argv[%d]" i) (List.tl params);
5777         pr ");\n";
5778         pr "}\n";
5779         pr "\n"
5780       )
5781   ) all_functions
5782
5783 and generate_ocaml_structure_decls () =
5784   List.iter (
5785     fun (typ, cols) ->
5786       pr "type %s = {\n" typ;
5787       List.iter (
5788         function
5789         | name, FString -> pr "  %s : string;\n" name
5790         | name, FUUID -> pr "  %s : string;\n" name
5791         | name, (FBytes|FInt64|FUInt64) -> pr "  %s : int64;\n" name
5792         | name, (FInt32|FUInt32) -> pr "  %s : int32;\n" name
5793         | name, FChar -> pr "  %s : char;\n" name
5794         | name, FOptPercent -> pr "  %s : float option;\n" name
5795       ) cols;
5796       pr "}\n";
5797       pr "\n"
5798   ) structs
5799
5800 and generate_ocaml_prototype ?(is_external = false) name style =
5801   if is_external then pr "external " else pr "val ";
5802   pr "%s : t -> " name;
5803   List.iter (
5804     function
5805     | String _ | FileIn _ | FileOut _ -> pr "string -> "
5806     | OptString _ -> pr "string option -> "
5807     | StringList _ -> pr "string array -> "
5808     | Bool _ -> pr "bool -> "
5809     | Int _ -> pr "int -> "
5810   ) (snd style);
5811   (match fst style with
5812    | RErr -> pr "unit" (* all errors are turned into exceptions *)
5813    | RInt _ -> pr "int"
5814    | RInt64 _ -> pr "int64"
5815    | RBool _ -> pr "bool"
5816    | RConstString _ -> pr "string"
5817    | RString _ -> pr "string"
5818    | RStringList _ -> pr "string array"
5819    | RStruct (_, typ) -> pr "%s" typ
5820    | RStructList (_, typ) -> pr "%s array" typ
5821    | RHashtable _ -> pr "(string * string) list"
5822   );
5823   if is_external then (
5824     pr " = ";
5825     if List.length (snd style) + 1 > 5 then
5826       pr "\"ocaml_guestfs_%s_byte\" " name;
5827     pr "\"ocaml_guestfs_%s\"" name
5828   );
5829   pr "\n"
5830
5831 (* Generate Perl xs code, a sort of crazy variation of C with macros. *)
5832 and generate_perl_xs () =
5833   generate_header CStyle LGPLv2;
5834
5835   pr "\
5836 #include \"EXTERN.h\"
5837 #include \"perl.h\"
5838 #include \"XSUB.h\"
5839
5840 #include <guestfs.h>
5841
5842 #ifndef PRId64
5843 #define PRId64 \"lld\"
5844 #endif
5845
5846 static SV *
5847 my_newSVll(long long val) {
5848 #ifdef USE_64_BIT_ALL
5849   return newSViv(val);
5850 #else
5851   char buf[100];
5852   int len;
5853   len = snprintf(buf, 100, \"%%\" PRId64, val);
5854   return newSVpv(buf, len);
5855 #endif
5856 }
5857
5858 #ifndef PRIu64
5859 #define PRIu64 \"llu\"
5860 #endif
5861
5862 static SV *
5863 my_newSVull(unsigned long long val) {
5864 #ifdef USE_64_BIT_ALL
5865   return newSVuv(val);
5866 #else
5867   char buf[100];
5868   int len;
5869   len = snprintf(buf, 100, \"%%\" PRIu64, val);
5870   return newSVpv(buf, len);
5871 #endif
5872 }
5873
5874 /* http://www.perlmonks.org/?node_id=680842 */
5875 static char **
5876 XS_unpack_charPtrPtr (SV *arg) {
5877   char **ret;
5878   AV *av;
5879   I32 i;
5880
5881   if (!arg || !SvOK (arg) || !SvROK (arg) || SvTYPE (SvRV (arg)) != SVt_PVAV)
5882     croak (\"array reference expected\");
5883
5884   av = (AV *)SvRV (arg);
5885   ret = malloc ((av_len (av) + 1 + 1) * sizeof (char *));
5886   if (!ret)
5887     croak (\"malloc failed\");
5888
5889   for (i = 0; i <= av_len (av); i++) {
5890     SV **elem = av_fetch (av, i, 0);
5891
5892     if (!elem || !*elem)
5893       croak (\"missing element in list\");
5894
5895     ret[i] = SvPV_nolen (*elem);
5896   }
5897
5898   ret[i] = NULL;
5899
5900   return ret;
5901 }
5902
5903 MODULE = Sys::Guestfs  PACKAGE = Sys::Guestfs
5904
5905 PROTOTYPES: ENABLE
5906
5907 guestfs_h *
5908 _create ()
5909    CODE:
5910       RETVAL = guestfs_create ();
5911       if (!RETVAL)
5912         croak (\"could not create guestfs handle\");
5913       guestfs_set_error_handler (RETVAL, NULL, NULL);
5914  OUTPUT:
5915       RETVAL
5916
5917 void
5918 DESTROY (g)
5919       guestfs_h *g;
5920  PPCODE:
5921       guestfs_close (g);
5922
5923 ";
5924
5925   List.iter (
5926     fun (name, style, _, _, _, _, _) ->
5927       (match fst style with
5928        | RErr -> pr "void\n"
5929        | RInt _ -> pr "SV *\n"
5930        | RInt64 _ -> pr "SV *\n"
5931        | RBool _ -> pr "SV *\n"
5932        | RConstString _ -> pr "SV *\n"
5933        | RString _ -> pr "SV *\n"
5934        | RStringList _
5935        | RStruct _ | RStructList _
5936        | RHashtable _ ->
5937            pr "void\n" (* all lists returned implictly on the stack *)
5938       );
5939       (* Call and arguments. *)
5940       pr "%s " name;
5941       generate_call_args ~handle:"g" (snd style);
5942       pr "\n";
5943       pr "      guestfs_h *g;\n";
5944       iteri (
5945         fun i ->
5946           function
5947           | String n | FileIn n | FileOut n -> pr "      char *%s;\n" n
5948           | OptString n ->
5949               (* http://www.perlmonks.org/?node_id=554277
5950                * Note that the implicit handle argument means we have
5951                * to add 1 to the ST(x) operator.
5952                *)
5953               pr "      char *%s = SvOK(ST(%d)) ? SvPV_nolen(ST(%d)) : NULL;\n" n (i+1) (i+1)
5954           | StringList n -> pr "      char **%s;\n" n
5955           | Bool n -> pr "      int %s;\n" n
5956           | Int n -> pr "      int %s;\n" n
5957       ) (snd style);
5958
5959       let do_cleanups () =
5960         List.iter (
5961           function
5962           | String _ | OptString _ | Bool _ | Int _
5963           | FileIn _ | FileOut _ -> ()
5964           | StringList n -> pr "      free (%s);\n" n
5965         ) (snd style)
5966       in
5967
5968       (* Code. *)
5969       (match fst style with
5970        | RErr ->
5971            pr "PREINIT:\n";
5972            pr "      int r;\n";
5973            pr " PPCODE:\n";
5974            pr "      r = guestfs_%s " name;
5975            generate_call_args ~handle:"g" (snd style);
5976            pr ";\n";
5977            do_cleanups ();
5978            pr "      if (r == -1)\n";
5979            pr "        croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5980        | RInt n
5981        | RBool n ->
5982            pr "PREINIT:\n";
5983            pr "      int %s;\n" n;
5984            pr "   CODE:\n";
5985            pr "      %s = guestfs_%s " n name;
5986            generate_call_args ~handle:"g" (snd style);
5987            pr ";\n";
5988            do_cleanups ();
5989            pr "      if (%s == -1)\n" n;
5990            pr "        croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
5991            pr "      RETVAL = newSViv (%s);\n" n;
5992            pr " OUTPUT:\n";
5993            pr "      RETVAL\n"
5994        | RInt64 n ->
5995            pr "PREINIT:\n";
5996            pr "      int64_t %s;\n" n;
5997            pr "   CODE:\n";
5998            pr "      %s = guestfs_%s " n name;
5999            generate_call_args ~handle:"g" (snd style);
6000            pr ";\n";
6001            do_cleanups ();
6002            pr "      if (%s == -1)\n" n;
6003            pr "        croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
6004            pr "      RETVAL = my_newSVll (%s);\n" n;
6005            pr " OUTPUT:\n";
6006            pr "      RETVAL\n"
6007        | RConstString n ->
6008            pr "PREINIT:\n";
6009            pr "      const char *%s;\n" n;
6010            pr "   CODE:\n";
6011            pr "      %s = guestfs_%s " n name;
6012            generate_call_args ~handle:"g" (snd style);
6013            pr ";\n";
6014            do_cleanups ();
6015            pr "      if (%s == NULL)\n" n;
6016            pr "        croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
6017            pr "      RETVAL = newSVpv (%s, 0);\n" n;
6018            pr " OUTPUT:\n";
6019            pr "      RETVAL\n"
6020        | RString n ->
6021            pr "PREINIT:\n";
6022            pr "      char *%s;\n" n;
6023            pr "   CODE:\n";
6024            pr "      %s = guestfs_%s " n name;
6025            generate_call_args ~handle:"g" (snd style);
6026            pr ";\n";
6027            do_cleanups ();
6028            pr "      if (%s == NULL)\n" n;
6029            pr "        croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
6030            pr "      RETVAL = newSVpv (%s, 0);\n" n;
6031            pr "      free (%s);\n" n;
6032            pr " OUTPUT:\n";
6033            pr "      RETVAL\n"
6034        | RStringList n | RHashtable n ->
6035            pr "PREINIT:\n";
6036            pr "      char **%s;\n" n;
6037            pr "      int i, n;\n";
6038            pr " PPCODE:\n";
6039            pr "      %s = guestfs_%s " n name;
6040            generate_call_args ~handle:"g" (snd style);
6041            pr ";\n";
6042            do_cleanups ();
6043            pr "      if (%s == NULL)\n" n;
6044            pr "        croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
6045            pr "      for (n = 0; %s[n] != NULL; ++n) /**/;\n" n;
6046            pr "      EXTEND (SP, n);\n";
6047            pr "      for (i = 0; i < n; ++i) {\n";
6048            pr "        PUSHs (sv_2mortal (newSVpv (%s[i], 0)));\n" n;
6049            pr "        free (%s[i]);\n" n;
6050            pr "      }\n";
6051            pr "      free (%s);\n" n;
6052        | RStruct (n, typ) ->
6053            let cols = cols_of_struct typ in
6054            generate_perl_struct_code typ cols name style n do_cleanups
6055        | RStructList (n, typ) ->
6056            let cols = cols_of_struct typ in
6057            generate_perl_struct_list_code typ cols name style n do_cleanups
6058       );
6059
6060       pr "\n"
6061   ) all_functions
6062
6063 and generate_perl_struct_list_code typ cols name style n do_cleanups =
6064   pr "PREINIT:\n";
6065   pr "      struct guestfs_%s_list *%s;\n" typ n;
6066   pr "      int i;\n";
6067   pr "      HV *hv;\n";
6068   pr " PPCODE:\n";
6069   pr "      %s = guestfs_%s " n name;
6070   generate_call_args ~handle:"g" (snd style);
6071   pr ";\n";
6072   do_cleanups ();
6073   pr "      if (%s == NULL)\n" n;
6074   pr "        croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
6075   pr "      EXTEND (SP, %s->len);\n" n;
6076   pr "      for (i = 0; i < %s->len; ++i) {\n" n;
6077   pr "        hv = newHV ();\n";
6078   List.iter (
6079     function
6080     | name, FString ->
6081         pr "        (void) hv_store (hv, \"%s\", %d, newSVpv (%s->val[i].%s, 0), 0);\n"
6082           name (String.length name) n name
6083     | name, FUUID ->
6084         pr "        (void) hv_store (hv, \"%s\", %d, newSVpv (%s->val[i].%s, 32), 0);\n"
6085           name (String.length name) n name
6086     | name, (FBytes|FUInt64) ->
6087         pr "        (void) hv_store (hv, \"%s\", %d, my_newSVull (%s->val[i].%s), 0);\n"
6088           name (String.length name) n name
6089     | name, FInt64 ->
6090         pr "        (void) hv_store (hv, \"%s\", %d, my_newSVll (%s->val[i].%s), 0);\n"
6091           name (String.length name) n name
6092     | name, (FInt32|FUInt32) ->
6093         pr "        (void) hv_store (hv, \"%s\", %d, newSVnv (%s->val[i].%s), 0);\n"
6094           name (String.length name) n name
6095     | name, FChar ->
6096         pr "        (void) hv_store (hv, \"%s\", %d, newSVpv (&%s->val[i].%s, 1), 0);\n"
6097           name (String.length name) n name
6098     | name, FOptPercent ->
6099         pr "        (void) hv_store (hv, \"%s\", %d, newSVnv (%s->val[i].%s), 0);\n"
6100           name (String.length name) n name
6101   ) cols;
6102   pr "        PUSHs (sv_2mortal (newRV ((SV *) hv)));\n";
6103   pr "      }\n";
6104   pr "      guestfs_free_%s_list (%s);\n" typ n
6105
6106 and generate_perl_struct_code typ cols name style n do_cleanups =
6107   pr "PREINIT:\n";
6108   pr "      struct guestfs_%s *%s;\n" typ n;
6109   pr " PPCODE:\n";
6110   pr "      %s = guestfs_%s " n name;
6111   generate_call_args ~handle:"g" (snd style);
6112   pr ";\n";
6113   do_cleanups ();
6114   pr "      if (%s == NULL)\n" n;
6115   pr "        croak (\"%s: %%s\", guestfs_last_error (g));\n" name;
6116   pr "      EXTEND (SP, 2 * %d);\n" (List.length cols);
6117   List.iter (
6118     fun ((name, _) as col) ->
6119       pr "      PUSHs (sv_2mortal (newSVpv (\"%s\", 0)));\n" name;
6120
6121       match col with
6122       | name, FString ->
6123           pr "      PUSHs (sv_2mortal (newSVpv (%s->%s, 0)));\n"
6124             n name
6125       | name, FUUID ->
6126           pr "      PUSHs (sv_2mortal (newSVpv (%s->%s, 32)));\n"
6127             n name
6128       | name, (FBytes|FUInt64) ->
6129           pr "      PUSHs (sv_2mortal (my_newSVull (%s->%s)));\n"
6130             n name
6131       | name, FInt64 ->
6132           pr "      PUSHs (sv_2mortal (my_newSVll (%s->%s)));\n"
6133             n name
6134       | name, (FInt32|FUInt32) ->
6135           pr "      PUSHs (sv_2mortal (newSVnv (%s->%s)));\n"
6136             n name
6137       | name, FChar ->
6138           pr "      PUSHs (sv_2mortal (newSVpv (&%s->%s, 1)));\n"
6139             n name
6140       | name, FOptPercent ->
6141           pr "      PUSHs (sv_2mortal (newSVnv (%s->%s)));\n"
6142             n name
6143   ) cols;
6144   pr "      free (%s);\n" n
6145
6146 (* Generate Sys/Guestfs.pm. *)
6147 and generate_perl_pm () =
6148   generate_header HashStyle LGPLv2;
6149
6150   pr "\
6151 =pod
6152
6153 =head1 NAME
6154
6155 Sys::Guestfs - Perl bindings for libguestfs
6156
6157 =head1 SYNOPSIS
6158
6159  use Sys::Guestfs;
6160
6161  my $h = Sys::Guestfs->new ();
6162  $h->add_drive ('guest.img');
6163  $h->launch ();
6164  $h->wait_ready ();
6165  $h->mount ('/dev/sda1', '/');
6166  $h->touch ('/hello');
6167  $h->sync ();
6168
6169 =head1 DESCRIPTION
6170
6171 The C<Sys::Guestfs> module provides a Perl XS binding to the
6172 libguestfs API for examining and modifying virtual machine
6173 disk images.
6174
6175 Amongst the things this is good for: making batch configuration
6176 changes to guests, getting disk used/free statistics (see also:
6177 virt-df), migrating between virtualization systems (see also:
6178 virt-p2v), performing partial backups, performing partial guest
6179 clones, cloning guests and changing registry/UUID/hostname info, and
6180 much else besides.
6181
6182 Libguestfs uses Linux kernel and qemu code, and can access any type of
6183 guest filesystem that Linux and qemu can, including but not limited
6184 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
6185 schemes, qcow, qcow2, vmdk.
6186
6187 Libguestfs provides ways to enumerate guest storage (eg. partitions,
6188 LVs, what filesystem is in each LV, etc.).  It can also run commands
6189 in the context of the guest.  Also you can access filesystems over FTP.
6190
6191 See also L<Sys::Guestfs::Lib(3)> for a set of useful library
6192 functions for using libguestfs from Perl, including integration
6193 with libvirt.
6194
6195 =head1 ERRORS
6196
6197 All errors turn into calls to C<croak> (see L<Carp(3)>).
6198
6199 =head1 METHODS
6200
6201 =over 4
6202
6203 =cut
6204
6205 package Sys::Guestfs;
6206
6207 use strict;
6208 use warnings;
6209
6210 require XSLoader;
6211 XSLoader::load ('Sys::Guestfs');
6212
6213 =item $h = Sys::Guestfs->new ();
6214
6215 Create a new guestfs handle.
6216
6217 =cut
6218
6219 sub new {
6220   my $proto = shift;
6221   my $class = ref ($proto) || $proto;
6222
6223   my $self = Sys::Guestfs::_create ();
6224   bless $self, $class;
6225   return $self;
6226 }
6227
6228 ";
6229
6230   (* Actions.  We only need to print documentation for these as
6231    * they are pulled in from the XS code automatically.
6232    *)
6233   List.iter (
6234     fun (name, style, _, flags, _, _, longdesc) ->
6235       if not (List.mem NotInDocs flags) then (
6236         let longdesc = replace_str longdesc "C<guestfs_" "C<$h-E<gt>" in
6237         pr "=item ";
6238         generate_perl_prototype name style;
6239         pr "\n\n";
6240         pr "%s\n\n" longdesc;
6241         if List.mem ProtocolLimitWarning flags then
6242           pr "%s\n\n" protocol_limit_warning;
6243         if List.mem DangerWillRobinson flags then
6244           pr "%s\n\n" danger_will_robinson
6245       )
6246   ) all_functions_sorted;
6247
6248   (* End of file. *)
6249   pr "\
6250 =cut
6251
6252 1;
6253
6254 =back
6255
6256 =head1 COPYRIGHT
6257
6258 Copyright (C) 2009 Red Hat Inc.
6259
6260 =head1 LICENSE
6261
6262 Please see the file COPYING.LIB for the full license.
6263
6264 =head1 SEE ALSO
6265
6266 L<guestfs(3)>,
6267 L<guestfish(1)>,
6268 L<http://libguestfs.org>,
6269 L<Sys::Guestfs::Lib(3)>.
6270
6271 =cut
6272 "
6273
6274 and generate_perl_prototype name style =
6275   (match fst style with
6276    | RErr -> ()
6277    | RBool n
6278    | RInt n
6279    | RInt64 n
6280    | RConstString n
6281    | RString n -> pr "$%s = " n
6282    | RStruct (n,_)
6283    | RHashtable n -> pr "%%%s = " n
6284    | RStringList n
6285    | RStructList (n,_) -> pr "@%s = " n
6286   );
6287   pr "$h->%s (" name;
6288   let comma = ref false in
6289   List.iter (
6290     fun arg ->
6291       if !comma then pr ", ";
6292       comma := true;
6293       match arg with
6294       | String n | OptString n | Bool n | Int n | FileIn n | FileOut n ->
6295           pr "$%s" n
6296       | StringList n ->
6297           pr "\\@%s" n
6298   ) (snd style);
6299   pr ");"
6300
6301 (* Generate Python C module. *)
6302 and generate_python_c () =
6303   generate_header CStyle LGPLv2;
6304
6305   pr "\
6306 #include <stdio.h>
6307 #include <stdlib.h>
6308 #include <assert.h>
6309
6310 #include <Python.h>
6311
6312 #include \"guestfs.h\"
6313
6314 typedef struct {
6315   PyObject_HEAD
6316   guestfs_h *g;
6317 } Pyguestfs_Object;
6318
6319 static guestfs_h *
6320 get_handle (PyObject *obj)
6321 {
6322   assert (obj);
6323   assert (obj != Py_None);
6324   return ((Pyguestfs_Object *) obj)->g;
6325 }
6326
6327 static PyObject *
6328 put_handle (guestfs_h *g)
6329 {
6330   assert (g);
6331   return
6332     PyCObject_FromVoidPtrAndDesc ((void *) g, (char *) \"guestfs_h\", NULL);
6333 }
6334
6335 /* This list should be freed (but not the strings) after use. */
6336 static const char **
6337 get_string_list (PyObject *obj)
6338 {
6339   int i, len;
6340   const char **r;
6341
6342   assert (obj);
6343
6344   if (!PyList_Check (obj)) {
6345     PyErr_SetString (PyExc_RuntimeError, \"expecting a list parameter\");
6346     return NULL;
6347   }
6348
6349   len = PyList_Size (obj);
6350   r = malloc (sizeof (char *) * (len+1));
6351   if (r == NULL) {
6352     PyErr_SetString (PyExc_RuntimeError, \"get_string_list: out of memory\");
6353     return NULL;
6354   }
6355
6356   for (i = 0; i < len; ++i)
6357     r[i] = PyString_AsString (PyList_GetItem (obj, i));
6358   r[len] = NULL;
6359
6360   return r;
6361 }
6362
6363 static PyObject *
6364 put_string_list (char * const * const argv)
6365 {
6366   PyObject *list;
6367   int argc, i;
6368
6369   for (argc = 0; argv[argc] != NULL; ++argc)
6370     ;
6371
6372   list = PyList_New (argc);
6373   for (i = 0; i < argc; ++i)
6374     PyList_SetItem (list, i, PyString_FromString (argv[i]));
6375
6376   return list;
6377 }
6378
6379 static PyObject *
6380 put_table (char * const * const argv)
6381 {
6382   PyObject *list, *item;
6383   int argc, i;
6384
6385   for (argc = 0; argv[argc] != NULL; ++argc)
6386     ;
6387
6388   list = PyList_New (argc >> 1);
6389   for (i = 0; i < argc; i += 2) {
6390     item = PyTuple_New (2);
6391     PyTuple_SetItem (item, 0, PyString_FromString (argv[i]));
6392     PyTuple_SetItem (item, 1, PyString_FromString (argv[i+1]));
6393     PyList_SetItem (list, i >> 1, item);
6394   }
6395
6396   return list;
6397 }
6398
6399 static void
6400 free_strings (char **argv)
6401 {
6402   int argc;
6403
6404   for (argc = 0; argv[argc] != NULL; ++argc)
6405     free (argv[argc]);
6406   free (argv);
6407 }
6408
6409 static PyObject *
6410 py_guestfs_create (PyObject *self, PyObject *args)
6411 {
6412   guestfs_h *g;
6413
6414   g = guestfs_create ();
6415   if (g == NULL) {
6416     PyErr_SetString (PyExc_RuntimeError,
6417                      \"guestfs.create: failed to allocate handle\");
6418     return NULL;
6419   }
6420   guestfs_set_error_handler (g, NULL, NULL);
6421   return put_handle (g);
6422 }
6423
6424 static PyObject *
6425 py_guestfs_close (PyObject *self, PyObject *args)
6426 {
6427   PyObject *py_g;
6428   guestfs_h *g;
6429
6430   if (!PyArg_ParseTuple (args, (char *) \"O:guestfs_close\", &py_g))
6431     return NULL;
6432   g = get_handle (py_g);
6433
6434   guestfs_close (g);
6435
6436   Py_INCREF (Py_None);
6437   return Py_None;
6438 }
6439
6440 ";
6441
6442   (* Structures, turned into Python dictionaries. *)
6443   List.iter (
6444     fun (typ, cols) ->
6445       pr "static PyObject *\n";
6446       pr "put_%s (struct guestfs_%s *%s)\n" typ typ typ;
6447       pr "{\n";
6448       pr "  PyObject *dict;\n";
6449       pr "\n";
6450       pr "  dict = PyDict_New ();\n";
6451       List.iter (
6452         function
6453         | name, FString ->
6454             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
6455             pr "                        PyString_FromString (%s->%s));\n"
6456               typ name
6457         | name, FUUID ->
6458             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
6459             pr "                        PyString_FromStringAndSize (%s->%s, 32));\n"
6460               typ name
6461         | name, (FBytes|FUInt64) ->
6462             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
6463             pr "                        PyLong_FromUnsignedLongLong (%s->%s));\n"
6464               typ name
6465         | name, FInt64 ->
6466             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
6467             pr "                        PyLong_FromLongLong (%s->%s));\n"
6468               typ name
6469         | name, FUInt32 ->
6470             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
6471             pr "                        PyLong_FromUnsignedLong (%s->%s));\n"
6472               typ name
6473         | name, FInt32 ->
6474             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
6475             pr "                        PyLong_FromLong (%s->%s));\n"
6476               typ name
6477         | name, FOptPercent ->
6478             pr "  if (%s->%s >= 0)\n" typ name;
6479             pr "    PyDict_SetItemString (dict, \"%s\",\n" name;
6480             pr "                          PyFloat_FromDouble ((double) %s->%s));\n"
6481               typ name;
6482             pr "  else {\n";
6483             pr "    Py_INCREF (Py_None);\n";
6484             pr "    PyDict_SetItemString (dict, \"%s\", Py_None);" name;
6485             pr "  }\n"
6486         | name, FChar ->
6487             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
6488             pr "                        PyString_FromStringAndSize (&dirent->%s, 1));\n" name
6489       ) cols;
6490       pr "  return dict;\n";
6491       pr "};\n";
6492       pr "\n";
6493
6494       pr "static PyObject *\n";
6495       pr "put_%s_list (struct guestfs_%s_list *%ss)\n" typ typ typ;
6496       pr "{\n";
6497       pr "  PyObject *list;\n";
6498       pr "  int i;\n";
6499       pr "\n";
6500       pr "  list = PyList_New (%ss->len);\n" typ;
6501       pr "  for (i = 0; i < %ss->len; ++i)\n" typ;
6502       pr "    PyList_SetItem (list, i, put_%s (&%ss->val[i]));\n" typ typ;
6503       pr "  return list;\n";
6504       pr "};\n";
6505       pr "\n"
6506   ) structs;
6507
6508   (* Python wrapper functions. *)
6509   List.iter (
6510     fun (name, style, _, _, _, _, _) ->
6511       pr "static PyObject *\n";
6512       pr "py_guestfs_%s (PyObject *self, PyObject *args)\n" name;
6513       pr "{\n";
6514
6515       pr "  PyObject *py_g;\n";
6516       pr "  guestfs_h *g;\n";
6517       pr "  PyObject *py_r;\n";
6518
6519       let error_code =
6520         match fst style with
6521         | RErr | RInt _ | RBool _ -> pr "  int r;\n"; "-1"
6522         | RInt64 _ -> pr "  int64_t r;\n"; "-1"
6523         | RConstString _ -> pr "  const char *r;\n"; "NULL"
6524         | RString _ -> pr "  char *r;\n"; "NULL"
6525         | RStringList _ | RHashtable _ -> pr "  char **r;\n"; "NULL"
6526         | RStruct (_, typ) -> pr "  struct guestfs_%s *r;\n" typ; "NULL"
6527         | RStructList (_, typ) ->
6528             pr "  struct guestfs_%s_list *r;\n" typ; "NULL" in
6529
6530       List.iter (
6531         function
6532         | String n | FileIn n | FileOut n -> pr "  const char *%s;\n" n
6533         | OptString n -> pr "  const char *%s;\n" n
6534         | StringList n ->
6535             pr "  PyObject *py_%s;\n" n;
6536             pr "  const char **%s;\n" n
6537         | Bool n -> pr "  int %s;\n" n
6538         | Int n -> pr "  int %s;\n" n
6539       ) (snd style);
6540
6541       pr "\n";
6542
6543       (* Convert the parameters. *)
6544       pr "  if (!PyArg_ParseTuple (args, (char *) \"O";
6545       List.iter (
6546         function
6547         | String _ | FileIn _ | FileOut _ -> pr "s"
6548         | OptString _ -> pr "z"
6549         | StringList _ -> pr "O"
6550         | Bool _ -> pr "i" (* XXX Python has booleans? *)
6551         | Int _ -> pr "i"
6552       ) (snd style);
6553       pr ":guestfs_%s\",\n" name;
6554       pr "                         &py_g";
6555       List.iter (
6556         function
6557         | String n | FileIn n | FileOut n -> pr ", &%s" n
6558         | OptString n -> pr ", &%s" n
6559         | StringList n -> pr ", &py_%s" n
6560         | Bool n -> pr ", &%s" n
6561         | Int n -> pr ", &%s" n
6562       ) (snd style);
6563
6564       pr "))\n";
6565       pr "    return NULL;\n";
6566
6567       pr "  g = get_handle (py_g);\n";
6568       List.iter (
6569         function
6570         | String _ | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ -> ()
6571         | StringList n ->
6572             pr "  %s = get_string_list (py_%s);\n" n n;
6573             pr "  if (!%s) return NULL;\n" n
6574       ) (snd style);
6575
6576       pr "\n";
6577
6578       pr "  r = guestfs_%s " name;
6579       generate_call_args ~handle:"g" (snd style);
6580       pr ";\n";
6581
6582       List.iter (
6583         function
6584         | String _ | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ -> ()
6585         | StringList n ->
6586             pr "  free (%s);\n" n
6587       ) (snd style);
6588
6589       pr "  if (r == %s) {\n" error_code;
6590       pr "    PyErr_SetString (PyExc_RuntimeError, guestfs_last_error (g));\n";
6591       pr "    return NULL;\n";
6592       pr "  }\n";
6593       pr "\n";
6594
6595       (match fst style with
6596        | RErr ->
6597            pr "  Py_INCREF (Py_None);\n";
6598            pr "  py_r = Py_None;\n"
6599        | RInt _
6600        | RBool _ -> pr "  py_r = PyInt_FromLong ((long) r);\n"
6601        | RInt64 _ -> pr "  py_r = PyLong_FromLongLong (r);\n"
6602        | RConstString _ -> pr "  py_r = PyString_FromString (r);\n"
6603        | RString _ ->
6604            pr "  py_r = PyString_FromString (r);\n";
6605            pr "  free (r);\n"
6606        | RStringList _ ->
6607            pr "  py_r = put_string_list (r);\n";
6608            pr "  free_strings (r);\n"
6609        | RStruct (_, typ) ->
6610            pr "  py_r = put_%s (r);\n" typ;
6611            pr "  guestfs_free_%s (r);\n" typ
6612        | RStructList (_, typ) ->
6613            pr "  py_r = put_%s_list (r);\n" typ;
6614            pr "  guestfs_free_%s_list (r);\n" typ
6615        | RHashtable n ->
6616            pr "  py_r = put_table (r);\n";
6617            pr "  free_strings (r);\n"
6618       );
6619
6620       pr "  return py_r;\n";
6621       pr "}\n";
6622       pr "\n"
6623   ) all_functions;
6624
6625   (* Table of functions. *)
6626   pr "static PyMethodDef methods[] = {\n";
6627   pr "  { (char *) \"create\", py_guestfs_create, METH_VARARGS, NULL },\n";
6628   pr "  { (char *) \"close\", py_guestfs_close, METH_VARARGS, NULL },\n";
6629   List.iter (
6630     fun (name, _, _, _, _, _, _) ->
6631       pr "  { (char *) \"%s\", py_guestfs_%s, METH_VARARGS, NULL },\n"
6632         name name
6633   ) all_functions;
6634   pr "  { NULL, NULL, 0, NULL }\n";
6635   pr "};\n";
6636   pr "\n";
6637
6638   (* Init function. *)
6639   pr "\
6640 void
6641 initlibguestfsmod (void)
6642 {
6643   static int initialized = 0;
6644
6645   if (initialized) return;
6646   Py_InitModule ((char *) \"libguestfsmod\", methods);
6647   initialized = 1;
6648 }
6649 "
6650
6651 (* Generate Python module. *)
6652 and generate_python_py () =
6653   generate_header HashStyle LGPLv2;
6654
6655   pr "\
6656 u\"\"\"Python bindings for libguestfs
6657
6658 import guestfs
6659 g = guestfs.GuestFS ()
6660 g.add_drive (\"guest.img\")
6661 g.launch ()
6662 g.wait_ready ()
6663 parts = g.list_partitions ()
6664
6665 The guestfs module provides a Python binding to the libguestfs API
6666 for examining and modifying virtual machine disk images.
6667
6668 Amongst the things this is good for: making batch configuration
6669 changes to guests, getting disk used/free statistics (see also:
6670 virt-df), migrating between virtualization systems (see also:
6671 virt-p2v), performing partial backups, performing partial guest
6672 clones, cloning guests and changing registry/UUID/hostname info, and
6673 much else besides.
6674
6675 Libguestfs uses Linux kernel and qemu code, and can access any type of
6676 guest filesystem that Linux and qemu can, including but not limited
6677 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
6678 schemes, qcow, qcow2, vmdk.
6679
6680 Libguestfs provides ways to enumerate guest storage (eg. partitions,
6681 LVs, what filesystem is in each LV, etc.).  It can also run commands
6682 in the context of the guest.  Also you can access filesystems over FTP.
6683
6684 Errors which happen while using the API are turned into Python
6685 RuntimeError exceptions.
6686
6687 To create a guestfs handle you usually have to perform the following
6688 sequence of calls:
6689
6690 # Create the handle, call add_drive at least once, and possibly
6691 # several times if the guest has multiple block devices:
6692 g = guestfs.GuestFS ()
6693 g.add_drive (\"guest.img\")
6694
6695 # Launch the qemu subprocess and wait for it to become ready:
6696 g.launch ()
6697 g.wait_ready ()
6698
6699 # Now you can issue commands, for example:
6700 logvols = g.lvs ()
6701
6702 \"\"\"
6703
6704 import libguestfsmod
6705
6706 class GuestFS:
6707     \"\"\"Instances of this class are libguestfs API handles.\"\"\"
6708
6709     def __init__ (self):
6710         \"\"\"Create a new libguestfs handle.\"\"\"
6711         self._o = libguestfsmod.create ()
6712
6713     def __del__ (self):
6714         libguestfsmod.close (self._o)
6715
6716 ";
6717
6718   List.iter (
6719     fun (name, style, _, flags, _, _, longdesc) ->
6720       pr "    def %s " name;
6721       generate_call_args ~handle:"self" (snd style);
6722       pr ":\n";
6723
6724       if not (List.mem NotInDocs flags) then (
6725         let doc = replace_str longdesc "C<guestfs_" "C<g." in
6726         let doc =
6727           match fst style with
6728           | RErr | RInt _ | RInt64 _ | RBool _ | RConstString _
6729           | RString _ -> doc
6730           | RStringList _ ->
6731               doc ^ "\n\nThis function returns a list of strings."
6732           | RStruct (_, typ) ->
6733               doc ^ sprintf "\n\nThis function returns a dictionary, with keys matching the various fields in the guestfs_%s structure." typ
6734           | RStructList (_, typ) ->
6735               doc ^ sprintf "\n\nThis function returns a list of %ss.  Each %s is represented as a dictionary." typ typ
6736           | RHashtable _ ->
6737               doc ^ "\n\nThis function returns a dictionary." in
6738         let doc =
6739           if List.mem ProtocolLimitWarning flags then
6740             doc ^ "\n\n" ^ protocol_limit_warning
6741           else doc in
6742         let doc =
6743           if List.mem DangerWillRobinson flags then
6744             doc ^ "\n\n" ^ danger_will_robinson
6745           else doc in
6746         let doc = pod2text ~width:60 name doc in
6747         let doc = List.map (fun line -> replace_str line "\\" "\\\\") doc in
6748         let doc = String.concat "\n        " doc in
6749         pr "        u\"\"\"%s\"\"\"\n" doc;
6750       );
6751       pr "        return libguestfsmod.%s " name;
6752       generate_call_args ~handle:"self._o" (snd style);
6753       pr "\n";
6754       pr "\n";
6755   ) all_functions
6756
6757 (* Useful if you need the longdesc POD text as plain text.  Returns a
6758  * list of lines.
6759  *
6760  * Because this is very slow (the slowest part of autogeneration),
6761  * we memoize the results.
6762  *)
6763 and pod2text ~width name longdesc =
6764   let key = width, name, longdesc in
6765   try Hashtbl.find pod2text_memo key
6766   with Not_found ->
6767     let filename, chan = Filename.open_temp_file "gen" ".tmp" in
6768     fprintf chan "=head1 %s\n\n%s\n" name longdesc;
6769     close_out chan;
6770     let cmd = sprintf "pod2text -w %d %s" width (Filename.quote filename) in
6771     let chan = Unix.open_process_in cmd in
6772     let lines = ref [] in
6773     let rec loop i =
6774       let line = input_line chan in
6775       if i = 1 then             (* discard the first line of output *)
6776         loop (i+1)
6777       else (
6778         let line = triml line in
6779         lines := line :: !lines;
6780         loop (i+1)
6781       ) in
6782     let lines = try loop 1 with End_of_file -> List.rev !lines in
6783     Unix.unlink filename;
6784     (match Unix.close_process_in chan with
6785      | Unix.WEXITED 0 -> ()
6786      | Unix.WEXITED i ->
6787          failwithf "pod2text: process exited with non-zero status (%d)" i
6788      | Unix.WSIGNALED i | Unix.WSTOPPED i ->
6789          failwithf "pod2text: process signalled or stopped by signal %d" i
6790     );
6791     Hashtbl.add pod2text_memo key lines;
6792     let chan = open_out pod2text_memo_filename in
6793     output_value chan pod2text_memo;
6794     close_out chan;
6795     lines
6796
6797 (* Generate ruby bindings. *)
6798 and generate_ruby_c () =
6799   generate_header CStyle LGPLv2;
6800
6801   pr "\
6802 #include <stdio.h>
6803 #include <stdlib.h>
6804
6805 #include <ruby.h>
6806
6807 #include \"guestfs.h\"
6808
6809 #include \"extconf.h\"
6810
6811 /* For Ruby < 1.9 */
6812 #ifndef RARRAY_LEN
6813 #define RARRAY_LEN(r) (RARRAY((r))->len)
6814 #endif
6815
6816 static VALUE m_guestfs;                 /* guestfs module */
6817 static VALUE c_guestfs;                 /* guestfs_h handle */
6818 static VALUE e_Error;                   /* used for all errors */
6819
6820 static void ruby_guestfs_free (void *p)
6821 {
6822   if (!p) return;
6823   guestfs_close ((guestfs_h *) p);
6824 }
6825
6826 static VALUE ruby_guestfs_create (VALUE m)
6827 {
6828   guestfs_h *g;
6829
6830   g = guestfs_create ();
6831   if (!g)
6832     rb_raise (e_Error, \"failed to create guestfs handle\");
6833
6834   /* Don't print error messages to stderr by default. */
6835   guestfs_set_error_handler (g, NULL, NULL);
6836
6837   /* Wrap it, and make sure the close function is called when the
6838    * handle goes away.
6839    */
6840   return Data_Wrap_Struct (c_guestfs, NULL, ruby_guestfs_free, g);
6841 }
6842
6843 static VALUE ruby_guestfs_close (VALUE gv)
6844 {
6845   guestfs_h *g;
6846   Data_Get_Struct (gv, guestfs_h, g);
6847
6848   ruby_guestfs_free (g);
6849   DATA_PTR (gv) = NULL;
6850
6851   return Qnil;
6852 }
6853
6854 ";
6855
6856   List.iter (
6857     fun (name, style, _, _, _, _, _) ->
6858       pr "static VALUE ruby_guestfs_%s (VALUE gv" name;
6859       List.iter (fun arg -> pr ", VALUE %sv" (name_of_argt arg)) (snd style);
6860       pr ")\n";
6861       pr "{\n";
6862       pr "  guestfs_h *g;\n";
6863       pr "  Data_Get_Struct (gv, guestfs_h, g);\n";
6864       pr "  if (!g)\n";
6865       pr "    rb_raise (rb_eArgError, \"%%s: used handle after closing it\", \"%s\");\n"
6866         name;
6867       pr "\n";
6868
6869       List.iter (
6870         function
6871         | String n | FileIn n | FileOut n ->
6872             pr "  Check_Type (%sv, T_STRING);\n" n;
6873             pr "  const char *%s = StringValueCStr (%sv);\n" n n;
6874             pr "  if (!%s)\n" n;
6875             pr "    rb_raise (rb_eTypeError, \"expected string for parameter %%s of %%s\",\n";
6876             pr "              \"%s\", \"%s\");\n" n name
6877         | OptString n ->
6878             pr "  const char *%s = !NIL_P (%sv) ? StringValueCStr (%sv) : NULL;\n" n n n
6879         | StringList n ->
6880             pr "  char **%s;\n" n;
6881             pr "  Check_Type (%sv, T_ARRAY);\n" n;
6882             pr "  {\n";
6883             pr "    int i, len;\n";
6884             pr "    len = RARRAY_LEN (%sv);\n" n;
6885             pr "    %s = guestfs_safe_malloc (g, sizeof (char *) * (len+1));\n"
6886               n;
6887             pr "    for (i = 0; i < len; ++i) {\n";
6888             pr "      VALUE v = rb_ary_entry (%sv, i);\n" n;
6889             pr "      %s[i] = StringValueCStr (v);\n" n;
6890             pr "    }\n";
6891             pr "    %s[len] = NULL;\n" n;
6892             pr "  }\n";
6893         | Bool n ->
6894             pr "  int %s = RTEST (%sv);\n" n n
6895         | Int n ->
6896             pr "  int %s = NUM2INT (%sv);\n" n n
6897       ) (snd style);
6898       pr "\n";
6899
6900       let error_code =
6901         match fst style with
6902         | RErr | RInt _ | RBool _ -> pr "  int r;\n"; "-1"
6903         | RInt64 _ -> pr "  int64_t r;\n"; "-1"
6904         | RConstString _ -> pr "  const char *r;\n"; "NULL"
6905         | RString _ -> pr "  char *r;\n"; "NULL"
6906         | RStringList _ | RHashtable _ -> pr "  char **r;\n"; "NULL"
6907         | RStruct (_, typ) -> pr "  struct guestfs_%s *r;\n" typ; "NULL"
6908         | RStructList (_, typ) ->
6909             pr "  struct guestfs_%s_list *r;\n" typ; "NULL" in
6910       pr "\n";
6911
6912       pr "  r = guestfs_%s " name;
6913       generate_call_args ~handle:"g" (snd style);
6914       pr ";\n";
6915
6916       List.iter (
6917         function
6918         | String _ | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ -> ()
6919         | StringList n ->
6920             pr "  free (%s);\n" n
6921       ) (snd style);
6922
6923       pr "  if (r == %s)\n" error_code;
6924       pr "    rb_raise (e_Error, \"%%s\", guestfs_last_error (g));\n";
6925       pr "\n";
6926
6927       (match fst style with
6928        | RErr ->
6929            pr "  return Qnil;\n"
6930        | RInt _ | RBool _ ->
6931            pr "  return INT2NUM (r);\n"
6932        | RInt64 _ ->
6933            pr "  return ULL2NUM (r);\n"
6934        | RConstString _ ->
6935            pr "  return rb_str_new2 (r);\n";
6936        | RString _ ->
6937            pr "  VALUE rv = rb_str_new2 (r);\n";
6938            pr "  free (r);\n";
6939            pr "  return rv;\n";
6940        | RStringList _ ->
6941            pr "  int i, len = 0;\n";
6942            pr "  for (i = 0; r[i] != NULL; ++i) len++;\n";
6943            pr "  VALUE rv = rb_ary_new2 (len);\n";
6944            pr "  for (i = 0; r[i] != NULL; ++i) {\n";
6945            pr "    rb_ary_push (rv, rb_str_new2 (r[i]));\n";
6946            pr "    free (r[i]);\n";
6947            pr "  }\n";
6948            pr "  free (r);\n";
6949            pr "  return rv;\n"
6950        | RStruct (_, typ) ->
6951            let cols = cols_of_struct typ in
6952            generate_ruby_struct_code typ cols
6953        | RStructList (_, typ) ->
6954            let cols = cols_of_struct typ in
6955            generate_ruby_struct_list_code typ cols
6956        | RHashtable _ ->
6957            pr "  VALUE rv = rb_hash_new ();\n";
6958            pr "  int i;\n";
6959            pr "  for (i = 0; r[i] != NULL; i+=2) {\n";
6960            pr "    rb_hash_aset (rv, rb_str_new2 (r[i]), rb_str_new2 (r[i+1]));\n";
6961            pr "    free (r[i]);\n";
6962            pr "    free (r[i+1]);\n";
6963            pr "  }\n";
6964            pr "  free (r);\n";
6965            pr "  return rv;\n"
6966       );
6967
6968       pr "}\n";
6969       pr "\n"
6970   ) all_functions;
6971
6972   pr "\
6973 /* Initialize the module. */
6974 void Init__guestfs ()
6975 {
6976   m_guestfs = rb_define_module (\"Guestfs\");
6977   c_guestfs = rb_define_class_under (m_guestfs, \"Guestfs\", rb_cObject);
6978   e_Error = rb_define_class_under (m_guestfs, \"Error\", rb_eStandardError);
6979
6980   rb_define_module_function (m_guestfs, \"create\", ruby_guestfs_create, 0);
6981   rb_define_method (c_guestfs, \"close\", ruby_guestfs_close, 0);
6982
6983 ";
6984   (* Define the rest of the methods. *)
6985   List.iter (
6986     fun (name, style, _, _, _, _, _) ->
6987       pr "  rb_define_method (c_guestfs, \"%s\",\n" name;
6988       pr "        ruby_guestfs_%s, %d);\n" name (List.length (snd style))
6989   ) all_functions;
6990
6991   pr "}\n"
6992
6993 (* Ruby code to return a struct. *)
6994 and generate_ruby_struct_code typ cols =
6995   pr "  VALUE rv = rb_hash_new ();\n";
6996   List.iter (
6997     function
6998     | name, FString ->
6999         pr "  rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_str_new2 (r->%s));\n" name name
7000     | name, FUUID ->
7001         pr "  rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_str_new (r->%s, 32));\n" name name
7002     | name, (FBytes|FUInt64) ->
7003         pr "  rb_hash_aset (rv, rb_str_new2 (\"%s\"), ULL2NUM (r->%s));\n" name name
7004     | name, FInt64 ->
7005         pr "  rb_hash_aset (rv, rb_str_new2 (\"%s\"), LL2NUM (r->%s));\n" name name
7006     | name, FUInt32 ->
7007         pr "  rb_hash_aset (rv, rb_str_new2 (\"%s\"), UINT2NUM (r->%s));\n" name name
7008     | name, FInt32 ->
7009         pr "  rb_hash_aset (rv, rb_str_new2 (\"%s\"), INT2NUM (r->%s));\n" name name
7010     | name, FOptPercent ->
7011         pr "  rb_hash_aset (rv, rb_str_new2 (\"%s\"), rb_dbl2big (r->%s));\n" name name
7012     | name, FChar -> (* XXX wrong? *)
7013         pr "  rb_hash_aset (rv, rb_str_new2 (\"%s\"), ULL2NUM (r->%s));\n" name name
7014   ) cols;
7015   pr "  guestfs_free_%s (r);\n" typ;
7016   pr "  return rv;\n"
7017
7018 (* Ruby code to return a struct list. *)
7019 and generate_ruby_struct_list_code typ cols =
7020   pr "  VALUE rv = rb_ary_new2 (r->len);\n";
7021   pr "  int i;\n";
7022   pr "  for (i = 0; i < r->len; ++i) {\n";
7023   pr "    VALUE hv = rb_hash_new ();\n";
7024   List.iter (
7025     function
7026     | name, FString ->
7027         pr "    rb_hash_aset (hv, rb_str_new2 (\"%s\"), rb_str_new2 (r->val[i].%s));\n" name name
7028     | name, FUUID ->
7029         pr "    rb_hash_aset (hv, rb_str_new2 (\"%s\"), rb_str_new (r->val[i].%s, 32));\n" name name
7030     | name, (FBytes|FUInt64) ->
7031         pr "    rb_hash_aset (hv, rb_str_new2 (\"%s\"), ULL2NUM (r->val[i].%s));\n" name name
7032     | name, FInt64 ->
7033         pr "    rb_hash_aset (hv, rb_str_new2 (\"%s\"), LL2NUM (r->val[i].%s));\n" name name
7034     | name, FUInt32 ->
7035         pr "    rb_hash_aset (hv, rb_str_new2 (\"%s\"), UINT2NUM (r->val[i].%s));\n" name name
7036     | name, FInt32 ->
7037         pr "    rb_hash_aset (hv, rb_str_new2 (\"%s\"), INT2NUM (r->val[i].%s));\n" name name
7038     | name, FOptPercent ->
7039         pr "    rb_hash_aset (hv, rb_str_new2 (\"%s\"), rb_dbl2big (r->val[i].%s));\n" name name
7040     | name, FChar -> (* XXX wrong? *)
7041         pr "    rb_hash_aset (hv, rb_str_new2 (\"%s\"), ULL2NUM (r->val[i].%s));\n" name name
7042   ) cols;
7043   pr "    rb_ary_push (rv, hv);\n";
7044   pr "  }\n";
7045   pr "  guestfs_free_%s_list (r);\n" typ;
7046   pr "  return rv;\n"
7047
7048 (* Generate Java bindings GuestFS.java file. *)
7049 and generate_java_java () =
7050   generate_header CStyle LGPLv2;
7051
7052   pr "\
7053 package com.redhat.et.libguestfs;
7054
7055 import java.util.HashMap;
7056 import com.redhat.et.libguestfs.LibGuestFSException;
7057 import com.redhat.et.libguestfs.PV;
7058 import com.redhat.et.libguestfs.VG;
7059 import com.redhat.et.libguestfs.LV;
7060 import com.redhat.et.libguestfs.Stat;
7061 import com.redhat.et.libguestfs.StatVFS;
7062 import com.redhat.et.libguestfs.IntBool;
7063 import com.redhat.et.libguestfs.Dirent;
7064
7065 /**
7066  * The GuestFS object is a libguestfs handle.
7067  *
7068  * @author rjones
7069  */
7070 public class GuestFS {
7071   // Load the native code.
7072   static {
7073     System.loadLibrary (\"guestfs_jni\");
7074   }
7075
7076   /**
7077    * The native guestfs_h pointer.
7078    */
7079   long g;
7080
7081   /**
7082    * Create a libguestfs handle.
7083    *
7084    * @throws LibGuestFSException
7085    */
7086   public GuestFS () throws LibGuestFSException
7087   {
7088     g = _create ();
7089   }
7090   private native long _create () throws LibGuestFSException;
7091
7092   /**
7093    * Close a libguestfs handle.
7094    *
7095    * You can also leave handles to be collected by the garbage
7096    * collector, but this method ensures that the resources used
7097    * by the handle are freed up immediately.  If you call any
7098    * other methods after closing the handle, you will get an
7099    * exception.
7100    *
7101    * @throws LibGuestFSException
7102    */
7103   public void close () throws LibGuestFSException
7104   {
7105     if (g != 0)
7106       _close (g);
7107     g = 0;
7108   }
7109   private native void _close (long g) throws LibGuestFSException;
7110
7111   public void finalize () throws LibGuestFSException
7112   {
7113     close ();
7114   }
7115
7116 ";
7117
7118   List.iter (
7119     fun (name, style, _, flags, _, shortdesc, longdesc) ->
7120       if not (List.mem NotInDocs flags); then (
7121         let doc = replace_str longdesc "C<guestfs_" "C<g." in
7122         let doc =
7123           if List.mem ProtocolLimitWarning flags then
7124             doc ^ "\n\n" ^ protocol_limit_warning
7125           else doc in
7126         let doc =
7127           if List.mem DangerWillRobinson flags then
7128             doc ^ "\n\n" ^ danger_will_robinson
7129           else doc in
7130         let doc = pod2text ~width:60 name doc in
7131         let doc = List.map (            (* RHBZ#501883 *)
7132           function
7133           | "" -> "<p>"
7134           | nonempty -> nonempty
7135         ) doc in
7136         let doc = String.concat "\n   * " doc in
7137
7138         pr "  /**\n";
7139         pr "   * %s\n" shortdesc;
7140         pr "   * <p>\n";
7141         pr "   * %s\n" doc;
7142         pr "   * @throws LibGuestFSException\n";
7143         pr "   */\n";
7144         pr "  ";
7145       );
7146       generate_java_prototype ~public:true ~semicolon:false name style;
7147       pr "\n";
7148       pr "  {\n";
7149       pr "    if (g == 0)\n";
7150       pr "      throw new LibGuestFSException (\"%s: handle is closed\");\n"
7151         name;
7152       pr "    ";
7153       if fst style <> RErr then pr "return ";
7154       pr "_%s " name;
7155       generate_call_args ~handle:"g" (snd style);
7156       pr ";\n";
7157       pr "  }\n";
7158       pr "  ";
7159       generate_java_prototype ~privat:true ~native:true name style;
7160       pr "\n";
7161       pr "\n";
7162   ) all_functions;
7163
7164   pr "}\n"
7165
7166 and generate_java_prototype ?(public=false) ?(privat=false) ?(native=false)
7167     ?(semicolon=true) name style =
7168   if privat then pr "private ";
7169   if public then pr "public ";
7170   if native then pr "native ";
7171
7172   (* return type *)
7173   (match fst style with
7174    | RErr -> pr "void ";
7175    | RInt _ -> pr "int ";
7176    | RInt64 _ -> pr "long ";
7177    | RBool _ -> pr "boolean ";
7178    | RConstString _ | RString _ -> pr "String ";
7179    | RStringList _ -> pr "String[] ";
7180    | RStruct (_, typ) ->
7181        let name = java_name_of_struct typ in
7182        pr "%s " name;
7183    | RStructList (_, typ) ->
7184        let name = java_name_of_struct typ in
7185        pr "%s[] " name;
7186    | RHashtable _ -> pr "HashMap<String,String> ";
7187   );
7188
7189   if native then pr "_%s " name else pr "%s " name;
7190   pr "(";
7191   let needs_comma = ref false in
7192   if native then (
7193     pr "long g";
7194     needs_comma := true
7195   );
7196
7197   (* args *)
7198   List.iter (
7199     fun arg ->
7200       if !needs_comma then pr ", ";
7201       needs_comma := true;
7202
7203       match arg with
7204       | String n
7205       | OptString n
7206       | FileIn n
7207       | FileOut n ->
7208           pr "String %s" n
7209       | StringList n ->
7210           pr "String[] %s" n
7211       | Bool n ->
7212           pr "boolean %s" n
7213       | Int n ->
7214           pr "int %s" n
7215   ) (snd style);
7216
7217   pr ")\n";
7218   pr "    throws LibGuestFSException";
7219   if semicolon then pr ";"
7220
7221 and generate_java_struct jtyp cols =
7222   generate_header CStyle LGPLv2;
7223
7224   pr "\
7225 package com.redhat.et.libguestfs;
7226
7227 /**
7228  * Libguestfs %s structure.
7229  *
7230  * @author rjones
7231  * @see GuestFS
7232  */
7233 public class %s {
7234 " jtyp jtyp;
7235
7236   List.iter (
7237     function
7238     | name, FString
7239     | name, FUUID -> pr "  public String %s;\n" name
7240     | name, (FBytes|FUInt64|FInt64) -> pr "  public long %s;\n" name
7241     | name, (FUInt32|FInt32) -> pr "  public int %s;\n" name
7242     | name, FChar -> pr "  public char %s;\n" name
7243     | name, FOptPercent ->
7244         pr "  /* The next field is [0..100] or -1 meaning 'not present': */\n";
7245         pr "  public float %s;\n" name
7246   ) cols;
7247
7248   pr "}\n"
7249
7250 and generate_java_c () =
7251   generate_header CStyle LGPLv2;
7252
7253   pr "\
7254 #include <stdio.h>
7255 #include <stdlib.h>
7256 #include <string.h>
7257
7258 #include \"com_redhat_et_libguestfs_GuestFS.h\"
7259 #include \"guestfs.h\"
7260
7261 /* Note that this function returns.  The exception is not thrown
7262  * until after the wrapper function returns.
7263  */
7264 static void
7265 throw_exception (JNIEnv *env, const char *msg)
7266 {
7267   jclass cl;
7268   cl = (*env)->FindClass (env,
7269                           \"com/redhat/et/libguestfs/LibGuestFSException\");
7270   (*env)->ThrowNew (env, cl, msg);
7271 }
7272
7273 JNIEXPORT jlong JNICALL
7274 Java_com_redhat_et_libguestfs_GuestFS__1create
7275   (JNIEnv *env, jobject obj)
7276 {
7277   guestfs_h *g;
7278
7279   g = guestfs_create ();
7280   if (g == NULL) {
7281     throw_exception (env, \"GuestFS.create: failed to allocate handle\");
7282     return 0;
7283   }
7284   guestfs_set_error_handler (g, NULL, NULL);
7285   return (jlong) (long) g;
7286 }
7287
7288 JNIEXPORT void JNICALL
7289 Java_com_redhat_et_libguestfs_GuestFS__1close
7290   (JNIEnv *env, jobject obj, jlong jg)
7291 {
7292   guestfs_h *g = (guestfs_h *) (long) jg;
7293   guestfs_close (g);
7294 }
7295
7296 ";
7297
7298   List.iter (
7299     fun (name, style, _, _, _, _, _) ->
7300       pr "JNIEXPORT ";
7301       (match fst style with
7302        | RErr -> pr "void ";
7303        | RInt _ -> pr "jint ";
7304        | RInt64 _ -> pr "jlong ";
7305        | RBool _ -> pr "jboolean ";
7306        | RConstString _ | RString _ -> pr "jstring ";
7307        | RStruct _ | RHashtable _ ->
7308            pr "jobject ";
7309        | RStringList _ | RStructList _ ->
7310            pr "jobjectArray ";
7311       );
7312       pr "JNICALL\n";
7313       pr "Java_com_redhat_et_libguestfs_GuestFS_";
7314       pr "%s" (replace_str ("_" ^ name) "_" "_1");
7315       pr "\n";
7316       pr "  (JNIEnv *env, jobject obj, jlong jg";
7317       List.iter (
7318         function
7319         | String n
7320         | OptString n
7321         | FileIn n
7322         | FileOut n ->
7323             pr ", jstring j%s" n
7324         | StringList n ->
7325             pr ", jobjectArray j%s" n
7326         | Bool n ->
7327             pr ", jboolean j%s" n
7328         | Int n ->
7329             pr ", jint j%s" n
7330       ) (snd style);
7331       pr ")\n";
7332       pr "{\n";
7333       pr "  guestfs_h *g = (guestfs_h *) (long) jg;\n";
7334       let error_code, no_ret =
7335         match fst style with
7336         | RErr -> pr "  int r;\n"; "-1", ""
7337         | RBool _
7338         | RInt _ -> pr "  int r;\n"; "-1", "0"
7339         | RInt64 _ -> pr "  int64_t r;\n"; "-1", "0"
7340         | RConstString _ -> pr "  const char *r;\n"; "NULL", "NULL"
7341         | RString _ ->
7342             pr "  jstring jr;\n";
7343             pr "  char *r;\n"; "NULL", "NULL"
7344         | RStringList _ ->
7345             pr "  jobjectArray jr;\n";
7346             pr "  int r_len;\n";
7347             pr "  jclass cl;\n";
7348             pr "  jstring jstr;\n";
7349             pr "  char **r;\n"; "NULL", "NULL"
7350         | RStruct (_, typ) ->
7351             pr "  jobject jr;\n";
7352             pr "  jclass cl;\n";
7353             pr "  jfieldID fl;\n";
7354             pr "  struct guestfs_%s *r;\n" typ; "NULL", "NULL"
7355         | RStructList (_, typ) ->
7356             pr "  jobjectArray jr;\n";
7357             pr "  jclass cl;\n";
7358             pr "  jfieldID fl;\n";
7359             pr "  jobject jfl;\n";
7360             pr "  struct guestfs_%s_list *r;\n" typ; "NULL", "NULL"
7361         | RHashtable _ -> pr "  char **r;\n"; "NULL", "NULL" in
7362       List.iter (
7363         function
7364         | String n
7365         | OptString n
7366         | FileIn n
7367         | FileOut n ->
7368             pr "  const char *%s;\n" n
7369         | StringList n ->
7370             pr "  int %s_len;\n" n;
7371             pr "  const char **%s;\n" n
7372         | Bool n
7373         | Int n ->
7374             pr "  int %s;\n" n
7375       ) (snd style);
7376
7377       let needs_i =
7378         (match fst style with
7379          | RStringList _ | RStructList _ -> true
7380          | RErr | RBool _ | RInt _ | RInt64 _ | RConstString _
7381          | RString _ | RStruct _ | RHashtable _ -> false) ||
7382           List.exists (function StringList _ -> true | _ -> false) (snd style) in
7383       if needs_i then
7384         pr "  int i;\n";
7385
7386       pr "\n";
7387
7388       (* Get the parameters. *)
7389       List.iter (
7390         function
7391         | String n
7392         | FileIn n
7393         | FileOut n ->
7394             pr "  %s = (*env)->GetStringUTFChars (env, j%s, NULL);\n" n n
7395         | OptString n ->
7396             (* This is completely undocumented, but Java null becomes
7397              * a NULL parameter.
7398              *)
7399             pr "  %s = j%s ? (*env)->GetStringUTFChars (env, j%s, NULL) : NULL;\n" n n n
7400         | StringList n ->
7401             pr "  %s_len = (*env)->GetArrayLength (env, j%s);\n" n n;
7402             pr "  %s = guestfs_safe_malloc (g, sizeof (char *) * (%s_len+1));\n" n n;
7403             pr "  for (i = 0; i < %s_len; ++i) {\n" n;
7404             pr "    jobject o = (*env)->GetObjectArrayElement (env, j%s, i);\n"
7405               n;
7406             pr "    %s[i] = (*env)->GetStringUTFChars (env, o, NULL);\n" n;
7407             pr "  }\n";
7408             pr "  %s[%s_len] = NULL;\n" n n;
7409         | Bool n
7410         | Int n ->
7411             pr "  %s = j%s;\n" n n
7412       ) (snd style);
7413
7414       (* Make the call. *)
7415       pr "  r = guestfs_%s " name;
7416       generate_call_args ~handle:"g" (snd style);
7417       pr ";\n";
7418
7419       (* Release the parameters. *)
7420       List.iter (
7421         function
7422         | String n
7423         | FileIn n
7424         | FileOut n ->
7425             pr "  (*env)->ReleaseStringUTFChars (env, j%s, %s);\n" n n
7426         | OptString n ->
7427             pr "  if (j%s)\n" n;
7428             pr "    (*env)->ReleaseStringUTFChars (env, j%s, %s);\n" n n
7429         | StringList n ->
7430             pr "  for (i = 0; i < %s_len; ++i) {\n" n;
7431             pr "    jobject o = (*env)->GetObjectArrayElement (env, j%s, i);\n"
7432               n;
7433             pr "    (*env)->ReleaseStringUTFChars (env, o, %s[i]);\n" n;
7434             pr "  }\n";
7435             pr "  free (%s);\n" n
7436         | Bool n
7437         | Int n -> ()
7438       ) (snd style);
7439
7440       (* Check for errors. *)
7441       pr "  if (r == %s) {\n" error_code;
7442       pr "    throw_exception (env, guestfs_last_error (g));\n";
7443       pr "    return %s;\n" no_ret;
7444       pr "  }\n";
7445
7446       (* Return value. *)
7447       (match fst style with
7448        | RErr -> ()
7449        | RInt _ -> pr "  return (jint) r;\n"
7450        | RBool _ -> pr "  return (jboolean) r;\n"
7451        | RInt64 _ -> pr "  return (jlong) r;\n"
7452        | RConstString _ -> pr "  return (*env)->NewStringUTF (env, r);\n"
7453        | RString _ ->
7454            pr "  jr = (*env)->NewStringUTF (env, r);\n";
7455            pr "  free (r);\n";
7456            pr "  return jr;\n"
7457        | RStringList _ ->
7458            pr "  for (r_len = 0; r[r_len] != NULL; ++r_len) ;\n";
7459            pr "  cl = (*env)->FindClass (env, \"java/lang/String\");\n";
7460            pr "  jstr = (*env)->NewStringUTF (env, \"\");\n";
7461            pr "  jr = (*env)->NewObjectArray (env, r_len, cl, jstr);\n";
7462            pr "  for (i = 0; i < r_len; ++i) {\n";
7463            pr "    jstr = (*env)->NewStringUTF (env, r[i]);\n";
7464            pr "    (*env)->SetObjectArrayElement (env, jr, i, jstr);\n";
7465            pr "    free (r[i]);\n";
7466            pr "  }\n";
7467            pr "  free (r);\n";
7468            pr "  return jr;\n"
7469        | RStruct (_, typ) ->
7470            let jtyp = java_name_of_struct typ in
7471            let cols = cols_of_struct typ in
7472            generate_java_struct_return typ jtyp cols
7473        | RStructList (_, typ) ->
7474            let jtyp = java_name_of_struct typ in
7475            let cols = cols_of_struct typ in
7476            generate_java_struct_list_return typ jtyp cols
7477        | RHashtable _ ->
7478            (* XXX *)
7479            pr "  throw_exception (env, \"%s: internal error: please let us know how to make a Java HashMap from JNI bindings!\");\n" name;
7480            pr "  return NULL;\n"
7481       );
7482
7483       pr "}\n";
7484       pr "\n"
7485   ) all_functions
7486
7487 and generate_java_struct_return typ jtyp cols =
7488   pr "  cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/%s\");\n" jtyp;
7489   pr "  jr = (*env)->AllocObject (env, cl);\n";
7490   List.iter (
7491     function
7492     | name, FString ->
7493         pr "  fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
7494         pr "  (*env)->SetObjectField (env, jr, fl, (*env)->NewStringUTF (env, r->%s));\n" name;
7495     | name, FUUID ->
7496         pr "  {\n";
7497         pr "    char s[33];\n";
7498         pr "    memcpy (s, r->%s, 32);\n" name;
7499         pr "    s[32] = 0;\n";
7500         pr "    fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
7501         pr "    (*env)->SetObjectField (env, jr, fl, (*env)->NewStringUTF (env, s));\n";
7502         pr "  }\n";
7503     | name, (FBytes|FUInt64|FInt64) ->
7504         pr "  fl = (*env)->GetFieldID (env, cl, \"%s\", \"J\");\n" name;
7505         pr "  (*env)->SetLongField (env, jr, fl, r->%s);\n" name;
7506     | name, (FUInt32|FInt32) ->
7507         pr "  fl = (*env)->GetFieldID (env, cl, \"%s\", \"I\");\n" name;
7508         pr "  (*env)->SetLongField (env, jr, fl, r->%s);\n" name;
7509     | name, FOptPercent ->
7510         pr "  fl = (*env)->GetFieldID (env, cl, \"%s\", \"F\");\n" name;
7511         pr "  (*env)->SetFloatField (env, jr, fl, r->%s);\n" name;
7512     | name, FChar ->
7513         pr "  fl = (*env)->GetFieldID (env, cl, \"%s\", \"C\");\n" name;
7514         pr "  (*env)->SetLongField (env, jr, fl, r->%s);\n" name;
7515   ) cols;
7516   pr "  free (r);\n";
7517   pr "  return jr;\n"
7518
7519 and generate_java_struct_list_return typ jtyp cols =
7520   pr "  cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/%s\");\n" jtyp;
7521   pr "  jr = (*env)->NewObjectArray (env, r->len, cl, NULL);\n";
7522   pr "  for (i = 0; i < r->len; ++i) {\n";
7523   pr "    jfl = (*env)->AllocObject (env, cl);\n";
7524   List.iter (
7525     function
7526     | name, FString ->
7527         pr "    fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
7528         pr "    (*env)->SetObjectField (env, jfl, fl, (*env)->NewStringUTF (env, r->val[i].%s));\n" name;
7529     | name, FUUID ->
7530         pr "    {\n";
7531         pr "      char s[33];\n";
7532         pr "      memcpy (s, r->val[i].%s, 32);\n" name;
7533         pr "      s[32] = 0;\n";
7534         pr "      fl = (*env)->GetFieldID (env, cl, \"%s\", \"Ljava/lang/String;\");\n" name;
7535         pr "      (*env)->SetObjectField (env, jfl, fl, (*env)->NewStringUTF (env, s));\n";
7536         pr "    }\n";
7537     | name, (FBytes|FUInt64|FInt64) ->
7538         pr "    fl = (*env)->GetFieldID (env, cl, \"%s\", \"J\");\n" name;
7539         pr "    (*env)->SetLongField (env, jfl, fl, r->val[i].%s);\n" name;
7540     | name, (FUInt32|FInt32) ->
7541         pr "    fl = (*env)->GetFieldID (env, cl, \"%s\", \"I\");\n" name;
7542         pr "    (*env)->SetLongField (env, jfl, fl, r->val[i].%s);\n" name;
7543     | name, FOptPercent ->
7544         pr "    fl = (*env)->GetFieldID (env, cl, \"%s\", \"F\");\n" name;
7545         pr "    (*env)->SetFloatField (env, jfl, fl, r->val[i].%s);\n" name;
7546     | name, FChar ->
7547         pr "    fl = (*env)->GetFieldID (env, cl, \"%s\", \"C\");\n" name;
7548         pr "    (*env)->SetLongField (env, jfl, fl, r->val[i].%s);\n" name;
7549   ) cols;
7550   pr "    (*env)->SetObjectArrayElement (env, jfl, i, jfl);\n";
7551   pr "  }\n";
7552   pr "  guestfs_free_%s_list (r);\n" typ;
7553   pr "  return jr;\n"
7554
7555 and generate_haskell_hs () =
7556   generate_header HaskellStyle LGPLv2;
7557
7558   (* XXX We only know how to generate partial FFI for Haskell
7559    * at the moment.  Please help out!
7560    *)
7561   let can_generate style =
7562     match style with
7563     | RErr, _
7564     | RInt _, _
7565     | RInt64 _, _ -> true
7566     | RBool _, _
7567     | RConstString _, _
7568     | RString _, _
7569     | RStringList _, _
7570     | RStruct _, _
7571     | RStructList _, _
7572     | RHashtable _, _ -> false in
7573
7574   pr "\
7575 {-# INCLUDE <guestfs.h> #-}
7576 {-# LANGUAGE ForeignFunctionInterface #-}
7577
7578 module Guestfs (
7579   create";
7580
7581   (* List out the names of the actions we want to export. *)
7582   List.iter (
7583     fun (name, style, _, _, _, _, _) ->
7584       if can_generate style then pr ",\n  %s" name
7585   ) all_functions;
7586
7587   pr "
7588   ) where
7589 import Foreign
7590 import Foreign.C
7591 import Foreign.C.Types
7592 import IO
7593 import Control.Exception
7594 import Data.Typeable
7595
7596 data GuestfsS = GuestfsS            -- represents the opaque C struct
7597 type GuestfsP = Ptr GuestfsS        -- guestfs_h *
7598 type GuestfsH = ForeignPtr GuestfsS -- guestfs_h * with attached finalizer
7599
7600 -- XXX define properly later XXX
7601 data PV = PV
7602 data VG = VG
7603 data LV = LV
7604 data IntBool = IntBool
7605 data Stat = Stat
7606 data StatVFS = StatVFS
7607 data Hashtable = Hashtable
7608
7609 foreign import ccall unsafe \"guestfs_create\" c_create
7610   :: IO GuestfsP
7611 foreign import ccall unsafe \"&guestfs_close\" c_close
7612   :: FunPtr (GuestfsP -> IO ())
7613 foreign import ccall unsafe \"guestfs_set_error_handler\" c_set_error_handler
7614   :: GuestfsP -> Ptr CInt -> Ptr CInt -> IO ()
7615
7616 create :: IO GuestfsH
7617 create = do
7618   p <- c_create
7619   c_set_error_handler p nullPtr nullPtr
7620   h <- newForeignPtr c_close p
7621   return h
7622
7623 foreign import ccall unsafe \"guestfs_last_error\" c_last_error
7624   :: GuestfsP -> IO CString
7625
7626 -- last_error :: GuestfsH -> IO (Maybe String)
7627 -- last_error h = do
7628 --   str <- withForeignPtr h (\\p -> c_last_error p)
7629 --   maybePeek peekCString str
7630
7631 last_error :: GuestfsH -> IO (String)
7632 last_error h = do
7633   str <- withForeignPtr h (\\p -> c_last_error p)
7634   if (str == nullPtr)
7635     then return \"no error\"
7636     else peekCString str
7637
7638 ";
7639
7640   (* Generate wrappers for each foreign function. *)
7641   List.iter (
7642     fun (name, style, _, _, _, _, _) ->
7643       if can_generate style then (
7644         pr "foreign import ccall unsafe \"guestfs_%s\" c_%s\n" name name;
7645         pr "  :: ";
7646         generate_haskell_prototype ~handle:"GuestfsP" style;
7647         pr "\n";
7648         pr "\n";
7649         pr "%s :: " name;
7650         generate_haskell_prototype ~handle:"GuestfsH" ~hs:true style;
7651         pr "\n";
7652         pr "%s %s = do\n" name
7653           (String.concat " " ("h" :: List.map name_of_argt (snd style)));
7654         pr "  r <- ";
7655         (* Convert pointer arguments using with* functions. *)
7656         List.iter (
7657           function
7658           | FileIn n
7659           | FileOut n
7660           | String n -> pr "withCString %s $ \\%s -> " n n
7661           | OptString n -> pr "maybeWith withCString %s $ \\%s -> " n n
7662           | StringList n -> pr "withMany withCString %s $ \\%s -> withArray0 nullPtr %s $ \\%s -> " n n n n
7663           | Bool _ | Int _ -> ()
7664         ) (snd style);
7665         (* Convert integer arguments. *)
7666         let args =
7667           List.map (
7668             function
7669             | Bool n -> sprintf "(fromBool %s)" n
7670             | Int n -> sprintf "(fromIntegral %s)" n
7671             | FileIn n | FileOut n | String n | OptString n | StringList n -> n
7672           ) (snd style) in
7673         pr "withForeignPtr h (\\p -> c_%s %s)\n" name
7674           (String.concat " " ("p" :: args));
7675         (match fst style with
7676          | RErr | RInt _ | RInt64 _ | RBool _ ->
7677              pr "  if (r == -1)\n";
7678              pr "    then do\n";
7679              pr "      err <- last_error h\n";
7680              pr "      fail err\n";
7681          | RConstString _ | RString _ | RStringList _ | RStruct _
7682          | RStructList _ | RHashtable _ ->
7683              pr "  if (r == nullPtr)\n";
7684              pr "    then do\n";
7685              pr "      err <- last_error h\n";
7686              pr "      fail err\n";
7687         );
7688         (match fst style with
7689          | RErr ->
7690              pr "    else return ()\n"
7691          | RInt _ ->
7692              pr "    else return (fromIntegral r)\n"
7693          | RInt64 _ ->
7694              pr "    else return (fromIntegral r)\n"
7695          | RBool _ ->
7696              pr "    else return (toBool r)\n"
7697          | RConstString _
7698          | RString _
7699          | RStringList _
7700          | RStruct _
7701          | RStructList _
7702          | RHashtable _ ->
7703              pr "    else return ()\n" (* XXXXXXXXXXXXXXXXXXXX *)
7704         );
7705         pr "\n";
7706       )
7707   ) all_functions
7708
7709 and generate_haskell_prototype ~handle ?(hs = false) style =
7710   pr "%s -> " handle;
7711   let string = if hs then "String" else "CString" in
7712   let int = if hs then "Int" else "CInt" in
7713   let bool = if hs then "Bool" else "CInt" in
7714   let int64 = if hs then "Integer" else "Int64" in
7715   List.iter (
7716     fun arg ->
7717       (match arg with
7718        | String _ -> pr "%s" string
7719        | OptString _ -> if hs then pr "Maybe String" else pr "CString"
7720        | StringList _ -> if hs then pr "[String]" else pr "Ptr CString"
7721        | Bool _ -> pr "%s" bool
7722        | Int _ -> pr "%s" int
7723        | FileIn _ -> pr "%s" string
7724        | FileOut _ -> pr "%s" string
7725       );
7726       pr " -> ";
7727   ) (snd style);
7728   pr "IO (";
7729   (match fst style with
7730    | RErr -> if not hs then pr "CInt"
7731    | RInt _ -> pr "%s" int
7732    | RInt64 _ -> pr "%s" int64
7733    | RBool _ -> pr "%s" bool
7734    | RConstString _ -> pr "%s" string
7735    | RString _ -> pr "%s" string
7736    | RStringList _ -> pr "[%s]" string
7737    | RStruct (_, typ) ->
7738        let name = java_name_of_struct typ in
7739        pr "%s" name
7740    | RStructList (_, typ) ->
7741        let name = java_name_of_struct typ in
7742        pr "[%s]" name
7743    | RHashtable _ -> pr "Hashtable"
7744   );
7745   pr ")"
7746
7747 and generate_bindtests () =
7748   generate_header CStyle LGPLv2;
7749
7750   pr "\
7751 #include <stdio.h>
7752 #include <stdlib.h>
7753 #include <inttypes.h>
7754 #include <string.h>
7755
7756 #include \"guestfs.h\"
7757 #include \"guestfs_protocol.h\"
7758
7759 #define error guestfs_error
7760 #define safe_calloc guestfs_safe_calloc
7761 #define safe_malloc guestfs_safe_malloc
7762
7763 static void
7764 print_strings (char * const* const argv)
7765 {
7766   int argc;
7767
7768   printf (\"[\");
7769   for (argc = 0; argv[argc] != NULL; ++argc) {
7770     if (argc > 0) printf (\", \");
7771     printf (\"\\\"%%s\\\"\", argv[argc]);
7772   }
7773   printf (\"]\\n\");
7774 }
7775
7776 /* The test0 function prints its parameters to stdout. */
7777 ";
7778
7779   let test0, tests =
7780     match test_functions with
7781     | [] -> assert false
7782     | test0 :: tests -> test0, tests in
7783
7784   let () =
7785     let (name, style, _, _, _, _, _) = test0 in
7786     generate_prototype ~extern:false ~semicolon:false ~newline:true
7787       ~handle:"g" ~prefix:"guestfs_" name style;
7788     pr "{\n";
7789     List.iter (
7790       function
7791       | String n
7792       | FileIn n
7793       | FileOut n -> pr "  printf (\"%%s\\n\", %s);\n" n
7794       | OptString n -> pr "  printf (\"%%s\\n\", %s ? %s : \"null\");\n" n n
7795       | StringList n -> pr "  print_strings (%s);\n" n
7796       | Bool n -> pr "  printf (\"%%s\\n\", %s ? \"true\" : \"false\");\n" n
7797       | Int n -> pr "  printf (\"%%d\\n\", %s);\n" n
7798     ) (snd style);
7799     pr "  /* Java changes stdout line buffering so we need this: */\n";
7800     pr "  fflush (stdout);\n";
7801     pr "  return 0;\n";
7802     pr "}\n";
7803     pr "\n" in
7804
7805   List.iter (
7806     fun (name, style, _, _, _, _, _) ->
7807       if String.sub name (String.length name - 3) 3 <> "err" then (
7808         pr "/* Test normal return. */\n";
7809         generate_prototype ~extern:false ~semicolon:false ~newline:true
7810           ~handle:"g" ~prefix:"guestfs_" name style;
7811         pr "{\n";
7812         (match fst style with
7813          | RErr ->
7814              pr "  return 0;\n"
7815          | RInt _ ->
7816              pr "  int r;\n";
7817              pr "  sscanf (val, \"%%d\", &r);\n";
7818              pr "  return r;\n"
7819          | RInt64 _ ->
7820              pr "  int64_t r;\n";
7821              pr "  sscanf (val, \"%%\" SCNi64, &r);\n";
7822              pr "  return r;\n"
7823          | RBool _ ->
7824              pr "  return strcmp (val, \"true\") == 0;\n"
7825          | RConstString _ ->
7826              (* Can't return the input string here.  Return a static
7827               * string so we ensure we get a segfault if the caller
7828               * tries to free it.
7829               *)
7830              pr "  return \"static string\";\n"
7831          | RString _ ->
7832              pr "  return strdup (val);\n"
7833          | RStringList _ ->
7834              pr "  char **strs;\n";
7835              pr "  int n, i;\n";
7836              pr "  sscanf (val, \"%%d\", &n);\n";
7837              pr "  strs = safe_malloc (g, (n+1) * sizeof (char *));\n";
7838              pr "  for (i = 0; i < n; ++i) {\n";
7839              pr "    strs[i] = safe_malloc (g, 16);\n";
7840              pr "    snprintf (strs[i], 16, \"%%d\", i);\n";
7841              pr "  }\n";
7842              pr "  strs[n] = NULL;\n";
7843              pr "  return strs;\n"
7844          | RStruct (_, typ) ->
7845              pr "  struct guestfs_%s *r;\n" typ;
7846              pr "  r = safe_calloc (g, sizeof *r, 1);\n";
7847              pr "  return r;\n"
7848          | RStructList (_, typ) ->
7849              pr "  struct guestfs_%s_list *r;\n" typ;
7850              pr "  r = safe_calloc (g, sizeof *r, 1);\n";
7851              pr "  sscanf (val, \"%%d\", &r->len);\n";
7852              pr "  r->val = safe_calloc (g, r->len, sizeof *r->val);\n";
7853              pr "  return r;\n"
7854          | RHashtable _ ->
7855              pr "  char **strs;\n";
7856              pr "  int n, i;\n";
7857              pr "  sscanf (val, \"%%d\", &n);\n";
7858              pr "  strs = safe_malloc (g, (n*2+1) * sizeof (*strs));\n";
7859              pr "  for (i = 0; i < n; ++i) {\n";
7860              pr "    strs[i*2] = safe_malloc (g, 16);\n";
7861              pr "    strs[i*2+1] = safe_malloc (g, 16);\n";
7862              pr "    snprintf (strs[i*2], 16, \"%%d\", i);\n";
7863              pr "    snprintf (strs[i*2+1], 16, \"%%d\", i);\n";
7864              pr "  }\n";
7865              pr "  strs[n*2] = NULL;\n";
7866              pr "  return strs;\n"
7867         );
7868         pr "}\n";
7869         pr "\n"
7870       ) else (
7871         pr "/* Test error return. */\n";
7872         generate_prototype ~extern:false ~semicolon:false ~newline:true
7873           ~handle:"g" ~prefix:"guestfs_" name style;
7874         pr "{\n";
7875         pr "  error (g, \"error\");\n";
7876         (match fst style with
7877          | RErr | RInt _ | RInt64 _ | RBool _ ->
7878              pr "  return -1;\n"
7879          | RConstString _
7880          | RString _ | RStringList _ | RStruct _
7881          | RStructList _
7882          | RHashtable _ ->
7883              pr "  return NULL;\n"
7884         );
7885         pr "}\n";
7886         pr "\n"
7887       )
7888   ) tests
7889
7890 and generate_ocaml_bindtests () =
7891   generate_header OCamlStyle GPLv2;
7892
7893   pr "\
7894 let () =
7895   let g = Guestfs.create () in
7896 ";
7897
7898   let mkargs args =
7899     String.concat " " (
7900       List.map (
7901         function
7902         | CallString s -> "\"" ^ s ^ "\""
7903         | CallOptString None -> "None"
7904         | CallOptString (Some s) -> sprintf "(Some \"%s\")" s
7905         | CallStringList xs ->
7906             "[|" ^ String.concat ";" (List.map (sprintf "\"%s\"") xs) ^ "|]"
7907         | CallInt i when i >= 0 -> string_of_int i
7908         | CallInt i (* when i < 0 *) -> "(" ^ string_of_int i ^ ")"
7909         | CallBool b -> string_of_bool b
7910       ) args
7911     )
7912   in
7913
7914   generate_lang_bindtests (
7915     fun f args -> pr "  Guestfs.%s g %s;\n" f (mkargs args)
7916   );
7917
7918   pr "print_endline \"EOF\"\n"
7919
7920 and generate_perl_bindtests () =
7921   pr "#!/usr/bin/perl -w\n";
7922   generate_header HashStyle GPLv2;
7923
7924   pr "\
7925 use strict;
7926
7927 use Sys::Guestfs;
7928
7929 my $g = Sys::Guestfs->new ();
7930 ";
7931
7932   let mkargs args =
7933     String.concat ", " (
7934       List.map (
7935         function
7936         | CallString s -> "\"" ^ s ^ "\""
7937         | CallOptString None -> "undef"
7938         | CallOptString (Some s) -> sprintf "\"%s\"" s
7939         | CallStringList xs ->
7940             "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
7941         | CallInt i -> string_of_int i
7942         | CallBool b -> if b then "1" else "0"
7943       ) args
7944     )
7945   in
7946
7947   generate_lang_bindtests (
7948     fun f args -> pr "$g->%s (%s);\n" f (mkargs args)
7949   );
7950
7951   pr "print \"EOF\\n\"\n"
7952
7953 and generate_python_bindtests () =
7954   generate_header HashStyle GPLv2;
7955
7956   pr "\
7957 import guestfs
7958
7959 g = guestfs.GuestFS ()
7960 ";
7961
7962   let mkargs args =
7963     String.concat ", " (
7964       List.map (
7965         function
7966         | CallString s -> "\"" ^ s ^ "\""
7967         | CallOptString None -> "None"
7968         | CallOptString (Some s) -> sprintf "\"%s\"" s
7969         | CallStringList xs ->
7970             "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
7971         | CallInt i -> string_of_int i
7972         | CallBool b -> if b then "1" else "0"
7973       ) args
7974     )
7975   in
7976
7977   generate_lang_bindtests (
7978     fun f args -> pr "g.%s (%s)\n" f (mkargs args)
7979   );
7980
7981   pr "print \"EOF\"\n"
7982
7983 and generate_ruby_bindtests () =
7984   generate_header HashStyle GPLv2;
7985
7986   pr "\
7987 require 'guestfs'
7988
7989 g = Guestfs::create()
7990 ";
7991
7992   let mkargs args =
7993     String.concat ", " (
7994       List.map (
7995         function
7996         | CallString s -> "\"" ^ s ^ "\""
7997         | CallOptString None -> "nil"
7998         | CallOptString (Some s) -> sprintf "\"%s\"" s
7999         | CallStringList xs ->
8000             "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
8001         | CallInt i -> string_of_int i
8002         | CallBool b -> string_of_bool b
8003       ) args
8004     )
8005   in
8006
8007   generate_lang_bindtests (
8008     fun f args -> pr "g.%s(%s)\n" f (mkargs args)
8009   );
8010
8011   pr "print \"EOF\\n\"\n"
8012
8013 and generate_java_bindtests () =
8014   generate_header CStyle GPLv2;
8015
8016   pr "\
8017 import com.redhat.et.libguestfs.*;
8018
8019 public class Bindtests {
8020     public static void main (String[] argv)
8021     {
8022         try {
8023             GuestFS g = new GuestFS ();
8024 ";
8025
8026   let mkargs args =
8027     String.concat ", " (
8028       List.map (
8029         function
8030         | CallString s -> "\"" ^ s ^ "\""
8031         | CallOptString None -> "null"
8032         | CallOptString (Some s) -> sprintf "\"%s\"" s
8033         | CallStringList xs ->
8034             "new String[]{" ^
8035               String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "}"
8036         | CallInt i -> string_of_int i
8037         | CallBool b -> string_of_bool b
8038       ) args
8039     )
8040   in
8041
8042   generate_lang_bindtests (
8043     fun f args -> pr "            g.%s (%s);\n" f (mkargs args)
8044   );
8045
8046   pr "
8047             System.out.println (\"EOF\");
8048         }
8049         catch (Exception exn) {
8050             System.err.println (exn);
8051             System.exit (1);
8052         }
8053     }
8054 }
8055 "
8056
8057 and generate_haskell_bindtests () =
8058   generate_header HaskellStyle GPLv2;
8059
8060   pr "\
8061 module Bindtests where
8062 import qualified Guestfs
8063
8064 main = do
8065   g <- Guestfs.create
8066 ";
8067
8068   let mkargs args =
8069     String.concat " " (
8070       List.map (
8071         function
8072         | CallString s -> "\"" ^ s ^ "\""
8073         | CallOptString None -> "Nothing"
8074         | CallOptString (Some s) -> sprintf "(Just \"%s\")" s
8075         | CallStringList xs ->
8076             "[" ^ String.concat "," (List.map (sprintf "\"%s\"") xs) ^ "]"
8077         | CallInt i when i < 0 -> "(" ^ string_of_int i ^ ")"
8078         | CallInt i -> string_of_int i
8079         | CallBool true -> "True"
8080         | CallBool false -> "False"
8081       ) args
8082     )
8083   in
8084
8085   generate_lang_bindtests (
8086     fun f args -> pr "  Guestfs.%s g %s\n" f (mkargs args)
8087   );
8088
8089   pr "  putStrLn \"EOF\"\n"
8090
8091 (* Language-independent bindings tests - we do it this way to
8092  * ensure there is parity in testing bindings across all languages.
8093  *)
8094 and generate_lang_bindtests call =
8095   call "test0" [CallString "abc"; CallOptString (Some "def");
8096                 CallStringList []; CallBool false;
8097                 CallInt 0; CallString "123"; CallString "456"];
8098   call "test0" [CallString "abc"; CallOptString None;
8099                 CallStringList []; CallBool false;
8100                 CallInt 0; CallString "123"; CallString "456"];
8101   call "test0" [CallString ""; CallOptString (Some "def");
8102                 CallStringList []; CallBool false;
8103                 CallInt 0; CallString "123"; CallString "456"];
8104   call "test0" [CallString ""; CallOptString (Some "");
8105                 CallStringList []; CallBool false;
8106                 CallInt 0; CallString "123"; CallString "456"];
8107   call "test0" [CallString "abc"; CallOptString (Some "def");
8108                 CallStringList ["1"]; CallBool false;
8109                 CallInt 0; CallString "123"; CallString "456"];
8110   call "test0" [CallString "abc"; CallOptString (Some "def");
8111                 CallStringList ["1"; "2"]; CallBool false;
8112                 CallInt 0; CallString "123"; CallString "456"];
8113   call "test0" [CallString "abc"; CallOptString (Some "def");
8114                 CallStringList ["1"]; CallBool true;
8115                 CallInt 0; CallString "123"; CallString "456"];
8116   call "test0" [CallString "abc"; CallOptString (Some "def");
8117                 CallStringList ["1"]; CallBool false;
8118                 CallInt (-1); CallString "123"; CallString "456"];
8119   call "test0" [CallString "abc"; CallOptString (Some "def");
8120                 CallStringList ["1"]; CallBool false;
8121                 CallInt (-2); CallString "123"; CallString "456"];
8122   call "test0" [CallString "abc"; CallOptString (Some "def");
8123                 CallStringList ["1"]; CallBool false;
8124                 CallInt 1; CallString "123"; CallString "456"];
8125   call "test0" [CallString "abc"; CallOptString (Some "def");
8126                 CallStringList ["1"]; CallBool false;
8127                 CallInt 2; CallString "123"; CallString "456"];
8128   call "test0" [CallString "abc"; CallOptString (Some "def");
8129                 CallStringList ["1"]; CallBool false;
8130                 CallInt 4095; CallString "123"; CallString "456"];
8131   call "test0" [CallString "abc"; CallOptString (Some "def");
8132                 CallStringList ["1"]; CallBool false;
8133                 CallInt 0; CallString ""; CallString ""]
8134
8135 (* XXX Add here tests of the return and error functions. *)
8136
8137 (* This is used to generate the src/MAX_PROC_NR file which
8138  * contains the maximum procedure number, a surrogate for the
8139  * ABI version number.  See src/Makefile.am for the details.
8140  *)
8141 and generate_max_proc_nr () =
8142   let proc_nrs = List.map (
8143     fun (_, _, proc_nr, _, _, _, _) -> proc_nr
8144   ) daemon_functions in
8145
8146   let max_proc_nr = List.fold_left max 0 proc_nrs in
8147
8148   pr "%d\n" max_proc_nr
8149
8150 let output_to filename =
8151   let filename_new = filename ^ ".new" in
8152   chan := open_out filename_new;
8153   let close () =
8154     close_out !chan;
8155     chan := stdout;
8156
8157     (* Is the new file different from the current file? *)
8158     if Sys.file_exists filename && files_equal filename filename_new then
8159       Unix.unlink filename_new          (* same, so skip it *)
8160     else (
8161       (* different, overwrite old one *)
8162       (try Unix.chmod filename 0o644 with Unix.Unix_error _ -> ());
8163       Unix.rename filename_new filename;
8164       Unix.chmod filename 0o444;
8165       printf "written %s\n%!" filename;
8166     )
8167   in
8168   close
8169
8170 (* Main program. *)
8171 let () =
8172   check_functions ();
8173
8174   if not (Sys.file_exists "HACKING") then (
8175     eprintf "\
8176 You are probably running this from the wrong directory.
8177 Run it from the top source directory using the command
8178   src/generator.ml
8179 ";
8180     exit 1
8181   );
8182
8183   let close = output_to "src/guestfs_protocol.x" in
8184   generate_xdr ();
8185   close ();
8186
8187   let close = output_to "src/guestfs-structs.h" in
8188   generate_structs_h ();
8189   close ();
8190
8191   let close = output_to "src/guestfs-actions.h" in
8192   generate_actions_h ();
8193   close ();
8194
8195   let close = output_to "src/guestfs-actions.c" in
8196   generate_client_actions ();
8197   close ();
8198
8199   let close = output_to "daemon/actions.h" in
8200   generate_daemon_actions_h ();
8201   close ();
8202
8203   let close = output_to "daemon/stubs.c" in
8204   generate_daemon_actions ();
8205   close ();
8206
8207   let close = output_to "daemon/names.c" in
8208   generate_daemon_names ();
8209   close ();
8210
8211   let close = output_to "capitests/tests.c" in
8212   generate_tests ();
8213   close ();
8214
8215   let close = output_to "src/guestfs-bindtests.c" in
8216   generate_bindtests ();
8217   close ();
8218
8219   let close = output_to "fish/cmds.c" in
8220   generate_fish_cmds ();
8221   close ();
8222
8223   let close = output_to "fish/completion.c" in
8224   generate_fish_completion ();
8225   close ();
8226
8227   let close = output_to "guestfs-structs.pod" in
8228   generate_structs_pod ();
8229   close ();
8230
8231   let close = output_to "guestfs-actions.pod" in
8232   generate_actions_pod ();
8233   close ();
8234
8235   let close = output_to "guestfish-actions.pod" in
8236   generate_fish_actions_pod ();
8237   close ();
8238
8239   let close = output_to "ocaml/guestfs.mli" in
8240   generate_ocaml_mli ();
8241   close ();
8242
8243   let close = output_to "ocaml/guestfs.ml" in
8244   generate_ocaml_ml ();
8245   close ();
8246
8247   let close = output_to "ocaml/guestfs_c_actions.c" in
8248   generate_ocaml_c ();
8249   close ();
8250
8251   let close = output_to "ocaml/bindtests.ml" in
8252   generate_ocaml_bindtests ();
8253   close ();
8254
8255   let close = output_to "perl/Guestfs.xs" in
8256   generate_perl_xs ();
8257   close ();
8258
8259   let close = output_to "perl/lib/Sys/Guestfs.pm" in
8260   generate_perl_pm ();
8261   close ();
8262
8263   let close = output_to "perl/bindtests.pl" in
8264   generate_perl_bindtests ();
8265   close ();
8266
8267   let close = output_to "python/guestfs-py.c" in
8268   generate_python_c ();
8269   close ();
8270
8271   let close = output_to "python/guestfs.py" in
8272   generate_python_py ();
8273   close ();
8274
8275   let close = output_to "python/bindtests.py" in
8276   generate_python_bindtests ();
8277   close ();
8278
8279   let close = output_to "ruby/ext/guestfs/_guestfs.c" in
8280   generate_ruby_c ();
8281   close ();
8282
8283   let close = output_to "ruby/bindtests.rb" in
8284   generate_ruby_bindtests ();
8285   close ();
8286
8287   let close = output_to "java/com/redhat/et/libguestfs/GuestFS.java" in
8288   generate_java_java ();
8289   close ();
8290
8291   List.iter (
8292     fun (typ, jtyp) ->
8293       let cols = cols_of_struct typ in
8294       let filename = sprintf "java/com/redhat/et/libguestfs/%s.java" jtyp in
8295       let close = output_to filename in
8296       generate_java_struct jtyp cols;
8297       close ();
8298   ) java_structs;
8299
8300   let close = output_to "java/com_redhat_et_libguestfs_GuestFS.c" in
8301   generate_java_c ();
8302   close ();
8303
8304   let close = output_to "java/Bindtests.java" in
8305   generate_java_bindtests ();
8306   close ();
8307
8308   let close = output_to "haskell/Guestfs.hs" in
8309   generate_haskell_hs ();
8310   close ();
8311
8312   let close = output_to "haskell/Bindtests.hs" in
8313   generate_haskell_bindtests ();
8314   close ();
8315
8316   let close = output_to "src/MAX_PROC_NR" in
8317   generate_max_proc_nr ();
8318   close ();
8319
8320   (* Always generate this file last, and unconditionally.  It's used
8321    * by the Makefile to know when we must re-run the generator.
8322    *)
8323   let chan = open_out "src/stamp-generator" in
8324   fprintf chan "1\n";
8325   close_out chan