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     (* Some limited tuples are possible: *)
  70   | RIntBool of string * string
  71     (* LVM PVs, VGs and LVs. *)
  72   | RPVList of string
  73   | RVGList of string
  74   | RLVList of string
  75     (* Stat buffers. *)
  76   | RStat of string
  77   | RStatVFS of string
  78     (* Key-value pairs of untyped strings.  Turns into a hashtable or
  79      * dictionary in languages which support it.  DON'T use this as a
  80      * general "bucket" for results.  Prefer a stronger typed return
  81      * value if one is available, or write a custom struct.  Don't use
  82      * this if the list could potentially be very long, since it is
  83      * inefficient.  Keys should be unique.  NULLs are not permitted.
  84      *)
  85   | RHashtable of string
  86
  87 and args = argt list    (* Function parameters, guestfs handle is implicit. *)
  88
  89     (* Note in future we should allow a "variable args" parameter as
  90      * the final parameter, to allow commands like
  91      *   chmod mode file [file(s)...]
  92      * This is not implemented yet, but many commands (such as chmod)
  93      * are currently defined with the argument order keeping this future
  94      * possibility in mind.
  95      *)
  96 and argt =
  97   | String of string    (* const char *name, cannot be NULL *)
  98   | OptString of string (* const char *name, may be NULL *)
  99   | StringList of string(* list of strings (each string cannot be NULL) *)
 100   | Bool of string      (* boolean *)
 101   | Int of string       (* int (smallish ints, signed, <= 31 bits) *)
 102     (* These are treated as filenames (simple string parameters) in
 103      * the C API and bindings.  But in the RPC protocol, we transfer
 104      * the actual file content up to or down from the daemon.
 105      * FileIn: local machine -> daemon (in request)
 106      * FileOut: daemon -> local machine (in reply)
 107      * In guestfish (only), the special name "-" means read from
 108      * stdin or write to stdout.
 109      *)
 110   | FileIn of string
 111   | FileOut of string
 112
 113 type flags =
 114   | ProtocolLimitWarning  (* display warning about protocol size limits *)
 115   | DangerWillRobinson    (* flags particularly dangerous commands *)
 116   | FishAlias of string   (* provide an alias for this cmd in guestfish *)
 117   | FishAction of string  (* call this function in guestfish *)
 118   | NotInFish             (* do not export via guestfish *)
 119   | NotInDocs             (* do not add this function to documentation *)
 120
 121 let protocol_limit_warning =
 122   "Because of the message protocol, there is a transfer limit
 123 of somewhere between 2MB and 4MB.  To transfer large files you should use
 124 FTP."
 125
 126 let danger_will_robinson =
 127   "B<This command is dangerous.  Without careful use you
 128 can easily destroy all your data>."
 129
 130 (* You can supply zero or as many tests as you want per API call.
 131  *
 132  * Note that the test environment has 3 block devices, of size 500MB,
 133  * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and
 134  * a fourth squashfs block device with some known files on it (/dev/sdd).
 135  *
 136  * Note for partitioning purposes, the 500MB device has 63 cylinders.
 137  *
 138  * The squashfs block device (/dev/sdd) comes from images/test.sqsh.
 139  *
 140  * To be able to run the tests in a reasonable amount of time,
 141  * the virtual machine and block devices are reused between tests.
 142  * So don't try testing kill_subprocess :-x
 143  *
 144  * Between each test we blockdev-setrw, umount-all, lvm-remove-all.
 145  *
 146  * If the appliance is running an older Linux kernel (eg. RHEL 5) then
 147  * devices are named /dev/hda etc.  To cope with this, the test suite
 148  * adds some hairly logic to detect this case, and then automagically
 149  * replaces all strings which match "/dev/sd.*" with "/dev/hd.*".
 150  * When writing test cases you shouldn't have to worry about this
 151  * difference.
 152  *
 153  * Don't assume anything about the previous contents of the block
 154  * devices.  Use 'Init*' to create some initial scenarios.
 155  *
 156  * You can add a prerequisite clause to any individual test.  This
 157  * is a run-time check, which, if it fails, causes the test to be
 158  * skipped.  Useful if testing a command which might not work on
 159  * all variations of libguestfs builds.  A test that has prerequisite
 160  * of 'Always' is run unconditionally.
 161  *
 162  * In addition, packagers can skip individual tests by setting the
 163  * environment variables:     eg:
 164  *   SKIP_TEST_<CMD>_<NUM>=1  SKIP_TEST_COMMAND_3=1  (skips test #3 of command)
 165  *   SKIP_TEST_<CMD>=1        SKIP_TEST_ZEROFREE=1   (skips all zerofree tests)
 166  *)
 167 type tests = (test_init * test_prereq * test) list
 168 and test =
 169     (* Run the command sequence and just expect nothing to fail. *)
 170   | TestRun of seq
 171     (* Run the command sequence and expect the output of the final
 172      * command to be the string.
 173      *)
 174   | TestOutput of seq * string
 175     (* Run the command sequence and expect the output of the final
 176      * command to be the list of strings.
 177      *)
 178   | TestOutputList of seq * string list
 179     (* Run the command sequence and expect the output of the final
 180      * command to be the integer.
 181      *)
 182   | TestOutputInt of seq * int
 183     (* Run the command sequence and expect the output of the final
 184      * command to be a true value (!= 0 or != NULL).
 185      *)
 186   | TestOutputTrue of seq
 187     (* Run the command sequence and expect the output of the final
 188      * command to be a false value (== 0 or == NULL, but not an error).
 189      *)
 190   | TestOutputFalse of seq
 191     (* Run the command sequence and expect the output of the final
 192      * command to be a list of the given length (but don't care about
 193      * content).
 194      *)
 195   | TestOutputLength of seq * int
 196     (* Run the command sequence and expect the output of the final
 197      * command to be a structure.
 198      *)
 199   | TestOutputStruct of seq * test_field_compare list
 200     (* Run the command sequence and expect the final command (only)
 201      * to fail.
 202      *)
 203   | TestLastFail of seq
 204
 205 and test_field_compare =
 206   | CompareWithInt of string * int
 207   | CompareWithString of string * string
 208   | CompareFieldsIntEq of string * string
 209   | CompareFieldsStrEq of string * string
 210
 211 (* Test prerequisites. *)
 212 and test_prereq =
 213     (* Test always runs. *)
 214   | Always
 215     (* Test is currently disabled - eg. it fails, or it tests some
 216      * unimplemented feature.
 217      *)
 218   | Disabled
 219     (* 'string' is some C code (a function body) that should return
 220      * true or false.  The test will run if the code returns true.
 221      *)
 222   | If of string
 223     (* As for 'If' but the test runs _unless_ the code returns true. *)
 224   | Unless of string
 225
 226 (* Some initial scenarios for testing. *)
 227 and test_init =
 228     (* Do nothing, block devices could contain random stuff including
 229      * LVM PVs, and some filesystems might be mounted.  This is usually
 230      * a bad idea.
 231      *)
 232   | InitNone
 233     (* Block devices are empty and no filesystems are mounted. *)
 234   | InitEmpty
 235     (* /dev/sda contains a single partition /dev/sda1, which is formatted
 236      * as ext2, empty [except for lost+found] and mounted on /.
 237      * /dev/sdb and /dev/sdc may have random content.
 238      * No LVM.
 239      *)
 240   | InitBasicFS
 241     (* /dev/sda:
 242      *   /dev/sda1 (is a PV):
 243      *     /dev/VG/LV (size 8MB):
 244      *       formatted as ext2, empty [except for lost+found], mounted on /
 245      * /dev/sdb and /dev/sdc may have random content.
 246      *)
 247   | InitBasicFSonLVM
 248
 249 (* Sequence of commands for testing. *)
 250 and seq = cmd list
 251 and cmd = string list
 252
 253 (* Note about long descriptions: When referring to another
 254  * action, use the format C<guestfs_other> (ie. the full name of
 255  * the C function).  This will be replaced as appropriate in other
 256  * language bindings.
 257  *
 258  * Apart from that, long descriptions are just perldoc paragraphs.
 259  *)
 260
 261 (* These test functions are used in the language binding tests. *)
 262
 263 let test_all_args = [
 264   String "str";
 265   OptString "optstr";
 266   StringList "strlist";
 267   Bool "b";
 268   Int "integer";
 269   FileIn "filein";
 270   FileOut "fileout";
 271 ]
 272
 273 let test_all_rets = [
 274   (* except for RErr, which is tested thoroughly elsewhere *)
 275   "test0rint",         RInt "valout";
 276   "test0rint64",       RInt64 "valout";
 277   "test0rbool",        RBool "valout";
 278   "test0rconststring", RConstString "valout";
 279   "test0rstring",      RString "valout";
 280   "test0rstringlist",  RStringList "valout";
 281   "test0rintbool",     RIntBool ("valout", "valout");
 282   "test0rpvlist",      RPVList "valout";
 283   "test0rvglist",      RVGList "valout";
 284   "test0rlvlist",      RLVList "valout";
 285   "test0rstat",        RStat "valout";
 286   "test0rstatvfs",     RStatVFS "valout";
 287   "test0rhashtable",   RHashtable "valout";
 288 ]
 289
 290 let test_functions = [
 291   ("test0", (RErr, test_all_args), -1, [NotInFish; NotInDocs],
 292    [],
 293    "internal test function - do not use",
 294    "\
 295 This is an internal test function which is used to test whether
 296 the automatically generated bindings can handle every possible
 297 parameter type correctly.
 298
 299 It echos the contents of each parameter to stdout.
 300
 301 You probably don't want to call this function.");
 302 ] @ List.flatten (
 303   List.map (
 304     fun (name, ret) ->
 305       [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs],
 306         [],
 307         "internal test function - do not use",
 308         "\
 309 This is an internal test function which is used to test whether
 310 the automatically generated bindings can handle every possible
 311 return type correctly.
 312
 313 It converts string C<val> to the return type.
 314
 315 You probably don't want to call this function.");
 316        (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs],
 317         [],
 318         "internal test function - do not use",
 319         "\
 320 This is an internal test function which is used to test whether
 321 the automatically generated bindings can handle every possible
 322 return type correctly.
 323
 324 This function always returns an error.
 325
 326 You probably don't want to call this function.")]
 327   ) test_all_rets
 328 )
 329
 330 (* non_daemon_functions are any functions which don't get processed
 331  * in the daemon, eg. functions for setting and getting local
 332  * configuration values.
 333  *)
 334
 335 let non_daemon_functions = test_functions @ [
 336   ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"],
 337    [],
 338    "launch the qemu subprocess",
 339    "\
 340 Internally libguestfs is implemented by running a virtual machine
 341 using L<qemu(1)>.
 342
 343 You should call this after configuring the handle
 344 (eg. adding drives) but before performing any actions.");
 345
 346   ("wait_ready", (RErr, []), -1, [NotInFish],
 347    [],
 348    "wait until the qemu subprocess launches",
 349    "\
 350 Internally libguestfs is implemented by running a virtual machine
 351 using L<qemu(1)>.
 352
 353 You should call this after C<guestfs_launch> to wait for the launch
 354 to complete.");
 355
 356   ("kill_subprocess", (RErr, []), -1, [],
 357    [],
 358    "kill the qemu subprocess",
 359    "\
 360 This kills the qemu subprocess.  You should never need to call this.");
 361
 362   ("add_drive", (RErr, [String "filename"]), -1, [FishAlias "add"],
 363    [],
 364    "add an image to examine or modify",
 365    "\
 366 This function adds a virtual machine disk image C<filename> to the
 367 guest.  The first time you call this function, the disk appears as IDE
 368 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
 369 so on.
 370
 371 You don't necessarily need to be root when using libguestfs.  However
 372 you obviously do need sufficient permissions to access the filename
 373 for whatever operations you want to perform (ie. read access if you
 374 just want to read the image or write access if you want to modify the
 375 image).
 376
 377 This is equivalent to the qemu parameter C<-drive file=filename>.");
 378
 379   ("add_cdrom", (RErr, [String "filename"]), -1, [FishAlias "cdrom"],
 380    [],
 381    "add a CD-ROM disk image to examine",
 382    "\
 383 This function adds a virtual CD-ROM disk image to the guest.
 384
 385 This is equivalent to the qemu parameter C<-cdrom filename>.");
 386
 387   ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"]), -1, [],
 388    [],
 389    "add qemu parameters",
 390    "\
 391 This can be used to add arbitrary qemu command line parameters
 392 of the form C<-param value>.  Actually it's not quite arbitrary - we
 393 prevent you from setting some parameters which would interfere with
 394 parameters that we use.
 395
 396 The first character of C<param> string must be a C<-> (dash).
 397
 398 C<value> can be NULL.");
 399
 400   ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"],
 401    [],
 402    "set the qemu binary",
 403    "\
 404 Set the qemu binary that we will use.
 405
 406 The default is chosen when the library was compiled by the
 407 configure script.
 408
 409 You can also override this by setting the C<LIBGUESTFS_QEMU>
 410 environment variable.
 411
 412 Setting C<qemu> to C<NULL> restores the default qemu binary.");
 413
 414   ("get_qemu", (RConstString "qemu", []), -1, [],
 415    [],
 416    "get the qemu binary",
 417    "\
 418 Return the current qemu binary.
 419
 420 This is always non-NULL.  If it wasn't set already, then this will
 421 return the default qemu binary name.");
 422
 423   ("set_path", (RErr, [String "path"]), -1, [FishAlias "path"],
 424    [],
 425    "set the search path",
 426    "\
 427 Set the path that libguestfs searches for kernel and initrd.img.
 428
 429 The default is C<$libdir/guestfs> unless overridden by setting
 430 C<LIBGUESTFS_PATH> environment variable.
 431
 432 Setting C<path> to C<NULL> restores the default path.");
 433
 434   ("get_path", (RConstString "path", []), -1, [],
 435    [],
 436    "get the search path",
 437    "\
 438 Return the current search path.
 439
 440 This is always non-NULL.  If it wasn't set already, then this will
 441 return the default path.");
 442
 443   ("set_append", (RErr, [String "append"]), -1, [FishAlias "append"],
 444    [],
 445    "add options to kernel command line",
 446    "\
 447 This function is used to add additional options to the
 448 guest kernel command line.
 449
 450 The default is C<NULL> unless overridden by setting
 451 C<LIBGUESTFS_APPEND> environment variable.
 452
 453 Setting C<append> to C<NULL> means I<no> additional options
 454 are passed (libguestfs always adds a few of its own).");
 455
 456   ("get_append", (RConstString "append", []), -1, [],
 457    [],
 458    "get the additional kernel options",
 459    "\
 460 Return the additional kernel options which are added to the
 461 guest kernel command line.
 462
 463 If C<NULL> then no options are added.");
 464
 465   ("set_autosync", (RErr, [Bool "autosync"]), -1, [FishAlias "autosync"],
 466    [],
 467    "set autosync mode",
 468    "\
 469 If C<autosync> is true, this enables autosync.  Libguestfs will make a
 470 best effort attempt to run C<guestfs_umount_all> followed by
 471 C<guestfs_sync> when the handle is closed
 472 (also if the program exits without closing handles).
 473
 474 This is disabled by default (except in guestfish where it is
 475 enabled by default).");
 476
 477   ("get_autosync", (RBool "autosync", []), -1, [],
 478    [],
 479    "get autosync mode",
 480    "\
 481 Get the autosync flag.");
 482
 483   ("set_verbose", (RErr, [Bool "verbose"]), -1, [FishAlias "verbose"],
 484    [],
 485    "set verbose mode",
 486    "\
 487 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
 488
 489 Verbose messages are disabled unless the environment variable
 490 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
 491
 492   ("get_verbose", (RBool "verbose", []), -1, [],
 493    [],
 494    "get verbose mode",
 495    "\
 496 This returns the verbose messages flag.");
 497
 498   ("is_ready", (RBool "ready", []), -1, [],
 499    [],
 500    "is ready to accept commands",
 501    "\
 502 This returns true iff this handle is ready to accept commands
 503 (in the C<READY> state).
 504
 505 For more information on states, see L<guestfs(3)>.");
 506
 507   ("is_config", (RBool "config", []), -1, [],
 508    [],
 509    "is in configuration state",
 510    "\
 511 This returns true iff this handle is being configured
 512 (in the C<CONFIG> state).
 513
 514 For more information on states, see L<guestfs(3)>.");
 515
 516   ("is_launching", (RBool "launching", []), -1, [],
 517    [],
 518    "is launching subprocess",
 519    "\
 520 This returns true iff this handle is launching the subprocess
 521 (in the C<LAUNCHING> state).
 522
 523 For more information on states, see L<guestfs(3)>.");
 524
 525   ("is_busy", (RBool "busy", []), -1, [],
 526    [],
 527    "is busy processing a command",
 528    "\
 529 This returns true iff this handle is busy processing a command
 530 (in the C<BUSY> state).
 531
 532 For more information on states, see L<guestfs(3)>.");
 533
 534   ("get_state", (RInt "state", []), -1, [],
 535    [],
 536    "get the current state",
 537    "\
 538 This returns the current state as an opaque integer.  This is
 539 only useful for printing debug and internal error messages.
 540
 541 For more information on states, see L<guestfs(3)>.");
 542
 543   ("set_busy", (RErr, []), -1, [NotInFish],
 544    [],
 545    "set state to busy",
 546    "\
 547 This sets the state to C<BUSY>.  This is only used when implementing
 548 actions using the low-level API.
 549
 550 For more information on states, see L<guestfs(3)>.");
 551
 552   ("set_ready", (RErr, []), -1, [NotInFish],
 553    [],
 554    "set state to ready",
 555    "\
 556 This sets the state to C<READY>.  This is only used when implementing
 557 actions using the low-level API.
 558
 559 For more information on states, see L<guestfs(3)>.");
 560
 561   ("end_busy", (RErr, []), -1, [NotInFish],
 562    [],
 563    "leave the busy state",
 564    "\
 565 This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
 566 state as is.  This is only used when implementing
 567 actions using the low-level API.
 568
 569 For more information on states, see L<guestfs(3)>.");
 570
 571 ]
 572
 573 (* daemon_functions are any functions which cause some action
 574  * to take place in the daemon.
 575  *)
 576
 577 let daemon_functions = [
 578   ("mount", (RErr, [String "device"; String "mountpoint"]), 1, [],
 579    [InitEmpty, Always, TestOutput (
 580       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
 581        ["mkfs"; "ext2"; "/dev/sda1"];
 582        ["mount"; "/dev/sda1"; "/"];
 583        ["write_file"; "/new"; "new file contents"; "0"];
 584        ["cat"; "/new"]], "new file contents")],
 585    "mount a guest disk at a position in the filesystem",
 586    "\
 587 Mount a guest disk at a position in the filesystem.  Block devices
 588 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
 589 the guest.  If those block devices contain partitions, they will have
 590 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
 591 names can be used.
 592
 593 The rules are the same as for L<mount(2)>:  A filesystem must
 594 first be mounted on C</> before others can be mounted.  Other
 595 filesystems can only be mounted on directories which already
 596 exist.
 597
 598 The mounted filesystem is writable, if we have sufficient permissions
 599 on the underlying device.
 600
 601 The filesystem options C<sync> and C<noatime> are set with this
 602 call, in order to improve reliability.");
 603
 604   ("sync", (RErr, []), 2, [],
 605    [ InitEmpty, Always, TestRun [["sync"]]],
 606    "sync disks, writes are flushed through to the disk image",
 607    "\
 608 This syncs the disk, so that any writes are flushed through to the
 609 underlying disk image.
 610
 611 You should always call this if you have modified a disk image, before
 612 closing the handle.");
 613
 614   ("touch", (RErr, [String "path"]), 3, [],
 615    [InitBasicFS, Always, TestOutputTrue (
 616       [["touch"; "/new"];
 617        ["exists"; "/new"]])],
 618    "update file timestamps or create a new file",
 619    "\
 620 Touch acts like the L<touch(1)> command.  It can be used to
 621 update the timestamps on a file, or, if the file does not exist,
 622 to create a new zero-length file.");
 623
 624   ("cat", (RString "content", [String "path"]), 4, [ProtocolLimitWarning],
 625    [InitBasicFS, Always, TestOutput (
 626       [["write_file"; "/new"; "new file contents"; "0"];
 627        ["cat"; "/new"]], "new file contents")],
 628    "list the contents of a file",
 629    "\
 630 Return the contents of the file named C<path>.
 631
 632 Note that this function cannot correctly handle binary files
 633 (specifically, files containing C<\\0> character which is treated
 634 as end of string).  For those you need to use the C<guestfs_download>
 635 function which has a more complex interface.");
 636
 637   ("ll", (RString "listing", [String "directory"]), 5, [],
 638    [], (* XXX Tricky to test because it depends on the exact format
 639         * of the 'ls -l' command, which changes between F10 and F11.
 640         *)
 641    "list the files in a directory (long format)",
 642    "\
 643 List the files in C<directory> (relative to the root directory,
 644 there is no cwd) in the format of 'ls -la'.
 645
 646 This command is mostly useful for interactive sessions.  It
 647 is I<not> intended that you try to parse the output string.");
 648
 649   ("ls", (RStringList "listing", [String "directory"]), 6, [],
 650    [InitBasicFS, Always, TestOutputList (
 651       [["touch"; "/new"];
 652        ["touch"; "/newer"];
 653        ["touch"; "/newest"];
 654        ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])],
 655    "list the files in a directory",
 656    "\
 657 List the files in C<directory> (relative to the root directory,
 658 there is no cwd).  The '.' and '..' entries are not returned, but
 659 hidden files are shown.
 660
 661 This command is mostly useful for interactive sessions.  Programs
 662 should probably use C<guestfs_readdir> instead.");
 663
 664   ("list_devices", (RStringList "devices", []), 7, [],
 665    [InitEmpty, Always, TestOutputList (
 666       [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
 667    "list the block devices",
 668    "\
 669 List all the block devices.
 670
 671 The full block device names are returned, eg. C</dev/sda>");
 672
 673   ("list_partitions", (RStringList "partitions", []), 8, [],
 674    [InitBasicFS, Always, TestOutputList (
 675       [["list_partitions"]], ["/dev/sda1"]);
 676     InitEmpty, Always, TestOutputList (
 677       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
 678        ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
 679    "list the partitions",
 680    "\
 681 List all the partitions detected on all block devices.
 682
 683 The full partition device names are returned, eg. C</dev/sda1>
 684
 685 This does not return logical volumes.  For that you will need to
 686 call C<guestfs_lvs>.");
 687
 688   ("pvs", (RStringList "physvols", []), 9, [],
 689    [InitBasicFSonLVM, Always, TestOutputList (
 690       [["pvs"]], ["/dev/sda1"]);
 691     InitEmpty, Always, TestOutputList (
 692       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
 693        ["pvcreate"; "/dev/sda1"];
 694        ["pvcreate"; "/dev/sda2"];
 695        ["pvcreate"; "/dev/sda3"];
 696        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
 697    "list the LVM physical volumes (PVs)",
 698    "\
 699 List all the physical volumes detected.  This is the equivalent
 700 of the L<pvs(8)> command.
 701
 702 This returns a list of just the device names that contain
 703 PVs (eg. C</dev/sda2>).
 704
 705 See also C<guestfs_pvs_full>.");
 706
 707   ("vgs", (RStringList "volgroups", []), 10, [],
 708    [InitBasicFSonLVM, Always, TestOutputList (
 709       [["vgs"]], ["VG"]);
 710     InitEmpty, Always, TestOutputList (
 711       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
 712        ["pvcreate"; "/dev/sda1"];
 713        ["pvcreate"; "/dev/sda2"];
 714        ["pvcreate"; "/dev/sda3"];
 715        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
 716        ["vgcreate"; "VG2"; "/dev/sda3"];
 717        ["vgs"]], ["VG1"; "VG2"])],
 718    "list the LVM volume groups (VGs)",
 719    "\
 720 List all the volumes groups detected.  This is the equivalent
 721 of the L<vgs(8)> command.
 722
 723 This returns a list of just the volume group names that were
 724 detected (eg. C<VolGroup00>).
 725
 726 See also C<guestfs_vgs_full>.");
 727
 728   ("lvs", (RStringList "logvols", []), 11, [],
 729    [InitBasicFSonLVM, Always, TestOutputList (
 730       [["lvs"]], ["/dev/VG/LV"]);
 731     InitEmpty, Always, TestOutputList (
 732       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
 733        ["pvcreate"; "/dev/sda1"];
 734        ["pvcreate"; "/dev/sda2"];
 735        ["pvcreate"; "/dev/sda3"];
 736        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
 737        ["vgcreate"; "VG2"; "/dev/sda3"];
 738        ["lvcreate"; "LV1"; "VG1"; "50"];
 739        ["lvcreate"; "LV2"; "VG1"; "50"];
 740        ["lvcreate"; "LV3"; "VG2"; "50"];
 741        ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
 742    "list the LVM logical volumes (LVs)",
 743    "\
 744 List all the logical volumes detected.  This is the equivalent
 745 of the L<lvs(8)> command.
 746
 747 This returns a list of the logical volume device names
 748 (eg. C</dev/VolGroup00/LogVol00>).
 749
 750 See also C<guestfs_lvs_full>.");
 751
 752   ("pvs_full", (RPVList "physvols", []), 12, [],
 753    [], (* XXX how to test? *)
 754    "list the LVM physical volumes (PVs)",
 755    "\
 756 List all the physical volumes detected.  This is the equivalent
 757 of the L<pvs(8)> command.  The \"full\" version includes all fields.");
 758
 759   ("vgs_full", (RVGList "volgroups", []), 13, [],
 760    [], (* XXX how to test? *)
 761    "list the LVM volume groups (VGs)",
 762    "\
 763 List all the volumes groups detected.  This is the equivalent
 764 of the L<vgs(8)> command.  The \"full\" version includes all fields.");
 765
 766   ("lvs_full", (RLVList "logvols", []), 14, [],
 767    [], (* XXX how to test? *)
 768    "list the LVM logical volumes (LVs)",
 769    "\
 770 List all the logical volumes detected.  This is the equivalent
 771 of the L<lvs(8)> command.  The \"full\" version includes all fields.");
 772
 773   ("read_lines", (RStringList "lines", [String "path"]), 15, [],
 774    [InitBasicFS, Always, TestOutputList (
 775       [["write_file"; "/new"; "line1\r\nline2\nline3"; "0"];
 776        ["read_lines"; "/new"]], ["line1"; "line2"; "line3"]);
 777     InitBasicFS, Always, TestOutputList (
 778       [["write_file"; "/new"; ""; "0"];
 779        ["read_lines"; "/new"]], [])],
 780    "read file as lines",
 781    "\
 782 Return the contents of the file named C<path>.
 783
 784 The file contents are returned as a list of lines.  Trailing
 785 C<LF> and C<CRLF> character sequences are I<not> returned.
 786
 787 Note that this function cannot correctly handle binary files
 788 (specifically, files containing C<\\0> character which is treated
 789 as end of line).  For those you need to use the C<guestfs_read_file>
 790 function which has a more complex interface.");
 791
 792   ("aug_init", (RErr, [String "root"; Int "flags"]), 16, [],
 793    [], (* XXX Augeas code needs tests. *)
 794    "create a new Augeas handle",
 795    "\
 796 Create a new Augeas handle for editing configuration files.
 797 If there was any previous Augeas handle associated with this
 798 guestfs session, then it is closed.
 799
 800 You must call this before using any other C<guestfs_aug_*>
 801 commands.
 802
 803 C<root> is the filesystem root.  C<root> must not be NULL,
 804 use C</> instead.
 805
 806 The flags are the same as the flags defined in
 807 E<lt>augeas.hE<gt>, the logical I<or> of the following
 808 integers:
 809
 810 =over 4
 811
 812 =item C<AUG_SAVE_BACKUP> = 1
 813
 814 Keep the original file with a C<.augsave> extension.
 815
 816 =item C<AUG_SAVE_NEWFILE> = 2
 817
 818 Save changes into a file with extension C<.augnew>, and
 819 do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
 820
 821 =item C<AUG_TYPE_CHECK> = 4
 822
 823 Typecheck lenses (can be expensive).
 824
 825 =item C<AUG_NO_STDINC> = 8
 826
 827 Do not use standard load path for modules.
 828
 829 =item C<AUG_SAVE_NOOP> = 16
 830
 831 Make save a no-op, just record what would have been changed.
 832
 833 =item C<AUG_NO_LOAD> = 32
 834
 835 Do not load the tree in C<guestfs_aug_init>.
 836
 837 =back
 838
 839 To close the handle, you can call C<guestfs_aug_close>.
 840
 841 To find out more about Augeas, see L<http://augeas.net/>.");
 842
 843   ("aug_close", (RErr, []), 26, [],
 844    [], (* XXX Augeas code needs tests. *)
 845    "close the current Augeas handle",
 846    "\
 847 Close the current Augeas handle and free up any resources
 848 used by it.  After calling this, you have to call
 849 C<guestfs_aug_init> again before you can use any other
 850 Augeas functions.");
 851
 852   ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [],
 853    [], (* XXX Augeas code needs tests. *)
 854    "define an Augeas variable",
 855    "\
 856 Defines an Augeas variable C<name> whose value is the result
 857 of evaluating C<expr>.  If C<expr> is NULL, then C<name> is
 858 undefined.
 859
 860 On success this returns the number of nodes in C<expr>, or
 861 C<0> if C<expr> evaluates to something which is not a nodeset.");
 862
 863   ("aug_defnode", (RIntBool ("nrnodes", "created"), [String "name"; String "expr"; String "val"]), 18, [],
 864    [], (* XXX Augeas code needs tests. *)
 865    "define an Augeas node",
 866    "\
 867 Defines a variable C<name> whose value is the result of
 868 evaluating C<expr>.
 869
 870 If C<expr> evaluates to an empty nodeset, a node is created,
 871 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
 872 C<name> will be the nodeset containing that single node.
 873
 874 On success this returns a pair containing the
 875 number of nodes in the nodeset, and a boolean flag
 876 if a node was created.");
 877
 878   ("aug_get", (RString "val", [String "path"]), 19, [],
 879    [], (* XXX Augeas code needs tests. *)
 880    "look up the value of an Augeas path",
 881    "\
 882 Look up the value associated with C<path>.  If C<path>
 883 matches exactly one node, the C<value> is returned.");
 884
 885   ("aug_set", (RErr, [String "path"; String "val"]), 20, [],
 886    [], (* XXX Augeas code needs tests. *)
 887    "set Augeas path to value",
 888    "\
 889 Set the value associated with C<path> to C<value>.");
 890
 891   ("aug_insert", (RErr, [String "path"; String "label"; Bool "before"]), 21, [],
 892    [], (* XXX Augeas code needs tests. *)
 893    "insert a sibling Augeas node",
 894    "\
 895 Create a new sibling C<label> for C<path>, inserting it into
 896 the tree before or after C<path> (depending on the boolean
 897 flag C<before>).
 898
 899 C<path> must match exactly one existing node in the tree, and
 900 C<label> must be a label, ie. not contain C</>, C<*> or end
 901 with a bracketed index C<[N]>.");
 902
 903   ("aug_rm", (RInt "nrnodes", [String "path"]), 22, [],
 904    [], (* XXX Augeas code needs tests. *)
 905    "remove an Augeas path",
 906    "\
 907 Remove C<path> and all of its children.
 908
 909 On success this returns the number of entries which were removed.");
 910
 911   ("aug_mv", (RErr, [String "src"; String "dest"]), 23, [],
 912    [], (* XXX Augeas code needs tests. *)
 913    "move Augeas node",
 914    "\
 915 Move the node C<src> to C<dest>.  C<src> must match exactly
 916 one node.  C<dest> is overwritten if it exists.");
 917
 918   ("aug_match", (RStringList "matches", [String "path"]), 24, [],
 919    [], (* XXX Augeas code needs tests. *)
 920    "return Augeas nodes which match path",
 921    "\
 922 Returns a list of paths which match the path expression C<path>.
 923 The returned paths are sufficiently qualified so that they match
 924 exactly one node in the current tree.");
 925
 926   ("aug_save", (RErr, []), 25, [],
 927    [], (* XXX Augeas code needs tests. *)
 928    "write all pending Augeas changes to disk",
 929    "\
 930 This writes all pending changes to disk.
 931
 932 The flags which were passed to C<guestfs_aug_init> affect exactly
 933 how files are saved.");
 934
 935   ("aug_load", (RErr, []), 27, [],
 936    [], (* XXX Augeas code needs tests. *)
 937    "load files into the tree",
 938    "\
 939 Load files into the tree.
 940
 941 See C<aug_load> in the Augeas documentation for the full gory
 942 details.");
 943
 944   ("aug_ls", (RStringList "matches", [String "path"]), 28, [],
 945    [], (* XXX Augeas code needs tests. *)
 946    "list Augeas nodes under a path",
 947    "\
 948 This is just a shortcut for listing C<guestfs_aug_match>
 949 C<path/*> and sorting the resulting nodes into alphabetical order.");
 950
 951   ("rm", (RErr, [String "path"]), 29, [],
 952    [InitBasicFS, Always, TestRun
 953       [["touch"; "/new"];
 954        ["rm"; "/new"]];
 955     InitBasicFS, Always, TestLastFail
 956       [["rm"; "/new"]];
 957     InitBasicFS, Always, TestLastFail
 958       [["mkdir"; "/new"];
 959        ["rm"; "/new"]]],
 960    "remove a file",
 961    "\
 962 Remove the single file C<path>.");
 963
 964   ("rmdir", (RErr, [String "path"]), 30, [],
 965    [InitBasicFS, Always, TestRun
 966       [["mkdir"; "/new"];
 967        ["rmdir"; "/new"]];
 968     InitBasicFS, Always, TestLastFail
 969       [["rmdir"; "/new"]];
 970     InitBasicFS, Always, TestLastFail
 971       [["touch"; "/new"];
 972        ["rmdir"; "/new"]]],
 973    "remove a directory",
 974    "\
 975 Remove the single directory C<path>.");
 976
 977   ("rm_rf", (RErr, [String "path"]), 31, [],
 978    [InitBasicFS, Always, TestOutputFalse
 979       [["mkdir"; "/new"];
 980        ["mkdir"; "/new/foo"];
 981        ["touch"; "/new/foo/bar"];
 982        ["rm_rf"; "/new"];
 983        ["exists"; "/new"]]],
 984    "remove a file or directory recursively",
 985    "\
 986 Remove the file or directory C<path>, recursively removing the
 987 contents if its a directory.  This is like the C<rm -rf> shell
 988 command.");
 989
 990   ("mkdir", (RErr, [String "path"]), 32, [],
 991    [InitBasicFS, Always, TestOutputTrue
 992       [["mkdir"; "/new"];
 993        ["is_dir"; "/new"]];
 994     InitBasicFS, Always, TestLastFail
 995       [["mkdir"; "/new/foo/bar"]]],
 996    "create a directory",
 997    "\
 998 Create a directory named C<path>.");
 999
1000   ("mkdir_p", (RErr, [String "path"]), 33, [],
1001    [InitBasicFS, Always, TestOutputTrue
1002       [["mkdir_p"; "/new/foo/bar"];
1003        ["is_dir"; "/new/foo/bar"]];
1004     InitBasicFS, Always, TestOutputTrue
1005       [["mkdir_p"; "/new/foo/bar"];
1006        ["is_dir"; "/new/foo"]];
1007     InitBasicFS, Always, TestOutputTrue
1008       [["mkdir_p"; "/new/foo/bar"];
1009        ["is_dir"; "/new"]];
1010     (* Regression tests for RHBZ#503133: *)
1011     InitBasicFS, Always, TestRun
1012       [["mkdir"; "/new"];
1013        ["mkdir_p"; "/new"]];
1014     InitBasicFS, Always, TestLastFail
1015       [["touch"; "/new"];
1016        ["mkdir_p"; "/new"]]],
1017    "create a directory and parents",
1018    "\
1019 Create a directory named C<path>, creating any parent directories
1020 as necessary.  This is like the C<mkdir -p> shell command.");
1021
1022   ("chmod", (RErr, [Int "mode"; String "path"]), 34, [],
1023    [], (* XXX Need stat command to test *)
1024    "change file mode",
1025    "\
1026 Change the mode (permissions) of C<path> to C<mode>.  Only
1027 numeric modes are supported.");
1028
1029   ("chown", (RErr, [Int "owner"; Int "group"; String "path"]), 35, [],
1030    [], (* XXX Need stat command to test *)
1031    "change file owner and group",
1032    "\
1033 Change the file owner to C<owner> and group to C<group>.
1034
1035 Only numeric uid and gid are supported.  If you want to use
1036 names, you will need to locate and parse the password file
1037 yourself (Augeas support makes this relatively easy).");
1038
1039   ("exists", (RBool "existsflag", [String "path"]), 36, [],
1040    [InitBasicFS, Always, TestOutputTrue (
1041       [["touch"; "/new"];
1042        ["exists"; "/new"]]);
1043     InitBasicFS, Always, TestOutputTrue (
1044       [["mkdir"; "/new"];
1045        ["exists"; "/new"]])],
1046    "test if file or directory exists",
1047    "\
1048 This returns C<true> if and only if there is a file, directory
1049 (or anything) with the given C<path> name.
1050
1051 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
1052
1053   ("is_file", (RBool "fileflag", [String "path"]), 37, [],
1054    [InitBasicFS, Always, TestOutputTrue (
1055       [["touch"; "/new"];
1056        ["is_file"; "/new"]]);
1057     InitBasicFS, Always, TestOutputFalse (
1058       [["mkdir"; "/new"];
1059        ["is_file"; "/new"]])],
1060    "test if file exists",
1061    "\
1062 This returns C<true> if and only if there is a file
1063 with the given C<path> name.  Note that it returns false for
1064 other objects like directories.
1065
1066 See also C<guestfs_stat>.");
1067
1068   ("is_dir", (RBool "dirflag", [String "path"]), 38, [],
1069    [InitBasicFS, Always, TestOutputFalse (
1070       [["touch"; "/new"];
1071        ["is_dir"; "/new"]]);
1072     InitBasicFS, Always, TestOutputTrue (
1073       [["mkdir"; "/new"];
1074        ["is_dir"; "/new"]])],
1075    "test if file exists",
1076    "\
1077 This returns C<true> if and only if there is a directory
1078 with the given C<path> name.  Note that it returns false for
1079 other objects like files.
1080
1081 See also C<guestfs_stat>.");
1082
1083   ("pvcreate", (RErr, [String "device"]), 39, [],
1084    [InitEmpty, Always, TestOutputList (
1085       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
1086        ["pvcreate"; "/dev/sda1"];
1087        ["pvcreate"; "/dev/sda2"];
1088        ["pvcreate"; "/dev/sda3"];
1089        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1090    "create an LVM physical volume",
1091    "\
1092 This creates an LVM physical volume on the named C<device>,
1093 where C<device> should usually be a partition name such
1094 as C</dev/sda1>.");
1095
1096   ("vgcreate", (RErr, [String "volgroup"; StringList "physvols"]), 40, [],
1097    [InitEmpty, Always, TestOutputList (
1098       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
1099        ["pvcreate"; "/dev/sda1"];
1100        ["pvcreate"; "/dev/sda2"];
1101        ["pvcreate"; "/dev/sda3"];
1102        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1103        ["vgcreate"; "VG2"; "/dev/sda3"];
1104        ["vgs"]], ["VG1"; "VG2"])],
1105    "create an LVM volume group",
1106    "\
1107 This creates an LVM volume group called C<volgroup>
1108 from the non-empty list of physical volumes C<physvols>.");
1109
1110   ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"]), 41, [],
1111    [InitEmpty, Always, TestOutputList (
1112       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
1113        ["pvcreate"; "/dev/sda1"];
1114        ["pvcreate"; "/dev/sda2"];
1115        ["pvcreate"; "/dev/sda3"];
1116        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1117        ["vgcreate"; "VG2"; "/dev/sda3"];
1118        ["lvcreate"; "LV1"; "VG1"; "50"];
1119        ["lvcreate"; "LV2"; "VG1"; "50"];
1120        ["lvcreate"; "LV3"; "VG2"; "50"];
1121        ["lvcreate"; "LV4"; "VG2"; "50"];
1122        ["lvcreate"; "LV5"; "VG2"; "50"];
1123        ["lvs"]],
1124       ["/dev/VG1/LV1"; "/dev/VG1/LV2";
1125        "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
1126    "create an LVM volume group",
1127    "\
1128 This creates an LVM volume group called C<logvol>
1129 on the volume group C<volgroup>, with C<size> megabytes.");
1130
1131   ("mkfs", (RErr, [String "fstype"; String "device"]), 42, [],
1132    [InitEmpty, Always, TestOutput (
1133       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1134        ["mkfs"; "ext2"; "/dev/sda1"];
1135        ["mount"; "/dev/sda1"; "/"];
1136        ["write_file"; "/new"; "new file contents"; "0"];
1137        ["cat"; "/new"]], "new file contents")],
1138    "make a filesystem",
1139    "\
1140 This creates a filesystem on C<device> (usually a partition
1141 or LVM logical volume).  The filesystem type is C<fstype>, for
1142 example C<ext3>.");
1143
1144   ("sfdisk", (RErr, [String "device";
1145                      Int "cyls"; Int "heads"; Int "sectors";
1146                      StringList "lines"]), 43, [DangerWillRobinson],
1147    [],
1148    "create partitions on a block device",
1149    "\
1150 This is a direct interface to the L<sfdisk(8)> program for creating
1151 partitions on block devices.
1152
1153 C<device> should be a block device, for example C</dev/sda>.
1154
1155 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1156 and sectors on the device, which are passed directly to sfdisk as
1157 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
1158 of these, then the corresponding parameter is omitted.  Usually for
1159 'large' disks, you can just pass C<0> for these, but for small
1160 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1161 out the right geometry and you will need to tell it.
1162
1163 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
1164 information refer to the L<sfdisk(8)> manpage.
1165
1166 To create a single partition occupying the whole disk, you would
1167 pass C<lines> as a single element list, when the single element being
1168 the string C<,> (comma).
1169
1170 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>");
1171
1172   ("write_file", (RErr, [String "path"; String "content"; Int "size"]), 44, [ProtocolLimitWarning],
1173    [InitBasicFS, Always, TestOutput (
1174       [["write_file"; "/new"; "new file contents"; "0"];
1175        ["cat"; "/new"]], "new file contents");
1176     InitBasicFS, Always, TestOutput (
1177       [["write_file"; "/new"; "\nnew file contents\n"; "0"];
1178        ["cat"; "/new"]], "\nnew file contents\n");
1179     InitBasicFS, Always, TestOutput (
1180       [["write_file"; "/new"; "\n\n"; "0"];
1181        ["cat"; "/new"]], "\n\n");
1182     InitBasicFS, Always, TestOutput (
1183       [["write_file"; "/new"; ""; "0"];
1184        ["cat"; "/new"]], "");
1185     InitBasicFS, Always, TestOutput (
1186       [["write_file"; "/new"; "\n\n\n"; "0"];
1187        ["cat"; "/new"]], "\n\n\n");
1188     InitBasicFS, Always, TestOutput (
1189       [["write_file"; "/new"; "\n"; "0"];
1190        ["cat"; "/new"]], "\n")],
1191    "create a file",
1192    "\
1193 This call creates a file called C<path>.  The contents of the
1194 file is the string C<content> (which can contain any 8 bit data),
1195 with length C<size>.
1196
1197 As a special case, if C<size> is C<0>
1198 then the length is calculated using C<strlen> (so in this case
1199 the content cannot contain embedded ASCII NULs).
1200
1201 I<NB.> Owing to a bug, writing content containing ASCII NUL
1202 characters does I<not> work, even if the length is specified.
1203 We hope to resolve this bug in a future version.  In the meantime
1204 use C<guestfs_upload>.");
1205
1206   ("umount", (RErr, [String "pathordevice"]), 45, [FishAlias "unmount"],
1207    [InitEmpty, Always, TestOutputList (
1208       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1209        ["mkfs"; "ext2"; "/dev/sda1"];
1210        ["mount"; "/dev/sda1"; "/"];
1211        ["mounts"]], ["/dev/sda1"]);
1212     InitEmpty, Always, TestOutputList (
1213       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1214        ["mkfs"; "ext2"; "/dev/sda1"];
1215        ["mount"; "/dev/sda1"; "/"];
1216        ["umount"; "/"];
1217        ["mounts"]], [])],
1218    "unmount a filesystem",
1219    "\
1220 This unmounts the given filesystem.  The filesystem may be
1221 specified either by its mountpoint (path) or the device which
1222 contains the filesystem.");
1223
1224   ("mounts", (RStringList "devices", []), 46, [],
1225    [InitBasicFS, Always, TestOutputList (
1226       [["mounts"]], ["/dev/sda1"])],
1227    "show mounted filesystems",
1228    "\
1229 This returns the list of currently mounted filesystems.  It returns
1230 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1231
1232 Some internal mounts are not shown.");
1233
1234   ("umount_all", (RErr, []), 47, [FishAlias "unmount-all"],
1235    [InitBasicFS, Always, TestOutputList (
1236       [["umount_all"];
1237        ["mounts"]], []);
1238     (* check that umount_all can unmount nested mounts correctly: *)
1239     InitEmpty, Always, TestOutputList (
1240       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"];
1241        ["mkfs"; "ext2"; "/dev/sda1"];
1242        ["mkfs"; "ext2"; "/dev/sda2"];
1243        ["mkfs"; "ext2"; "/dev/sda3"];
1244        ["mount"; "/dev/sda1"; "/"];
1245        ["mkdir"; "/mp1"];
1246        ["mount"; "/dev/sda2"; "/mp1"];
1247        ["mkdir"; "/mp1/mp2"];
1248        ["mount"; "/dev/sda3"; "/mp1/mp2"];
1249        ["mkdir"; "/mp1/mp2/mp3"];
1250        ["umount_all"];
1251        ["mounts"]], [])],
1252    "unmount all filesystems",
1253    "\
1254 This unmounts all mounted filesystems.
1255
1256 Some internal mounts are not unmounted by this call.");
1257
1258   ("lvm_remove_all", (RErr, []), 48, [DangerWillRobinson],
1259    [],
1260    "remove all LVM LVs, VGs and PVs",
1261    "\
1262 This command removes all LVM logical volumes, volume groups
1263 and physical volumes.");
1264
1265   ("file", (RString "description", [String "path"]), 49, [],
1266    [InitBasicFS, Always, TestOutput (
1267       [["touch"; "/new"];
1268        ["file"; "/new"]], "empty");
1269     InitBasicFS, Always, TestOutput (
1270       [["write_file"; "/new"; "some content\n"; "0"];
1271        ["file"; "/new"]], "ASCII text");
1272     InitBasicFS, Always, TestLastFail (
1273       [["file"; "/nofile"]])],
1274    "determine file type",
1275    "\
1276 This call uses the standard L<file(1)> command to determine
1277 the type or contents of the file.  This also works on devices,
1278 for example to find out whether a partition contains a filesystem.
1279
1280 The exact command which runs is C<file -bsL path>.  Note in
1281 particular that the filename is not prepended to the output
1282 (the C<-b> option).");
1283
1284   ("command", (RString "output", [StringList "arguments"]), 50, [ProtocolLimitWarning],
1285    [InitBasicFS, Always, TestOutput (
1286       [["upload"; "test-command"; "/test-command"];
1287        ["chmod"; "493"; "/test-command"];
1288        ["command"; "/test-command 1"]], "Result1");
1289     InitBasicFS, Always, TestOutput (
1290       [["upload"; "test-command"; "/test-command"];
1291        ["chmod"; "493"; "/test-command"];
1292        ["command"; "/test-command 2"]], "Result2\n");
1293     InitBasicFS, Always, TestOutput (
1294       [["upload"; "test-command"; "/test-command"];
1295        ["chmod"; "493"; "/test-command"];
1296        ["command"; "/test-command 3"]], "\nResult3");
1297     InitBasicFS, Always, TestOutput (
1298       [["upload"; "test-command"; "/test-command"];
1299        ["chmod"; "493"; "/test-command"];
1300        ["command"; "/test-command 4"]], "\nResult4\n");
1301     InitBasicFS, Always, TestOutput (
1302       [["upload"; "test-command"; "/test-command"];
1303        ["chmod"; "493"; "/test-command"];
1304        ["command"; "/test-command 5"]], "\nResult5\n\n");
1305     InitBasicFS, Always, TestOutput (
1306       [["upload"; "test-command"; "/test-command"];
1307        ["chmod"; "493"; "/test-command"];
1308        ["command"; "/test-command 6"]], "\n\nResult6\n\n");
1309     InitBasicFS, Always, TestOutput (
1310       [["upload"; "test-command"; "/test-command"];
1311        ["chmod"; "493"; "/test-command"];
1312        ["command"; "/test-command 7"]], "");
1313     InitBasicFS, Always, TestOutput (
1314       [["upload"; "test-command"; "/test-command"];
1315        ["chmod"; "493"; "/test-command"];
1316        ["command"; "/test-command 8"]], "\n");
1317     InitBasicFS, Always, TestOutput (
1318       [["upload"; "test-command"; "/test-command"];
1319        ["chmod"; "493"; "/test-command"];
1320        ["command"; "/test-command 9"]], "\n\n");
1321     InitBasicFS, Always, TestOutput (
1322       [["upload"; "test-command"; "/test-command"];
1323        ["chmod"; "493"; "/test-command"];
1324        ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n");
1325     InitBasicFS, Always, TestOutput (
1326       [["upload"; "test-command"; "/test-command"];
1327        ["chmod"; "493"; "/test-command"];
1328        ["command"; "/test-command 11"]], "Result11-1\nResult11-2");
1329     InitBasicFS, Always, TestLastFail (
1330       [["upload"; "test-command"; "/test-command"];
1331        ["chmod"; "493"; "/test-command"];
1332        ["command"; "/test-command"]])],
1333    "run a command from the guest filesystem",
1334    "\
1335 This call runs a command from the guest filesystem.  The
1336 filesystem must be mounted, and must contain a compatible
1337 operating system (ie. something Linux, with the same
1338 or compatible processor architecture).
1339
1340 The single parameter is an argv-style list of arguments.
1341 The first element is the name of the program to run.
1342 Subsequent elements are parameters.  The list must be
1343 non-empty (ie. must contain a program name).
1344
1345 The return value is anything printed to I<stdout> by
1346 the command.
1347
1348 If the command returns a non-zero exit status, then
1349 this function returns an error message.  The error message
1350 string is the content of I<stderr> from the command.
1351
1352 The C<$PATH> environment variable will contain at least
1353 C</usr/bin> and C</bin>.  If you require a program from
1354 another location, you should provide the full path in the
1355 first parameter.
1356
1357 Shared libraries and data files required by the program
1358 must be available on filesystems which are mounted in the
1359 correct places.  It is the caller's responsibility to ensure
1360 all filesystems that are needed are mounted at the right
1361 locations.");
1362
1363   ("command_lines", (RStringList "lines", [StringList "arguments"]), 51, [ProtocolLimitWarning],
1364    [InitBasicFS, Always, TestOutputList (
1365       [["upload"; "test-command"; "/test-command"];
1366        ["chmod"; "493"; "/test-command"];
1367        ["command_lines"; "/test-command 1"]], ["Result1"]);
1368     InitBasicFS, Always, TestOutputList (
1369       [["upload"; "test-command"; "/test-command"];
1370        ["chmod"; "493"; "/test-command"];
1371        ["command_lines"; "/test-command 2"]], ["Result2"]);
1372     InitBasicFS, Always, TestOutputList (
1373       [["upload"; "test-command"; "/test-command"];
1374        ["chmod"; "493"; "/test-command"];
1375        ["command_lines"; "/test-command 3"]], ["";"Result3"]);
1376     InitBasicFS, Always, TestOutputList (
1377       [["upload"; "test-command"; "/test-command"];
1378        ["chmod"; "493"; "/test-command"];
1379        ["command_lines"; "/test-command 4"]], ["";"Result4"]);
1380     InitBasicFS, Always, TestOutputList (
1381       [["upload"; "test-command"; "/test-command"];
1382        ["chmod"; "493"; "/test-command"];
1383        ["command_lines"; "/test-command 5"]], ["";"Result5";""]);
1384     InitBasicFS, Always, TestOutputList (
1385       [["upload"; "test-command"; "/test-command"];
1386        ["chmod"; "493"; "/test-command"];
1387        ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]);
1388     InitBasicFS, Always, TestOutputList (
1389       [["upload"; "test-command"; "/test-command"];
1390        ["chmod"; "493"; "/test-command"];
1391        ["command_lines"; "/test-command 7"]], []);
1392     InitBasicFS, Always, TestOutputList (
1393       [["upload"; "test-command"; "/test-command"];
1394        ["chmod"; "493"; "/test-command"];
1395        ["command_lines"; "/test-command 8"]], [""]);
1396     InitBasicFS, Always, TestOutputList (
1397       [["upload"; "test-command"; "/test-command"];
1398        ["chmod"; "493"; "/test-command"];
1399        ["command_lines"; "/test-command 9"]], ["";""]);
1400     InitBasicFS, Always, TestOutputList (
1401       [["upload"; "test-command"; "/test-command"];
1402        ["chmod"; "493"; "/test-command"];
1403        ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]);
1404     InitBasicFS, Always, TestOutputList (
1405       [["upload"; "test-command"; "/test-command"];
1406        ["chmod"; "493"; "/test-command"];
1407        ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])],
1408    "run a command, returning lines",
1409    "\
1410 This is the same as C<guestfs_command>, but splits the
1411 result into a list of lines.");
1412
1413   ("stat", (RStat "statbuf", [String "path"]), 52, [],
1414    [InitBasicFS, Always, TestOutputStruct (
1415       [["touch"; "/new"];
1416        ["stat"; "/new"]], [CompareWithInt ("size", 0)])],
1417    "get file information",
1418    "\
1419 Returns file information for the given C<path>.
1420
1421 This is the same as the C<stat(2)> system call.");
1422
1423   ("lstat", (RStat "statbuf", [String "path"]), 53, [],
1424    [InitBasicFS, Always, TestOutputStruct (
1425       [["touch"; "/new"];
1426        ["lstat"; "/new"]], [CompareWithInt ("size", 0)])],
1427    "get file information for a symbolic link",
1428    "\
1429 Returns file information for the given C<path>.
1430
1431 This is the same as C<guestfs_stat> except that if C<path>
1432 is a symbolic link, then the link is stat-ed, not the file it
1433 refers to.
1434
1435 This is the same as the C<lstat(2)> system call.");
1436
1437   ("statvfs", (RStatVFS "statbuf", [String "path"]), 54, [],
1438    [InitBasicFS, Always, TestOutputStruct (
1439       [["statvfs"; "/"]], [CompareWithInt ("bfree", 487702);
1440                            CompareWithInt ("blocks", 490020);
1441                            CompareWithInt ("bsize", 1024)])],
1442    "get file system statistics",
1443    "\
1444 Returns file system statistics for any mounted file system.
1445 C<path> should be a file or directory in the mounted file system
1446 (typically it is the mount point itself, but it doesn't need to be).
1447
1448 This is the same as the C<statvfs(2)> system call.");
1449
1450   ("tune2fs_l", (RHashtable "superblock", [String "device"]), 55, [],
1451    [], (* XXX test *)
1452    "get ext2/ext3/ext4 superblock details",
1453    "\
1454 This returns the contents of the ext2, ext3 or ext4 filesystem
1455 superblock on C<device>.
1456
1457 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
1458 manpage for more details.  The list of fields returned isn't
1459 clearly defined, and depends on both the version of C<tune2fs>
1460 that libguestfs was built against, and the filesystem itself.");
1461
1462   ("blockdev_setro", (RErr, [String "device"]), 56, [],
1463    [InitEmpty, Always, TestOutputTrue (
1464       [["blockdev_setro"; "/dev/sda"];
1465        ["blockdev_getro"; "/dev/sda"]])],
1466    "set block device to read-only",
1467    "\
1468 Sets the block device named C<device> to read-only.
1469
1470 This uses the L<blockdev(8)> command.");
1471
1472   ("blockdev_setrw", (RErr, [String "device"]), 57, [],
1473    [InitEmpty, Always, TestOutputFalse (
1474       [["blockdev_setrw"; "/dev/sda"];
1475        ["blockdev_getro"; "/dev/sda"]])],
1476    "set block device to read-write",
1477    "\
1478 Sets the block device named C<device> to read-write.
1479
1480 This uses the L<blockdev(8)> command.");
1481
1482   ("blockdev_getro", (RBool "ro", [String "device"]), 58, [],
1483    [InitEmpty, Always, TestOutputTrue (
1484       [["blockdev_setro"; "/dev/sda"];
1485        ["blockdev_getro"; "/dev/sda"]])],
1486    "is block device set to read-only",
1487    "\
1488 Returns a boolean indicating if the block device is read-only
1489 (true if read-only, false if not).
1490
1491 This uses the L<blockdev(8)> command.");
1492
1493   ("blockdev_getss", (RInt "sectorsize", [String "device"]), 59, [],
1494    [InitEmpty, Always, TestOutputInt (
1495       [["blockdev_getss"; "/dev/sda"]], 512)],
1496    "get sectorsize of block device",
1497    "\
1498 This returns the size of sectors on a block device.
1499 Usually 512, but can be larger for modern devices.
1500
1501 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
1502 for that).
1503
1504 This uses the L<blockdev(8)> command.");
1505
1506   ("blockdev_getbsz", (RInt "blocksize", [String "device"]), 60, [],
1507    [InitEmpty, Always, TestOutputInt (
1508       [["blockdev_getbsz"; "/dev/sda"]], 4096)],
1509    "get blocksize of block device",
1510    "\
1511 This returns the block size of a device.
1512
1513 (Note this is different from both I<size in blocks> and
1514 I<filesystem block size>).
1515
1516 This uses the L<blockdev(8)> command.");
1517
1518   ("blockdev_setbsz", (RErr, [String "device"; Int "blocksize"]), 61, [],
1519    [], (* XXX test *)
1520    "set blocksize of block device",
1521    "\
1522 This sets the block size of a device.
1523
1524 (Note this is different from both I<size in blocks> and
1525 I<filesystem block size>).
1526
1527 This uses the L<blockdev(8)> command.");
1528
1529   ("blockdev_getsz", (RInt64 "sizeinsectors", [String "device"]), 62, [],
1530    [InitEmpty, Always, TestOutputInt (
1531       [["blockdev_getsz"; "/dev/sda"]], 1024000)],
1532    "get total size of device in 512-byte sectors",
1533    "\
1534 This returns the size of the device in units of 512-byte sectors
1535 (even if the sectorsize isn't 512 bytes ... weird).
1536
1537 See also C<guestfs_blockdev_getss> for the real sector size of
1538 the device, and C<guestfs_blockdev_getsize64> for the more
1539 useful I<size in bytes>.
1540
1541 This uses the L<blockdev(8)> command.");
1542
1543   ("blockdev_getsize64", (RInt64 "sizeinbytes", [String "device"]), 63, [],
1544    [InitEmpty, Always, TestOutputInt (
1545       [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
1546    "get total size of device in bytes",
1547    "\
1548 This returns the size of the device in bytes.
1549
1550 See also C<guestfs_blockdev_getsz>.
1551
1552 This uses the L<blockdev(8)> command.");
1553
1554   ("blockdev_flushbufs", (RErr, [String "device"]), 64, [],
1555    [InitEmpty, Always, TestRun
1556       [["blockdev_flushbufs"; "/dev/sda"]]],
1557    "flush device buffers",
1558    "\
1559 This tells the kernel to flush internal buffers associated
1560 with C<device>.
1561
1562 This uses the L<blockdev(8)> command.");
1563
1564   ("blockdev_rereadpt", (RErr, [String "device"]), 65, [],
1565    [InitEmpty, Always, TestRun
1566       [["blockdev_rereadpt"; "/dev/sda"]]],
1567    "reread partition table",
1568    "\
1569 Reread the partition table on C<device>.
1570
1571 This uses the L<blockdev(8)> command.");
1572
1573   ("upload", (RErr, [FileIn "filename"; String "remotefilename"]), 66, [],
1574    [InitBasicFS, Always, TestOutput (
1575       (* Pick a file from cwd which isn't likely to change. *)
1576     [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1577      ["checksum"; "md5"; "/COPYING.LIB"]], "e3eda01d9815f8d24aae2dbd89b68b06")],
1578    "upload a file from the local machine",
1579    "\
1580 Upload local file C<filename> to C<remotefilename> on the
1581 filesystem.
1582
1583 C<filename> can also be a named pipe.
1584
1585 See also C<guestfs_download>.");
1586
1587   ("download", (RErr, [String "remotefilename"; FileOut "filename"]), 67, [],
1588    [InitBasicFS, Always, TestOutput (
1589       (* Pick a file from cwd which isn't likely to change. *)
1590     [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1591      ["download"; "/COPYING.LIB"; "testdownload.tmp"];
1592      ["upload"; "testdownload.tmp"; "/upload"];
1593      ["checksum"; "md5"; "/upload"]], "e3eda01d9815f8d24aae2dbd89b68b06")],
1594    "download a file to the local machine",
1595    "\
1596 Download file C<remotefilename> and save it as C<filename>
1597 on the local machine.
1598
1599 C<filename> can also be a named pipe.
1600
1601 See also C<guestfs_upload>, C<guestfs_cat>.");
1602
1603   ("checksum", (RString "checksum", [String "csumtype"; String "path"]), 68, [],
1604    [InitBasicFS, Always, TestOutput (
1605       [["write_file"; "/new"; "test\n"; "0"];
1606        ["checksum"; "crc"; "/new"]], "935282863");
1607     InitBasicFS, Always, TestLastFail (
1608       [["checksum"; "crc"; "/new"]]);
1609     InitBasicFS, Always, TestOutput (
1610       [["write_file"; "/new"; "test\n"; "0"];
1611        ["checksum"; "md5"; "/new"]], "d8e8fca2dc0f896fd7cb4cb0031ba249");
1612     InitBasicFS, Always, TestOutput (
1613       [["write_file"; "/new"; "test\n"; "0"];
1614        ["checksum"; "sha1"; "/new"]], "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83");
1615     InitBasicFS, Always, TestOutput (
1616       [["write_file"; "/new"; "test\n"; "0"];
1617        ["checksum"; "sha224"; "/new"]], "52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec");
1618     InitBasicFS, Always, TestOutput (
1619       [["write_file"; "/new"; "test\n"; "0"];
1620        ["checksum"; "sha256"; "/new"]], "f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2");
1621     InitBasicFS, Always, TestOutput (
1622       [["write_file"; "/new"; "test\n"; "0"];
1623        ["checksum"; "sha384"; "/new"]], "109bb6b5b6d5547c1ce03c7a8bd7d8f80c1cb0957f50c4f7fda04692079917e4f9cad52b878f3d8234e1a170b154b72d");
1624     InitBasicFS, Always, TestOutput (
1625       [["write_file"; "/new"; "test\n"; "0"];
1626        ["checksum"; "sha512"; "/new"]], "0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123");
1627     InitBasicFS, Always, TestOutput (
1628       [["mount"; "/dev/sdd"; "/"];
1629        ["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c")],
1630    "compute MD5, SHAx or CRC checksum of file",
1631    "\
1632 This call computes the MD5, SHAx or CRC checksum of the
1633 file named C<path>.
1634
1635 The type of checksum to compute is given by the C<csumtype>
1636 parameter which must have one of the following values:
1637
1638 =over 4
1639
1640 =item C<crc>
1641
1642 Compute the cyclic redundancy check (CRC) specified by POSIX
1643 for the C<cksum> command.
1644
1645 =item C<md5>
1646
1647 Compute the MD5 hash (using the C<md5sum> program).
1648
1649 =item C<sha1>
1650
1651 Compute the SHA1 hash (using the C<sha1sum> program).
1652
1653 =item C<sha224>
1654
1655 Compute the SHA224 hash (using the C<sha224sum> program).
1656
1657 =item C<sha256>
1658
1659 Compute the SHA256 hash (using the C<sha256sum> program).
1660
1661 =item C<sha384>
1662
1663 Compute the SHA384 hash (using the C<sha384sum> program).
1664
1665 =item C<sha512>
1666
1667 Compute the SHA512 hash (using the C<sha512sum> program).
1668
1669 =back
1670
1671 The checksum is returned as a printable string.");
1672
1673   ("tar_in", (RErr, [FileIn "tarfile"; String "directory"]), 69, [],
1674    [InitBasicFS, Always, TestOutput (
1675       [["tar_in"; "../images/helloworld.tar"; "/"];
1676        ["cat"; "/hello"]], "hello\n")],
1677    "unpack tarfile to directory",
1678    "\
1679 This command uploads and unpacks local file C<tarfile> (an
1680 I<uncompressed> tar file) into C<directory>.
1681
1682 To upload a compressed tarball, use C<guestfs_tgz_in>.");
1683
1684   ("tar_out", (RErr, [String "directory"; FileOut "tarfile"]), 70, [],
1685    [],
1686    "pack directory into tarfile",
1687    "\
1688 This command packs the contents of C<directory> and downloads
1689 it to local file C<tarfile>.
1690
1691 To download a compressed tarball, use C<guestfs_tgz_out>.");
1692
1693   ("tgz_in", (RErr, [FileIn "tarball"; String "directory"]), 71, [],
1694    [InitBasicFS, Always, TestOutput (
1695       [["tgz_in"; "../images/helloworld.tar.gz"; "/"];
1696        ["cat"; "/hello"]], "hello\n")],
1697    "unpack compressed tarball to directory",
1698    "\
1699 This command uploads and unpacks local file C<tarball> (a
1700 I<gzip compressed> tar file) into C<directory>.
1701
1702 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
1703
1704   ("tgz_out", (RErr, [String "directory"; FileOut "tarball"]), 72, [],
1705    [],
1706    "pack directory into compressed tarball",
1707    "\
1708 This command packs the contents of C<directory> and downloads
1709 it to local file C<tarball>.
1710
1711 To download an uncompressed tarball, use C<guestfs_tar_out>.");
1712
1713   ("mount_ro", (RErr, [String "device"; String "mountpoint"]), 73, [],
1714    [InitBasicFS, Always, TestLastFail (
1715       [["umount"; "/"];
1716        ["mount_ro"; "/dev/sda1"; "/"];
1717        ["touch"; "/new"]]);
1718     InitBasicFS, Always, TestOutput (
1719       [["write_file"; "/new"; "data"; "0"];
1720        ["umount"; "/"];
1721        ["mount_ro"; "/dev/sda1"; "/"];
1722        ["cat"; "/new"]], "data")],
1723    "mount a guest disk, read-only",
1724    "\
1725 This is the same as the C<guestfs_mount> command, but it
1726 mounts the filesystem with the read-only (I<-o ro>) flag.");
1727
1728   ("mount_options", (RErr, [String "options"; String "device"; String "mountpoint"]), 74, [],
1729    [],
1730    "mount a guest disk with mount options",
1731    "\
1732 This is the same as the C<guestfs_mount> command, but it
1733 allows you to set the mount options as for the
1734 L<mount(8)> I<-o> flag.");
1735
1736   ("mount_vfs", (RErr, [String "options"; String "vfstype"; String "device"; String "mountpoint"]), 75, [],
1737    [],
1738    "mount a guest disk with mount options and vfstype",
1739    "\
1740 This is the same as the C<guestfs_mount> command, but it
1741 allows you to set both the mount options and the vfstype
1742 as for the L<mount(8)> I<-o> and I<-t> flags.");
1743
1744   ("debug", (RString "result", [String "subcmd"; StringList "extraargs"]), 76, [],
1745    [],
1746    "debugging and internals",
1747    "\
1748 The C<guestfs_debug> command exposes some internals of
1749 C<guestfsd> (the guestfs daemon) that runs inside the
1750 qemu subprocess.
1751
1752 There is no comprehensive help for this command.  You have
1753 to look at the file C<daemon/debug.c> in the libguestfs source
1754 to find out what you can do.");
1755
1756   ("lvremove", (RErr, [String "device"]), 77, [],
1757    [InitEmpty, Always, TestOutputList (
1758       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1759        ["pvcreate"; "/dev/sda1"];
1760        ["vgcreate"; "VG"; "/dev/sda1"];
1761        ["lvcreate"; "LV1"; "VG"; "50"];
1762        ["lvcreate"; "LV2"; "VG"; "50"];
1763        ["lvremove"; "/dev/VG/LV1"];
1764        ["lvs"]], ["/dev/VG/LV2"]);
1765     InitEmpty, Always, TestOutputList (
1766       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1767        ["pvcreate"; "/dev/sda1"];
1768        ["vgcreate"; "VG"; "/dev/sda1"];
1769        ["lvcreate"; "LV1"; "VG"; "50"];
1770        ["lvcreate"; "LV2"; "VG"; "50"];
1771        ["lvremove"; "/dev/VG"];
1772        ["lvs"]], []);
1773     InitEmpty, Always, TestOutputList (
1774       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1775        ["pvcreate"; "/dev/sda1"];
1776        ["vgcreate"; "VG"; "/dev/sda1"];
1777        ["lvcreate"; "LV1"; "VG"; "50"];
1778        ["lvcreate"; "LV2"; "VG"; "50"];
1779        ["lvremove"; "/dev/VG"];
1780        ["vgs"]], ["VG"])],
1781    "remove an LVM logical volume",
1782    "\
1783 Remove an LVM logical volume C<device>, where C<device> is
1784 the path to the LV, such as C</dev/VG/LV>.
1785
1786 You can also remove all LVs in a volume group by specifying
1787 the VG name, C</dev/VG>.");
1788
1789   ("vgremove", (RErr, [String "vgname"]), 78, [],
1790    [InitEmpty, Always, TestOutputList (
1791       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1792        ["pvcreate"; "/dev/sda1"];
1793        ["vgcreate"; "VG"; "/dev/sda1"];
1794        ["lvcreate"; "LV1"; "VG"; "50"];
1795        ["lvcreate"; "LV2"; "VG"; "50"];
1796        ["vgremove"; "VG"];
1797        ["lvs"]], []);
1798     InitEmpty, Always, TestOutputList (
1799       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1800        ["pvcreate"; "/dev/sda1"];
1801        ["vgcreate"; "VG"; "/dev/sda1"];
1802        ["lvcreate"; "LV1"; "VG"; "50"];
1803        ["lvcreate"; "LV2"; "VG"; "50"];
1804        ["vgremove"; "VG"];
1805        ["vgs"]], [])],
1806    "remove an LVM volume group",
1807    "\
1808 Remove an LVM volume group C<vgname>, (for example C<VG>).
1809
1810 This also forcibly removes all logical volumes in the volume
1811 group (if any).");
1812
1813   ("pvremove", (RErr, [String "device"]), 79, [],
1814    [InitEmpty, Always, TestOutputList (
1815       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1816        ["pvcreate"; "/dev/sda1"];
1817        ["vgcreate"; "VG"; "/dev/sda1"];
1818        ["lvcreate"; "LV1"; "VG"; "50"];
1819        ["lvcreate"; "LV2"; "VG"; "50"];
1820        ["vgremove"; "VG"];
1821        ["pvremove"; "/dev/sda1"];
1822        ["lvs"]], []);
1823     InitEmpty, Always, TestOutputList (
1824       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1825        ["pvcreate"; "/dev/sda1"];
1826        ["vgcreate"; "VG"; "/dev/sda1"];
1827        ["lvcreate"; "LV1"; "VG"; "50"];
1828        ["lvcreate"; "LV2"; "VG"; "50"];
1829        ["vgremove"; "VG"];
1830        ["pvremove"; "/dev/sda1"];
1831        ["vgs"]], []);
1832     InitEmpty, Always, TestOutputList (
1833       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
1834        ["pvcreate"; "/dev/sda1"];
1835        ["vgcreate"; "VG"; "/dev/sda1"];
1836        ["lvcreate"; "LV1"; "VG"; "50"];
1837        ["lvcreate"; "LV2"; "VG"; "50"];
1838        ["vgremove"; "VG"];
1839        ["pvremove"; "/dev/sda1"];
1840        ["pvs"]], [])],
1841    "remove an LVM physical volume",
1842    "\
1843 This wipes a physical volume C<device> so that LVM will no longer
1844 recognise it.
1845
1846 The implementation uses the C<pvremove> command which refuses to
1847 wipe physical volumes that contain any volume groups, so you have
1848 to remove those first.");
1849
1850   ("set_e2label", (RErr, [String "device"; String "label"]), 80, [],
1851    [InitBasicFS, Always, TestOutput (
1852       [["set_e2label"; "/dev/sda1"; "testlabel"];
1853        ["get_e2label"; "/dev/sda1"]], "testlabel")],
1854    "set the ext2/3/4 filesystem label",
1855    "\
1856 This sets the ext2/3/4 filesystem label of the filesystem on
1857 C<device> to C<label>.  Filesystem labels are limited to
1858 16 characters.
1859
1860 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
1861 to return the existing label on a filesystem.");
1862
1863   ("get_e2label", (RString "label", [String "device"]), 81, [],
1864    [],
1865    "get the ext2/3/4 filesystem label",
1866    "\
1867 This returns the ext2/3/4 filesystem label of the filesystem on
1868 C<device>.");
1869
1870   ("set_e2uuid", (RErr, [String "device"; String "uuid"]), 82, [],
1871    [InitBasicFS, Always, TestOutput (
1872       [["set_e2uuid"; "/dev/sda1"; "a3a61220-882b-4f61-89f4-cf24dcc7297d"];
1873        ["get_e2uuid"; "/dev/sda1"]], "a3a61220-882b-4f61-89f4-cf24dcc7297d");
1874     InitBasicFS, Always, TestOutput (
1875       [["set_e2uuid"; "/dev/sda1"; "clear"];
1876        ["get_e2uuid"; "/dev/sda1"]], "");
1877     (* We can't predict what UUIDs will be, so just check the commands run. *)
1878     InitBasicFS, Always, TestRun (
1879       [["set_e2uuid"; "/dev/sda1"; "random"]]);
1880     InitBasicFS, Always, TestRun (
1881       [["set_e2uuid"; "/dev/sda1"; "time"]])],
1882    "set the ext2/3/4 filesystem UUID",
1883    "\
1884 This sets the ext2/3/4 filesystem UUID of the filesystem on
1885 C<device> to C<uuid>.  The format of the UUID and alternatives
1886 such as C<clear>, C<random> and C<time> are described in the
1887 L<tune2fs(8)> manpage.
1888
1889 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
1890 to return the existing UUID of a filesystem.");
1891
1892   ("get_e2uuid", (RString "uuid", [String "device"]), 83, [],
1893    [],
1894    "get the ext2/3/4 filesystem UUID",
1895    "\
1896 This returns the ext2/3/4 filesystem UUID of the filesystem on
1897 C<device>.");
1898
1899   ("fsck", (RInt "status", [String "fstype"; String "device"]), 84, [],
1900    [InitBasicFS, Always, TestOutputInt (
1901       [["umount"; "/dev/sda1"];
1902        ["fsck"; "ext2"; "/dev/sda1"]], 0);
1903     InitBasicFS, Always, TestOutputInt (
1904       [["umount"; "/dev/sda1"];
1905        ["zero"; "/dev/sda1"];
1906        ["fsck"; "ext2"; "/dev/sda1"]], 8)],
1907    "run the filesystem checker",
1908    "\
1909 This runs the filesystem checker (fsck) on C<device> which
1910 should have filesystem type C<fstype>.
1911
1912 The returned integer is the status.  See L<fsck(8)> for the
1913 list of status codes from C<fsck>.
1914
1915 Notes:
1916
1917 =over 4
1918
1919 =item *
1920
1921 Multiple status codes can be summed together.
1922
1923 =item *
1924
1925 A non-zero return code can mean \"success\", for example if
1926 errors have been corrected on the filesystem.
1927
1928 =item *
1929
1930 Checking or repairing NTFS volumes is not supported
1931 (by linux-ntfs).
1932
1933 =back
1934
1935 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
1936
1937   ("zero", (RErr, [String "device"]), 85, [],
1938    [InitBasicFS, Always, TestOutput (
1939       [["umount"; "/dev/sda1"];
1940        ["zero"; "/dev/sda1"];
1941        ["file"; "/dev/sda1"]], "data")],
1942    "write zeroes to the device",
1943    "\
1944 This command writes zeroes over the first few blocks of C<device>.
1945
1946 How many blocks are zeroed isn't specified (but it's I<not> enough
1947 to securely wipe the device).  It should be sufficient to remove
1948 any partition tables, filesystem superblocks and so on.");
1949
1950   ("grub_install", (RErr, [String "root"; String "device"]), 86, [],
1951    [InitBasicFS, Always, TestOutputTrue (
1952       [["grub_install"; "/"; "/dev/sda1"];
1953        ["is_dir"; "/boot"]])],
1954    "install GRUB",
1955    "\
1956 This command installs GRUB (the Grand Unified Bootloader) on
1957 C<device>, with the root directory being C<root>.");
1958
1959   ("cp", (RErr, [String "src"; String "dest"]), 87, [],
1960    [InitBasicFS, Always, TestOutput (
1961       [["write_file"; "/old"; "file content"; "0"];
1962        ["cp"; "/old"; "/new"];
1963        ["cat"; "/new"]], "file content");
1964     InitBasicFS, Always, TestOutputTrue (
1965       [["write_file"; "/old"; "file content"; "0"];
1966        ["cp"; "/old"; "/new"];
1967        ["is_file"; "/old"]]);
1968     InitBasicFS, Always, TestOutput (
1969       [["write_file"; "/old"; "file content"; "0"];
1970        ["mkdir"; "/dir"];
1971        ["cp"; "/old"; "/dir/new"];
1972        ["cat"; "/dir/new"]], "file content")],
1973    "copy a file",
1974    "\
1975 This copies a file from C<src> to C<dest> where C<dest> is
1976 either a destination filename or destination directory.");
1977
1978   ("cp_a", (RErr, [String "src"; String "dest"]), 88, [],
1979    [InitBasicFS, Always, TestOutput (
1980       [["mkdir"; "/olddir"];
1981        ["mkdir"; "/newdir"];
1982        ["write_file"; "/olddir/file"; "file content"; "0"];
1983        ["cp_a"; "/olddir"; "/newdir"];
1984        ["cat"; "/newdir/olddir/file"]], "file content")],
1985    "copy a file or directory recursively",
1986    "\
1987 This copies a file or directory from C<src> to C<dest>
1988 recursively using the C<cp -a> command.");
1989
1990   ("mv", (RErr, [String "src"; String "dest"]), 89, [],
1991    [InitBasicFS, Always, TestOutput (
1992       [["write_file"; "/old"; "file content"; "0"];
1993        ["mv"; "/old"; "/new"];
1994        ["cat"; "/new"]], "file content");
1995     InitBasicFS, Always, TestOutputFalse (
1996       [["write_file"; "/old"; "file content"; "0"];
1997        ["mv"; "/old"; "/new"];
1998        ["is_file"; "/old"]])],
1999    "move a file",
2000    "\
2001 This moves a file from C<src> to C<dest> where C<dest> is
2002 either a destination filename or destination directory.");
2003
2004   ("drop_caches", (RErr, [Int "whattodrop"]), 90, [],
2005    [InitEmpty, Always, TestRun (
2006       [["drop_caches"; "3"]])],
2007    "drop kernel page cache, dentries and inodes",
2008    "\
2009 This instructs the guest kernel to drop its page cache,
2010 and/or dentries and inode caches.  The parameter C<whattodrop>
2011 tells the kernel what precisely to drop, see
2012 L<http://linux-mm.org/Drop_Caches>
2013
2014 Setting C<whattodrop> to 3 should drop everything.
2015
2016 This automatically calls L<sync(2)> before the operation,
2017 so that the maximum guest memory is freed.");
2018
2019   ("dmesg", (RString "kmsgs", []), 91, [],
2020    [InitEmpty, Always, TestRun (
2021       [["dmesg"]])],
2022    "return kernel messages",
2023    "\
2024 This returns the kernel messages (C<dmesg> output) from
2025 the guest kernel.  This is sometimes useful for extended
2026 debugging of problems.
2027
2028 Another way to get the same information is to enable
2029 verbose messages with C<guestfs_set_verbose> or by setting
2030 the environment variable C<LIBGUESTFS_DEBUG=1> before
2031 running the program.");
2032
2033   ("ping_daemon", (RErr, []), 92, [],
2034    [InitEmpty, Always, TestRun (
2035       [["ping_daemon"]])],
2036    "ping the guest daemon",
2037    "\
2038 This is a test probe into the guestfs daemon running inside
2039 the qemu subprocess.  Calling this function checks that the
2040 daemon responds to the ping message, without affecting the daemon
2041 or attached block device(s) in any other way.");
2042
2043   ("equal", (RBool "equality", [String "file1"; String "file2"]), 93, [],
2044    [InitBasicFS, Always, TestOutputTrue (
2045       [["write_file"; "/file1"; "contents of a file"; "0"];
2046        ["cp"; "/file1"; "/file2"];
2047        ["equal"; "/file1"; "/file2"]]);
2048     InitBasicFS, Always, TestOutputFalse (
2049       [["write_file"; "/file1"; "contents of a file"; "0"];
2050        ["write_file"; "/file2"; "contents of another file"; "0"];
2051        ["equal"; "/file1"; "/file2"]]);
2052     InitBasicFS, Always, TestLastFail (
2053       [["equal"; "/file1"; "/file2"]])],
2054    "test if two files have equal contents",
2055    "\
2056 This compares the two files C<file1> and C<file2> and returns
2057 true if their content is exactly equal, or false otherwise.
2058
2059 The external L<cmp(1)> program is used for the comparison.");
2060
2061   ("strings", (RStringList "stringsout", [String "path"]), 94, [ProtocolLimitWarning],
2062    [InitBasicFS, Always, TestOutputList (
2063       [["write_file"; "/new"; "hello\nworld\n"; "0"];
2064        ["strings"; "/new"]], ["hello"; "world"]);
2065     InitBasicFS, Always, TestOutputList (
2066       [["touch"; "/new"];
2067        ["strings"; "/new"]], [])],
2068    "print the printable strings in a file",
2069    "\
2070 This runs the L<strings(1)> command on a file and returns
2071 the list of printable strings found.");
2072
2073   ("strings_e", (RStringList "stringsout", [String "encoding"; String "path"]), 95, [ProtocolLimitWarning],
2074    [InitBasicFS, Always, TestOutputList (
2075       [["write_file"; "/new"; "hello\nworld\n"; "0"];
2076        ["strings_e"; "b"; "/new"]], []);
2077     InitBasicFS, Disabled, TestOutputList (
2078       [["write_file"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"; "24"];
2079        ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2080    "print the printable strings in a file",
2081    "\
2082 This is like the C<guestfs_strings> command, but allows you to
2083 specify the encoding.
2084
2085 See the L<strings(1)> manpage for the full list of encodings.
2086
2087 Commonly useful encodings are C<l> (lower case L) which will
2088 show strings inside Windows/x86 files.
2089
2090 The returned strings are transcoded to UTF-8.");
2091
2092   ("hexdump", (RString "dump", [String "path"]), 96, [ProtocolLimitWarning],
2093    [InitBasicFS, Always, TestOutput (
2094       [["write_file"; "/new"; "hello\nworld\n"; "12"];
2095        ["hexdump"; "/new"]], "00000000  68 65 6c 6c 6f 0a 77 6f  72 6c 64 0a              |hello.world.|\n0000000c\n")],
2096    "dump a file in hexadecimal",
2097    "\
2098 This runs C<hexdump -C> on the given C<path>.  The result is
2099 the human-readable, canonical hex dump of the file.");
2100
2101   ("zerofree", (RErr, [String "device"]), 97, [],
2102    [InitNone, Always, TestOutput (
2103       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2104        ["mkfs"; "ext3"; "/dev/sda1"];
2105        ["mount"; "/dev/sda1"; "/"];
2106        ["write_file"; "/new"; "test file"; "0"];
2107        ["umount"; "/dev/sda1"];
2108        ["zerofree"; "/dev/sda1"];
2109        ["mount"; "/dev/sda1"; "/"];
2110        ["cat"; "/new"]], "test file")],
2111    "zero unused inodes and disk blocks on ext2/3 filesystem",
2112    "\
2113 This runs the I<zerofree> program on C<device>.  This program
2114 claims to zero unused inodes and disk blocks on an ext2/3
2115 filesystem, thus making it possible to compress the filesystem
2116 more effectively.
2117
2118 You should B<not> run this program if the filesystem is
2119 mounted.
2120
2121 It is possible that using this program can damage the filesystem
2122 or data on the filesystem.");
2123
2124   ("pvresize", (RErr, [String "device"]), 98, [],
2125    [],
2126    "resize an LVM physical volume",
2127    "\
2128 This resizes (expands or shrinks) an existing LVM physical
2129 volume to match the new size of the underlying device.");
2130
2131   ("sfdisk_N", (RErr, [String "device"; Int "n";
2132                        Int "cyls"; Int "heads"; Int "sectors";
2133                        String "line"]), 99, [DangerWillRobinson],
2134    [],
2135    "modify a single partition on a block device",
2136    "\
2137 This runs L<sfdisk(8)> option to modify just the single
2138 partition C<n> (note: C<n> counts from 1).
2139
2140 For other parameters, see C<guestfs_sfdisk>.  You should usually
2141 pass C<0> for the cyls/heads/sectors parameters.");
2142
2143   ("sfdisk_l", (RString "partitions", [String "device"]), 100, [],
2144    [],
2145    "display the partition table",
2146    "\
2147 This displays the partition table on C<device>, in the
2148 human-readable output of the L<sfdisk(8)> command.  It is
2149 not intended to be parsed.");
2150
2151   ("sfdisk_kernel_geometry", (RString "partitions", [String "device"]), 101, [],
2152    [],
2153    "display the kernel geometry",
2154    "\
2155 This displays the kernel's idea of the geometry of C<device>.
2156
2157 The result is in human-readable format, and not designed to
2158 be parsed.");
2159
2160   ("sfdisk_disk_geometry", (RString "partitions", [String "device"]), 102, [],
2161    [],
2162    "display the disk geometry from the partition table",
2163    "\
2164 This displays the disk geometry of C<device> read from the
2165 partition table.  Especially in the case where the underlying
2166 block device has been resized, this can be different from the
2167 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2168
2169 The result is in human-readable format, and not designed to
2170 be parsed.");
2171
2172   ("vg_activate_all", (RErr, [Bool "activate"]), 103, [],
2173    [],
2174    "activate or deactivate all volume groups",
2175    "\
2176 This command activates or (if C<activate> is false) deactivates
2177 all logical volumes in all volume groups.
2178 If activated, then they are made known to the
2179 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2180 then those devices disappear.
2181
2182 This command is the same as running C<vgchange -a y|n>");
2183
2184   ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"]), 104, [],
2185    [],
2186    "activate or deactivate some volume groups",
2187    "\
2188 This command activates or (if C<activate> is false) deactivates
2189 all logical volumes in the listed volume groups C<volgroups>.
2190 If activated, then they are made known to the
2191 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2192 then those devices disappear.
2193
2194 This command is the same as running C<vgchange -a y|n volgroups...>
2195
2196 Note that if C<volgroups> is an empty list then B<all> volume groups
2197 are activated or deactivated.");
2198
2199   ("lvresize", (RErr, [String "device"; Int "mbytes"]), 105, [],
2200    [InitNone, Always, TestOutput (
2201     [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2202      ["pvcreate"; "/dev/sda1"];
2203      ["vgcreate"; "VG"; "/dev/sda1"];
2204      ["lvcreate"; "LV"; "VG"; "10"];
2205      ["mkfs"; "ext2"; "/dev/VG/LV"];
2206      ["mount"; "/dev/VG/LV"; "/"];
2207      ["write_file"; "/new"; "test content"; "0"];
2208      ["umount"; "/"];
2209      ["lvresize"; "/dev/VG/LV"; "20"];
2210      ["e2fsck_f"; "/dev/VG/LV"];
2211      ["resize2fs"; "/dev/VG/LV"];
2212      ["mount"; "/dev/VG/LV"; "/"];
2213      ["cat"; "/new"]], "test content")],
2214    "resize an LVM logical volume",
2215    "\
2216 This resizes (expands or shrinks) an existing LVM logical
2217 volume to C<mbytes>.  When reducing, data in the reduced part
2218 is lost.");
2219
2220   ("resize2fs", (RErr, [String "device"]), 106, [],
2221    [], (* lvresize tests this *)
2222    "resize an ext2/ext3 filesystem",
2223    "\
2224 This resizes an ext2 or ext3 filesystem to match the size of
2225 the underlying device.
2226
2227 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2228 on the C<device> before calling this command.  For unknown reasons
2229 C<resize2fs> sometimes gives an error about this and sometimes not.
2230 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2231 calling this function.");
2232
2233   ("find", (RStringList "names", [String "directory"]), 107, [],
2234    [InitBasicFS, Always, TestOutputList (
2235       [["find"; "/"]], ["lost+found"]);
2236     InitBasicFS, Always, TestOutputList (
2237       [["touch"; "/a"];
2238        ["mkdir"; "/b"];
2239        ["touch"; "/b/c"];
2240        ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2241     InitBasicFS, Always, TestOutputList (
2242       [["mkdir_p"; "/a/b/c"];
2243        ["touch"; "/a/b/c/d"];
2244        ["find"; "/a/b/"]], ["c"; "c/d"])],
2245    "find all files and directories",
2246    "\
2247 This command lists out all files and directories, recursively,
2248 starting at C<directory>.  It is essentially equivalent to
2249 running the shell command C<find directory -print> but some
2250 post-processing happens on the output, described below.
2251
2252 This returns a list of strings I<without any prefix>.  Thus
2253 if the directory structure was:
2254
2255  /tmp/a
2256  /tmp/b
2257  /tmp/c/d
2258
2259 then the returned list from C<guestfs_find> C</tmp> would be
2260 4 elements:
2261
2262  a
2263  b
2264  c
2265  c/d
2266
2267 If C<directory> is not a directory, then this command returns
2268 an error.
2269
2270 The returned list is sorted.");
2271
2272   ("e2fsck_f", (RErr, [String "device"]), 108, [],
2273    [], (* lvresize tests this *)
2274    "check an ext2/ext3 filesystem",
2275    "\
2276 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2277 filesystem checker on C<device>, noninteractively (C<-p>),
2278 even if the filesystem appears to be clean (C<-f>).
2279
2280 This command is only needed because of C<guestfs_resize2fs>
2281 (q.v.).  Normally you should use C<guestfs_fsck>.");
2282
2283 ]
2284
2285 let all_functions = non_daemon_functions @ daemon_functions
2286
2287 (* In some places we want the functions to be displayed sorted
2288  * alphabetically, so this is useful:
2289  *)
2290 let all_functions_sorted =
2291   List.sort (fun (n1,_,_,_,_,_,_) (n2,_,_,_,_,_,_) ->
2292                compare n1 n2) all_functions
2293
2294 (* Column names and types from LVM PVs/VGs/LVs. *)
2295 let pv_cols = [
2296   "pv_name", `String;
2297   "pv_uuid", `UUID;
2298   "pv_fmt", `String;
2299   "pv_size", `Bytes;
2300   "dev_size", `Bytes;
2301   "pv_free", `Bytes;
2302   "pv_used", `Bytes;
2303   "pv_attr", `String (* XXX *);
2304   "pv_pe_count", `Int;
2305   "pv_pe_alloc_count", `Int;
2306   "pv_tags", `String;
2307   "pe_start", `Bytes;
2308   "pv_mda_count", `Int;
2309   "pv_mda_free", `Bytes;
2310 (* Not in Fedora 10:
2311   "pv_mda_size", `Bytes;
2312 *)
2313 ]
2314 let vg_cols = [
2315   "vg_name", `String;
2316   "vg_uuid", `UUID;
2317   "vg_fmt", `String;
2318   "vg_attr", `String (* XXX *);
2319   "vg_size", `Bytes;
2320   "vg_free", `Bytes;
2321   "vg_sysid", `String;
2322   "vg_extent_size", `Bytes;
2323   "vg_extent_count", `Int;
2324   "vg_free_count", `Int;
2325   "max_lv", `Int;
2326   "max_pv", `Int;
2327   "pv_count", `Int;
2328   "lv_count", `Int;
2329   "snap_count", `Int;
2330   "vg_seqno", `Int;
2331   "vg_tags", `String;
2332   "vg_mda_count", `Int;
2333   "vg_mda_free", `Bytes;
2334 (* Not in Fedora 10:
2335   "vg_mda_size", `Bytes;
2336 *)
2337 ]
2338 let lv_cols = [
2339   "lv_name", `String;
2340   "lv_uuid", `UUID;
2341   "lv_attr", `String (* XXX *);
2342   "lv_major", `Int;
2343   "lv_minor", `Int;
2344   "lv_kernel_major", `Int;
2345   "lv_kernel_minor", `Int;
2346   "lv_size", `Bytes;
2347   "seg_count", `Int;
2348   "origin", `String;
2349   "snap_percent", `OptPercent;
2350   "copy_percent", `OptPercent;
2351   "move_pv", `String;
2352   "lv_tags", `String;
2353   "mirror_log", `String;
2354   "modules", `String;
2355 ]
2356
2357 (* Column names and types from stat structures.
2358  * NB. Can't use things like 'st_atime' because glibc header files
2359  * define some of these as macros.  Ugh.
2360  *)
2361 let stat_cols = [
2362   "dev", `Int;
2363   "ino", `Int;
2364   "mode", `Int;
2365   "nlink", `Int;
2366   "uid", `Int;
2367   "gid", `Int;
2368   "rdev", `Int;
2369   "size", `Int;
2370   "blksize", `Int;
2371   "blocks", `Int;
2372   "atime", `Int;
2373   "mtime", `Int;
2374   "ctime", `Int;
2375 ]
2376 let statvfs_cols = [
2377   "bsize", `Int;
2378   "frsize", `Int;
2379   "blocks", `Int;
2380   "bfree", `Int;
2381   "bavail", `Int;
2382   "files", `Int;
2383   "ffree", `Int;
2384   "favail", `Int;
2385   "fsid", `Int;
2386   "flag", `Int;
2387   "namemax", `Int;
2388 ]
2389
2390 (* Used for testing language bindings. *)
2391 type callt =
2392   | CallString of string
2393   | CallOptString of string option
2394   | CallStringList of string list
2395   | CallInt of int
2396   | CallBool of bool
2397
2398 (* Useful functions.
2399  * Note we don't want to use any external OCaml libraries which
2400  * makes this a bit harder than it should be.
2401  *)
2402 let failwithf fs = ksprintf failwith fs
2403
2404 let replace_char s c1 c2 =
2405   let s2 = String.copy s in
2406   let r = ref false in
2407   for i = 0 to String.length s2 - 1 do
2408     if String.unsafe_get s2 i = c1 then (
2409       String.unsafe_set s2 i c2;
2410       r := true
2411     )
2412   done;
2413   if not !r then s else s2
2414
2415 let isspace c =
2416   c = ' '
2417   (* || c = '\f' *) || c = '\n' || c = '\r' || c = '\t' (* || c = '\v' *)
2418
2419 let triml ?(test = isspace) str =
2420   let i = ref 0 in
2421   let n = ref (String.length str) in
2422   while !n > 0 && test str.[!i]; do
2423     decr n;
2424     incr i
2425   done;
2426   if !i = 0 then str
2427   else String.sub str !i !n
2428
2429 let trimr ?(test = isspace) str =
2430   let n = ref (String.length str) in
2431   while !n > 0 && test str.[!n-1]; do
2432     decr n
2433   done;
2434   if !n = String.length str then str
2435   else String.sub str 0 !n
2436
2437 let trim ?(test = isspace) str =
2438   trimr ~test (triml ~test str)
2439
2440 let rec find s sub =
2441   let len = String.length s in
2442   let sublen = String.length sub in
2443   let rec loop i =
2444     if i <= len-sublen then (
2445       let rec loop2 j =
2446         if j < sublen then (
2447           if s.[i+j] = sub.[j] then loop2 (j+1)
2448           else -1
2449         ) else
2450           i (* found *)
2451       in
2452       let r = loop2 0 in
2453       if r = -1 then loop (i+1) else r
2454     ) else
2455       -1 (* not found *)
2456   in
2457   loop 0
2458
2459 let rec replace_str s s1 s2 =
2460   let len = String.length s in
2461   let sublen = String.length s1 in
2462   let i = find s s1 in
2463   if i = -1 then s
2464   else (
2465     let s' = String.sub s 0 i in
2466     let s'' = String.sub s (i+sublen) (len-i-sublen) in
2467     s' ^ s2 ^ replace_str s'' s1 s2
2468   )
2469
2470 let rec string_split sep str =
2471   let len = String.length str in
2472   let seplen = String.length sep in
2473   let i = find str sep in
2474   if i = -1 then [str]
2475   else (
2476     let s' = String.sub str 0 i in
2477     let s'' = String.sub str (i+seplen) (len-i-seplen) in
2478     s' :: string_split sep s''
2479   )
2480
2481 let files_equal n1 n2 =
2482   let cmd = sprintf "cmp -s %s %s" (Filename.quote n1) (Filename.quote n2) in
2483   match Sys.command cmd with
2484   | 0 -> true
2485   | 1 -> false
2486   | i -> failwithf "%s: failed with error code %d" cmd i
2487
2488 let rec find_map f = function
2489   | [] -> raise Not_found
2490   | x :: xs ->
2491       match f x with
2492       | Some y -> y
2493       | None -> find_map f xs
2494
2495 let iteri f xs =
2496   let rec loop i = function
2497     | [] -> ()
2498     | x :: xs -> f i x; loop (i+1) xs
2499   in
2500   loop 0 xs
2501
2502 let mapi f xs =
2503   let rec loop i = function
2504     | [] -> []
2505     | x :: xs -> let r = f i x in r :: loop (i+1) xs
2506   in
2507   loop 0 xs
2508
2509 let name_of_argt = function
2510   | String n | OptString n | StringList n | Bool n | Int n
2511   | FileIn n | FileOut n -> n
2512
2513 let seq_of_test = function
2514   | TestRun s | TestOutput (s, _) | TestOutputList (s, _)
2515   | TestOutputInt (s, _) | TestOutputTrue s | TestOutputFalse s
2516   | TestOutputLength (s, _) | TestOutputStruct (s, _)
2517   | TestLastFail s -> s
2518
2519 (* Check function names etc. for consistency. *)
2520 let check_functions () =
2521   let contains_uppercase str =
2522     let len = String.length str in
2523     let rec loop i =
2524       if i >= len then false
2525       else (
2526         let c = str.[i] in
2527         if c >= 'A' && c <= 'Z' then true
2528         else loop (i+1)
2529       )
2530     in
2531     loop 0
2532   in
2533
2534   (* Check function names. *)
2535   List.iter (
2536     fun (name, _, _, _, _, _, _) ->
2537       if String.length name >= 7 && String.sub name 0 7 = "guestfs" then
2538         failwithf "function name %s does not need 'guestfs' prefix" name;
2539       if name = "" then
2540         failwithf "function name is empty";
2541       if name.[0] < 'a' || name.[0] > 'z' then
2542         failwithf "function name %s must start with lowercase a-z" name;
2543       if String.contains name '-' then
2544         failwithf "function name %s should not contain '-', use '_' instead."
2545           name
2546   ) all_functions;
2547
2548   (* Check function parameter/return names. *)
2549   List.iter (
2550     fun (name, style, _, _, _, _, _) ->
2551       let check_arg_ret_name n =
2552         if contains_uppercase n then
2553           failwithf "%s param/ret %s should not contain uppercase chars"
2554             name n;
2555         if String.contains n '-' || String.contains n '_' then
2556           failwithf "%s param/ret %s should not contain '-' or '_'"
2557             name n;
2558         if n = "value" then
2559           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;
2560         if n = "int" || n = "char" || n = "short" || n = "long" then
2561           failwithf "%s has a param/ret which conflicts with a C type (eg. 'int', 'char' etc.)" name;
2562         if n = "i" then
2563           failwithf "%s has a param/ret called 'i', which will cause some conflicts in the generated code" name;
2564         if n = "argv" || n = "args" then
2565           failwithf "%s has a param/ret called 'argv' or 'args', which will cause some conflicts in the generated code" name
2566       in
2567
2568       (match fst style with
2569        | RErr -> ()
2570        | RInt n | RInt64 n | RBool n | RConstString n | RString n
2571        | RStringList n | RPVList n | RVGList n | RLVList n
2572        | RStat n | RStatVFS n
2573        | RHashtable n ->
2574            check_arg_ret_name n
2575        | RIntBool (n,m) ->
2576            check_arg_ret_name n;
2577            check_arg_ret_name m
2578       );
2579       List.iter (fun arg -> check_arg_ret_name (name_of_argt arg)) (snd style)
2580   ) all_functions;
2581
2582   (* Check short descriptions. *)
2583   List.iter (
2584     fun (name, _, _, _, _, shortdesc, _) ->
2585       if shortdesc.[0] <> Char.lowercase shortdesc.[0] then
2586         failwithf "short description of %s should begin with lowercase." name;
2587       let c = shortdesc.[String.length shortdesc-1] in
2588       if c = '\n' || c = '.' then
2589         failwithf "short description of %s should not end with . or \\n." name
2590   ) all_functions;
2591
2592   (* Check long dscriptions. *)
2593   List.iter (
2594     fun (name, _, _, _, _, _, longdesc) ->
2595       if longdesc.[String.length longdesc-1] = '\n' then
2596         failwithf "long description of %s should not end with \\n." name
2597   ) all_functions;
2598
2599   (* Check proc_nrs. *)
2600   List.iter (
2601     fun (name, _, proc_nr, _, _, _, _) ->
2602       if proc_nr <= 0 then
2603         failwithf "daemon function %s should have proc_nr > 0" name
2604   ) daemon_functions;
2605
2606   List.iter (
2607     fun (name, _, proc_nr, _, _, _, _) ->
2608       if proc_nr <> -1 then
2609         failwithf "non-daemon function %s should have proc_nr -1" name
2610   ) non_daemon_functions;
2611
2612   let proc_nrs =
2613     List.map (fun (name, _, proc_nr, _, _, _, _) -> name, proc_nr)
2614       daemon_functions in
2615   let proc_nrs =
2616     List.sort (fun (_,nr1) (_,nr2) -> compare nr1 nr2) proc_nrs in
2617   let rec loop = function
2618     | [] -> ()
2619     | [_] -> ()
2620     | (name1,nr1) :: ((name2,nr2) :: _ as rest) when nr1 < nr2 ->
2621         loop rest
2622     | (name1,nr1) :: (name2,nr2) :: _ ->
2623         failwithf "%s and %s have conflicting procedure numbers (%d, %d)"
2624           name1 name2 nr1 nr2
2625   in
2626   loop proc_nrs;
2627
2628   (* Check tests. *)
2629   List.iter (
2630     function
2631       (* Ignore functions that have no tests.  We generate a
2632        * warning when the user does 'make check' instead.
2633        *)
2634     | name, _, _, _, [], _, _ -> ()
2635     | name, _, _, _, tests, _, _ ->
2636         let funcs =
2637           List.map (
2638             fun (_, _, test) ->
2639               match seq_of_test test with
2640               | [] ->
2641                   failwithf "%s has a test containing an empty sequence" name
2642               | cmds -> List.map List.hd cmds
2643           ) tests in
2644         let funcs = List.flatten funcs in
2645
2646         let tested = List.mem name funcs in
2647
2648         if not tested then
2649           failwithf "function %s has tests but does not test itself" name
2650   ) all_functions
2651
2652 (* 'pr' prints to the current output file. *)
2653 let chan = ref stdout
2654 let pr fs = ksprintf (output_string !chan) fs
2655
2656 (* Generate a header block in a number of standard styles. *)
2657 type comment_style = CStyle | HashStyle | OCamlStyle | HaskellStyle
2658 type license = GPLv2 | LGPLv2
2659
2660 let generate_header comment license =
2661   let c = match comment with
2662     | CStyle ->     pr "/* "; " *"
2663     | HashStyle ->  pr "# ";  "#"
2664     | OCamlStyle -> pr "(* "; " *"
2665     | HaskellStyle -> pr "{- "; "  " in
2666   pr "libguestfs generated file\n";
2667   pr "%s WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.\n" c;
2668   pr "%s ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.\n" c;
2669   pr "%s\n" c;
2670   pr "%s Copyright (C) 2009 Red Hat Inc.\n" c;
2671   pr "%s\n" c;
2672   (match license with
2673    | GPLv2 ->
2674        pr "%s This program is free software; you can redistribute it and/or modify\n" c;
2675        pr "%s it under the terms of the GNU General Public License as published by\n" c;
2676        pr "%s the Free Software Foundation; either version 2 of the License, or\n" c;
2677        pr "%s (at your option) any later version.\n" c;
2678        pr "%s\n" c;
2679        pr "%s This program is distributed in the hope that it will be useful,\n" c;
2680        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
2681        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n" c;
2682        pr "%s GNU General Public License for more details.\n" c;
2683        pr "%s\n" c;
2684        pr "%s You should have received a copy of the GNU General Public License along\n" c;
2685        pr "%s with this program; if not, write to the Free Software Foundation, Inc.,\n" c;
2686        pr "%s 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n" c;
2687
2688    | LGPLv2 ->
2689        pr "%s This library is free software; you can redistribute it and/or\n" c;
2690        pr "%s modify it under the terms of the GNU Lesser General Public\n" c;
2691        pr "%s License as published by the Free Software Foundation; either\n" c;
2692        pr "%s version 2 of the License, or (at your option) any later version.\n" c;
2693        pr "%s\n" c;
2694        pr "%s This library is distributed in the hope that it will be useful,\n" c;
2695        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
2696        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\n" c;
2697        pr "%s Lesser General Public License for more details.\n" c;
2698        pr "%s\n" c;
2699        pr "%s You should have received a copy of the GNU Lesser General Public\n" c;
2700        pr "%s License along with this library; if not, write to the Free Software\n" c;
2701        pr "%s Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA\n" c;
2702   );
2703   (match comment with
2704    | CStyle -> pr " */\n"
2705    | HashStyle -> ()
2706    | OCamlStyle -> pr " *)\n"
2707    | HaskellStyle -> pr "-}\n"
2708   );
2709   pr "\n"
2710
2711 (* Start of main code generation functions below this line. *)
2712
2713 (* Generate the pod documentation for the C API. *)
2714 let rec generate_actions_pod () =
2715   List.iter (
2716     fun (shortname, style, _, flags, _, _, longdesc) ->
2717       if not (List.mem NotInDocs flags) then (
2718         let name = "guestfs_" ^ shortname in
2719         pr "=head2 %s\n\n" name;
2720         pr " ";
2721         generate_prototype ~extern:false ~handle:"handle" name style;
2722         pr "\n\n";
2723         pr "%s\n\n" longdesc;
2724         (match fst style with
2725          | RErr ->
2726              pr "This function returns 0 on success or -1 on error.\n\n"
2727          | RInt _ ->
2728              pr "On error this function returns -1.\n\n"
2729          | RInt64 _ ->
2730              pr "On error this function returns -1.\n\n"
2731          | RBool _ ->
2732              pr "This function returns a C truth value on success or -1 on error.\n\n"
2733          | RConstString _ ->
2734              pr "This function returns a string, or NULL on error.
2735 The string is owned by the guest handle and must I<not> be freed.\n\n"
2736          | RString _ ->
2737              pr "This function returns a string, or NULL on error.
2738 I<The caller must free the returned string after use>.\n\n"
2739          | RStringList _ ->
2740              pr "This function returns a NULL-terminated array of strings
2741 (like L<environ(3)>), or NULL if there was an error.
2742 I<The caller must free the strings and the array after use>.\n\n"
2743          | RIntBool _ ->
2744              pr "This function returns a C<struct guestfs_int_bool *>,
2745 or NULL if there was an error.
2746 I<The caller must call C<guestfs_free_int_bool> after use>.\n\n"
2747          | RPVList _ ->
2748              pr "This function returns a C<struct guestfs_lvm_pv_list *>
2749 (see E<lt>guestfs-structs.hE<gt>),
2750 or NULL if there was an error.
2751 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.\n\n"
2752          | RVGList _ ->
2753              pr "This function returns a C<struct guestfs_lvm_vg_list *>
2754 (see E<lt>guestfs-structs.hE<gt>),
2755 or NULL if there was an error.
2756 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.\n\n"
2757          | RLVList _ ->
2758              pr "This function returns a C<struct guestfs_lvm_lv_list *>
2759 (see E<lt>guestfs-structs.hE<gt>),
2760 or NULL if there was an error.
2761 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.\n\n"
2762          | RStat _ ->
2763              pr "This function returns a C<struct guestfs_stat *>
2764 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
2765 or NULL if there was an error.
2766 I<The caller must call C<free> after use>.\n\n"
2767          | RStatVFS _ ->
2768              pr "This function returns a C<struct guestfs_statvfs *>
2769 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
2770 or NULL if there was an error.
2771 I<The caller must call C<free> after use>.\n\n"
2772          | RHashtable _ ->
2773              pr "This function returns a NULL-terminated array of
2774 strings, or NULL if there was an error.
2775 The array of strings will always have length C<2n+1>, where
2776 C<n> keys and values alternate, followed by the trailing NULL entry.
2777 I<The caller must free the strings and the array after use>.\n\n"
2778         );
2779         if List.mem ProtocolLimitWarning flags then
2780           pr "%s\n\n" protocol_limit_warning;
2781         if List.mem DangerWillRobinson flags then
2782           pr "%s\n\n" danger_will_robinson
2783       )
2784   ) all_functions_sorted
2785
2786 and generate_structs_pod () =
2787   (* LVM structs documentation. *)
2788   List.iter (
2789     fun (typ, cols) ->
2790       pr "=head2 guestfs_lvm_%s\n" typ;
2791       pr "\n";
2792       pr " struct guestfs_lvm_%s {\n" typ;
2793       List.iter (
2794         function
2795         | name, `String -> pr "  char *%s;\n" name
2796         | name, `UUID ->
2797             pr "  /* The next field is NOT nul-terminated, be careful when printing it: */\n";
2798             pr "  char %s[32];\n" name
2799         | name, `Bytes -> pr "  uint64_t %s;\n" name
2800         | name, `Int -> pr "  int64_t %s;\n" name
2801         | name, `OptPercent ->
2802             pr "  /* The next field is [0..100] or -1 meaning 'not present': */\n";
2803             pr "  float %s;\n" name
2804       ) cols;
2805       pr " \n";
2806       pr " struct guestfs_lvm_%s_list {\n" typ;
2807       pr "   uint32_t len; /* Number of elements in list. */\n";
2808       pr "   struct guestfs_lvm_%s *val; /* Elements. */\n" typ;
2809       pr " };\n";
2810       pr " \n";
2811       pr " void guestfs_free_lvm_%s_list (struct guestfs_free_lvm_%s_list *);\n"
2812         typ typ;
2813       pr "\n"
2814   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols]
2815
2816 (* Generate the protocol (XDR) file, 'guestfs_protocol.x' and
2817  * indirectly 'guestfs_protocol.h' and 'guestfs_protocol.c'.
2818  *
2819  * We have to use an underscore instead of a dash because otherwise
2820  * rpcgen generates incorrect code.
2821  *
2822  * This header is NOT exported to clients, but see also generate_structs_h.
2823  *)
2824 and generate_xdr () =
2825   generate_header CStyle LGPLv2;
2826
2827   (* This has to be defined to get around a limitation in Sun's rpcgen. *)
2828   pr "typedef string str<>;\n";
2829   pr "\n";
2830
2831   (* LVM internal structures. *)
2832   List.iter (
2833     function
2834     | typ, cols ->
2835         pr "struct guestfs_lvm_int_%s {\n" typ;
2836         List.iter (function
2837                    | name, `String -> pr "  string %s<>;\n" name
2838                    | name, `UUID -> pr "  opaque %s[32];\n" name
2839                    | name, `Bytes -> pr "  hyper %s;\n" name
2840                    | name, `Int -> pr "  hyper %s;\n" name
2841                    | name, `OptPercent -> pr "  float %s;\n" name
2842                   ) cols;
2843         pr "};\n";
2844         pr "\n";
2845         pr "typedef struct guestfs_lvm_int_%s guestfs_lvm_int_%s_list<>;\n" typ typ;
2846         pr "\n";
2847   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
2848
2849   (* Stat internal structures. *)
2850   List.iter (
2851     function
2852     | typ, cols ->
2853         pr "struct guestfs_int_%s {\n" typ;
2854         List.iter (function
2855                    | name, `Int -> pr "  hyper %s;\n" name
2856                   ) cols;
2857         pr "};\n";
2858         pr "\n";
2859   ) ["stat", stat_cols; "statvfs", statvfs_cols];
2860
2861   List.iter (
2862     fun (shortname, style, _, _, _, _, _) ->
2863       let name = "guestfs_" ^ shortname in
2864
2865       (match snd style with
2866        | [] -> ()
2867        | args ->
2868            pr "struct %s_args {\n" name;
2869            List.iter (
2870              function
2871              | String n -> pr "  string %s<>;\n" n
2872              | OptString n -> pr "  str *%s;\n" n
2873              | StringList n -> pr "  str %s<>;\n" n
2874              | Bool n -> pr "  bool %s;\n" n
2875              | Int n -> pr "  int %s;\n" n
2876              | FileIn _ | FileOut _ -> ()
2877            ) args;
2878            pr "};\n\n"
2879       );
2880       (match fst style with
2881        | RErr -> ()
2882        | RInt n ->
2883            pr "struct %s_ret {\n" name;
2884            pr "  int %s;\n" n;
2885            pr "};\n\n"
2886        | RInt64 n ->
2887            pr "struct %s_ret {\n" name;
2888            pr "  hyper %s;\n" n;
2889            pr "};\n\n"
2890        | RBool n ->
2891            pr "struct %s_ret {\n" name;
2892            pr "  bool %s;\n" n;
2893            pr "};\n\n"
2894        | RConstString _ ->
2895            failwithf "RConstString cannot be returned from a daemon function"
2896        | RString n ->
2897            pr "struct %s_ret {\n" name;
2898            pr "  string %s<>;\n" n;
2899            pr "};\n\n"
2900        | RStringList n ->
2901            pr "struct %s_ret {\n" name;
2902            pr "  str %s<>;\n" n;
2903            pr "};\n\n"
2904        | RIntBool (n,m) ->
2905            pr "struct %s_ret {\n" name;
2906            pr "  int %s;\n" n;
2907            pr "  bool %s;\n" m;
2908            pr "};\n\n"
2909        | RPVList n ->
2910            pr "struct %s_ret {\n" name;
2911            pr "  guestfs_lvm_int_pv_list %s;\n" n;
2912            pr "};\n\n"
2913        | RVGList n ->
2914            pr "struct %s_ret {\n" name;
2915            pr "  guestfs_lvm_int_vg_list %s;\n" n;
2916            pr "};\n\n"
2917        | RLVList n ->
2918            pr "struct %s_ret {\n" name;
2919            pr "  guestfs_lvm_int_lv_list %s;\n" n;
2920            pr "};\n\n"
2921        | RStat n ->
2922            pr "struct %s_ret {\n" name;
2923            pr "  guestfs_int_stat %s;\n" n;
2924            pr "};\n\n"
2925        | RStatVFS n ->
2926            pr "struct %s_ret {\n" name;
2927            pr "  guestfs_int_statvfs %s;\n" n;
2928            pr "};\n\n"
2929        | RHashtable n ->
2930            pr "struct %s_ret {\n" name;
2931            pr "  str %s<>;\n" n;
2932            pr "};\n\n"
2933       );
2934   ) daemon_functions;
2935
2936   (* Table of procedure numbers. *)
2937   pr "enum guestfs_procedure {\n";
2938   List.iter (
2939     fun (shortname, _, proc_nr, _, _, _, _) ->
2940       pr "  GUESTFS_PROC_%s = %d,\n" (String.uppercase shortname) proc_nr
2941   ) daemon_functions;
2942   pr "  GUESTFS_PROC_NR_PROCS\n";
2943   pr "};\n";
2944   pr "\n";
2945
2946   (* Having to choose a maximum message size is annoying for several
2947    * reasons (it limits what we can do in the API), but it (a) makes
2948    * the protocol a lot simpler, and (b) provides a bound on the size
2949    * of the daemon which operates in limited memory space.  For large
2950    * file transfers you should use FTP.
2951    *)
2952   pr "const GUESTFS_MESSAGE_MAX = %d;\n" (4 * 1024 * 1024);
2953   pr "\n";
2954
2955   (* Message header, etc. *)
2956   pr "\
2957 /* The communication protocol is now documented in the guestfs(3)
2958  * manpage.
2959  */
2960
2961 const GUESTFS_PROGRAM = 0x2000F5F5;
2962 const GUESTFS_PROTOCOL_VERSION = 1;
2963
2964 /* These constants must be larger than any possible message length. */
2965 const GUESTFS_LAUNCH_FLAG = 0xf5f55ff5;
2966 const GUESTFS_CANCEL_FLAG = 0xffffeeee;
2967
2968 enum guestfs_message_direction {
2969   GUESTFS_DIRECTION_CALL = 0,        /* client -> daemon */
2970   GUESTFS_DIRECTION_REPLY = 1        /* daemon -> client */
2971 };
2972
2973 enum guestfs_message_status {
2974   GUESTFS_STATUS_OK = 0,
2975   GUESTFS_STATUS_ERROR = 1
2976 };
2977
2978 const GUESTFS_ERROR_LEN = 256;
2979
2980 struct guestfs_message_error {
2981   string error_message<GUESTFS_ERROR_LEN>;
2982 };
2983
2984 struct guestfs_message_header {
2985   unsigned prog;                     /* GUESTFS_PROGRAM */
2986   unsigned vers;                     /* GUESTFS_PROTOCOL_VERSION */
2987   guestfs_procedure proc;            /* GUESTFS_PROC_x */
2988   guestfs_message_direction direction;
2989   unsigned serial;                   /* message serial number */
2990   guestfs_message_status status;
2991 };
2992
2993 const GUESTFS_MAX_CHUNK_SIZE = 8192;
2994
2995 struct guestfs_chunk {
2996   int cancel;                        /* if non-zero, transfer is cancelled */
2997   /* data size is 0 bytes if the transfer has finished successfully */
2998   opaque data<GUESTFS_MAX_CHUNK_SIZE>;
2999 };
3000 "
3001
3002 (* Generate the guestfs-structs.h file. *)
3003 and generate_structs_h () =
3004   generate_header CStyle LGPLv2;
3005
3006   (* This is a public exported header file containing various
3007    * structures.  The structures are carefully written to have
3008    * exactly the same in-memory format as the XDR structures that
3009    * we use on the wire to the daemon.  The reason for creating
3010    * copies of these structures here is just so we don't have to
3011    * export the whole of guestfs_protocol.h (which includes much
3012    * unrelated and XDR-dependent stuff that we don't want to be
3013    * public, or required by clients).
3014    *
3015    * To reiterate, we will pass these structures to and from the
3016    * client with a simple assignment or memcpy, so the format
3017    * must be identical to what rpcgen / the RFC defines.
3018    *)
3019
3020   (* guestfs_int_bool structure. *)
3021   pr "struct guestfs_int_bool {\n";
3022   pr "  int32_t i;\n";
3023   pr "  int32_t b;\n";
3024   pr "};\n";
3025   pr "\n";
3026
3027   (* LVM public structures. *)
3028   List.iter (
3029     function
3030     | typ, cols ->
3031         pr "struct guestfs_lvm_%s {\n" typ;
3032         List.iter (
3033           function
3034           | name, `String -> pr "  char *%s;\n" name
3035           | name, `UUID -> pr "  char %s[32]; /* this is NOT nul-terminated, be careful when printing */\n" name
3036           | name, `Bytes -> pr "  uint64_t %s;\n" name
3037           | name, `Int -> pr "  int64_t %s;\n" name
3038           | name, `OptPercent -> pr "  float %s; /* [0..100] or -1 */\n" name
3039         ) cols;
3040         pr "};\n";
3041         pr "\n";
3042         pr "struct guestfs_lvm_%s_list {\n" typ;
3043         pr "  uint32_t len;\n";
3044         pr "  struct guestfs_lvm_%s *val;\n" typ;
3045         pr "};\n";
3046         pr "\n"
3047   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
3048
3049   (* Stat structures. *)
3050   List.iter (
3051     function
3052     | typ, cols ->
3053         pr "struct guestfs_%s {\n" typ;
3054         List.iter (
3055           function
3056           | name, `Int -> pr "  int64_t %s;\n" name
3057         ) cols;
3058         pr "};\n";
3059         pr "\n"
3060   ) ["stat", stat_cols; "statvfs", statvfs_cols]
3061
3062 (* Generate the guestfs-actions.h file. *)
3063 and generate_actions_h () =
3064   generate_header CStyle LGPLv2;
3065   List.iter (
3066     fun (shortname, style, _, _, _, _, _) ->
3067       let name = "guestfs_" ^ shortname in
3068       generate_prototype ~single_line:true ~newline:true ~handle:"handle"
3069         name style
3070   ) all_functions
3071
3072 (* Generate the client-side dispatch stubs. *)
3073 and generate_client_actions () =
3074   generate_header CStyle LGPLv2;
3075
3076   pr "\
3077 #include <stdio.h>
3078 #include <stdlib.h>
3079
3080 #include \"guestfs.h\"
3081 #include \"guestfs_protocol.h\"
3082
3083 #define error guestfs_error
3084 #define perrorf guestfs_perrorf
3085 #define safe_malloc guestfs_safe_malloc
3086 #define safe_realloc guestfs_safe_realloc
3087 #define safe_strdup guestfs_safe_strdup
3088 #define safe_memdup guestfs_safe_memdup
3089
3090 /* Check the return message from a call for validity. */
3091 static int
3092 check_reply_header (guestfs_h *g,
3093                     const struct guestfs_message_header *hdr,
3094                     int proc_nr, int serial)
3095 {
3096   if (hdr->prog != GUESTFS_PROGRAM) {
3097     error (g, \"wrong program (%%d/%%d)\", hdr->prog, GUESTFS_PROGRAM);
3098     return -1;
3099   }
3100   if (hdr->vers != GUESTFS_PROTOCOL_VERSION) {
3101     error (g, \"wrong protocol version (%%d/%%d)\",
3102            hdr->vers, GUESTFS_PROTOCOL_VERSION);
3103     return -1;
3104   }
3105   if (hdr->direction != GUESTFS_DIRECTION_REPLY) {
3106     error (g, \"unexpected message direction (%%d/%%d)\",
3107            hdr->direction, GUESTFS_DIRECTION_REPLY);
3108     return -1;
3109   }
3110   if (hdr->proc != proc_nr) {
3111     error (g, \"unexpected procedure number (%%d/%%d)\", hdr->proc, proc_nr);
3112     return -1;
3113   }
3114   if (hdr->serial != serial) {
3115     error (g, \"unexpected serial (%%d/%%d)\", hdr->serial, serial);
3116     return -1;
3117   }
3118
3119   return 0;
3120 }
3121
3122 /* Check we are in the right state to run a high-level action. */
3123 static int
3124 check_state (guestfs_h *g, const char *caller)
3125 {
3126   if (!guestfs_is_ready (g)) {
3127     if (guestfs_is_config (g))
3128       error (g, \"%%s: call launch() before using this function\",
3129         caller);
3130     else if (guestfs_is_launching (g))
3131       error (g, \"%%s: call wait_ready() before using this function\",
3132         caller);
3133     else
3134       error (g, \"%%s called from the wrong state, %%d != READY\",
3135         caller, guestfs_get_state (g));
3136     return -1;
3137   }
3138   return 0;
3139 }
3140
3141 ";
3142
3143   (* Client-side stubs for each function. *)
3144   List.iter (
3145     fun (shortname, style, _, _, _, _, _) ->
3146       let name = "guestfs_" ^ shortname in
3147
3148       (* Generate the context struct which stores the high-level
3149        * state between callback functions.
3150        *)
3151       pr "struct %s_ctx {\n" shortname;
3152       pr "  /* This flag is set by the callbacks, so we know we've done\n";
3153       pr "   * the callbacks as expected, and in the right sequence.\n";
3154       pr "   * 0 = not called, 1 = reply_cb called.\n";
3155       pr "   */\n";
3156       pr "  int cb_sequence;\n";
3157       pr "  struct guestfs_message_header hdr;\n";
3158       pr "  struct guestfs_message_error err;\n";
3159       (match fst style with
3160        | RErr -> ()
3161        | RConstString _ ->
3162            failwithf "RConstString cannot be returned from a daemon function"
3163        | RInt _ | RInt64 _
3164        | RBool _ | RString _ | RStringList _
3165        | RIntBool _
3166        | RPVList _ | RVGList _ | RLVList _
3167        | RStat _ | RStatVFS _
3168        | RHashtable _ ->
3169            pr "  struct %s_ret ret;\n" name
3170       );
3171       pr "};\n";
3172       pr "\n";
3173
3174       (* Generate the reply callback function. *)
3175       pr "static void %s_reply_cb (guestfs_h *g, void *data, XDR *xdr)\n" shortname;
3176       pr "{\n";
3177       pr "  guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3178       pr "  struct %s_ctx *ctx = (struct %s_ctx *) data;\n" shortname shortname;
3179       pr "\n";
3180       pr "  /* This should definitely not happen. */\n";
3181       pr "  if (ctx->cb_sequence != 0) {\n";
3182       pr "    ctx->cb_sequence = 9999;\n";
3183       pr "    error (g, \"%%s: internal error: reply callback called twice\", \"%s\");\n" name;
3184       pr "    return;\n";
3185       pr "  }\n";
3186       pr "\n";
3187       pr "  ml->main_loop_quit (ml, g);\n";
3188       pr "\n";
3189       pr "  if (!xdr_guestfs_message_header (xdr, &ctx->hdr)) {\n";
3190       pr "    error (g, \"%%s: failed to parse reply header\", \"%s\");\n" name;
3191       pr "    return;\n";
3192       pr "  }\n";
3193       pr "  if (ctx->hdr.status == GUESTFS_STATUS_ERROR) {\n";
3194       pr "    if (!xdr_guestfs_message_error (xdr, &ctx->err)) {\n";
3195       pr "      error (g, \"%%s: failed to parse reply error\", \"%s\");\n"
3196         name;
3197       pr "      return;\n";
3198       pr "    }\n";
3199       pr "    goto done;\n";
3200       pr "  }\n";
3201
3202       (match fst style with
3203        | RErr -> ()
3204        | RConstString _ ->
3205            failwithf "RConstString cannot be returned from a daemon function"
3206        | RInt _ | RInt64 _
3207        | RBool _ | RString _ | RStringList _
3208        | RIntBool _
3209        | RPVList _ | RVGList _ | RLVList _
3210        | RStat _ | RStatVFS _
3211        | RHashtable _ ->
3212             pr "  if (!xdr_%s_ret (xdr, &ctx->ret)) {\n" name;
3213             pr "    error (g, \"%%s: failed to parse reply\", \"%s\");\n" name;
3214             pr "    return;\n";
3215             pr "  }\n";
3216       );
3217
3218       pr " done:\n";
3219       pr "  ctx->cb_sequence = 1;\n";
3220       pr "}\n\n";
3221
3222       (* Generate the action stub. *)
3223       generate_prototype ~extern:false ~semicolon:false ~newline:true
3224         ~handle:"g" name style;
3225
3226       let error_code =
3227         match fst style with
3228         | RErr | RInt _ | RInt64 _ | RBool _ -> "-1"
3229         | RConstString _ ->
3230             failwithf "RConstString cannot be returned from a daemon function"
3231         | RString _ | RStringList _ | RIntBool _
3232         | RPVList _ | RVGList _ | RLVList _
3233         | RStat _ | RStatVFS _
3234         | RHashtable _ ->
3235             "NULL" in
3236
3237       pr "{\n";
3238
3239       (match snd style with
3240        | [] -> ()
3241        | _ -> pr "  struct %s_args args;\n" name
3242       );
3243
3244       pr "  struct %s_ctx ctx;\n" shortname;
3245       pr "  guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3246       pr "  int serial;\n";
3247       pr "\n";
3248       pr "  if (check_state (g, \"%s\") == -1) return %s;\n" name error_code;
3249       pr "  guestfs_set_busy (g);\n";
3250       pr "\n";
3251       pr "  memset (&ctx, 0, sizeof ctx);\n";
3252       pr "\n";
3253
3254       (* Send the main header and arguments. *)
3255       (match snd style with
3256        | [] ->
3257            pr "  serial = guestfs__send_sync (g, GUESTFS_PROC_%s, NULL, NULL);\n"
3258              (String.uppercase shortname)
3259        | args ->
3260            List.iter (
3261              function
3262              | String n ->
3263                  pr "  args.%s = (char *) %s;\n" n n
3264              | OptString n ->
3265                  pr "  args.%s = %s ? (char **) &%s : NULL;\n" n n n
3266              | StringList n ->
3267                  pr "  args.%s.%s_val = (char **) %s;\n" n n n;
3268                  pr "  for (args.%s.%s_len = 0; %s[args.%s.%s_len]; args.%s.%s_len++) ;\n" n n n n n n n;
3269              | Bool n ->
3270                  pr "  args.%s = %s;\n" n n
3271              | Int n ->
3272                  pr "  args.%s = %s;\n" n n
3273              | FileIn _ | FileOut _ -> ()
3274            ) args;
3275            pr "  serial = guestfs__send_sync (g, GUESTFS_PROC_%s,\n"
3276              (String.uppercase shortname);
3277            pr "        (xdrproc_t) xdr_%s_args, (char *) &args);\n"
3278              name;
3279       );
3280       pr "  if (serial == -1) {\n";
3281       pr "    guestfs_end_busy (g);\n";
3282       pr "    return %s;\n" error_code;
3283       pr "  }\n";
3284       pr "\n";
3285
3286       (* Send any additional files (FileIn) requested. *)
3287       let need_read_reply_label = ref false in
3288       List.iter (
3289         function
3290         | FileIn n ->
3291             pr "  {\n";
3292             pr "    int r;\n";
3293             pr "\n";
3294             pr "    r = guestfs__send_file_sync (g, %s);\n" n;
3295             pr "    if (r == -1) {\n";
3296             pr "      guestfs_end_busy (g);\n";
3297             pr "      return %s;\n" error_code;
3298             pr "    }\n";
3299             pr "    if (r == -2) /* daemon cancelled */\n";
3300             pr "      goto read_reply;\n";
3301             need_read_reply_label := true;
3302             pr "  }\n";
3303             pr "\n";
3304         | _ -> ()
3305       ) (snd style);
3306
3307       (* Wait for the reply from the remote end. *)
3308       if !need_read_reply_label then pr " read_reply:\n";
3309       pr "  guestfs__switch_to_receiving (g);\n";
3310       pr "  ctx.cb_sequence = 0;\n";
3311       pr "  guestfs_set_reply_callback (g, %s_reply_cb, &ctx);\n" shortname;
3312       pr "  (void) ml->main_loop_run (ml, g);\n";
3313       pr "  guestfs_set_reply_callback (g, NULL, NULL);\n";
3314       pr "  if (ctx.cb_sequence != 1) {\n";
3315       pr "    error (g, \"%%s reply failed, see earlier error messages\", \"%s\");\n" name;
3316       pr "    guestfs_end_busy (g);\n";
3317       pr "    return %s;\n" error_code;
3318       pr "  }\n";
3319       pr "\n";
3320
3321       pr "  if (check_reply_header (g, &ctx.hdr, GUESTFS_PROC_%s, serial) == -1) {\n"
3322         (String.uppercase shortname);
3323       pr "    guestfs_end_busy (g);\n";
3324       pr "    return %s;\n" error_code;
3325       pr "  }\n";
3326       pr "\n";
3327
3328       pr "  if (ctx.hdr.status == GUESTFS_STATUS_ERROR) {\n";
3329       pr "    error (g, \"%%s\", ctx.err.error_message);\n";
3330       pr "    free (ctx.err.error_message);\n";
3331       pr "    guestfs_end_busy (g);\n";
3332       pr "    return %s;\n" error_code;
3333       pr "  }\n";
3334       pr "\n";
3335
3336       (* Expecting to receive further files (FileOut)? *)
3337       List.iter (
3338         function
3339         | FileOut n ->
3340             pr "  if (guestfs__receive_file_sync (g, %s) == -1) {\n" n;
3341             pr "    guestfs_end_busy (g);\n";
3342             pr "    return %s;\n" error_code;
3343             pr "  }\n";
3344             pr "\n";
3345         | _ -> ()
3346       ) (snd style);
3347
3348       pr "  guestfs_end_busy (g);\n";
3349
3350       (match fst style with
3351        | RErr -> pr "  return 0;\n"
3352        | RInt n | RInt64 n | RBool n ->
3353            pr "  return ctx.ret.%s;\n" n
3354        | RConstString _ ->
3355            failwithf "RConstString cannot be returned from a daemon function"
3356        | RString n ->
3357            pr "  return ctx.ret.%s; /* caller will free */\n" n
3358        | RStringList n | RHashtable n ->
3359            pr "  /* caller will free this, but we need to add a NULL entry */\n";
3360            pr "  ctx.ret.%s.%s_val =\n" n n;
3361            pr "    safe_realloc (g, ctx.ret.%s.%s_val,\n" n n;
3362            pr "                  sizeof (char *) * (ctx.ret.%s.%s_len + 1));\n"
3363              n n;
3364            pr "  ctx.ret.%s.%s_val[ctx.ret.%s.%s_len] = NULL;\n" n n n n;
3365            pr "  return ctx.ret.%s.%s_val;\n" n n
3366        | RIntBool _ ->
3367            pr "  /* caller with free this */\n";
3368            pr "  return safe_memdup (g, &ctx.ret, sizeof (ctx.ret));\n"
3369        | RPVList n | RVGList n | RLVList n
3370        | RStat n | RStatVFS n ->
3371            pr "  /* caller will free this */\n";
3372            pr "  return safe_memdup (g, &ctx.ret.%s, sizeof (ctx.ret.%s));\n" n n
3373       );
3374
3375       pr "}\n\n"
3376   ) daemon_functions
3377
3378 (* Generate daemon/actions.h. *)
3379 and generate_daemon_actions_h () =
3380   generate_header CStyle GPLv2;
3381
3382   pr "#include \"../src/guestfs_protocol.h\"\n";
3383   pr "\n";
3384
3385   List.iter (
3386     fun (name, style, _, _, _, _, _) ->
3387         generate_prototype
3388           ~single_line:true ~newline:true ~in_daemon:true ~prefix:"do_"
3389           name style;
3390   ) daemon_functions
3391
3392 (* Generate the server-side stubs. *)
3393 and generate_daemon_actions () =
3394   generate_header CStyle GPLv2;
3395
3396   pr "#include <config.h>\n";
3397   pr "\n";
3398   pr "#include <stdio.h>\n";
3399   pr "#include <stdlib.h>\n";
3400   pr "#include <string.h>\n";
3401   pr "#include <inttypes.h>\n";
3402   pr "#include <ctype.h>\n";
3403   pr "#include <rpc/types.h>\n";
3404   pr "#include <rpc/xdr.h>\n";
3405   pr "\n";
3406   pr "#include \"daemon.h\"\n";
3407   pr "#include \"../src/guestfs_protocol.h\"\n";
3408   pr "#include \"actions.h\"\n";
3409   pr "\n";
3410
3411   List.iter (
3412     fun (name, style, _, _, _, _, _) ->
3413       (* Generate server-side stubs. *)
3414       pr "static void %s_stub (XDR *xdr_in)\n" name;
3415       pr "{\n";
3416       let error_code =
3417         match fst style with
3418         | RErr | RInt _ -> pr "  int r;\n"; "-1"
3419         | RInt64 _ -> pr "  int64_t r;\n"; "-1"
3420         | RBool _ -> pr "  int r;\n"; "-1"
3421         | RConstString _ ->
3422             failwithf "RConstString cannot be returned from a daemon function"
3423         | RString _ -> pr "  char *r;\n"; "NULL"
3424         | RStringList _ | RHashtable _ -> pr "  char **r;\n"; "NULL"
3425         | RIntBool _ -> pr "  guestfs_%s_ret *r;\n" name; "NULL"
3426         | RPVList _ -> pr "  guestfs_lvm_int_pv_list *r;\n"; "NULL"
3427         | RVGList _ -> pr "  guestfs_lvm_int_vg_list *r;\n"; "NULL"
3428         | RLVList _ -> pr "  guestfs_lvm_int_lv_list *r;\n"; "NULL"
3429         | RStat _ -> pr "  guestfs_int_stat *r;\n"; "NULL"
3430         | RStatVFS _ -> pr "  guestfs_int_statvfs *r;\n"; "NULL" in
3431
3432       (match snd style with
3433        | [] -> ()
3434        | args ->
3435            pr "  struct guestfs_%s_args args;\n" name;
3436            List.iter (
3437              function
3438              | String n
3439              | OptString n -> pr "  const char *%s;\n" n
3440              | StringList n -> pr "  char **%s;\n" n
3441              | Bool n -> pr "  int %s;\n" n
3442              | Int n -> pr "  int %s;\n" n
3443              | FileIn _ | FileOut _ -> ()
3444            ) args
3445       );
3446       pr "\n";
3447
3448       (match snd style with
3449        | [] -> ()
3450        | args ->
3451            pr "  memset (&args, 0, sizeof args);\n";
3452            pr "\n";
3453            pr "  if (!xdr_guestfs_%s_args (xdr_in, &args)) {\n" name;
3454            pr "    reply_with_error (\"%%s: daemon failed to decode procedure arguments\", \"%s\");\n" name;
3455            pr "    return;\n";
3456            pr "  }\n";
3457            List.iter (
3458              function
3459              | String n -> pr "  %s = args.%s;\n" n n
3460              | OptString n -> pr "  %s = args.%s ? *args.%s : NULL;\n" n n n
3461              | StringList n ->
3462                  pr "  %s = realloc (args.%s.%s_val,\n" n n n;
3463                  pr "                sizeof (char *) * (args.%s.%s_len+1));\n" n n;
3464                  pr "  if (%s == NULL) {\n" n;
3465                  pr "    reply_with_perror (\"realloc\");\n";
3466                  pr "    goto done;\n";
3467                  pr "  }\n";
3468                  pr "  %s[args.%s.%s_len] = NULL;\n" n n n;
3469                  pr "  args.%s.%s_val = %s;\n" n n n;
3470              | Bool n -> pr "  %s = args.%s;\n" n n
3471              | Int n -> pr "  %s = args.%s;\n" n n
3472              | FileIn _ | FileOut _ -> ()
3473            ) args;
3474            pr "\n"
3475       );
3476
3477       (* Don't want to call the impl with any FileIn or FileOut
3478        * parameters, since these go "outside" the RPC protocol.
3479        *)
3480       let argsnofile =
3481         List.filter (function FileIn _ | FileOut _ -> false | _ -> true)
3482           (snd style) in
3483       pr "  r = do_%s " name;
3484       generate_call_args argsnofile;
3485       pr ";\n";
3486
3487       pr "  if (r == %s)\n" error_code;
3488       pr "    /* do_%s has already called reply_with_error */\n" name;
3489       pr "    goto done;\n";
3490       pr "\n";
3491
3492       (* If there are any FileOut parameters, then the impl must
3493        * send its own reply.
3494        *)
3495       let no_reply =
3496         List.exists (function FileOut _ -> true | _ -> false) (snd style) in
3497       if no_reply then
3498         pr "  /* do_%s has already sent a reply */\n" name
3499       else (
3500         match fst style with
3501         | RErr -> pr "  reply (NULL, NULL);\n"
3502         | RInt n | RInt64 n | RBool n ->
3503             pr "  struct guestfs_%s_ret ret;\n" name;
3504             pr "  ret.%s = r;\n" n;
3505             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3506               name
3507         | RConstString _ ->
3508             failwithf "RConstString cannot be returned from a daemon function"
3509         | RString n ->
3510             pr "  struct guestfs_%s_ret ret;\n" name;
3511             pr "  ret.%s = r;\n" n;
3512             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3513               name;
3514             pr "  free (r);\n"
3515         | RStringList n | RHashtable n ->
3516             pr "  struct guestfs_%s_ret ret;\n" name;
3517             pr "  ret.%s.%s_len = count_strings (r);\n" n n;
3518             pr "  ret.%s.%s_val = r;\n" n n;
3519             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3520               name;
3521             pr "  free_strings (r);\n"
3522         | RIntBool _ ->
3523             pr "  reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) r);\n"
3524               name;
3525             pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) r);\n" name
3526         | RPVList n | RVGList n | RLVList n
3527         | RStat n | RStatVFS n ->
3528             pr "  struct guestfs_%s_ret ret;\n" name;
3529             pr "  ret.%s = *r;\n" n;
3530             pr "  reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
3531               name;
3532             pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
3533               name
3534       );
3535
3536       (* Free the args. *)
3537       (match snd style with
3538        | [] ->
3539            pr "done: ;\n";
3540        | _ ->
3541            pr "done:\n";
3542            pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_args, (char *) &args);\n"
3543              name
3544       );
3545
3546       pr "}\n\n";
3547   ) daemon_functions;
3548
3549   (* Dispatch function. *)
3550   pr "void dispatch_incoming_message (XDR *xdr_in)\n";
3551   pr "{\n";
3552   pr "  switch (proc_nr) {\n";
3553
3554   List.iter (
3555     fun (name, style, _, _, _, _, _) ->
3556         pr "    case GUESTFS_PROC_%s:\n" (String.uppercase name);
3557         pr "      %s_stub (xdr_in);\n" name;
3558         pr "      break;\n"
3559   ) daemon_functions;
3560
3561   pr "    default:\n";
3562   pr "      reply_with_error (\"dispatch_incoming_message: unknown procedure number %%d\", proc_nr);\n";
3563   pr "  }\n";
3564   pr "}\n";
3565   pr "\n";
3566
3567   (* LVM columns and tokenization functions. *)
3568   (* XXX This generates crap code.  We should rethink how we
3569    * do this parsing.
3570    *)
3571   List.iter (
3572     function
3573     | typ, cols ->
3574         pr "static const char *lvm_%s_cols = \"%s\";\n"
3575           typ (String.concat "," (List.map fst cols));
3576         pr "\n";
3577
3578         pr "static int lvm_tokenize_%s (char *str, struct guestfs_lvm_int_%s *r)\n" typ typ;
3579         pr "{\n";
3580         pr "  char *tok, *p, *next;\n";
3581         pr "  int i, j;\n";
3582         pr "\n";
3583         (*
3584         pr "  fprintf (stderr, \"%%s: <<%%s>>\\n\", __func__, str);\n";
3585         pr "\n";
3586         *)
3587         pr "  if (!str) {\n";
3588         pr "    fprintf (stderr, \"%%s: failed: passed a NULL string\\n\", __func__);\n";
3589         pr "    return -1;\n";
3590         pr "  }\n";
3591         pr "  if (!*str || isspace (*str)) {\n";
3592         pr "    fprintf (stderr, \"%%s: failed: passed a empty string or one beginning with whitespace\\n\", __func__);\n";
3593         pr "    return -1;\n";
3594         pr "  }\n";
3595         pr "  tok = str;\n";
3596         List.iter (
3597           fun (name, coltype) ->
3598             pr "  if (!tok) {\n";
3599             pr "    fprintf (stderr, \"%%s: failed: string finished early, around token %%s\\n\", __func__, \"%s\");\n" name;
3600             pr "    return -1;\n";
3601             pr "  }\n";
3602             pr "  p = strchrnul (tok, ',');\n";
3603             pr "  if (*p) next = p+1; else next = NULL;\n";
3604             pr "  *p = '\\0';\n";
3605             (match coltype with
3606              | `String ->
3607                  pr "  r->%s = strdup (tok);\n" name;
3608                  pr "  if (r->%s == NULL) {\n" name;
3609                  pr "    perror (\"strdup\");\n";
3610                  pr "    return -1;\n";
3611                  pr "  }\n"
3612              | `UUID ->
3613                  pr "  for (i = j = 0; i < 32; ++j) {\n";
3614                  pr "    if (tok[j] == '\\0') {\n";
3615                  pr "      fprintf (stderr, \"%%s: failed to parse UUID from '%%s'\\n\", __func__, tok);\n";
3616                  pr "      return -1;\n";
3617                  pr "    } else if (tok[j] != '-')\n";
3618                  pr "      r->%s[i++] = tok[j];\n" name;
3619                  pr "  }\n";
3620              | `Bytes ->
3621                  pr "  if (sscanf (tok, \"%%\"SCNu64, &r->%s) != 1) {\n" name;
3622                  pr "    fprintf (stderr, \"%%s: failed to parse size '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
3623                  pr "    return -1;\n";
3624                  pr "  }\n";
3625              | `Int ->
3626                  pr "  if (sscanf (tok, \"%%\"SCNi64, &r->%s) != 1) {\n" name;
3627                  pr "    fprintf (stderr, \"%%s: failed to parse int '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
3628                  pr "    return -1;\n";
3629                  pr "  }\n";
3630              | `OptPercent ->
3631                  pr "  if (tok[0] == '\\0')\n";
3632                  pr "    r->%s = -1;\n" name;
3633                  pr "  else if (sscanf (tok, \"%%f\", &r->%s) != 1) {\n" name;
3634                  pr "    fprintf (stderr, \"%%s: failed to parse float '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
3635                  pr "    return -1;\n";
3636                  pr "  }\n";
3637             );
3638             pr "  tok = next;\n";
3639         ) cols;
3640
3641         pr "  if (tok != NULL) {\n";
3642         pr "    fprintf (stderr, \"%%s: failed: extra tokens at end of string\\n\", __func__);\n";
3643         pr "    return -1;\n";
3644         pr "  }\n";
3645         pr "  return 0;\n";
3646         pr "}\n";