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