/libguestfs-1.19.22/generator/generator_actions.ml

   1(* libguestfs
   2 * Copyright (C) 2009-2012 Red Hat Inc.
   3 *
   4 * This program is free software; you can redistribute it and/or modify
   5 * it under the terms of the GNU General Public License as published by
   6 * the Free Software Foundation; either version 2 of the License, or
   7 * (at your option) any later version.
   8 *
   9 * This program is distributed in the hope that it will be useful,
  10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 * GNU General Public License for more details.
  13 *
  14 * You should have received a copy of the GNU General Public License
  15 * along with this program; if not, write to the Free Software
  16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17 *)
  18
  19(* Please read generator/README first. *)
  20
  21open Generator_types
  22open Generator_utils
  23
  24(* Default settings for all action fields.  So we copy and override
  25 * this struct by writing '{ defaults with name = &c }'
  26 *)
  27let defaults = { name = ""; style = RErr, [], []; proc_nr = None;
  28                 tests = []; shortdesc = ""; longdesc = "";
  29                 protocol_limit_warning = false; fish_alias = [];
  30                 fish_output = None; in_fish = true; in_docs = true;
  31                 deprecated_by = None; optional = None;
  32                 progress = false; camel_name = "";
  33                 cancellable = false; config_only = false;
  34                 once_had_no_optargs = false;
  35                 c_name = ""; c_function = ""; c_optarg_prefix = "";
  36                 non_c_aliases = [] }
  37
  38(* These test functions are used in the language binding tests. *)
  39
  40let test_all_args = [
  41  String "str";
  42  OptString "optstr";
  43  StringList "strlist";
  44  Bool "b";
  45  Int "integer";
  46  Int64 "integer64";
  47  FileIn "filein";
  48  FileOut "fileout";
  49  BufferIn "bufferin";
  50]
  51
  52let test_all_optargs = [
  53  OBool   "obool";
  54  OInt    "oint";
  55  OInt64  "oint64";
  56  OString "ostring"
  57]
  58
  59let test_all_rets = [
  60  (* except for RErr, which is tested thoroughly elsewhere *)
  61  "internal_test_rint",         RInt "valout";
  62  "internal_test_rint64",       RInt64 "valout";
  63  "internal_test_rbool",        RBool "valout";
  64  "internal_test_rconststring", RConstString "valout";
  65  "internal_test_rconstoptstring", RConstOptString "valout";
  66  "internal_test_rstring",      RString "valout";
  67  "internal_test_rstringlist",  RStringList "valout";
  68  "internal_test_rstruct",      RStruct ("valout", "lvm_pv");
  69  "internal_test_rstructlist",  RStructList ("valout", "lvm_pv");
  70  "internal_test_rhashtable",   RHashtable "valout";
  71  "internal_test_rbufferout",   RBufferOut "valout";
  72]
  73
  74let test_functions = [
  75  { defaults with
  76    name = "internal_test";
  77    style = RErr, test_all_args, test_all_optargs;
  78    in_fish = false; in_docs = false; cancellable = true;
  79    shortdesc = "internal test function - do not use";
  80    longdesc = "\
  81This is an internal test function which is used to test whether
  82the automatically generated bindings can handle every possible
  83parameter type correctly.
  84
  85It echos the contents of each parameter to stdout.
  86
  87You probably don't want to call this function." }
  88] @ List.flatten (
  89  List.map (
  90    fun (name, ret) -> [
  91      { defaults with
  92        name = name;
  93        style = ret, [String "val"], [];
  94        in_fish = false; in_docs = false;
  95        shortdesc = "internal test function - do not use";
  96        longdesc = "\
  97This is an internal test function which is used to test whether
  98the automatically generated bindings can handle every possible
  99return type correctly.
 100
 101It converts string C<val> to the return type.
 102
 103You probably don't want to call this function." };
 104      { defaults with
 105        name = name ^ "err";
 106        style = ret, [], [];
 107        in_fish = false; in_docs = false;
 108        shortdesc = "internal test function - do not use";
 109        longdesc = "\
 110This is an internal test function which is used to test whether
 111the automatically generated bindings can handle every possible
 112return type correctly.
 113
 114This function always returns an error.
 115
 116You probably don't want to call this function." }
 117    ]
 118  ) test_all_rets
 119)
 120
 121(* non_daemon_functions are any functions which don't get processed
 122 * in the daemon, eg. functions for setting and getting local
 123 * configuration values.
 124 *)
 125
 126let non_daemon_functions = test_functions @ [
 127  { defaults with
 128    name = "launch";
 129    style = RErr, [], [];
 130    fish_alias = ["run"]; progress = true; config_only = true;
 131    shortdesc = "launch the qemu subprocess";
 132    longdesc = "\
 133Internally libguestfs is implemented by running a virtual machine
 134using L<qemu(1)>.
 135
 136You should call this after configuring the handle
 137(eg. adding drives) but before performing any actions." };
 138
 139  { defaults with
 140    name = "wait_ready";
 141    style = RErr, [], [];
 142    in_fish = false; deprecated_by = Some "launch";
 143    shortdesc = "wait until the qemu subprocess launches (no op)";
 144    longdesc = "\
 145This function is a no op.
 146
 147In versions of the API E<lt> 1.0.71 you had to call this function
 148just after calling C<guestfs_launch> to wait for the launch
 149to complete.  However this is no longer necessary because
 150C<guestfs_launch> now does the waiting.
 151
 152If you see any calls to this function in code then you can just
 153remove them, unless you want to retain compatibility with older
 154versions of the API." };
 155
 156  { defaults with
 157    name = "kill_subprocess";
 158    style = RErr, [], [];
 159    deprecated_by = Some "shutdown";
 160    shortdesc = "kill the qemu subprocess";
 161    longdesc = "\
 162This kills the qemu subprocess.
 163
 164Do not call this.  See: C<guestfs_shutdown> instead." };
 165
 166  { defaults with
 167    name = "add_cdrom";
 168    style = RErr, [String "filename"], [];
 169    deprecated_by = Some "add_drive"; config_only = true;
 170    shortdesc = "add a CD-ROM disk image to examine";
 171    longdesc = "\
 172This function adds a virtual CD-ROM disk image to the guest.
 173
 174This is equivalent to the qemu parameter I<-cdrom filename>.
 175
 176Notes:
 177
 178=over 4
 179
 180=item *
 181
 182This call checks for the existence of C<filename>.  This
 183stops you from specifying other types of drive which are supported
 184by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
 185the general C<guestfs_config> call instead.
 186
 187=item *
 188
 189If you just want to add an ISO file (often you use this as an
 190efficient way to transfer large files into the guest), then you
 191should probably use C<guestfs_add_drive_ro> instead.
 192
 193=back" };
 194
 195  { defaults with
 196    name = "add_drive_ro";
 197    style = RErr, [String "filename"], [];
 198    fish_alias = ["add-ro"]; config_only = true;
 199    shortdesc = "add a drive in snapshot mode (read-only)";
 200    longdesc = "\
 201This function is the equivalent of calling C<guestfs_add_drive_opts>
 202with the optional parameter C<GUESTFS_ADD_DRIVE_OPTS_READONLY> set to 1,
 203so the disk is added read-only, with the format being detected
 204automatically." };
 205
 206  { defaults with
 207    name = "config";
 208    style = RErr, [String "qemuparam"; OptString "qemuvalue"], [];
 209    config_only = true;
 210    shortdesc = "add qemu parameters";
 211    longdesc = "\
 212This can be used to add arbitrary qemu command line parameters
 213of the form I<-param value>.  Actually it's not quite arbitrary - we
 214prevent you from setting some parameters which would interfere with
 215parameters that we use.
 216
 217The first character of C<param> string must be a C<-> (dash).
 218
 219C<value> can be NULL." };
 220
 221  { defaults with
 222    name = "set_qemu";
 223    style = RErr, [OptString "qemu"], [];
 224    fish_alias = ["qemu"]; config_only = true;
 225    shortdesc = "set the qemu binary";
 226    longdesc = "\
 227Set the qemu binary that we will use.
 228
 229The default is chosen when the library was compiled by the
 230configure script.
 231
 232You can also override this by setting the C<LIBGUESTFS_QEMU>
 233environment variable.
 234
 235Setting C<qemu> to C<NULL> restores the default qemu binary.
 236
 237Note that you should call this function as early as possible
 238after creating the handle.  This is because some pre-launch
 239operations depend on testing qemu features (by running C<qemu -help>).
 240If the qemu binary changes, we don't retest features, and
 241so you might see inconsistent results.  Using the environment
 242variable C<LIBGUESTFS_QEMU> is safest of all since that picks
 243the qemu binary at the same time as the handle is created." };
 244
 245  { defaults with
 246    name = "get_qemu";
 247    style = RConstString "qemu", [], [];
 248    tests = [
 249      InitNone, Always, TestRun (
 250        [["get_qemu"]])
 251    ];
 252    shortdesc = "get the qemu binary";
 253    longdesc = "\
 254Return the current qemu binary.
 255
 256This is always non-NULL.  If it wasn't set already, then this will
 257return the default qemu binary name." };
 258
 259  { defaults with
 260    name = "set_path";
 261    style = RErr, [OptString "searchpath"], [];
 262    fish_alias = ["path"]; config_only = true;
 263    shortdesc = "set the search path";
 264    longdesc = "\
 265Set the path that libguestfs searches for kernel and initrd.img.
 266
 267The default is C<$libdir/guestfs> unless overridden by setting
 268C<LIBGUESTFS_PATH> environment variable.
 269
 270Setting C<path> to C<NULL> restores the default path." };
 271
 272  { defaults with
 273    name = "get_path";
 274    style = RConstString "path", [], [];
 275    tests = [
 276      InitNone, Always, TestRun (
 277      [["get_path"]])
 278    ];
 279    shortdesc = "get the search path";
 280    longdesc = "\
 281Return the current search path.
 282
 283This is always non-NULL.  If it wasn't set already, then this will
 284return the default path." };
 285
 286  { defaults with
 287    name = "set_append";
 288    style = RErr, [OptString "append"], [];
 289    fish_alias = ["append"]; config_only = true;
 290    shortdesc = "add options to kernel command line";
 291    longdesc = "\
 292This function is used to add additional options to the
 293guest kernel command line.
 294
 295The default is C<NULL> unless overridden by setting
 296C<LIBGUESTFS_APPEND> environment variable.
 297
 298Setting C<append> to C<NULL> means I<no> additional options
 299are passed (libguestfs always adds a few of its own)." };
 300
 301  { defaults with
 302    name = "get_append";
 303    style = RConstOptString "append", [], [];
 304    (* This cannot be tested with the current framework.  The
 305     * function can return NULL in normal operations, which the
 306     * test framework interprets as an error.
 307     *)
 308    tests = [];
 309    shortdesc = "get the additional kernel options";
 310    longdesc = "\
 311Return the additional kernel options which are added to the
 312guest kernel command line.
 313
 314If C<NULL> then no options are added." };
 315
 316  { defaults with
 317    name = "set_autosync";
 318    style = RErr, [Bool "autosync"], [];
 319    fish_alias = ["autosync"];
 320    shortdesc = "set autosync mode";
 321    longdesc = "\
 322If C<autosync> is true, this enables autosync.  Libguestfs will make a
 323best effort attempt to make filesystems consistent and synchronized
 324when the handle is closed
 325(also if the program exits without closing handles).
 326
 327This is enabled by default (since libguestfs 1.5.24, previously it was
 328disabled by default)." };
 329
 330  { defaults with
 331    name = "get_autosync";
 332    style = RBool "autosync", [], [];
 333    tests = [
 334      InitNone, Always, TestOutputTrue (
 335        [["get_autosync"]])
 336    ];
 337    shortdesc = "get autosync mode";
 338    longdesc = "\
 339Get the autosync flag." };
 340
 341  { defaults with
 342    name = "set_verbose";
 343    style = RErr, [Bool "verbose"], [];
 344    fish_alias = ["verbose"];
 345    shortdesc = "set verbose mode";
 346    longdesc = "\
 347If C<verbose> is true, this turns on verbose messages.
 348
 349Verbose messages are disabled unless the environment variable
 350C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
 351
 352Verbose messages are normally sent to C<stderr>, unless you
 353register a callback to send them somewhere else (see
 354C<guestfs_set_event_callback>)." };
 355
 356  { defaults with
 357    name = "get_verbose";
 358    style = RBool "verbose", [], [];
 359    shortdesc = "get verbose mode";
 360    longdesc = "\
 361This returns the verbose messages flag." };
 362
 363  { defaults with
 364    name = "is_ready";
 365    style = RBool "ready", [], [];
 366    tests = [
 367      InitNone, Always, TestOutputTrue (
 368      [["is_ready"]])
 369    ];
 370    shortdesc = "is ready to accept commands";
 371    longdesc = "\
 372This returns true iff this handle is ready to accept commands
 373(in the C<READY> state).
 374
 375For more information on states, see L<guestfs(3)>." };
 376
 377  { defaults with
 378    name = "is_config";
 379    style = RBool "config", [], [];
 380    tests = [
 381      InitNone, Always, TestOutputFalse (
 382      [["is_config"]])
 383    ];
 384    shortdesc = "is in configuration state";
 385    longdesc = "\
 386This returns true iff this handle is being configured
 387(in the C<CONFIG> state).
 388
 389For more information on states, see L<guestfs(3)>." };
 390
 391  { defaults with
 392    name = "is_launching";
 393    style = RBool "launching", [], [];
 394    tests = [
 395      InitNone, Always, TestOutputFalse (
 396        [["is_launching"]])
 397    ];
 398    shortdesc = "is launching subprocess";
 399    longdesc = "\
 400This returns true iff this handle is launching the subprocess
 401(in the C<LAUNCHING> state).
 402
 403For more information on states, see L<guestfs(3)>." };
 404
 405  { defaults with
 406    name = "is_busy";
 407    style = RBool "busy", [], [];
 408    in_docs = false;
 409    tests = [
 410      InitNone, Always, TestOutputFalse (
 411        [["is_busy"]])
 412    ];
 413    shortdesc = "is busy processing a command";
 414    longdesc = "\
 415This always returns false.  Do not use this function.
 416
 417For more information on states, see L<guestfs(3)>." };
 418
 419  { defaults with
 420    name = "get_state";
 421    style = RInt "state", [], [];
 422    shortdesc = "get the current state";
 423    longdesc = "\
 424This returns the current state as an opaque integer.  This is
 425only useful for printing debug and internal error messages.
 426
 427For more information on states, see L<guestfs(3)>." };
 428
 429  { defaults with
 430    name = "set_memsize";
 431    style = RErr, [Int "memsize"], [];
 432    fish_alias = ["memsize"]; config_only = true;
 433    shortdesc = "set memory allocated to the qemu subprocess";
 434    longdesc = "\
 435This sets the memory size in megabytes allocated to the
 436qemu subprocess.  This only has any effect if called before
 437C<guestfs_launch>.
 438
 439You can also change this by setting the environment
 440variable C<LIBGUESTFS_MEMSIZE> before the handle is
 441created.
 442
 443For more information on the architecture of libguestfs,
 444see L<guestfs(3)>." };
 445
 446  { defaults with
 447    name = "get_memsize";
 448    style = RInt "memsize", [], [];
 449    tests = [
 450      InitNone, Always, TestOutputIntOp (
 451      [["get_memsize"]], ">=", 256)
 452    ];
 453    shortdesc = "get memory allocated to the qemu subprocess";
 454    longdesc = "\
 455This gets the memory size in megabytes allocated to the
 456qemu subprocess.
 457
 458If C<guestfs_set_memsize> was not called
 459on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
 460then this returns the compiled-in default value for memsize.
 461
 462For more information on the architecture of libguestfs,
 463see L<guestfs(3)>." };
 464
 465  { defaults with
 466    name = "get_pid";
 467    style = RInt "pid", [], [];
 468    fish_alias = ["pid"];
 469    tests = [
 470      InitNone, Always, TestOutputIntOp (
 471        [["get_pid"]], ">=", 1)
 472    ];
 473    shortdesc = "get PID of qemu subprocess";
 474    longdesc = "\
 475Return the process ID of the qemu subprocess.  If there is no
 476qemu subprocess, then this will return an error.
 477
 478This is an internal call used for debugging and testing." };
 479
 480  { defaults with
 481    name = "version";
 482    style = RStruct ("version", "version"), [], [];
 483    tests = [
 484      InitNone, Always, TestOutputStruct (
 485        [["version"]], [CompareWithInt ("major", 1)])
 486    ];
 487    shortdesc = "get the library version number";
 488    longdesc = "\
 489Return the libguestfs version number that the program is linked
 490against.
 491
 492Note that because of dynamic linking this is not necessarily
 493the version of libguestfs that you compiled against.  You can
 494compile the program, and then at runtime dynamically link
 495against a completely different C<libguestfs.so> library.
 496
 497This call was added in version C<1.0.58>.  In previous
 498versions of libguestfs there was no way to get the version
 499number.  From C code you can use dynamic linker functions
 500to find out if this symbol exists (if it doesn't, then
 501it's an earlier version).
 502
 503The call returns a structure with four elements.  The first
 504three (C<major>, C<minor> and C<release>) are numbers and
 505correspond to the usual version triplet.  The fourth element
 506(C<extra>) is a string and is normally empty, but may be
 507used for distro-specific information.
 508
 509To construct the original version string:
 510C<$major.$minor.$release$extra>
 511
 512See also: L<guestfs(3)/LIBGUESTFS VERSION NUMBERS>.
 513
 514I<Note:> Don't use this call to test for availability
 515of features.  In enterprise distributions we backport
 516features from later versions into earlier versions,
 517making this an unreliable way to test for features.
 518Use C<guestfs_available> instead." };
 519
 520  { defaults with
 521    name = "set_selinux";
 522    style = RErr, [Bool "selinux"], [];
 523    fish_alias = ["selinux"]; config_only = true;
 524    shortdesc = "set SELinux enabled or disabled at appliance boot";
 525    longdesc = "\
 526This sets the selinux flag that is passed to the appliance
 527at boot time.  The default is C<selinux=0> (disabled).
 528
 529Note that if SELinux is enabled, it is always in
 530Permissive mode (C<enforcing=0>).
 531
 532For more information on the architecture of libguestfs,
 533see L<guestfs(3)>." };
 534
 535  { defaults with
 536    name = "get_selinux";
 537    style = RBool "selinux", [], [];
 538    shortdesc = "get SELinux enabled flag";
 539    longdesc = "\
 540This returns the current setting of the selinux flag which
 541is passed to the appliance at boot time.  See C<guestfs_set_selinux>.
 542
 543For more information on the architecture of libguestfs,
 544see L<guestfs(3)>." };
 545
 546  { defaults with
 547    name = "set_trace";
 548    style = RErr, [Bool "trace"], [];
 549    fish_alias = ["trace"];
 550    tests = [
 551      InitNone, Always, TestOutputFalse (
 552        [["set_trace"; "false"];
 553         ["get_trace"]])
 554    ];
 555    shortdesc = "enable or disable command traces";
 556    longdesc = "\
 557If the command trace flag is set to 1, then libguestfs
 558calls, parameters and return values are traced.
 559
 560If you want to trace C API calls into libguestfs (and
 561other libraries) then possibly a better way is to use
 562the external ltrace(1) command.
 563
 564Command traces are disabled unless the environment variable
 565C<LIBGUESTFS_TRACE> is defined and set to C<1>.
 566
 567Trace messages are normally sent to C<stderr>, unless you
 568register a callback to send them somewhere else (see
 569C<guestfs_set_event_callback>)." };
 570
 571  { defaults with
 572    name = "get_trace";
 573    style = RBool "trace", [], [];
 574    shortdesc = "get command trace enabled flag";
 575    longdesc = "\
 576Return the command trace flag." };
 577
 578  { defaults with
 579    name = "set_direct";
 580    style = RErr, [Bool "direct"], [];
 581    fish_alias = ["direct"]; config_only = true;
 582    shortdesc = "enable or disable direct appliance mode";
 583    longdesc = "\
 584If the direct appliance mode flag is enabled, then stdin and
 585stdout are passed directly through to the appliance once it
 586is launched.
 587
 588One consequence of this is that log messages aren't caught
 589by the library and handled by C<guestfs_set_log_message_callback>,
 590but go straight to stdout.
 591
 592You probably don't want to use this unless you know what you
 593are doing.
 594
 595The default is disabled." };
 596
 597  { defaults with
 598    name = "get_direct";
 599    style = RBool "direct", [], [];
 600    shortdesc = "get direct appliance mode flag";
 601    longdesc = "\
 602Return the direct appliance mode flag." };
 603
 604  { defaults with
 605    name = "set_recovery_proc";
 606    style = RErr, [Bool "recoveryproc"], [];
 607    fish_alias = ["recovery-proc"]; config_only = true;
 608    shortdesc = "enable or disable the recovery process";
 609    longdesc = "\
 610If this is called with the parameter C<false> then
 611C<guestfs_launch> does not create a recovery process.  The
 612purpose of the recovery process is to stop runaway qemu
 613processes in the case where the main program aborts abruptly.
 614
 615This only has any effect if called before C<guestfs_launch>,
 616and the default is true.
 617
 618About the only time when you would want to disable this is
 619if the main process will fork itself into the background
 620(\"daemonize\" itself).  In this case the recovery process
 621thinks that the main program has disappeared and so kills
 622qemu, which is not very helpful." };
 623
 624  { defaults with
 625    name = "get_recovery_proc";
 626    style = RBool "recoveryproc", [], [];
 627    shortdesc = "get recovery process enabled flag";
 628    longdesc = "\
 629Return the recovery process enabled flag." };
 630
 631  { defaults with
 632    name = "add_drive_with_if";
 633    style = RErr, [String "filename"; String "iface"], [];
 634    deprecated_by = Some "add_drive"; config_only = true;
 635    shortdesc = "add a drive specifying the QEMU block emulation to use";
 636    longdesc = "\
 637This is the same as C<guestfs_add_drive> but it allows you
 638to specify the QEMU interface emulation to use at run time." };
 639
 640  { defaults with
 641    name = "add_drive_ro_with_if";
 642    style = RErr, [String "filename"; String "iface"], [];
 643    deprecated_by = Some "add_drive"; config_only = true;
 644    shortdesc = "add a drive read-only specifying the QEMU block emulation to use";
 645    longdesc = "\
 646This is the same as C<guestfs_add_drive_ro> but it allows you
 647to specify the QEMU interface emulation to use at run time." };
 648
 649  { defaults with
 650    name = "file_architecture";
 651    style = RString "arch", [Pathname "filename"], [];
 652    tests = [
 653      InitISOFS, Always, TestOutput (
 654        [["file_architecture"; "/bin-i586-dynamic"]], "i386");
 655      InitISOFS, Always, TestOutput (
 656        [["file_architecture"; "/bin-sparc-dynamic"]], "sparc");
 657      InitISOFS, Always, TestOutput (
 658        [["file_architecture"; "/bin-win32.exe"]], "i386");
 659      InitISOFS, Always, TestOutput (
 660        [["file_architecture"; "/bin-win64.exe"]], "x86_64");
 661      InitISOFS, Always, TestOutput (
 662        [["file_architecture"; "/bin-x86_64-dynamic"]], "x86_64");
 663      InitISOFS, Always, TestOutput (
 664        [["file_architecture"; "/lib-i586.so"]], "i386");
 665      InitISOFS, Always, TestOutput (
 666        [["file_architecture"; "/lib-sparc.so"]], "sparc");
 667      InitISOFS, Always, TestOutput (
 668        [["file_architecture"; "/lib-win32.dll"]], "i386");
 669      InitISOFS, Always, TestOutput (
 670        [["file_architecture"; "/lib-win64.dll"]], "x86_64");
 671      InitISOFS, Always, TestOutput (
 672        [["file_architecture"; "/lib-x86_64.so"]], "x86_64");
 673      InitISOFS, Always, TestOutput (
 674        [["file_architecture"; "/initrd-x86_64.img"]], "x86_64");
 675      InitISOFS, Always, TestOutput (
 676        [["file_architecture"; "/initrd-x86_64.img.gz"]], "x86_64");
 677    ];
 678    shortdesc = "detect the architecture of a binary file";
 679    longdesc = "\
 680This detects the architecture of the binary C<filename>,
 681and returns it if known.
 682
 683Currently defined architectures are:
 684
 685=over 4
 686
 687=item \"i386\"
 688
 689This string is returned for all 32 bit i386, i486, i586, i686 binaries
 690irrespective of the precise processor requirements of the binary.
 691
 692=item \"x86_64\"
 693
 69464 bit x86-64.
 695
 696=item \"sparc\"
 697
 69832 bit SPARC.
 699
 700=item \"sparc64\"
 701
 70264 bit SPARC V9 and above.
 703
 704=item \"ia64\"
 705
 706Intel Itanium.
 707
 708=item \"ppc\"
 709
 71032 bit Power PC.
 711
 712=item \"ppc64\"
 713
 71464 bit Power PC.
 715
 716=back
 717
 718Libguestfs may return other architecture strings in future.
 719
 720The function works on at least the following types of files:
 721
 722=over 4
 723
 724=item *
 725
 726many types of Un*x and Linux binary
 727
 728=item *
 729
 730many types of Un*x and Linux shared library
 731
 732=item *
 733
 734Windows Win32 and Win64 binaries
 735
 736=item *
 737
 738Windows Win32 and Win64 DLLs
 739
 740Win32 binaries and DLLs return C<i386>.
 741
 742Win64 binaries and DLLs return C<x86_64>.
 743
 744=item *
 745
 746Linux kernel modules
 747
 748=item *
 749
 750Linux new-style initrd images
 751
 752=item *
 753
 754some non-x86 Linux vmlinuz kernels
 755
 756=back
 757
 758What it can't do currently:
 759
 760=over 4
 761
 762=item *
 763
 764static libraries (libfoo.a)
 765
 766=item *
 767
 768Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
 769
 770=item *
 771
 772x86 Linux vmlinuz kernels
 773
 774x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32- and
 775compressed code, and are horribly hard to unpack.  If you want to find
 776the architecture of a kernel, use the architecture of the associated
 777initrd or kernel module(s) instead.
 778
 779=back" };
 780
 781  { defaults with
 782    name = "inspect_os";
 783    style = RStringList "roots", [], [];
 784    shortdesc = "inspect disk and return list of operating systems found";
 785    longdesc = "\
 786This function uses other libguestfs functions and certain
 787heuristics to inspect the disk(s) (usually disks belonging to
 788a virtual machine), looking for operating systems.
 789
 790The list returned is empty if no operating systems were found.
 791
 792If one operating system was found, then this returns a list with
 793a single element, which is the name of the root filesystem of
 794this operating system.  It is also possible for this function
 795to return a list containing more than one element, indicating
 796a dual-boot or multi-boot virtual machine, with each element being
 797the root filesystem of one of the operating systems.
 798
 799You can pass the root string(s) returned to other
 800C<guestfs_inspect_get_*> functions in order to query further
 801information about each operating system, such as the name
 802and version.
 803
 804This function uses other libguestfs features such as
 805C<guestfs_mount_ro> and C<guestfs_umount_all> in order to mount
 806and unmount filesystems and look at the contents.  This should
 807be called with no disks currently mounted.  The function may also
 808use Augeas, so any existing Augeas handle will be closed.
 809
 810This function cannot decrypt encrypted disks.  The caller
 811must do that first (supplying the necessary keys) if the
 812disk is encrypted.
 813
 814Please read L<guestfs(3)/INSPECTION> for more details.
 815
 816See also C<guestfs_list_filesystems>." };
 817
 818  { defaults with
 819    name = "inspect_get_type";
 820    style = RString "name", [Device "root"], [];
 821    shortdesc = "get type of inspected operating system";
 822    longdesc = "\
 823This returns the type of the inspected operating system.
 824Currently defined types are:
 825
 826=over 4
 827
 828=item \"linux\"
 829
 830Any Linux-based operating system.
 831
 832=item \"windows\"
 833
 834Any Microsoft Windows operating system.
 835
 836=item \"freebsd\"
 837
 838FreeBSD.
 839
 840=item \"netbsd\"
 841
 842NetBSD.
 843
 844=item \"hurd\"
 845
 846GNU/Hurd.
 847
 848=item \"dos\"
 849
 850MS-DOS, FreeDOS and others.
 851
 852=item \"unknown\"
 853
 854The operating system type could not be determined.
 855
 856=back
 857
 858Future versions of libguestfs may return other strings here.
 859The caller should be prepared to handle any string.
 860
 861Please read L<guestfs(3)/INSPECTION> for more details." };
 862
 863  { defaults with
 864    name = "inspect_get_arch";
 865    style = RString "arch", [Device "root"], [];
 866    shortdesc = "get architecture of inspected operating system";
 867    longdesc = "\
 868This returns the architecture of the inspected operating system.
 869The possible return values are listed under
 870C<guestfs_file_architecture>.
 871
 872If the architecture could not be determined, then the
 873string C<unknown> is returned.
 874
 875Please read L<guestfs(3)/INSPECTION> for more details." };
 876
 877  { defaults with
 878    name = "inspect_get_distro";
 879    style = RString "distro", [Device "root"], [];
 880    shortdesc = "get distro of inspected operating system";
 881    longdesc = "\
 882This returns the distro (distribution) of the inspected operating
 883system.
 884
 885Currently defined distros are:
 886
 887=over 4
 888
 889=item \"archlinux\"
 890
 891Arch Linux.
 892
 893=item \"buildroot\"
 894
 895Buildroot-derived distro, but not one we specifically recognize.
 896
 897=item \"centos\"
 898
 899CentOS.
 900
 901=item \"cirros\"
 902
 903Cirros.
 904
 905=item \"debian\"
 906
 907Debian.
 908
 909=item \"fedora\"
 910
 911Fedora.
 912
 913=item \"freedos\"
 914
 915FreeDOS.
 916
 917=item \"gentoo\"
 918
 919Gentoo.
 920
 921=item \"linuxmint\"
 922
 923Linux Mint.
 924
 925=item \"mageia\"
 926
 927Mageia.
 928
 929=item \"mandriva\"
 930
 931Mandriva.
 932
 933=item \"meego\"
 934
 935MeeGo.
 936
 937=item \"opensuse\"
 938
 939OpenSUSE.
 940
 941=item \"pardus\"
 942
 943Pardus.
 944
 945=item \"redhat-based\"
 946
 947Some Red Hat-derived distro.
 948
 949=item \"rhel\"
 950
 951Red Hat Enterprise Linux.
 952
 953=item \"scientificlinux\"
 954
 955Scientific Linux.
 956
 957=item \"slackware\"
 958
 959Slackware.
 960
 961=item \"ttylinux\"
 962
 963ttylinux.
 964
 965=item \"ubuntu\"
 966
 967Ubuntu.
 968
 969=item \"unknown\"
 970
 971The distro could not be determined.
 972
 973=item \"windows\"
 974
 975Windows does not have distributions.  This string is
 976returned if the OS type is Windows.
 977
 978=back
 979
 980Future versions of libguestfs may return other strings here.
 981The caller should be prepared to handle any string.
 982
 983Please read L<guestfs(3)/INSPECTION> for more details." };
 984
 985  { defaults with
 986    name = "inspect_get_major_version";
 987    style = RInt "major", [Device "root"], [];
 988    shortdesc = "get major version of inspected operating system";
 989    longdesc = "\
 990This returns the major version number of the inspected operating
 991system.
 992
 993Windows uses a consistent versioning scheme which is I<not>
 994reflected in the popular public names used by the operating system.
 995Notably the operating system known as \"Windows 7\" is really
 996version 6.1 (ie. major = 6, minor = 1).  You can find out the
 997real versions corresponding to releases of Windows by consulting
 998Wikipedia or MSDN.
 999
1000If the version could not be determined, then C<0> is returned.
1001
1002Please read L<guestfs(3)/INSPECTION> for more details." };
1003
1004  { defaults with
1005    name = "inspect_get_minor_version";
1006    style = RInt "minor", [Device "root"], [];
1007    shortdesc = "get minor version of inspected operating system";
1008    longdesc = "\
1009This returns the minor version number of the inspected operating
1010system.
1011
1012If the version could not be determined, then C<0> is returned.
1013
1014Please read L<guestfs(3)/INSPECTION> for more details.
1015See also C<guestfs_inspect_get_major_version>." };
1016
1017  { defaults with
1018    name = "inspect_get_product_name";
1019    style = RString "product", [Device "root"], [];
1020    shortdesc = "get product name of inspected operating system";
1021    longdesc = "\
1022This returns the product name of the inspected operating
1023system.  The product name is generally some freeform string
1024which can be displayed to the user, but should not be
1025parsed by programs.
1026
1027If the product name could not be determined, then the
1028string C<unknown> is returned.
1029
1030Please read L<guestfs(3)/INSPECTION> for more details." };
1031
1032  { defaults with
1033    name = "inspect_get_mountpoints";
1034    style = RHashtable "mountpoints", [Device "root"], [];
1035    shortdesc = "get mountpoints of inspected operating system";
1036    longdesc = "\
1037This returns a hash of where we think the filesystems
1038associated with this operating system should be mounted.
1039Callers should note that this is at best an educated guess
1040made by reading configuration files such as C</etc/fstab>.
1041I<In particular note> that this may return filesystems
1042which are non-existent or not mountable and callers should
1043be prepared to handle or ignore failures if they try to
1044mount them.
1045
1046Each element in the returned hashtable has a key which
1047is the path of the mountpoint (eg. C</boot>) and a value
1048which is the filesystem that would be mounted there
1049(eg. C</dev/sda1>).
1050
1051Non-mounted devices such as swap devices are I<not>
1052returned in this list.
1053
1054For operating systems like Windows which still use drive
1055letters, this call will only return an entry for the first
1056drive \"mounted on\" C</>.  For information about the
1057mapping of drive letters to partitions, see
1058C<guestfs_inspect_get_drive_mappings>.
1059
1060Please read L<guestfs(3)/INSPECTION> for more details.
1061See also C<guestfs_inspect_get_filesystems>." };
1062
1063  { defaults with
1064    name = "inspect_get_filesystems";
1065    style = RStringList "filesystems", [Device "root"], [];
1066    shortdesc = "get filesystems associated with inspected operating system";
1067    longdesc = "\
1068This returns a list of all the filesystems that we think
1069are associated with this operating system.  This includes
1070the root filesystem, other ordinary filesystems, and
1071non-mounted devices like swap partitions.
1072
1073In the case of a multi-boot virtual machine, it is possible
1074for a filesystem to be shared between operating systems.
1075
1076Please read L<guestfs(3)/INSPECTION> for more details.
1077See also C<guestfs_inspect_get_mountpoints>." };
1078
1079  { defaults with
1080    name = "set_network";
1081    style = RErr, [Bool "network"], [];
1082    fish_alias = ["network"]; config_only = true;
1083    shortdesc = "set enable network flag";
1084    longdesc = "\
1085If C<network> is true, then the network is enabled in the
1086libguestfs appliance.  The default is false.
1087
1088This affects whether commands are able to access the network
1089(see L<guestfs(3)/RUNNING COMMANDS>).
1090
1091You must call this before calling C<guestfs_launch>, otherwise
1092it has no effect." };
1093
1094  { defaults with
1095    name = "get_network";
1096    style = RBool "network", [], [];
1097    shortdesc = "get enable network flag";
1098    longdesc = "\
1099This returns the enable network flag." };
1100
1101  { defaults with
1102    name = "list_filesystems";
1103    style = RHashtable "fses", [], [];
1104    shortdesc = "list filesystems";
1105    longdesc = "\
1106This inspection command looks for filesystems on partitions,
1107block devices and logical volumes, returning a list of devices
1108containing filesystems and their type.
1109
1110The return value is a hash, where the keys are the devices
1111containing filesystems, and the values are the filesystem types.
1112For example:
1113
1114 \"/dev/sda1\" => \"ntfs\"
1115 \"/dev/sda2\" => \"ext2\"
1116 \"/dev/vg_guest/lv_root\" => \"ext4\"
1117 \"/dev/vg_guest/lv_swap\" => \"swap\"
1118
1119The value can have the special value \"unknown\", meaning the
1120content of the device is undetermined or empty.
1121\"swap\" means a Linux swap partition.
1122
1123This command runs other libguestfs commands, which might include
1124C<guestfs_mount> and C<guestfs_umount>, and therefore you should
1125use this soon after launch and only when nothing is mounted.
1126
1127Not all of the filesystems returned will be mountable.  In
1128particular, swap partitions are returned in the list.  Also
1129this command does not check that each filesystem
1130found is valid and mountable, and some filesystems might
1131be mountable but require special options.  Filesystems may
1132not all belong to a single logical operating system
1133(use C<guestfs_inspect_os> to look for OSes)." };
1134
1135  { defaults with
1136    name = "add_drive";
1137    style = RErr, [String "filename"], [OBool "readonly"; OString "format"; OString "iface"; OString "name"];
1138    once_had_no_optargs = true;
1139    fish_alias = ["add"]; config_only = true;
1140    shortdesc = "add an image to examine or modify";
1141    longdesc = "\
1142This function adds a virtual machine disk image C<filename> to
1143libguestfs.  The first time you call this function, the disk
1144appears as C</dev/sda>, the second time as C</dev/sdb>, and
1145so on.
1146
1147You don't necessarily need to be root when using libguestfs.  However
1148you obviously do need sufficient permissions to access the filename
1149for whatever operations you want to perform (ie. read access if you
1150just want to read the image or write access if you want to modify the
1151image).
1152
1153This call checks that C<filename> exists.
1154
1155The optional arguments are:
1156
1157=over 4
1158
1159=item C<readonly>
1160
1161If true then the image is treated as read-only.  Writes are still
1162allowed, but they are stored in a temporary snapshot overlay which
1163is discarded at the end.  The disk that you add is not modified.
1164
1165=item C<format>
1166
1167This forces the image format.  If you omit this (or use C<guestfs_add_drive>
1168or C<guestfs_add_drive_ro>) then the format is automatically detected.
1169Possible formats include C<raw> and C<qcow2>.
1170
1171Automatic detection of the format opens you up to a potential
1172security hole when dealing with untrusted raw-format images.
1173See CVE-2010-3851 and RHBZ#642934.  Specifying the format closes
1174this security hole.
1175
1176=item C<iface>
1177
1178This rarely-used option lets you emulate the behaviour of the
1179deprecated C<guestfs_add_drive_with_if> call (q.v.)
1180
1181=item C<name>
1182
1183The name the drive had in the original guest, e.g. /dev/sdb. This is used as a
1184hint to the guest inspection process if it is available.
1185
1186=back
1187
1188C<filename> can have the special value C</dev/null>, which means
1189to add a null (zero length) raw format device.  You can add C</dev/null>
1190multiple times." };
1191
1192  { defaults with
1193    name = "inspect_get_windows_systemroot";
1194    style = RString "systemroot", [Device "root"], [];
1195    shortdesc = "get Windows systemroot of inspected operating system";
1196    longdesc = "\
1197This returns the Windows systemroot of the inspected guest.
1198The systemroot is a directory path such as C</WINDOWS>.
1199
1200This call assumes that the guest is Windows and that the
1201systemroot could be determined by inspection.  If this is not
1202the case then an error is returned.
1203
1204Please read L<guestfs(3)/INSPECTION> for more details." };
1205
1206  { defaults with
1207    name = "inspect_get_roots";
1208    style = RStringList "roots", [], [];
1209    shortdesc = "return list of operating systems found by last inspection";
1210    longdesc = "\
1211This function is a convenient way to get the list of root
1212devices, as returned from a previous call to C<guestfs_inspect_os>,
1213but without redoing the whole inspection process.
1214
1215This returns an empty list if either no root devices were
1216found or the caller has not called C<guestfs_inspect_os>.
1217
1218Please read L<guestfs(3)/INSPECTION> for more details." };
1219
1220  { defaults with
1221    name = "debug_cmdline";
1222    style = RStringList "cmdline", [], [];
1223    in_docs = false;
1224    shortdesc = "debug the QEMU command line (internal use only)";
1225    longdesc = "\
1226This returns the internal QEMU command line.  'debug' commands are
1227not part of the formal API and can be removed or changed at any time." };
1228
1229  { defaults with
1230    name = "debug_drives";
1231    style = RStringList "cmdline", [], [];
1232    in_docs = false;
1233    shortdesc = "debug the drives (internal use only)";
1234    longdesc = "\
1235This returns the internal list of drives.  'debug' commands are
1236not part of the formal API and can be removed or changed at any time." };
1237
1238  { defaults with
1239    name = "add_domain";
1240    style = RInt "nrdisks", [String "dom"], [OString "libvirturi"; OBool "readonly"; OString "iface"; OBool "live"; OBool "allowuuid"; OString "readonlydisk"];
1241    fish_alias = ["domain"]; config_only = true;
1242    shortdesc = "add the disk(s) from a named libvirt domain";
1243    longdesc = "\
1244This function adds the disk(s) attached to the named libvirt
1245domain C<dom>.  It works by connecting to libvirt, requesting
1246the domain and domain XML from libvirt, parsing it for disks,
1247and calling C<guestfs_add_drive_opts> on each one.
1248
1249The number of disks added is returned.  This operation is atomic:
1250if an error is returned, then no disks are added.
1251
1252This function does some minimal checks to make sure the libvirt
1253domain is not running (unless C<readonly> is true).  In a future
1254version we will try to acquire the libvirt lock on each disk.
1255
1256Disks must be accessible locally.  This often means that adding disks
1257from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
1258will fail unless those disks are accessible via the same device path
1259locally too.
1260
1261The optional C<libvirturi> parameter sets the libvirt URI
1262(see L<http://libvirt.org/uri.html>).  If this is not set then
1263we connect to the default libvirt URI (or one set through an
1264environment variable, see the libvirt documentation for full
1265details).
1266
1267The optional C<live> flag controls whether this call will try
1268to connect to a running virtual machine C<guestfsd> process if
1269it sees a suitable E<lt>channelE<gt> element in the libvirt
1270XML definition.  The default (if the flag is omitted) is never
1271to try.  See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
1272information.
1273
1274If the C<allowuuid> flag is true (default is false) then a UUID
1275I<may> be passed instead of the domain name.  The C<dom> string is
1276treated as a UUID first and looked up, and if that lookup fails
1277then we treat C<dom> as a name as usual.
1278
1279The optional C<readonlydisk> parameter controls what we do for
1280disks which are marked E<lt>readonly/E<gt> in the libvirt XML.
1281Possible values are:
1282
1283=over 4
1284
1285=item readonlydisk = \"error\"
1286
1287If C<readonly> is false:
1288
1289The whole call is aborted with an error if any disk with
1290the E<lt>readonly/E<gt> flag is found.
1291
1292If C<readonly> is true:
1293
1294Disks with the E<lt>readonly/E<gt> flag are added read-only.
1295
1296=item readonlydisk = \"read\"
1297
1298If C<readonly> is false:
1299
1300Disks with the E<lt>readonly/E<gt> flag are added read-only.
1301Other disks are added read/write.
1302
1303If C<readonly> is true:
1304
1305Disks with the E<lt>readonly/E<gt> flag are added read-only.
1306
1307=item readonlydisk = \"write\" (default)
1308
1309If C<readonly> is false:
1310
1311Disks with the E<lt>readonly/E<gt> flag are added read/write.
1312
1313If C<readonly> is true:
1314
1315Disks with the E<lt>readonly/E<gt> flag are added read-only.
1316
1317=item readonlydisk = \"ignore\"
1318
1319If C<readonly> is true or false:
1320
1321Disks with the E<lt>readonly/E<gt> flag are skipped.
1322
1323=back
1324
1325The other optional parameters are passed directly through to
1326C<guestfs_add_drive_opts>." };
1327
1328(*
1329This interface is not quite baked yet. -- RWMJ 2010-11-11
1330  { defaults with
1331    name = "add_libvirt_dom";
1332    style = RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"; Bool "live"; String "readonlydisk"];
1333    in_fish = false;
1334    shortdesc = "add the disk(s) from a libvirt domain";
1335    longdesc = "\
1336This function adds the disk(s) attached to the libvirt domain C<dom>.
1337It works by requesting the domain XML from libvirt, parsing it for
1338disks, and calling C<guestfs_add_drive_opts> on each one.
1339
1340In the C API we declare C<void *dom>, but really it has type
1341C<virDomainPtr dom>.  This is so we don't need E<lt>libvirt.hE<gt>.
1342
1343The number of disks added is returned.  This operation is atomic:
1344if an error is returned, then no disks are added.
1345
1346This function does some minimal checks to make sure the libvirt
1347domain is not running (unless C<readonly> is true).  In a future
1348version we will try to acquire the libvirt lock on each disk.
1349
1350Disks must be accessible locally.  This often means that adding disks
1351from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
1352will fail unless those disks are accessible via the same device path
1353locally too.
1354
1355The optional C<live> flag controls whether this call will try
1356to connect to a running virtual machine C<guestfsd> process if
1357it sees a suitable E<lt>channelE<gt> element in the libvirt
1358XML definition.  The default (if the flag is omitted) is never
1359to try.  See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
1360information.
1361
1362The optional C<readonlydisk> parameter controls what we do for
1363disks which are marked E<lt>readonly/E<gt> in the libvirt XML.
1364See C<guestfs_add_domain> for possible values.
1365
1366The other optional parameters are passed directly through to
1367C<guestfs_add_drive_opts>." };
1368*)
1369
1370  { defaults with
1371    name = "inspect_get_package_format";
1372    style = RString "packageformat", [Device "root"], [];
1373    shortdesc = "get package format used by the operating system";
1374    longdesc = "\
1375This function and C<guestfs_inspect_get_package_management> return
1376the package format and package management tool used by the
1377inspected operating system.  For example for Fedora these
1378functions would return C<rpm> (package format) and
1379C<yum> (package management).
1380
1381This returns the string C<unknown> if we could not determine the
1382package format I<or> if the operating system does not have
1383a real packaging system (eg. Windows).
1384
1385Possible strings include:
1386C<rpm>, C<deb>, C<ebuild>, C<pisi>, C<pacman>, C<pkgsrc>.
1387Future versions of libguestfs may return other strings.
1388
1389Please read L<guestfs(3)/INSPECTION> for more details." };
1390
1391  { defaults with
1392    name = "inspect_get_package_management";
1393    style = RString "packagemanagement", [Device "root"], [];
1394    shortdesc = "get package management tool used by the operating system";
1395    longdesc = "\
1396C<guestfs_inspect_get_package_format> and this function return
1397the package format and package management tool used by the
1398inspected operating system.  For example for Fedora these
1399functions would return C<rpm> (package format) and
1400C<yum> (package management).
1401
1402This returns the string C<unknown> if we could not determine the
1403package management tool I<or> if the operating system does not have
1404a real packaging system (eg. Windows).
1405
1406Possible strings include: C<yum>, C<up2date>,
1407C<apt> (for all Debian derivatives),
1408C<portage>, C<pisi>, C<pacman>, C<urpmi>, C<zypper>.
1409Future versions of libguestfs may return other strings.
1410
1411Please read L<guestfs(3)/INSPECTION> for more details." };
1412
1413  { defaults with
1414    name = "inspect_list_applications";
1415    style = RStructList ("applications", "application"), [Device "root"], [];
1416    shortdesc = "get list of applications installed in the operating system";
1417    longdesc = "\
1418Return the list of applications installed in the operating system.
1419
1420I<Note:> This call works differently from other parts of the
1421inspection API.  You have to call C<guestfs_inspect_os>, then
1422C<guestfs_inspect_get_mountpoints>, then mount up the disks,
1423before calling this.  Listing applications is a significantly
1424more difficult operation which requires access to the full
1425filesystem.  Also note that unlike the other
1426C<guestfs_inspect_get_*> calls which are just returning
1427data cached in the libguestfs handle, this call actually reads
1428parts of the mounted filesystems during the call.
1429
1430This returns an empty list if the inspection code was not able
1431to determine the list of applications.
1432
1433The application structure contains the following fields:
1434
1435=over 4
1436
1437=item C<app_name>
1438
1439The name of the application.  For Red Hat-derived and Debian-derived
1440Linux guests, this is the package name.
1441
1442=item C<app_display_name>
1443
1444The display name of the application, sometimes localized to the
1445install language of the guest operating system.
1446
1447If unavailable this is returned as an empty string C<\"\">.
1448Callers needing to display something can use C<app_name> instead.
1449
1450=item C<app_epoch>
1451
1452For package managers which use epochs, this contains the epoch of
1453the package (an integer).  If unavailable, this is returned as C<0>.
1454
1455=item C<app_version>
1456
1457The version string of the application or package.  If unavailable
1458this is returned as an empty string C<\"\">.
1459
1460=item C<app_release>
1461
1462The release string of the application or package, for package
1463managers that use this.  If unavailable this is returned as an
1464empty string C<\"\">.
1465
1466=item C<app_install_path>
1467
1468The installation path of the application (on operating systems
1469such as Windows which use installation paths).  This path is
1470in the format used by the guest operating system, it is not
1471a libguestfs path.
1472
1473If unavailable this is returned as an empty string C<\"\">.
1474
1475=item C<app_trans_path>
1476
1477The install path translated into a libguestfs path.
1478If unavailable this is returned as an empty string C<\"\">.
1479
1480=item C<app_publisher>
1481
1482The name of the publisher of the application, for package
1483managers that use this.  If unavailable this is returned
1484as an empty string C<\"\">.
1485
1486=item C<app_url>
1487
1488The URL (eg. upstream URL) of the application.
1489If unavailable this is returned as an empty string C<\"\">.
1490
1491=item C<app_source_package>
1492
1493For packaging systems which support this, the name of the source
1494package.  If unavailable this is returned as an empty string C<\"\">.
1495
1496=item C<app_summary>
1497
1498A short (usually one line) description of the application or package.
1499If unavailable this is returned as an empty string C<\"\">.
1500
1501=item C<app_description>
1502
1503A longer description of the application or package.
1504If unavailable this is returned as an empty string C<\"\">.
1505
1506=back
1507
1508Please read L<guestfs(3)/INSPECTION> for more details." };
1509
1510  { defaults with
1511    name = "inspect_get_hostname";
1512    style = RString "hostname", [Device "root"], [];
1513    shortdesc = "get hostname of the operating system";
1514    longdesc = "\
1515This function returns the hostname of the operating system
1516as found by inspection of the guest's configuration files.
1517
1518If the hostname could not be determined, then the
1519string C<unknown> is returned.
1520
1521Please read L<guestfs(3)/INSPECTION> for more details." };
1522
1523  { defaults with
1524    name = "inspect_get_format";
1525    style = RString "format", [Device "root"], [];
1526    shortdesc = "get format of inspected operating system";
1527    longdesc = "\
1528This returns the format of the inspected operating system.  You
1529can use it to detect install images, live CDs and similar.
1530
1531Currently defined formats are:
1532
1533=over 4
1534
1535=item \"installed\"
1536
1537This is an installed operating system.
1538
1539=item \"installer\"
1540
1541The disk image being inspected is not an installed operating system,
1542but a I<bootable> install disk, live CD, or similar.
1543
1544=item \"unknown\"
1545
1546The format of this disk image is not known.
1547
1548=back
1549
1550Future versions of libguestfs may return other strings here.
1551The caller should be prepared to handle any string.
1552
1553Please read L<guestfs(3)/INSPECTION> for more details." };
1554
1555  { defaults with
1556    name = "inspect_is_live";
1557    style = RBool "live", [Device "root"], [];
1558    shortdesc = "get live flag for install disk";
1559    longdesc = "\
1560If C<guestfs_inspect_get_format> returns C<installer> (this
1561is an install disk), then this returns true if a live image
1562was detected on the disk.
1563
1564Please read L<guestfs(3)/INSPECTION> for more details." };
1565
1566  { defaults with
1567    name = "inspect_is_netinst";
1568    style = RBool "netinst", [Device "root"], [];
1569    shortdesc = "get netinst (network installer) flag for install disk";
1570    longdesc = "\
1571If C<guestfs_inspect_get_format> returns C<installer> (this
1572is an install disk), then this returns true if the disk is
1573a network installer, ie. not a self-contained install CD but
1574one which is likely to require network access to complete
1575the install.
1576
1577Please read L<guestfs(3)/INSPECTION> for more details." };
1578
1579  { defaults with
1580    name = "inspect_is_multipart";
1581    style = RBool "multipart", [Device "root"], [];
1582    shortdesc = "get multipart flag for install disk";
1583    longdesc = "\
1584If C<guestfs_inspect_get_format> returns C<installer> (this
1585is an install disk), then this returns true if the disk is
1586part of a set.
1587
1588Please read L<guestfs(3)/INSPECTION> for more details." };
1589
1590  { defaults with
1591    name = "set_attach_method";
1592    style = RErr, [String "attachmethod"], [];
1593    fish_alias = ["attach-method"]; config_only = true;
1594    shortdesc = "set the attach method";
1595    longdesc = "\
1596Set the method that libguestfs uses to connect to the back end
1597guestfsd daemon.  Possible methods are:
1598
1599=over 4
1600
1601=item C<appliance>
1602
1603Launch an appliance and connect to it.  This is the ordinary method
1604and the default.
1605
1606=item C<unix:I<path>>
1607
1608Connect to the Unix domain socket I<path>.
1609
1610This method lets you connect to an existing daemon or (using
1611virtio-serial) to a live guest.  For more information, see
1612L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>.
1613
1614=back" };
1615
1616  { defaults with
1617    name = "get_attach_method";
1618    style = RString "attachmethod", [], [];
1619    tests = [
1620      InitNone, Always, TestOutput (
1621        [["get_attach_method"]], "appliance")
1622    ];
1623    shortdesc = "get the attach method";
1624    longdesc = "\
1625Return the current attach method.  See C<guestfs_set_attach_method>." };
1626
1627  { defaults with
1628    name = "inspect_get_product_variant";
1629    style = RString "variant", [Device "root"], [];
1630    shortdesc = "get product variant of inspected operating system";
1631    longdesc = "\
1632This returns the product variant of the inspected operating
1633system.
1634
1635For Windows guests, this returns the contents of the Registry key
1636C<HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion>
1637C<InstallationType> which is usually a string such as
1638C<Client> or C<Server> (other values are possible).  This
1639can be used to distinguish consumer and enterprise versions
1640of Windows that have the same version number (for example,
1641Windows 7 and Windows 2008 Server are both version 6.1,
1642but the former is C<Client> and the latter is C<Server>).
1643
1644For enterprise Linux guests, in future we intend this to return
1645the product variant such as C<Desktop>, C<Server> and so on.  But
1646this is not implemented at present.
1647
1648If the product variant could not be determined, then the
1649string C<unknown> is returned.
1650
1651Please read L<guestfs(3)/INSPECTION> for more details.
1652See also C<guestfs_inspect_get_product_name>,
1653C<guestfs_inspect_get_major_version>." };
1654
1655  { defaults with
1656    name = "inspect_get_windows_current_control_set";
1657    style = RString "controlset", [Device "root"], [];
1658    shortdesc = "get Windows CurrentControlSet of inspected operating system";
1659    longdesc = "\
1660This returns the Windows CurrentControlSet of the inspected guest.
1661The CurrentControlSet is a registry key name such as C<ControlSet001>.
1662
1663This call assumes that the guest is Windows and that the
1664Registry could be examined by inspection.  If this is not
1665the case then an error is returned.
1666
1667Please read L<guestfs(3)/INSPECTION> for more details." };
1668
1669  { defaults with
1670    name = "inspect_get_drive_mappings";
1671    style = RHashtable "drives", [Device "root"], [];
1672    shortdesc = "get drive letter mappings";
1673    longdesc = "\
1674This call is useful for Windows which uses a primitive system
1675of assigning drive letters (like \"C:\") to partitions.
1676This inspection API examines the Windows Registry to find out
1677how disks/partitions are mapped to drive letters, and returns
1678a hash table as in the example below:
1679
1680 C      =>     /dev/vda2
1681 E      =>     /dev/vdb1
1682 F      =>     /dev/vdc1
1683
1684Note that keys are drive letters.  For Windows, the key is
1685case insensitive and just contains the drive letter, without
1686the customary colon separator character.
1687
1688In future we may support other operating systems that also used drive
1689letters, but the keys for those might not be case insensitive
1690and might be longer than 1 character.  For example in OS-9,
1691hard drives were named C<h0>, C<h1> etc.
1692
1693For Windows guests, currently only hard drive mappings are
1694returned.  Removable disks (eg. DVD-ROMs) are ignored.
1695
1696For guests that do not use drive mappings, or if the drive mappings
1697could not be determined, this returns an empty hash table.
1698
1699Please read L<guestfs(3)/INSPECTION> for more details.
1700See also C<guestfs_inspect_get_mountpoints>,
1701C<guestfs_inspect_get_filesystems>." };
1702
1703  { defaults with
1704    name = "inspect_get_icon";
1705    style = RBufferOut "icon", [Device "root"],  [OBool "favicon"; OBool "highquality"];
1706    shortdesc = "get the icon corresponding to this operating system";
1707    longdesc = "\
1708This function returns an icon corresponding to the inspected
1709operating system.  The icon is returned as a buffer containing a
1710PNG image (re-encoded to PNG if necessary).
1711
1712If it was not possible to get an icon this function returns a
1713zero-length (non-NULL) buffer.  I<Callers must check for this case>.
1714
1715Libguestfs will start by looking for a file called
1716C</etc/favicon.png> or C<C:\\etc\\favicon.png>
1717and if it has the correct format, the contents of this file will
1718be returned.  You can disable favicons by passing the
1719optional C<favicon> boolean as false (default is true).
1720
1721If finding the favicon fails, then we look in other places in the
1722guest for a suitable icon.
1723
1724If the optional C<highquality> boolean is true then
1725only high quality icons are returned, which means only icons of
1726high resolution with an alpha channel.  The default (false) is
1727to return any icon we can, even if it is of substandard quality.
1728
1729Notes:
1730
1731=over 4
1732
1733=item *
1734
1735Unlike most other inspection API calls, the guest's disks must be
1736mounted up before you call this, since it needs to read information
1737from the guest filesystem during the call.
1738
1739=item *
1740
1741B<Security:> The icon data comes from the untrusted guest,
1742and should be treated with caution.  PNG files have been
1743known to contain exploits.  Ensure that libpng (or other relevant
1744libraries) are fully up to date before trying to process or
1745display the icon.
1746
1747=item *
1748
1749The PNG image returned can be any size.  It might not be square.
1750Libguestfs tries to return the largest, highest quality
1751icon available.  The application must scale the icon to the
1752required size.
1753
1754=item *
1755
1756Extracting icons from Windows guests requires the external
1757C<wrestool> program from the C<icoutils> package, and
1758several programs (C<bmptopnm>, C<pnmtopng>, C<pamcut>)
1759from the C<netpbm> package.  These must be installed separately.
1760
1761=item *
1762
1763Operating system icons are usually trademarks.  Seek legal
1764advice before using trademarks in applications.
1765
1766=back" };
1767
1768  { defaults with
1769    name = "set_pgroup";
1770    style = RErr, [Bool "pgroup"], [];
1771    fish_alias = ["pgroup"]; config_only = true;
1772    shortdesc = "set process group flag";
1773    longdesc = "\
1774If C<pgroup> is true, child processes are placed into
1775their own process group.
1776
1777The practical upshot of this is that signals like C<SIGINT> (from
1778users pressing C<^C>) won't be received by the child process.
1779
1780The default for this flag is false, because usually you want
1781C<^C> to kill the subprocess.  Guestfish sets this flag to
1782true when used interactively, so that C<^C> can cancel
1783long-running commands gracefully (see C<guestfs_user_cancel>)." };
1784
1785  { defaults with
1786    name = "get_pgroup";
1787    style = RBool "pgroup", [], [];
1788    shortdesc = "get process group flag";
1789    longdesc = "\
1790This returns the process group flag." };
1791
1792  { defaults with
1793    name = "set_smp";
1794    style = RErr, [Int "smp"], [];
1795    fish_alias = ["smp"]; config_only = true;
1796    shortdesc = "set number of virtual CPUs in appliance";
1797    longdesc = "\
1798Change the number of virtual CPUs assigned to the appliance.  The
1799default is C<1>.  Increasing this may improve performance, though
1800often it has no effect.
1801
1802This function must be called before C<guestfs_launch>." };
1803
1804  { defaults with
1805    name = "get_smp";
1806    style = RInt "smp", [], [];
1807    shortdesc = "get number of virtual CPUs in appliance";
1808    longdesc = "\
1809This returns the number of virtual CPUs assigned to the appliance." };
1810
1811  { defaults with
1812    name = "mount_local";
1813    style = RErr, [String "localmountpoint"], [OBool "readonly"; OString "options"; OInt "cachetimeout"; OBool "debugcalls"];
1814    shortdesc = "mount on the local filesystem";
1815    longdesc = "\
1816This call exports the libguestfs-accessible filesystem to
1817a local mountpoint (directory) called C<localmountpoint>.
1818Ordinary reads and writes to files and directories under
1819C<localmountpoint> are redirected through libguestfs.
1820
1821If the optional C<readonly> flag is set to true, then
1822writes to the filesystem return error C<EROFS>.
1823
1824C<options> is a comma-separated list of mount options.
1825See L<guestmount(1)> for some useful options.
1826
1827C<cachetimeout> sets the timeout (in seconds) for cached directory
1828entries.  The default is 60 seconds.  See L<guestmount(1)>
1829for further information.
1830
1831If C<debugcalls> is set to true, then additional debugging
1832information is generated for every FUSE call.
1833
1834When C<guestfs_mount_local> returns, the filesystem is ready,
1835but is not processing requests (access to it will block).  You
1836have to call C<guestfs_mount_local_run> to run the main loop.
1837
1838See L<guestfs(3)/MOUNT LOCAL> for full documentation." };
1839
1840  { defaults with
1841    name = "mount_local_run";
1842    style = RErr, [], [];
1843    cancellable = true (* in a future version *);
1844    shortdesc = "run main loop of mount on the local filesystem";
1845    longdesc = "\
1846Run the main loop which translates kernel calls to libguestfs
1847calls.
1848
1849This should only be called after C<guestfs_mount_local>
1850returns successfully.  The call will not return until the
1851filesystem is unmounted.
1852
1853B<Note> you must I<not> make concurrent libguestfs calls
1854on the same handle from another thread,
1855with the exception of C<guestfs_umount_local>.
1856
1857You may call this from a different thread than the one which
1858called C<guestfs_mount_local>, subject to the usual rules
1859for threads and libguestfs (see
1860L<guestfs(3)/MULTIPLE HANDLES AND MULTIPLE THREADS>).
1861
1862See L<guestfs(3)/MOUNT LOCAL> for full documentation." };
1863
1864  { defaults with
1865    name = "umount_local";
1866    style = RErr, [], [OBool "retry"];
1867    tests = [] (* tests in fuse subdirectory *);
1868    shortdesc = "unmount a locally mounted filesystem";
1869    longdesc = "\
1870If libguestfs is exporting the filesystem on a local
1871mountpoint, then this unmounts it.
1872
1873See L<guestfs(3)/MOUNT LOCAL> for full documentation." };
1874
1875  { defaults with
1876    name = "max_disks";
1877    style = RInt "disks", [], [];
1878    shortdesc = "maximum number of disks that may be added";
1879    longdesc = "\
1880Return the maximum number of disks that may be added to a
1881handle (eg. by C<guestfs_add_drive_opts> and similar calls).
1882
1883This function was added in libguestfs 1.19.7.  In previous
1884versions of libguestfs the limit was 25.
1885
1886See L<guestfs(3)/MAXIMUM NUMBER OF DISKS> for additional
1887information on this topic." };
1888
1889  { defaults with
1890    name = "canonical_device_name";
1891    style = RString "canonical", [String "device"], [];
1892    shortdesc = "return canonical device name";
1893    longdesc = "\
1894This utility function is useful when displaying device names to
1895the user.  It takes a number of irregular device names and
1896returns them in a consistent format:
1897
1898=over 4
1899
1900=item C</dev/hdX>
1901
1902=item C</dev/vdX>
1903
1904These are returned as C</dev/sdX>.  Note this works for device
1905names and partition names.  This is approximately the reverse of
1906the algorithm described in L<guestfs(3)/BLOCK DEVICE NAMING>.
1907
1908=item C</dev/mapper/VG-LV>
1909
1910=item C</dev/dm-N>
1911
1912Converted to C</dev/VG/LV> form using C<guestfs_lvm_canonical_lvm_name>.
1913
1914=back
1915
1916Other strings are returned unmodified." };
1917
1918  { defaults with
1919    name = "shutdown";
1920    style = RErr, [], [];
1921    shortdesc = "shutdown the qemu subprocess";
1922    longdesc = "\
1923This is the opposite of C<guestfs_launch>.  It performs an orderly
1924shutdown of the backend process(es).  If the autosync flag is set
1925(which is the default) then the disk image is synchronized.
1926
1927If the subprocess exits with an error then this function will return
1928an error, which should I<not> be ignored (it may indicate that the
1929disk image could not be written out properly).
1930
1931It is safe to call this multiple times.  Extra calls are ignored.
1932
1933This call does I<not> close or free up the handle.  You still
1934need to call C<guestfs_close> afterwards.
1935
1936C<guestfs_close> will call this if you don't do it explicitly,
1937but note that any errors are ignored in that case." };
1938
1939]
1940
1941(* daemon_functions are any functions which cause some action
1942 * to take place in the daemon.
1943 *)
1944
1945let daemon_functions = [
1946  { defaults with
1947    name = "mount";
1948    style = RErr, [Device "device"; String "mountpoint"], [];
1949    proc_nr = Some 1;
1950    tests = [
1951      InitEmpty, Always, TestOutput (
1952        [["part_disk"; "/dev/sda"; "mbr"];
1953         ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""];
1954         ["mount"; "/dev/sda1"; "/"];
1955         ["write"; "/new"; "new file contents"];
1956         ["cat"; "/new"]], "new file contents")
1957    ];
1958    shortdesc = "mount a guest disk at a position in the filesystem";
1959    longdesc = "\
1960Mount a guest disk at a position in the filesystem.  Block devices
1961are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1962the guest.  If those block devices contain partitions, they will have
1963the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
1964names can be used.
1965
1966The rules are the same as for L<mount(2)>:  A filesystem must
1967first be mounted on C</> before others can be mounted.  Other
1968filesystems can only be mounted on directories which already
1969exist.
1970
1971The mounted filesystem is writable, if we have sufficient permissions
1972on the underlying device.
1973
1974Before libguestfs 1.13.16, this call implicitly added the options
1975C<sync> and C<noatime>.  The C<sync> option greatly slowed
1976writes and caused many problems for users.  If your program
1977might need to work with older versions of libguestfs, use
1978C<guestfs_mount_options> instead (using an empty string for the
1979first parameter if you don't want any options)." };
1980
1981  { defaults with
1982    name = "sync";
1983    style = RErr, [], [];
1984    proc_nr = Some 2;
1985    tests = [
1986      InitEmpty, Always, TestRun [["sync"]]
1987    ];
1988    shortdesc = "sync disks, writes are flushed through to the disk image";
1989    longdesc = "\
1990This syncs the disk, so that any writes are flushed through to the
1991underlying disk image.
1992
1993You should always call this if you have modified a disk image, before
1994closing the handle." };
1995
1996  { defaults with
1997    name = "touch";
1998    style = RErr, [Pathname "path"], [];
1999    proc_nr = Some 3;
2000    tests = [
2001      InitScratchFS, Always, TestOutputTrue (
2002        [["touch"; "/touch"];
2003         ["exists"; "/touch"]])
2004    ];
2005    shortdesc = "update file timestamps or create a new file";
2006    longdesc = "\
2007Touch acts like the L<touch(1)> command.  It can be used to
2008update the timestamps on a file, or, if the file does not exist,
2009to create a new zero-length file.
2010
2011This command only works on regular files, and will fail on other
2012file types such as directories, symbolic links, block special etc." };
2013
2014  { defaults with
2015    name = "cat";
2016    style = RString "content", [Pathname "path"], [];
2017    proc_nr = Some 4;
2018    protocol_limit_warning = true;
2019    tests = [
2020      InitISOFS, Always, TestOutput (
2021        [["cat"; "/known-2"]], "abcdef\n")
2022    ];
2023    shortdesc = "list the contents of a file";
2024    longdesc = "\
2025Return the contents of the file named C<path>.
2026
2027Note that this function cannot correctly handle binary files
2028(specifically, files containing C<\\0> character which is treated
2029as end of string).  For those you need to use the C<guestfs_read_file>
2030or C<guestfs_download> functions which have a more complex interface." };
2031
2032  { defaults with
2033    name = "ll";
2034    style = RString "listing", [Pathname "directory"], [];
2035    proc_nr = Some 5;
2036    tests = []; (* XXX Tricky to test because it depends on the exact format
2037                 * of the 'ls -l' command, which changes between F10 and F11.
2038                 *)
2039    shortdesc = "list the files in a directory (long format)";
2040    longdesc = "\
2041List the files in C<directory> (relative to the root directory,
2042there is no cwd) in the format of 'ls -la'.
2043
2044This command is mostly useful for interactive sessions.  It
2045is I<not> intended that you try to parse the output string." };
2046
2047  { defaults with
2048    name = "ls";
2049    style = RStringList "listing", [Pathname "directory"], [];
2050    proc_nr = Some 6;
2051    tests = [
2052      InitScratchFS, Always, TestOutputList (
2053        [["mkdir"; "/ls"];
2054         ["touch"; "/ls/new"];
2055         ["touch"; "/ls/newer"];
2056         ["touch"; "/ls/newest"];
2057         ["ls"; "/ls"]], ["new"; "newer"; "newest"])
2058    ];
2059    shortdesc = "list the files in a directory";
2060    longdesc = "\
2061List the files in C<directory> (relative to the root directory,
2062there is no cwd).  The '.' and '..' entries are not returned, but
2063hidden files are shown.
2064
2065This command is mostly useful for interactive sessions.  Programs
2066should probably use C<guestfs_readdir> instead." };
2067
2068  { defaults with
2069    name = "list_devices";
2070    style = RStringList "devices", [], [];
2071    proc_nr = Some 7;
2072    tests = [
2073      InitEmpty, Always, TestOutputListOfDevices (
2074        [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])
2075    ];
2076    shortdesc = "list the block devices";
2077    longdesc = "\
2078List all the block devices.
2079
2080The full block device names are returned, eg. C</dev/sda>.
2081
2082See also C<guestfs_list_filesystems>." };
2083
2084  { defaults with
2085    name = "list_partitions";
2086    style = RStringList "partitions", [], [];
2087    proc_nr = Some 8;
2088    tests = [
2089      InitBasicFS, Always, TestOutputListOfDevices (
2090        [["list_partitions"]], ["/dev/sda1"; "/dev/sdb1"]);
2091      InitEmpty, Always, TestOutputListOfDevices (
2092        [["part_init"; "/dev/sda"; "mbr"];
2093         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2094         ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2095         ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2096         ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"; "/dev/sdb1"])
2097    ];
2098    shortdesc = "list the partitions";
2099    longdesc = "\
2100List all the partitions detected on all block devices.
2101
2102The full partition device names are returned, eg. C</dev/sda1>
2103
2104This does not return logical volumes.  For that you will need to
2105call C<guestfs_lvs>.
2106
2107See also C<guestfs_list_filesystems>." };
2108
2109  { defaults with
2110    name = "pvs";
2111    style = RStringList "physvols", [], [];
2112    proc_nr = Some 9;
2113    optional = Some "lvm2";
2114    tests = [
2115      InitBasicFSonLVM, Always, TestOutputListOfDevices (
2116        [["pvs"]], ["/dev/sda1"]);
2117      InitEmpty, Always, TestOutputListOfDevices (
2118        [["part_init"; "/dev/sda"; "mbr"];
2119         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2120         ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2121         ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2122         ["pvcreate"; "/dev/sda1"];
2123         ["pvcreate"; "/dev/sda2"];
2124         ["pvcreate"; "/dev/sda3"];
2125         ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])
2126    ];
2127    shortdesc = "list the LVM physical volumes (PVs)";
2128    longdesc = "\
2129List all the physical volumes detected.  This is the equivalent
2130of the L<pvs(8)> command.
2131
2132This returns a list of just the device names that contain
2133PVs (eg. C</dev/sda2>).
2134
2135See also C<guestfs_pvs_full>." };
2136
2137  { defaults with
2138    name = "vgs";
2139    style = RStringList "volgroups", [], [];
2140    proc_nr = Some 10;
2141    optional = Some "lvm2";
2142    tests = [
2143      InitBasicFSonLVM, Always, TestOutputList (
2144        [["vgs"]], ["VG"]);
2145      InitEmpty, Always, TestOutputList (
2146        [["part_init"; "/dev/sda"; "mbr"];
2147         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2148         ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2149         ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2150         ["pvcreate"; "/dev/sda1"];
2151         ["pvcreate"; "/dev/sda2"];
2152         ["pvcreate"; "/dev/sda3"];
2153         ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
2154         ["vgcreate"; "VG2"; "/dev/sda3"];
2155         ["vgs"]], ["VG1"; "VG2"])
2156    ];
2157    shortdesc = "list the LVM volume groups (VGs)";
2158    longdesc = "\
2159List all the volumes groups detected.  This is the equivalent
2160of the L<vgs(8)> command.
2161
2162This returns a list of just the volume group names that were
2163detected (eg. C<VolGroup00>).
2164
2165See also C<guestfs_vgs_full>." };
2166
2167  { defaults with
2168    name = "lvs";
2169    style = RStringList "logvols", [], [];
2170    proc_nr = Some 11;
2171    optional = Some "lvm2";
2172    tests = [
2173      InitBasicFSonLVM, Always, TestOutputList (
2174        [["lvs"]], ["/dev/VG/LV"]);
2175      InitEmpty, Always, TestOutputList (
2176        [["part_init"; "/dev/sda"; "mbr"];
2177         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2178         ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2179         ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2180         ["pvcreate"; "/dev/sda1"];
2181         ["pvcreate"; "/dev/sda2"];
2182         ["pvcreate"; "/dev/sda3"];
2183         ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
2184         ["vgcreate"; "VG2"; "/dev/sda3"];
2185         ["lvcreate"; "LV1"; "VG1"; "50"];
2186         ["lvcreate"; "LV2"; "VG1"; "50"];
2187         ["lvcreate"; "LV3"; "VG2"; "50"];
2188         ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])
2189    ];
2190    shortdesc = "list the LVM logical volumes (LVs)";
2191    longdesc = "\
2192List all the logical volumes detected.  This is the equivalent
2193of the L<lvs(8)> command.
2194
2195This returns a list of the logical volume device names
2196(eg. C</dev/VolGroup00/LogVol00>).
2197
2198See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>." };
2199
2200  { defaults with
2201    name = "pvs_full";
2202    style = RStructList ("physvols", "lvm_pv"), [], [];
2203    proc_nr = Some 12;
2204    optional = Some "lvm2";
2205    shortdesc = "list the LVM physical volumes (PVs)";
2206    longdesc = "\
2207List all the physical volumes detected.  This is the equivalent
2208of the L<pvs(8)> command.  The \"full\" version includes all fields." };
2209
2210  { defaults with
2211    name = "vgs_full";
2212    style = RStructList ("volgroups", "lvm_vg"), [], [];
2213    proc_nr = Some 13;
2214    optional = Some "lvm2";
2215    shortdesc = "list the LVM volume groups (VGs)";
2216    longdesc = "\
2217List all the volumes groups detected.  This is the equivalent
2218of the L<vgs(8)> command.  The \"full\" version includes all fields." };
2219
2220  { defaults with
2221    name = "lvs_full";
2222    style = RStructList ("logvols", "lvm_lv"), [], [];
2223    proc_nr = Some 14;
2224    optional = Some "lvm2";
2225    shortdesc = "list the LVM logical volumes (LVs)";
2226    longdesc = "\
2227List all the logical volumes detected.  This is the equivalent
2228of the L<lvs(8)> command.  The \"full\" version includes all fields." };
2229
2230  { defaults with
2231    name = "read_lines";
2232    style = RStringList "lines", [Pathname "path"], [];
2233    proc_nr = Some 15;
2234    tests = [
2235      InitISOFS, Always, TestOutputList (
2236        [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]);
2237      InitISOFS, Always, TestOutputList (
2238        [["read_lines"; "/empty"]], [])
2239    ];
2240    shortdesc = "read file as lines";
2241    longdesc = "\
2242Return the contents of the file named C<path>.
2243
2244The file contents are returned as a list of lines.  Trailing
2245C<LF> and C<CRLF> character sequences are I<not> returned.
2246
2247Note that this function cannot correctly handle binary files
2248(specifically, files containing C<\\0> character which is treated
2249as end of line).  For those you need to use the C<guestfs_read_file>
2250function which has a more complex interface." };
2251
2252  { defaults with
2253    name = "aug_init";
2254    style = RErr, [Pathname "root"; Int "flags"], [];
2255    proc_nr = Some 16;
2256    optional = Some "augeas";
2257    shortdesc = "create a new Augeas handle";
2258    longdesc = "\
2259Create a new Augeas handle for editing configuration files.
2260If there was any previous Augeas handle associated with this
2261guestfs session, then it is closed.
2262
2263You must call this before using any other C<guestfs_aug_*>
2264commands.
2265
2266C<root> is the filesystem root.  C<root> must not be NULL,
2267use C</> instead.
2268
2269The flags are the same as the flags defined in
2270E<lt>augeas.hE<gt>, the logical I<or> of the following
2271integers:
2272
2273=over 4
2274
2275=item C<AUG_SAVE_BACKUP> = 1
2276
2277Keep the original file with a C<.augsave> extension.
2278
2279=item C<AUG_SAVE_NEWFILE> = 2
2280
2281Save changes into a file with extension C<.augnew>, and
2282do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
2283
2284=item C<AUG_TYPE_CHECK> = 4
2285
2286Typecheck lenses.
2287
2288This option is only useful when debugging Augeas lenses.  Use
2289of this option may require additional memory for the libguestfs
2290appliance.  You may need to set the C<LIBGUESTFS_MEMSIZE>
2291environment variable or call C<guestfs_set_memsize>.
2292
2293=item C<AUG_NO_STDINC> = 8
2294
2295Do not use standard load path for modules.
2296
2297=item C<AUG_SAVE_NOOP> = 16
2298
2299Make save a no-op, just record what would have been changed.
2300
2301=item C<AUG_NO_LOAD> = 32
2302
2303Do not load the tree in C<guestfs_aug_init>.
2304
2305=back
2306
2307To close the handle, you can call C<guestfs_aug_close>.
2308
2309To find out more about Augeas, see L<http://augeas.net/>." };
2310
2311  { defaults with
2312    name = "aug_close";
2313    style = RErr, [], [];
2314    proc_nr = Some 26;
2315    optional = Some "augeas";
2316    shortdesc = "close the current Augeas handle";
2317    longdesc = "\
2318Close the current Augeas handle and free up any resources
2319used by it.  After calling this, you have to call
2320C<guestfs_aug_init> again before you can use any other
2321Augeas functions." };
2322
2323  { defaults with
2324    name = "aug_defvar";
2325    style = RInt "nrnodes", [String "name"; OptString "expr"], [];
2326    proc_nr = Some 17;
2327    optional = Some "augeas";
2328    shortdesc = "define an Augeas variable";
2329    longdesc = "\
2330Defines an Augeas variable C<name> whose value is the result
2331of evaluating C<expr>.  If C<expr> is NULL, then C<name> is
2332undefined.
2333
2334On success this returns the number of nodes in C<expr>, or
2335C<0> if C<expr> evaluates to something which is not a nodeset." };
2336
2337  { defaults with
2338    name = "aug_defnode";
2339    style = RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"], [];
2340    proc_nr = Some 18;
2341    optional = Some "augeas";
2342    shortdesc = "define an Augeas node";
2343    longdesc = "\
2344Defines a variable C<name> whose value is the result of
2345evaluating C<expr>.
2346
2347If C<expr> evaluates to an empty nodeset, a node is created,
2348equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
2349C<name> will be the nodeset containing that single node.
2350
2351On success this returns a pair containing the
2352number of nodes in the nodeset, and a boolean flag
2353if a node was created." };
2354
2355  { defaults with
2356    name = "aug_get";
2357    style = RString "val", [String "augpath"], [];
2358    proc_nr = Some 19;
2359    optional = Some "augeas";
2360    shortdesc = "look up the value of an Augeas path";
2361    longdesc = "\
2362Look up the value associated with C<path>.  If C<path>
2363matches exactly one node, the C<value> is returned." };
2364
2365  { defaults with
2366    name = "aug_set";
2367    style = RErr, [String "augpath"; String "val"], [];
2368    proc_nr = Some 20;
2369    optional = Some "augeas";
2370    shortdesc = "set Augeas path to value";
2371    longdesc = "\
2372Set the value associated with C<path> to C<val>.
2373
2374In the Augeas API, it is possible to clear a node by setting
2375the value to NULL.  Due to an oversight in the libguestfs API
2376you cannot do that with this call.  Instead you must use the
2377C<guestfs_aug_clear> call." };
2378
2379  { defaults with
2380    name = "aug_insert";
2381    style = RErr, [String "augpath"; String "label"; Bool "before"], [];
2382    proc_nr = Some 21;
2383    optional = Some "augeas";
2384    shortdesc = "insert a sibling Augeas node";
2385    longdesc = "\
2386Create a new sibling C<label> for C<path>, inserting it into
2387the tree before or after C<path> (depending on the boolean
2388flag C<before>).
2389
2390C<path> must match exactly one existing node in the tree, and
2391C<label> must be a label, ie. not contain C</>, C<*> or end
2392with a bracketed index C<[N]>." };
2393
2394  { defaults with
2395    name = "aug_rm";
2396    style = RInt "nrnodes", [String "augpath"], [];
2397    proc_nr = Some 22;
2398    optional = Some "augeas";
2399    shortdesc = "remove an Augeas path";
2400    longdesc = "\
2401Remove C<path> and all of its children.
2402
2403On success this returns the number of entries which were removed." };
2404
2405  { defaults with
2406    name = "aug_mv";
2407    style = RErr, [String "src"; String "dest"], [];
2408    proc_nr = Some 23;
2409    optional = Some "augeas";
2410    shortdesc = "move Augeas node";
2411    longdesc = "\
2412Move the node C<src> to C<dest>.  C<src> must match exactly
2413one node.  C<dest> is overwritten if it exists." };
2414
2415  { defaults with
2416    name = "aug_match";
2417    style = RStringList "matches", [String "augpath"], [];
2418    proc_nr = Some 24;
2419    optional = Some "augeas";
2420    shortdesc = "return Augeas nodes which match augpath";
2421    longdesc = "\
2422Returns a list of paths which match the path expression C<path>.
2423The returned paths are sufficiently qualified so that they match
2424exactly one node in the current tree." };
2425
2426  { defaults with
2427    name = "aug_save";
2428    style = RErr, [], [];
2429    proc_nr = Some 25;
2430    optional = Some "augeas";
2431    shortdesc = "write all pending Augeas changes to disk";
2432    longdesc = "\
2433This writes all pending changes to disk.
2434
2435The flags which were passed to C<guestfs_aug_init> affect exactly
2436how files are saved." };
2437
2438  { defaults with
2439    name = "aug_load";
2440    style = RErr, [], [];
2441    proc_nr = Some 27;
2442    optional = Some "augeas";
2443    shortdesc = "load files into the tree";
2444    longdesc = "\
2445Load files into the tree.
2446
2447See C<aug_load> in the Augeas documentation for the full gory
2448details." };
2449
2450  { defaults with
2451    name = "aug_ls";
2452    style = RStringList "matches", [String "augpath"], [];
2453    proc_nr = Some 28;
2454    optional = Some "augeas";
2455    shortdesc = "list Augeas nodes under augpath";
2456    longdesc = "\
2457This is just a shortcut for listing C<guestfs_aug_match>
2458C<path/*> and sorting the resulting nodes into alphabetical order." };
2459
2460  { defaults with
2461    name = "rm";
2462    style = RErr, [Pathname "path"], [];
2463    proc_nr = Some 29;
2464    tests = [
2465      InitScratchFS, Always, TestRun
2466        [["mkdir"; "/rm"];
2467         ["touch"; "/rm/new"];
2468         ["rm"; "/rm/new"]];
2469      InitScratchFS, Always, TestLastFail
2470        [["rm"; "/nosuchfile"]];
2471      InitScratchFS, Always, TestLastFail
2472        [["mkdir"; "/rm2"];
2473         ["rm"; "/rm2"]]
2474    ];
2475    shortdesc = "remove a file";
2476    longdesc = "\
2477Remove the single file C<path>." };
2478
2479  { defaults with
2480    name = "rmdir";
2481    style = RErr, [Pathname "path"], [];
2482    proc_nr = Some 30;
2483    tests = [
2484      InitScratchFS, Always, TestRun
2485        [["mkdir"; "/rmdir"];
2486         ["rmdir"; "/rmdir"]];
2487      InitScratchFS, Always, TestLastFail
2488        [["rmdir"; "/rmdir2"]];
2489      InitScratchFS, Always, TestLastFail
2490        [["mkdir"; "/rmdir3"];
2491         ["touch"; "/rmdir3/new"];
2492         ["rmdir"; "/rmdir3/new"]]
2493    ];
2494    shortdesc = "remove a directory";
2495    longdesc = "\
2496Remove the single directory C<path>." };
2497
2498  { defaults with
2499    name = "rm_rf";
2500    style = RErr, [Pathname "path"], [];
2501    proc_nr = Some 31;
2502    tests = [
2503      InitScratchFS, Always, TestOutputFalse
2504        [["mkdir"; "/rm_rf"];
2505         ["mkdir"; "/rm_rf/foo"];
2506         ["touch"; "/rm_rf/foo/bar"];
2507         ["rm_rf"; "/rm_rf"];
2508         ["exists"; "/rm_rf"]]
2509    ];
2510    shortdesc = "remove a file or directory recursively";
2511    longdesc = "\
2512Remove the file or directory C<path>, recursively removing the
2513contents if its a directory.  This is like the C<rm -rf> shell
2514command." };
2515
2516  { defaults with
2517    name = "mkdir";
2518    style = RErr, [Pathname "path"], [];
2519    proc_nr = Some 32;
2520    tests = [
2521      InitScratchFS, Always, TestOutputTrue
2522        [["mkdir"; "/mkdir"];
2523         ["is_dir"; "/mkdir"]];
2524      InitScratchFS, Always, TestLastFail
2525        [["mkdir"; "/mkdir2/foo/bar"]]
2526    ];
2527    shortdesc = "create a directory";
2528    longdesc = "\
2529Create a directory named C<path>." };
2530
2531  { defaults with
2532    name = "mkdir_p";
2533    style = RErr, [Pathname "path"], [];
2534    proc_nr = Some 33;
2535    tests = [
2536      InitScratchFS, Always, TestOutputTrue
2537        [["mkdir_p"; "/mkdir_p/foo/bar"];
2538         ["is_dir"; "/mkdir_p/foo/bar"]];
2539      InitScratchFS, Always, TestOutputTrue
2540        [["mkdir_p"; "/mkdir_p2/foo/bar"];
2541         ["is_dir"; "/mkdir_p2/foo"]];
2542      InitScratchFS, Always, TestOutputTrue
2543        [["mkdir_p"; "/mkdir_p3/foo/bar"];
2544         ["is_dir"; "/mkdir_p3"]];
2545      (* Regression tests for RHBZ#503133: *)
2546      InitScratchFS, Always, TestRun
2547        [["mkdir"; "/mkdir_p4"];
2548         ["mkdir_p"; "/mkdir_p4"]];
2549      InitScratchFS, Always, TestLastFail
2550        [["touch"; "/mkdir_p5"];
2551         ["mkdir_p"; "/mkdir_p5"]]
2552    ];
2553    shortdesc = "create a directory and parents";
2554    longdesc = "\
2555Create a directory named C<path>, creating any parent directories
2556as necessary.  This is like the C<mkdir -p> shell command." };
2557
2558  { defaults with
2559    name = "chmod";
2560    style = RErr, [Int "mode"; Pathname "path"], [];
2561    proc_nr = Some 34;
2562    tests = [] (* XXX Need stat command to test *);
2563    shortdesc = "change file mode";
2564    longdesc = "\
2565Change the mode (permissions) of C<path> to C<mode>.  Only
2566numeric modes are supported.
2567
2568I<Note>: When using this command from guestfish, C<mode>
2569by default would be decimal, unless you prefix it with
2570C<0> to get octal, ie. use C<0700> not C<700>.
2571
2572The mode actually set is affected by the umask." };
2573
2574  { defaults with
2575    name = "chown";
2576    style = RErr, [Int "owner"; Int "group"; Pathname "path"], [];
2577    proc_nr = Some 35;
2578    tests = [] (* XXX Need stat command to test *);
2579    shortdesc = "change file owner and group";
2580    longdesc = "\
2581Change the file owner to C<owner> and group to C<group>.
2582
2583Only numeric uid and gid are supported.  If you want to use
2584names, you will need to locate and parse the password file
2585yourself (Augeas support makes this relatively easy)." };
2586
2587  { defaults with
2588    name = "exists";
2589    style = RBool "existsflag", [Pathname "path"], [];
2590    proc_nr = Some 36;
2591    tests = [
2592      InitISOFS, Always, TestOutputTrue (
2593        [["exists"; "/empty"]]);
2594      InitISOFS, Always, TestOutputTrue (
2595        [["exists"; "/directory"]])
2596    ];
2597    shortdesc = "test if file or directory exists";
2598    longdesc = "\
2599This returns C<true> if and only if there is a file, directory
2600(or anything) with the given C<path> name.
2601
2602See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>." };
2603
2604  { defaults with
2605    name = "is_file";
2606    style = RBool "fileflag", [Pathname "path"], [];
2607    proc_nr = Some 37;
2608    tests = [
2609      InitISOFS, Always, TestOutputTrue (
2610        [["is_file"; "/known-1"]]);
2611      InitISOFS, Always, TestOutputFalse (
2612        [["is_file"; "/directory"]])
2613    ];
2614    shortdesc = "test if a regular file";
2615    longdesc = "\
2616This returns C<true> if and only if there is a regular file
2617with the given C<path> name.  Note that it returns false for
2618other objects like directories.
2619
2620See also C<guestfs_stat>." };
2621
2622  { defaults with
2623    name = "is_dir";
2624    style = RBool "dirflag", [Pathname "path"], [];
2625    proc_nr = Some 38;
2626    tests = [
2627      InitISOFS, Always, TestOutputFalse (
2628        [["is_dir"; "/known-3"]]);
2629      InitISOFS, Always, TestOutputTrue (
2630        [["is_dir"; "/directory"]])
2631    ];
2632    shortdesc = "test if a directory";
2633    longdesc = "\
2634This returns C<true> if and only if there is a directory
2635with the given C<path> name.  Note that it returns false for
2636other objects like files.
2637
2638See also C<guestfs_stat>." };
2639
2640  { defaults with
2641    name = "pvcreate";
2642    style = RErr, [Device "device"], [];
2643    proc_nr = Some 39;
2644    optional = Some "lvm2";
2645    tests = [
2646      InitEmpty, Always, TestOutputListOfDevices (
2647        [["part_init"; "/dev/sda"; "mbr"];
2648         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2649         ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2650         ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2651         ["pvcreate"; "/dev/sda1"];
2652         ["pvcreate"; "/dev/sda2"];
2653         ["pvcreate"; "/dev/sda3"];
2654         ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])
2655    ];
2656    shortdesc = "create an LVM physical volume";
2657    longdesc = "\
2658This creates an LVM physical volume on the named C<device>,
2659where C<device> should usually be a partition name such
2660as C</dev/sda1>." };
2661
2662  { defaults with
2663    name = "vgcreate";
2664    style = RErr, [String "volgroup"; DeviceList "physvols"], [];
2665    proc_nr = Some 40;
2666    optional = Some "lvm2";
2667    tests = [
2668      InitEmpty, Always, TestOutputList (
2669        [["part_init"; "/dev/sda"; "mbr"];
2670         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2671         ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2672         ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2673         ["pvcreate"; "/dev/sda1"];
2674         ["pvcreate"; "/dev/sda2"];
2675         ["pvcreate"; "/dev/sda3"];
2676         ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
2677         ["vgcreate"; "VG2"; "/dev/sda3"];
2678         ["vgs"]], ["VG1"; "VG2"])
2679    ];
2680    shortdesc = "create an LVM volume group";
2681    longdesc = "\
2682This creates an LVM volume group called C<volgroup>
2683from the non-empty list of physical volumes C<physvols>." };
2684
2685  { defaults with
2686    name = "lvcreate";
2687    style = RErr, [String "logvol"; String "volgroup"; Int "mbytes"], [];
2688    proc_nr = Some 41;
2689    optional = Some "lvm2";
2690    tests = [
2691      InitEmpty, Always, TestOutputList (
2692        [["part_init"; "/dev/sda"; "mbr"];
2693         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2694         ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2695         ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2696         ["pvcreate"; "/dev/sda1"];
2697         ["pvcreate"; "/dev/sda2"];
2698         ["pvcreate"; "/dev/sda3"];
2699         ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
2700         ["vgcreate"; "VG2"; "/dev/sda3"];
2701         ["lvcreate"; "LV1"; "VG1"; "50"];
2702         ["lvcreate"; "LV2"; "VG1"; "50"];
2703         ["lvcreate"; "LV3"; "VG2"; "50"];
2704         ["lvcreate"; "LV4"; "VG2"; "50"];
2705         ["lvcreate"; "LV5"; "VG2"; "50"];
2706         ["lvs"]],
2707        ["/dev/VG1/LV1"; "/dev/VG1/LV2";
2708         "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])
2709    ];
2710    shortdesc = "create an LVM logical volume";
2711    longdesc = "\
2712This creates an LVM logical volume called C<logvol>
2713on the volume group C<volgroup>, with C<size> megabytes." };
2714
2715  { defaults with
2716    name = "sfdisk";
2717    style = RErr, [Device "device";
2718                   Int "cyls"; Int "heads"; Int "sectors";
2719                   StringList "lines"], [];
2720    proc_nr = Some 43;
2721    deprecated_by = Some "part_add";
2722    shortdesc = "create partitions on a block device";
2723    longdesc = "\
2724This is a direct interface to the L<sfdisk(8)> program for creating
2725partitions on block devices.
2726
2727C<device> should be a block device, for example C</dev/sda>.
2728
2729C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
2730and sectors on the device, which are passed directly to sfdisk as
2731the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
2732of these, then the corresponding parameter is omitted.  Usually for
2733'large' disks, you can just pass C<0> for these, but for small
2734(floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
2735out the right geometry and you will need to tell it.
2736
2737C<lines> is a list of lines that we feed to C<sfdisk>.  For more
2738information refer to the L<sfdisk(8)> manpage.
2739
2740To create a single partition occupying the whole disk, you would
2741pass C<lines> as a single element list, when the single element being
2742the string C<,> (comma).
2743
2744See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>,
2745C<guestfs_part_init>" };
2746
2747  { defaults with
2748    name = "write_file";
2749    style = RErr, [Pathname "path"; String "content"; Int "size"], [];
2750    proc_nr = Some 44;
2751    protocol_limit_warning = true; deprecated_by = Some "write";
2752    (* Regression test for RHBZ#597135. *)
2753    tests = [
2754      InitScratchFS, Always, TestLastFail
2755        [["write_file"; "/write_file"; "abc"; "10000"]]
2756    ];
2757    shortdesc = "create a file";
2758    longdesc = "\
2759This call creates a file called C<path>.  The contents of the
2760file is the string C<content> (which can contain any 8 bit data),
2761with length C<size>.
2762
2763As a special case, if C<size> is C<0>
2764then the length is calculated using C<strlen> (so in this case
2765the content cannot contain embedded ASCII NULs).
2766
2767I<NB.> Owing to a bug, writing content containing ASCII NUL
2768characters does I<not> work, even if the length is specified." };
2769
2770  { defaults with
2771    name = "umount";
2772    style = RErr, [String "pathordevice"], [];
2773    proc_nr = Some 45;
2774    fish_alias = ["unmount"];
2775    tests = [
2776      InitEmpty, Always, TestOutputListOfDevices (
2777        [["part_disk"; "/dev/sda"; "mbr"];
2778         ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""];
2779         ["mount_options"; ""; "/dev/sda1"; "/"];
2780         ["mounts"]], ["/dev/sda1"]);
2781      InitEmpty, Always, TestOutputList (
2782        [["part_disk"; "/dev/sda"; "mbr"];
2783         ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""];
2784         ["mount_options"; ""; "/dev/sda1"; "/"];
2785         ["umount"; "/"];
2786         ["mounts"]], [])
2787    ];
2788    shortdesc = "unmount a filesystem";
2789    longdesc = "\
2790This unmounts the given filesystem.  The filesystem may be
2791specified either by its mountpoint (path) or the device which
2792contains the filesystem." };
2793
2794  { defaults with
2795    name = "mounts";
2796    style = RStringList "devices", [], [];
2797    proc_nr = Some 46;
2798    tests = [
2799      InitScratchFS, Always, TestOutputListOfDevices (
2800        [["mounts"]], ["/dev/sdb1"])
2801    ];
2802    shortdesc = "show mounted filesystems";
2803    longdesc = "\
2804This returns the list of currently mounted filesystems.  It returns
2805the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
2806
2807Some internal mounts are not shown.
2808
2809See also: C<guestfs_mountpoints>" };
2810
2811  { defaults with
2812    name = "umount_all";
2813    style = RErr, [], [];
2814    proc_nr = Some 47;
2815    fish_alias = ["unmount-all"];
2816    tests = [
2817      InitScratchFS, Always, TestOutputList (
2818        [["umount_all"];
2819         ["mounts"]], []);
2820      (* check that umount_all can unmount nested mounts correctly: *)
2821      InitEmpty, Always, TestOutputList (
2822        [["part_init"; "/dev/sda"; "mbr"];
2823         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2824         ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2825         ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2826         ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""];
2827         ["mkfs"; "ext2"; "/dev/sda2"; ""; "NOARG"; ""; ""];
2828         ["mkfs"; "ext2"; "/dev/sda3"; ""; "NOARG"; ""; ""];
2829         ["mount_options"; ""; "/dev/sda1"; "/"];
2830         ["mkdir"; "/mp1"];
2831         ["mount_options"; ""; "/dev/sda2"; "/mp1"];
2832         ["mkdir"; "/mp1/mp2"];
2833         ["mount_options"; ""; "/dev/sda3"; "/mp1/mp2"];
2834         ["mkdir"; "/mp1/mp2/mp3"];
2835         ["umount_all"];
2836         ["mounts"]], [])
2837    ];
2838    shortdesc = "unmount all filesystems";
2839    longdesc = "\
2840This unmounts all mounted filesystems.
2841
2842Some internal mounts are not unmounted by this call." };
2843
2844  { defaults with
2845    name = "lvm_remove_all";
2846    style = RErr, [], [];
2847    proc_nr = Some 48;
2848    optional = Some "lvm2";
2849    shortdesc = "remove all LVM LVs, VGs and PVs";
2850    longdesc = "\
2851This command removes all LVM logical volumes, volume groups
2852and physical volumes." };
2853
2854  { defaults with
2855    name = "file";
2856    style = RString "description", [Dev_or_Path "path"], [];
2857    proc_nr = Some 49;
2858    tests = [
2859      InitISOFS, Always, TestOutput (
2860        [["file"; "/empty"]], "empty");
2861      InitISOFS, Always, TestOutput (
2862        [["file"; "/known-1"]], "ASCII text");
2863      InitISOFS, Always, TestLastFail (
2864        [["file"; "/notexists"]]);
2865      InitISOFS, Always, TestOutput (
2866        [["file"; "/abssymlink"]], "symbolic link");
2867      InitISOFS, Always, TestOutput (
2868        [["file"; "/directory"]], "directory")
2869    ];
2870    shortdesc = "determine file type";
2871    longdesc = "\
2872This call uses the standard L<file(1)> command to determine
2873the type or contents of the file.
2874
2875This call will also transparently look inside various types
2876of compressed file.
2877
2878The exact command which runs is C<file -zb path>.  Note in
2879particular that the filename is not prepended to the output
2880(the I<-b> option).
2881
2882The output depends on the output of the underlying L<file(1)>
2883command and it can change in future in ways beyond our control.
2884In other words, the output is not guaranteed by the ABI.
2885
2886See also: L<file(1)>, C<guestfs_vfs_type>, C<guestfs_lstat>,
2887C<guestfs_is_file>, C<guestfs_is_blockdev> (etc), C<guestfs_is_zero>." };
2888
2889  { defaults with
2890    name = "command";
2891    style = RString "output", [StringList "arguments"], [];
2892    proc_nr = Some 50;
2893    protocol_limit_warning = true;
2894    tests = [
2895      InitScratchFS, Always, TestOutput (
2896        [["mkdir"; "/command"];
2897         ["upload"; "test-command"; "/command/test-command"];
2898         ["chmod"; "0o755"; "/command/test-command"];
2899         ["command"; "/command/test-command 1"]], "Result1");
2900      InitScratchFS, Always, TestOutput (
2901        [["mkdir"; "/command2"];
2902         ["upload"; "test-command"; "/command2/test-command"];
2903         ["chmod"; "0o755"; "/command2/test-command"];
2904         ["command"; "/command2/test-command 2"]], "Result2\n");
2905      InitScratchFS, Always, TestOutput (
2906        [["mkdir"; "/command3"];
2907         ["upload"; "test-command"; "/command3/test-command"];
2908         ["chmod"; "0o755"; "/command3/test-command"];
2909         ["command"; "/command3/test-command 3"]], "\nResult3");
2910      InitScratchFS, Always, TestOutput (
2911        [["mkdir"; "/command4"];
2912         ["upload"; "test-command"; "/command4/test-command"];
2913         ["chmod"; "0o755"; "/command4/test-command"];
2914         ["command"; "/command4/test-command 4"]], "\nResult4\n");
2915      InitScratchFS, Always, TestOutput (
2916        [["mkdir"; "/command5"];
2917         ["upload"; "test-command"; "/command5/test-command"];
2918         ["chmod"; "0o755"; "/command5/test-command"];
2919         ["command"; "/command5/test-command 5"]], "\nResult5\n\n");
2920      InitScratchFS, Always, TestOutput (
2921        [["mkdir"; "/command6"];
2922         ["upload"; "test-command"; "/command6/test-command"];
2923         ["chmod"; "0o755"; "/command6/test-command"];
2924         ["command"; "/command6/test-command 6"]], "\n\nResult6\n\n");
2925      InitScratchFS, Always, TestOutput (
2926        [["mkdir"; "/command7"];
2927         ["upload"; "test-command"; "/command7/test-command"];
2928         ["chmod"; "0o755"; "/command7/test-command"];
2929         ["command"; "/command7/test-command 7"]], "");
2930      InitScratchFS, Always, TestOutput (
2931        [["mkdir"; "/command8"];
2932         ["upload"; "test-command"; "/command8/test-command"];
2933         ["chmod"; "0o755"; "/command8/test-command"];
2934         ["command"; "/command8/test-command 8"]], "\n");
2935      InitScratchFS, Always, TestOutput (
2936        [["mkdir"; "/command9"];
2937         ["upload"; "test-command"; "/command9/test-command"];
2938         ["chmod"; "0o755"; "/command9/test-command"];
2939         ["command"; "/command9/test-command 9"]], "\n\n");
2940      InitScratchFS, Always, TestOutput (
2941        [["mkdir"; "/command10"];
2942         ["upload"; "test-command"; "/command10/test-command"];
2943         ["chmod"; "0o755"; "/command10/test-command"];
2944         ["command"; "/command10/test-command 10"]], "Result10-1\nResult10-2\n");
2945      InitScratchFS, Always, TestOutput (
2946        [["mkdir"; "/command11"];
2947         ["upload"; "test-command"; "/command11/test-command"];
2948         ["chmod"; "0o755"; "/command11/test-command"];
2949         ["command"; "/command11/test-command 11"]], "Result11-1\nResult11-2");
2950      InitScratchFS, Always, TestLastFail (
2951        [["mkdir"; "/command12"];
2952         ["upload"; "test-command"; "/command12/test-command"];
2953         ["chmod"; "0o755"; "/command12/test-command"];
2954         ["command"; "/command12/test-command"]])
2955    ];
2956    shortdesc = "run a command from the guest filesystem";
2957    longdesc = "\
2958This call runs a command from the guest filesystem.  The
2959filesystem must be mounted, and must contain a compatible
2960operating system (ie. something Linux, with the same
2961or compatible processor architecture).
2962
2963The single parameter is an argv-style list of arguments.
2964The first element is the name of the program to run.
2965Subsequent elements are parameters.  The list must be
2966non-empty (ie. must contain a program name).  Note that
2967the command runs directly, and is I<not> invoked via
2968the shell (see C<guestfs_sh>).
2969
2970The return value is anything printed to I<stdout> by
2971the command.
2972
2973If the command returns a non-zero exit status, then
2974this function returns an error message.  The error message
2975string is the content of I<stderr> from the command.
2976
2977The C<$PATH> environment variable will contain at least
2978C</usr/bin> and C</bin>.  If you require a program from
2979another location, you should provide the full path in the
2980first parameter.
2981
2982Shared libraries and data files required by the program
2983must be available on filesystems which are mounted in the
2984correct places.  It is the caller's responsibility to ensure
2985all filesystems that are needed are mounted at the right
2986locations." };
2987
2988  { defaults with
2989    name = "command_lines";
2990    style = RStringList "lines", [StringList "arguments"], [];
2991    proc_nr = Some 51;
2992    protocol_limit_warning = true;
2993    tests = [
2994      InitScratchFS, Always, TestOutputList (
2995        [["mkdir"; "/command_lines"];
2996         ["upload"; "test-command"; "/command_lines/test-command"];
2997         ["chmod"; "0o755"; "/command_lines/test-command"];
2998         ["command_lines"; "/command_lines/test-command 1"]], ["Result1"]);
2999      InitScratchFS, Always, TestOutputList (
3000        [["mkdir"; "/command_lines2"];
3001         ["upload"; "test-command"; "/command_lines2/test-command"];
3002         ["chmod"; "0o755"; "/command_lines2/test-command"];
3003         ["command_lines"; "/command_lines2/test-command 2"]], ["Result2"]);
3004      InitScratchFS, Always, TestOutputList (
3005        [["mkdir"; "/command_lines3"];
3006         ["upload"; "test-command"; "/command_lines3/test-command"];
3007         ["chmod"; "0o755"; "/command_lines3/test-command"];
3008         ["command_lines"; "/command_lines3/test-command 3"]], ["";"Result3"]);
3009      InitScratchFS, Always, TestOutputList (
3010        [["mkdir"; "/command_lines4"];
3011         ["upload"; "test-command"; "/command_lines4/test-command"];
3012         ["chmod"; "0o755"; "/command_lines4/test-command"];
3013         ["command_lines"; "/command_lines4/test-command 4"]], ["";"Result4"]);
3014      InitScratchFS, Always, TestOutputList (
3015        [["mkdir"; "/command_lines5"];
3016         ["upload"; "test-command"; "/command_lines5/test-command"];
3017         ["chmod"; "0o755"; "/command_lines5/test-command"];
3018         ["command_lines"; "/command_lines5/test-command 5"]], ["";"Result5";""]);
3019      InitScratchFS, Always, TestOutputList (
3020        [["mkdir"; "/command_lines6"];
3021         ["upload"; "test-command"; "/command_lines6/test-command"];
3022         ["chmod"; "0o755"; "/command_lines6/test-command"];
3023         ["command_lines"; "/command_lines6/test-command 6"]], ["";"";"Result6";""]);
3024      InitScratchFS, Always, TestOutputList (
3025        [["mkdir"; "/command_lines7"];
3026         ["upload"; "test-command"; "/command_lines7/test-command"];
3027         ["chmod"; "0o755"; "/command_lines7/test-command"];
3028         ["command_lines"; "/command_lines7/test-command 7"]], []);
3029      InitScratchFS, Always, TestOutputList (
3030        [["mkdir"; "/command_lines8"];
3031         ["upload"; "test-command"; "/command_lines8/test-command"];
3032         ["chmod"; "0o755"; "/command_lines8/test-command"];
3033         ["command_lines"; "/command_lines8/test-command 8"]], [""]);
3034      InitScratchFS, Always, TestOutputList (
3035        [["mkdir"; "/command_lines9"];
3036         ["upload"; "test-command"; "/command_lines9/test-command"];
3037         ["chmod"; "0o755"; "/command_lines9/test-command"];
3038         ["command_lines"; "/command_lines9/test-command 9"]], ["";""]);
3039      InitScratchFS, Always, TestOutputList (
3040        [["mkdir"; "/command_lines10"];
3041         ["upload"; "test-command"; "/command_lines10/test-command"];
3042         ["chmod"; "0o755"; "/command_lines10/test-command"];
3043         ["command_lines"; "/command_lines10/test-command 10"]], ["Result10-1";"Result10-2"]);
3044      InitScratchFS, Always, TestOutputList (
3045        [["mkdir"; "/command_lines11"];
3046         ["upload"; "test-command"; "/command_lines11/test-command"];
3047         ["chmod"; "0o755"; "/command_lines11/test-command"];
3048         ["command_lines"; "/command_lines11/test-command 11"]], ["Result11-1";"Result11-2"])
3049    ];
3050    shortdesc = "run a command, returning lines";
3051    longdesc = "\
3052This is the same as C<guestfs_command>, but splits the
3053result into a list of lines.
3054
3055See also: C<guestfs_sh_lines>" };
3056
3057  { defaults with
3058    name = "stat";
3059    style = RStruct ("statbuf", "stat"), [Pathname "path"], [];
3060    proc_nr = Some 52;
3061    tests = [
3062      InitISOFS, Always, TestOutputStruct (
3063        [["stat"; "/empty"]], [CompareWithInt ("size", 0)])
3064    ];
3065    shortdesc = "get file information";
3066    longdesc = "\
3067Returns file information for the given C<path>.
3068
3069This is the same as the C<stat(2)> system call." };
3070
3071  { defaults with
3072    name = "lstat";
3073    style = RStruct ("statbuf", "stat"), [Pathname "path"], [];
3074    proc_nr = Some 53;
3075    tests = [
3076      InitISOFS, Always, TestOutputStruct (
3077        [["lstat"; "/empty"]], [CompareWithInt ("size", 0)])
3078    ];
3079    shortdesc = "get file information for a symbolic link";
3080    longdesc = "\
3081Returns file information for the given C<path>.
3082
3083This is the same as C<guestfs_stat> except that if C<path>
3084is a symbolic link, then the link is stat-ed, not the file it
3085refers to.
3086
3087This is the same as the C<lstat(2)> system call." };
3088
3089  { defaults with
3090    name = "statvfs";
3091    style = RStruct ("statbuf", "statvfs"), [Pathname "path"], [];
3092    proc_nr = Some 54;
3093    tests = [
3094      InitISOFS, Always, TestOutputStruct (
3095        [["statvfs"; "/"]], [CompareWithInt ("namemax", 255)])
3096    ];
3097    shortdesc = "get file system statistics";
3098    longdesc = "\
3099Returns file system statistics for any mounted file system.
3100C<path> should be a file or directory in the mounted file system
3101(typically it is the mount point itself, but it doesn't need to be).
3102
3103This is the same as the C<statvfs(2)> system call." };
3104
3105  { defaults with
3106    name = "tune2fs_l";
3107    style = RHashtable "superblock", [Device "device"], [];
3108    proc_nr = Some 55;
3109    tests = [
3110      InitScratchFS, Always, TestOutputHashtable (
3111        [["tune2fs_l"; "/dev/sdb1"]],
3112        ["Filesystem magic number", "0xEF53";
3113         "Filesystem OS type", "Linux"])
3114    ];
3115    shortdesc = "get ext2/ext3/ext4 superblock details";
3116    longdesc = "\
3117This returns the contents of the ext2, ext3 or ext4 filesystem
3118superblock on C<device>.
3119
3120It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
3121manpage for more details.  The list of fields returned isn't
3122clearly defined, and depends on both the version of C<tune2fs>
3123that libguestfs was built against, and the filesystem itself." };
3124
3125  { defaults with
3126    name = "blockdev_setro";
3127    style = RErr, [Device "device"], [];
3128    proc_nr = Some 56;
3129    tests = [
3130      InitEmpty, Always, TestOutputTrue (
3131        [["blockdev_setro"; "/dev/sda"];
3132         ["blockdev_getro"; "/dev/sda"]])
3133    ];
3134    shortdesc = "set block device to read-only";
3135    longdesc = "\
3136Sets the block device named C<device> to read-only.
3137
3138This uses the L<blockdev(8)> command." };
3139
3140  { defaults with
3141    name = "blockdev_setrw";
3142    style = RErr, [Device "device"], [];
3143    proc_nr = Some 57;
3144    tests = [
3145      InitEmpty, Always, TestOutputFalse (
3146        [["blockdev_setrw"; "/dev/sda"];
3147         ["blockdev_getro"; "/dev/sda"]])
3148    ];
3149    shortdesc = "set block device to read-write";
3150    longdesc = "\
3151Sets the block device named C<device> to read-write.
3152
3153This uses the L<blockdev(8)> command." };
3154
3155  { defaults with
3156    name = "blockdev_getro";
3157    style = RBool "ro", [Device "device"], [];
3158    proc_nr = Some 58;
3159    tests = [
3160      InitEmpty, Always, TestOutputTrue (
3161        [["blockdev_setro"; "/dev/sda"];
3162         ["blockdev_getro"; "/dev/sda"]])
3163    ];
3164    shortdesc = "is block device set to read-only";
3165    longdesc = "\
3166Returns a boolean indicating if the block device is read-only
3167(true if read-only, false if not).
3168
3169This uses the L<blockdev(8)> command." };
3170
3171  { defaults with
3172    name = "blockdev_getss";
3173    style = RInt "sectorsize", [Device "device"], [];
3174    proc_nr = Some 59;
3175    tests = [
3176      InitEmpty, Always, TestOutputInt (
3177        [["blockdev_getss"; "/dev/sda"]], 512)
3178    ];
3179    shortdesc = "get sectorsize of block device";
3180    longdesc = "\
3181This returns the size of sectors on a block device.
3182Usually 512, but can be larger for modern devices.
3183
3184(Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
3185for that).
3186
3187This uses the L<blockdev(8)> command." };
3188
3189  { defaults with
3190    name = "blockdev_getbsz";
3191    style = RInt "blocksize", [Device "device"], [];
3192    proc_nr = Some 60;
3193    (* cannot be tested because output differs depending on page size *)
3194    tests = [];
3195    shortdesc = "get blocksize of block device";
3196    longdesc = "\
3197This returns the block size of a device.
3198
3199(Note this is different from both I<size in blocks> and
3200I<filesystem block size>).
3201
3202This uses the L<blockdev(8)> command." };
3203
3204  { defaults with
3205    name = "blockdev_setbsz";
3206    style = RErr, [Device "device"; Int "blocksize"], [];
3207    proc_nr = Some 61;
3208    shortdesc = "set blocksize of block device";
3209    longdesc = "\
3210This sets the block size of a device.
3211
3212(Note this is different from both I<size in blocks> and
3213I<filesystem block size>).
3214
3215This uses the L<blockdev(8)> command." };
3216
3217  { defaults with
3218    name = "blockdev_getsz";
3219    style = RInt64 "sizeinsectors", [Device "device"], [];
3220    proc_nr = Some 62;
3221    tests = [
3222      InitEmpty, Always, TestOutputInt (
3223        [["blockdev_getsz"; "/dev/sda"]], 1024000)
3224    ];
3225    shortdesc = "get total size of device in 512-byte sectors";
3226    longdesc = "\
3227This returns the size of the device in units of 512-byte sectors
3228(even if the sectorsize isn't 512 bytes ... weird).
3229
3230See also C<guestfs_blockdev_getss> for the real sector size of
3231the device, and C<guestfs_blockdev_getsize64> for the more
3232useful I<size in bytes>.
3233
3234This uses the L<blockdev(8)> command." };
3235
3236  { defaults with
3237    name = "blockdev_getsize64";
3238    style = RInt64 "sizeinbytes", [Device "device"], [];
3239    proc_nr = Some 63;
3240    tests = [
3241      InitEmpty, Always, TestOutputInt (
3242        [["blockdev_getsize64"; "/dev/sda"]], 524288000)
3243    ];
3244    shortdesc = "get total size of device in bytes";
3245    longdesc = "\
3246This returns the size of the device in bytes.
3247
3248See also C<guestfs_blockdev_getsz>.
3249
3250This uses the L<blockdev(8)> command." };
3251
3252  { defaults with
3253    name = "blockdev_flushbufs";
3254    style = RErr, [Device "device"], [];
3255    proc_nr = Some 64;
3256    tests = [
3257      InitEmpty, Always, TestRun
3258        [["blockdev_flushbufs"; "/dev/sda"]]
3259    ];
3260    shortdesc = "flush device buffers";
3261    longdesc = "\
3262This tells the kernel to flush internal buffers associated
3263with C<device>.
3264
3265This uses the L<blockdev(8)> command." };
3266
3267  { defaults with
3268    name = "blockdev_rereadpt";
3269    style = RErr, [Device "device"], [];
3270    proc_nr = Some 65;
3271    tests = [
3272      InitEmpty, Always, TestRun
3273        [["blockdev_rereadpt"; "/dev/sda"]]
3274    ];
3275    shortdesc = "reread partition table";
3276    longdesc = "\
3277Reread the partition table on C<device>.
3278
3279This uses the L<blockdev(8)> command." };
3280
3281  { defaults with
3282    name = "upload";
3283    style = RErr, [FileIn "filename"; Dev_or_Path "remotefilename"], [];
3284    proc_nr = Some 66;
3285    progress = true; cancellable = true;
3286    tests = [
3287      InitScratchFS, Always, TestOutput (
3288        (* Pick a file from cwd which isn't likely to change. *)
3289        [["mkdir"; "/upload"];
3290         ["upload"; "../../COPYING.LIB"; "/upload/COPYING.LIB"];
3291         ["checksum"; "md5"; "/upload/COPYING.LIB"]],
3292        Digest.to_hex (Digest.file "COPYING.LIB"))
3293    ];
3294    shortdesc = "upload a file from the local machine";
3295    longdesc = "\
3296Upload local file C<filename> to C<remotefilename> on the
3297filesystem.
3298
3299C<filename> can also be a named pipe.
3300
3301See also C<guestfs_download>." };
3302
3303  { defaults with
3304    name = "download";
3305    style = RErr, [Dev_or_Path "remotefilename"; FileOut "filename"], [];
3306    proc_nr = Some 67;
3307    progress = true; cancellable = true;
3308    tests = [
3309      InitScratchFS, Always, TestOutput (
3310        (* Pick a file from cwd which isn't likely to change. *)
3311        [["mkdir"; "/download"];
3312         ["upload"; "../../COPYING.LIB"; "/download/COPYING.LIB"];
3313         ["download"; "/download/COPYING.LIB"; "testdownload.tmp"];
3314         ["upload"; "testdownload.tmp"; "/download/upload"];
3315         ["checksum"; "md5"; "/download/upload"]],
3316        Digest.to_hex (Digest.file "COPYING.LIB"))
3317    ];
3318    shortdesc = "download a file to the local machine";
3319    longdesc = "\
3320Download file C<remotefilename> and save it as C<filename>
3321on the local machine.
3322
3323C<filename> can also be a named pipe.
3324
3325See also C<guestfs_upload>, C<guestfs_cat>." };
3326
3327  { defaults with
3328    name = "checksum";
3329    style = RString "checksum", [String "csumtype"; Pathname "path"], [];
3330    proc_nr = Some 68;
3331    tests = [
3332      InitISOFS, Always, TestOutput (
3333        [["checksum"; "crc"; "/known-3"]], "2891671662");
3334      InitISOFS, Always, TestLastFail (
3335        [["checksum"; "crc"; "/notexists"]]);
3336      InitISOFS, Always, TestOutput (
3337        [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c");
3338      InitISOFS, Always, TestOutput (
3339        [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15");
3340      InitISOFS, Always, TestOutput (
3341        [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741");
3342      InitISOFS, Always, TestOutput (
3343        [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30");
3344      InitISOFS, Always, TestOutput (
3345        [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640");
3346      InitISOFS, Always, TestOutput (
3347        [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6");
3348      (* Test for RHBZ#579608, absolute symbolic links. *)
3349      InitISOFS, Always, TestOutput (
3350        [["checksum"; "sha512"; "/abssymlink"]], "5f57d0639bc95081c53afc63a449403883818edc64da48930ad6b1a4fb49be90404686877743fbcd7c99811f3def7df7bc22635c885c6a8cf79c806b43451c1a")
3351    ];
3352    shortdesc = "compute MD5, SHAx or CRC checksum of file";
3353    longdesc = "\
3354This call computes the MD5, SHAx or CRC checksum of the
3355file named C<path>.
3356
3357The type of checksum to compute is given by the C<csumtype>
3358parameter which must have one of the following values:
3359
3360=over 4
3361
3362=item C<crc>
3363
3364Compute the cyclic redundancy check (CRC) specified by POSIX
3365for the C<cksum> command.
3366
3367=item C<md5>
3368
3369Compute the MD5 hash (using the C<md5sum> program).
3370
3371=item C<sha1>
3372
3373Compute the SHA1 hash (using the C<sha1sum> program).
3374
3375=item C<sha224>
3376
3377Compute the SHA224 hash (using the C<sha224sum> program).
3378
3379=item C<sha256>
3380
3381Compute the SHA256 hash (using the C<sha256sum> program).
3382
3383=item C<sha384>
3384
3385Compute the SHA384 hash (using the C<sha384sum> program).
3386
3387=item C<sha512>
3388
3389Compute the SHA512 hash (using the C<sha512sum> program).
3390
3391=back
3392
3393The checksum is returned as a printable string.
3394
3395To get the checksum for a device, use C<guestfs_checksum_device>.
3396
3397To get the checksums for many files, use C<guestfs_checksums_out>." };
3398
3399  { defaults with
3400    name = "tar_in";
3401    style = RErr, [FileIn "tarfile"; Pathname "directory"], [];
3402    proc_nr = Some 69;
3403    cancellable = true;
3404    tests = [
3405      InitScratchFS, Always, TestOutput (
3406        [["mkdir"; "/tar_in"];
3407         ["tar_in"; "../data/helloworld.tar"; "/tar_in"];
3408         ["cat"; "/tar_in/hello"]], "hello\n")
3409    ];
3410    shortdesc = "unpack tarfile to directory";
3411    longdesc = "\
3412This command uploads and unpacks local file C<tarfile> (an
3413I<uncompressed> tar file) into C<directory>.
3414
3415To upload a compressed tarball, use C<guestfs_tgz_in>
3416or C<guestfs_txz_in>." };
3417
3418  { defaults with
3419    name = "tar_out";
3420    style = RErr, [String "directory"; FileOut "tarfile"], [];
3421    proc_nr = Some 70;
3422    cancellable = true;
3423    shortdesc = "pack directory into tarfile";
3424    longdesc = "\
3425This command packs the contents of C<directory> and downloads
3426it to local file C<tarfile>.
3427
3428To download a compressed tarball, use C<guestfs_tgz_out>
3429or C<guestfs_txz_out>." };
3430
3431  { defaults with
3432    name = "tgz_in";
3433    style = RErr, [FileIn "tarball"; Pathname "directory"], [];
3434    proc_nr = Some 71;
3435    cancellable = true;
3436    tests = [
3437      InitScratchFS, Always, TestOutput (
3438        [["mkdir"; "/tgz_in"];
3439         ["tgz_in"; "../data/helloworld.tar.gz"; "/tgz_in"];
3440         ["cat"; "/tgz_in/hello"]], "hello\n")
3441    ];
3442    shortdesc = "unpack compressed tarball to directory";
3443    longdesc = "\
3444This command uploads and unpacks local file C<tarball> (a
3445I<gzip compressed> tar file) into C<directory>.
3446
3447To upload an uncompressed tarball, use C<guestfs_tar_in>." };
3448
3449  { defaults with
3450    name = "tgz_out";
3451    style = RErr, [Pathname "directory"; FileOut "tarball"], [];
3452    proc_nr = Some 72;
3453    cancellable = true;
3454    shortdesc = "pack directory into compressed tarball";
3455    longdesc = "\
3456This command packs the contents of C<directory> and downloads
3457it to local file C<tarball>.
3458
3459To download an uncompressed tarball, use C<guestfs_tar_out>." };
3460
3461  { defaults with
3462    name = "mount_ro";
3463    style = RErr, [Device "device"; String "mountpoint"], [];
3464    proc_nr = Some 73;
3465    tests = [
3466      InitBasicFS, Always, TestLastFail (
3467        [["umount"; "/"];
3468         ["mount_ro"; "/dev/sda1"; "/"];
3469         ["touch"; "/new"]]);
3470      InitBasicFS, Always, TestOutput (
3471        [["write"; "/new"; "data"];
3472         ["umount"; "/"];
3473         ["mount_ro"; "/dev/sda1"; "/"];
3474         ["cat"; "/new"]], "data")
3475    ];
3476    shortdesc = "mount a guest disk, read-only";
3477    longdesc = "\
3478This is the same as the C<guestfs_mount> command, but it
3479mounts the filesystem with the read-only (I<-o ro>) flag." };
3480
3481  { defaults with
3482    name = "mount_options";
3483    style = RErr, [String "options"; Device "device"; String "mountpoint"], [];
3484    proc_nr = Some 74;
3485    shortdesc = "mount a guest disk with mount options";
3486    longdesc = "\
3487This is the same as the C<guestfs_mount> command, but it
3488allows you to set the mount options as for the
3489L<mount(8)> I<-o> flag.
3490
3491If the C<options> parameter is an empty string, then
3492no options are passed (all options default to whatever
3493the filesystem uses)." };
3494
3495  { defaults with
3496    name = "mount_vfs";
3497    style = RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"], [];
3498    proc_nr = Some 75;
3499    shortdesc = "mount a guest disk with mount options and vfstype";
3500    longdesc = "\
3501This is the same as the C<guestfs_mount> command, but it
3502allows you to set both the mount options and the vfstype
3503as for the L<mount(8)> I<-o> and I<-t> flags." };
3504
3505  { defaults with
3506    name = "debug";
3507    style = RString "result", [String "subcmd"; StringList "extraargs"], [];
3508    proc_nr = Some 76;
3509    in_docs = false;
3510    shortdesc = "debugging and internals";
3511    longdesc = "\
3512The C<guestfs_debug> command exposes some internals of
3513C<guestfsd> (the guestfs daemon) that runs inside the
3514qemu subprocess.
3515
3516There is no comprehensive help for this command.  You have
3517to look at the file C<daemon/debug.c> in the libguestfs source
3518to find out what you can do." };
3519
3520  { defaults with
3521    name = "lvremove";
3522    style = RErr, [Device "device"], [];
3523    proc_nr = Some 77;
3524    optional = Some "lvm2";
3525    tests = [
3526      InitEmpty, Always, TestOutputList (
3527        [["part_disk"; "/dev/sda"; "mbr"];
3528         ["pvcreate"; "/dev/sda1"];
3529         ["vgcreate"; "VG"; "/dev/sda1"];
3530         ["lvcreate"; "LV1"; "VG"; "50"];
3531         ["lvcreate"; "LV2"; "VG"; "50"];
3532         ["lvremove"; "/dev/VG/LV1"];
3533         ["lvs"]], ["/dev/VG/LV2"]);
3534      InitEmpty, Always, TestOutputList (
3535        [["part_disk"; "/dev/sda"; "mbr"];
3536         ["pvcreate"; "/dev/sda1"];
3537         ["vgcreate"; "VG"; "/dev/sda1"];
3538         ["lvcreate"; "LV1"; "VG"; "50"];
3539         ["lvcreate"; "LV2"; "VG"; "50"];
3540         ["lvremove"; "/dev/VG"];
3541         ["lvs"]], []);
3542      InitEmpty, Always, TestOutputList (
3543        [["part_disk"; "/dev/sda"; "mbr"];
3544         ["pvcreate"; "/dev/sda1"];
3545         ["vgcreate"; "VG"; "/dev/sda1"];
3546         ["lvcreate"; "LV1"; "VG"; "50"];
3547         ["lvcreate"; "LV2"; "VG"; "50"];
3548         ["lvremove"; "/dev/VG"];
3549         ["vgs"]], ["VG"])
3550    ];
3551    shortdesc = "remove an LVM logical volume";
3552    longdesc = "\
3553Remove an LVM logical volume C<device>, where C<device> is
3554the path to the LV, such as C</dev/VG/LV>.
3555
3556You can also remove all LVs in a volume group by specifying
3557the VG name, C</dev/VG>." };
3558
3559  { defaults with
3560    name = "vgremove";
3561    style = RErr, [String "vgname"], [];
3562    proc_nr = Some 78;
3563    optional = Some "lvm2";
3564    tests = [
3565      InitEmpty, Always, TestOutputList (
3566        [["part_disk"; "/dev/sda"; "mbr"];
3567         ["pvcreate"; "/dev/sda1"];
3568         ["vgcreate"; "VG"; "/dev/sda1"];
3569         ["lvcreate"; "LV1"; "VG"; "50"];
3570         ["lvcreate"; "LV2"; "VG"; "50"];
3571         ["vgremove"; "VG"];
3572         ["lvs"]], []);
3573      InitEmpty, Always, TestOutputList (
3574        [["part_disk"; "/dev/sda"; "mbr"];
3575         ["pvcreate"; "/dev/sda1"];
3576         ["vgcreate"; "VG"; "/dev/sda1"];
3577         ["lvcreate"; "LV1"; "VG"; "50"];
3578         ["lvcreate"; "LV2"; "VG"; "50"];
3579         ["vgremove"; "VG"];
3580         ["vgs"]], [])
3581    ];
3582    shortdesc = "remove an LVM volume group";
3583    longdesc = "\
3584Remove an LVM volume group C<vgname>, (for example C<VG>).
3585
3586This also forcibly removes all logical volumes in the volume
3587group (if any)." };
3588
3589  { defaults with
3590    name = "pvremove";
3591    style = RErr, [Device "device"], [];
3592    proc_nr = Some 79;
3593    optional = Some "lvm2";
3594    tests = [
3595      InitEmpty, Always, TestOutputListOfDevices (
3596        [["part_disk"; "/dev/sda"; "mbr"];
3597         ["pvcreate"; "/dev/sda1"];
3598         ["vgcreate"; "VG"; "/dev/sda1"];
3599         ["lvcreate"; "LV1"; "VG"; "50"];
3600         ["lvcreate"; "LV2"; "VG"; "50"];
3601         ["vgremove"; "VG"];
3602         ["pvremove"; "/dev/sda1"];
3603         ["lvs"]], []);
3604      InitEmpty, Always, TestOutputListOfDevices (
3605        [["part_disk"; "/dev/sda"; "mbr"];
3606         ["pvcreate"; "/dev/sda1"];
3607         ["vgcreate"; "VG"; "/dev/sda1"];
3608         ["lvcreate"; "LV1"; "VG"; "50"];
3609         ["lvcreate"; "LV2"; "VG"; "50"];
3610         ["vgremove"; "VG"];
3611         ["pvremove"; "/dev/sda1"];
3612         ["vgs"]], []);
3613      InitEmpty, Always, TestOutputListOfDevices (
3614        [["part_disk"; "/dev/sda"; "mbr"];
3615         ["pvcreate"; "/dev/sda1"];
3616         ["vgcreate"; "VG"; "/dev/sda1"];
3617         ["lvcreate"; "LV1"; "VG"; "50"];
3618         ["lvcreate"; "LV2"; "VG"; "50"];
3619         ["vgremove"; "VG"];
3620         ["pvremove"; "/dev/sda1"];
3621         ["pvs"]], [])
3622    ];
3623    shortdesc = "remove an LVM physical volume";
3624    longdesc = "\
3625This wipes a physical volume C<device> so that LVM will no longer
3626recognise it.
3627
3628The implementation uses the C<pvremove> command which refuses to
3629wipe physical volumes that contain any volume groups, so you have
3630to remove those first." };
3631
3632  { defaults with
3633    name = "set_e2label";
3634    style = RErr, [Device "device"; String "label"], [];
3635    proc_nr = Some 80;
3636    deprecated_by = Some "set_label";
3637    tests = [
3638      InitBasicFS, Always, TestOutput (
3639        [["set_e2label"; "/dev/sda1"; "testlabel"];
3640         ["get_e2label"; "/dev/sda1"]], "testlabel")
3641    ];
3642    shortdesc = "set the ext2/3/4 filesystem label";
3643    longdesc = "\
3644This sets the ext2/3/4 filesystem label of the filesystem on
3645C<device> to C<label>.  Filesystem labels are limited to
364616 characters.
3647
3648You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
3649to return the existing label on a filesystem." };
3650
3651  { defaults with
3652    name = "get_e2label";
3653    style = RString "label", [Device "device"], [];
3654    proc_nr = Some 81;
3655    deprecated_by = Some "vfs_label";
3656    shortdesc = "get the ext2/3/4 filesystem label";
3657    longdesc = "\
3658This returns the ext2/3/4 filesystem label of the filesystem on
3659C<device>." };
3660
3661  { defaults with
3662    name = "set_e2uuid";
3663    style = RErr, [Device "device"; String "uuid"], [];
3664    proc_nr = Some 82;
3665    tests = 
3666      (let uuid = uuidgen () in [
3667        InitBasicFS, Always, TestOutput (
3668          [["set_e2uuid"; "/dev/sda1"; uuid];
3669           ["get_e2uuid"; "/dev/sda1"]], uuid);
3670        InitBasicFS, Always, TestOutput (
3671          [["set_e2uuid"; "/dev/sda1"; "clear"];
3672           ["get_e2uuid"; "/dev/sda1"]], "");
3673        (* We can't predict what UUIDs will be, so just check
3674           the commands run. *)
3675        InitBasicFS, Always, TestRun (
3676          [["set_e2uuid"; "/dev/sda1"; "random"]]);
3677        InitBasicFS, Always, TestRun (
3678          [["set_e2uuid"; "/dev/sda1"; "time"]])
3679      ]);
3680    shortdesc = "set the ext2/3/4 filesystem UUID";
3681    longdesc = "\
3682This sets the ext2/3/4 filesystem UUID of the filesystem on
3683C<device> to C<uuid>.  The format of the UUID and alternatives
3684such as C<clear>, C<random> and C<time> are described in the
3685L<tune2fs(8)> manpage.
3686
3687You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
3688to return the existing UUID of a filesystem." };
3689
3690  { defaults with
3691    name = "get_e2uuid";
3692    style = RString "uuid", [Device "device"], [];
3693    proc_nr = Some 83;
3694    deprecated_by = Some "vfs_uuid";
3695    tests =
3696      (* Regression test for RHBZ#597112. *)
3697      (let uuid = uuidgen () in [
3698        InitNone, Always, TestOutput (
3699          [["mke2journal"; "1024"; "/dev/sdc"];
3700           ["set_e2uuid"; "/dev/sdc"; uuid];
3701           ["get_e2uuid"; "/dev/sdc"]], uuid)
3702      ]);
3703      shortdesc = "get the ext2/3/4 filesystem UUID";
3704      longdesc = "\
3705This returns the ext2/3/4 filesystem UUID of the filesystem on
3706C<device>." };
3707
3708  { defaults with
3709    name = "fsck";
3710    style = RInt "status", [String "fstype"; Device "device"], [];
3711    proc_nr = Some 84;
3712    fish_output = Some FishOutputHexadecimal;
3713    tests = [
3714      InitBasicFS, Always, TestOutputInt (
3715        [["umount"; "/dev/sda1"];
3716         ["fsck"; "ext2"; "/dev/sda1"]], 0);
3717      InitBasicFS, Always, TestOutputInt (
3718        [["umount"; "/dev/sda1"];
3719         ["zero"; "/dev/sda1"];
3720         ["fsck"; "ext2"; "/dev/sda1"]], 8)
3721    ];
3722    shortdesc = "run the filesystem checker";
3723    longdesc = "\
3724This runs the filesystem checker (fsck) on C<device> which
3725should have filesystem type C<fstype>.
3726
3727The returned integer is the status.  See L<fsck(8)> for the
3728list of status codes from C<fsck>.
3729
3730Notes:
3731
3732=over 4
3733
3734=item *
3735
3736Multiple status codes can be summed together.
3737
3738=item *
3739
3740A non-zero return code can mean \"success\", for example if
3741errors have been corrected on the filesystem.
3742
3743=item *
3744
3745Checking or repairing NTFS volumes is not supported
3746(by linux-ntfs).
3747
3748=back
3749
3750This command is entirely equivalent to running C<fsck -a -t fstype device>." };
3751
3752  { defaults with
3753    name = "zero";
3754    style = RErr, [Device "device"], [];
3755    proc_nr = Some 85;
3756    progress = true;
3757    tests = [
3758      InitBasicFS, Always, TestRun (
3759        [["umount"; "/dev/sda1"];
3760         ["zero"; "/dev/sda1"]])
3761    ];
3762    shortdesc = "write zeroes to the device";
3763    longdesc = "\
3764This command writes zeroes over the first few blocks of C<device>.
3765
3766How many blocks are zeroed isn't specified (but it's I<not> enough
3767to securely wipe the device).  It should be sufficient to remove
3768any partition tables, filesystem superblocks and so on.
3769
3770If blocks are already zero, then this command avoids writing
3771zeroes.  This prevents the underlying device from becoming non-sparse
3772or growing unnecessarily.
3773
3774See also: C<guestfs_zero_device>, C<guestfs_scrub_device>,
3775C<guestfs_is_zero_device>" };
3776
3777  { defaults with
3778    name = "grub_install";
3779    style = RErr, [Pathname "root"; Device "device"], [];
3780    proc_nr = Some 86;
3781    optional = Some "grub";
3782    (* See:
3783     * https://bugzilla.redhat.com/show_bug.cgi?id=484986
3784     * https://bugzilla.redhat.com/show_bug.cgi?id=479760
3785     *)
3786    tests = [
3787      InitBasicFS, Always, TestOutputTrue (
3788        [["mkdir_p"; "/boot/grub"];
3789         ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
3790         ["grub_install"; "/"; "/dev/vda"];
3791         ["is_dir"; "/boot"]])
3792    ];
3793    shortdesc = "install GRUB 1";
3794    longdesc = "\
3795This command installs GRUB 1 (the Grand Unified Bootloader) on
3796C<device>, with the root directory being C<root>.
3797
3798Notes:
3799
3800=over 4
3801
3802=item *
3803
3804There is currently no way in the API to install grub2, which
3805is used by most modern Linux guests.  It is possible to run
3806the grub2 command from the guest, although see the
3807caveats in L<guestfs(3)/RUNNING COMMANDS>.
3808
3809=item *
3810
3811This uses C<grub-install> from the host.  Unfortunately grub is
3812not always compatible with itself, so this only works in rather
3813narrow circumstances.  Careful testing with each guest version
3814is advisable.
3815
3816=item *
3817
3818If grub-install reports the error
3819\"No suitable drive was found in the generated device map.\"
3820it may be that you need to create a C</boot/grub/device.map>
3821file first that contains the mapping between grub device names
3822and Linux device names.  It is usually sufficient to create
3823a file containing:
3824
3825 (hd0) /dev/vda
3826
3827replacing C</dev/vda> with the name of the installation device.
3828
3829=back" };
3830
3831  { defaults with
3832    name = "cp";
3833    style = RErr, [Pathname "src"; Pathname "dest"], [];
3834    proc_nr = Some 87;
3835    tests = [
3836      InitScratchFS, Always, TestOutput (
3837        [["mkdir"; "/cp"];
3838         ["write"; "/cp/old"; "file content"];
3839         ["cp"; "/cp/old"; "/cp/new"];
3840         ["cat"; "/cp/new"]], "file content");
3841      InitScratchFS, Always, TestOutputTrue (
3842        [["mkdir"; "/cp2"];
3843         ["write"; "/cp2/old"; "file content"];
3844         ["cp"; "/cp2/old"; "/cp2/new"];
3845         ["is_file"; "/cp2/old"]]);
3846      InitScratchFS, Always, TestOutput (
3847        [["mkdir"; "/cp3"];
3848         ["write"; "/cp3/old"; "file content"];
3849         ["mkdir"; "/cp3/dir"];
3850         ["cp"; "/cp3/old"; "/cp3/dir/new"];
3851         ["cat"; "/cp3/dir/new"]], "file content")
3852    ];
3853    shortdesc = "copy a file";
3854    longdesc = "\
3855This copies a file from C<src> to C<dest> where C<dest> is
3856either a destination filename or destination directory." };
3857
3858  { defaults with
3859    name = "cp_a";
3860    style = RErr, [Pathname "src"; Pathname "dest"], [];
3861    proc_nr = Some 88;
3862    tests = [
3863      InitScratchFS, Always, TestOutput (
3864        [["mkdir"; "/cp_a1"];
3865         ["mkdir"; "/cp_a2"];
3866         ["write"; "/cp_a1/file"; "file content"];
3867         ["cp_a"; "/cp_a1"; "/cp_a2"];
3868         ["cat"; "/cp_a2/cp_a1/file"]], "file content")
3869    ];
3870    shortdesc = "copy a file or directory recursively";
3871    longdesc = "\
3872This copies a file or directory from C<src> to C<dest>
3873recursively using the C<cp -a> command." };
3874
3875  { defaults with
3876    name = "mv";
3877    style = RErr, [Pathname "src"; Pathname "dest"], [];
3878    proc_nr = Some 89;
3879    tests = [
3880      InitScratchFS, Always, TestOutput (
3881        [["mkdir"; "/mv"];
3882         ["write"; "/mv/old"; "file content"];
3883         ["mv"; "/mv/old"; "/mv/new"];
3884         ["cat"; "/mv/new"]], "file content");
3885      InitScratchFS, Always, TestOutputFalse (
3886        [["mkdir"; "/mv2"];
3887         ["write"; "/mv2/old"; "file content"];
3888         ["mv"; "/mv2/old"; "/mv2/new"];
3889         ["is_file"; "/mv2/old"]])
3890    ];
3891    shortdesc = "move a file";
3892    longdesc = "\
3893This moves a file from C<src> to C<dest> where C<dest> is
3894either a destination filename or destination directory." };
3895
3896  { defaults with
3897    name = "drop_caches";
3898    style = RErr, [Int "whattodrop"], [];
3899    proc_nr = Some 90;
3900    tests = [
3901      InitEmpty, Always, TestRun (
3902        [["drop_caches"; "3"]])
3903    ];
3904    shortdesc = "drop kernel page cache, dentries and inodes";
3905    longdesc = "\
3906This instructs the guest kernel to drop its page cache,
3907and/or dentries and inode caches.  The parameter C<whattodrop>
3908tells the kernel what precisely to drop, see
3909L<http://linux-mm.org/Drop_Caches>
3910
3911Setting C<whattodrop> to 3 should drop everything.
3912
3913This automatically calls L<sync(2)> before the operation,
3914so that the maximum guest memory is freed." };
3915
3916  { defaults with
3917    name = "dmesg";
3918    style = RString "kmsgs", [], [];
3919    proc_nr = Some 91;
3920    tests = [
3921      InitEmpty, Always, TestRun (
3922        [["dmesg"]])
3923    ];
3924    shortdesc = "return kernel messages";
3925    longdesc = "\
3926This returns the kernel messages (C<dmesg> output) from
3927the guest kernel.  This is sometimes useful for extended
3928debugging of problems.
3929
3930Another way to get the same information is to enable
3931verbose messages with C<guestfs_set_verbose> or by setting
3932the environment variable C<LIBGUESTFS_DEBUG=1> before
3933running the program." };
3934
3935  { defaults with
3936    name = "ping_daemon";
3937    style = RErr, [], [];
3938    proc_nr = Some 92;
3939    tests = [
3940      InitEmpty, Always, TestRun (
3941        [["ping_daemon"]])
3942    ];
3943    shortdesc = "ping the guest daemon";
3944    longdesc = "\
3945This is a test probe into the guestfs daemon running inside
3946the qemu subprocess.  Calling this function checks that the
3947daemon responds to the ping message, without affecting the daemon
3948or attached block device(s) in any other way." };
3949
3950  { defaults with
3951    name = "equal";
3952    style = RBool "equality", [Pathname "file1"; Pathname "file2"], [];
3953    proc_nr = Some 93;
3954    tests = [
3955      InitScratchFS, Always, TestOutputTrue (
3956        [["mkdir"; "/equal"];
3957         ["write"; "/equal/file1"; "contents of a file"];
3958         ["cp"; "/equal/file1"; "/equal/file2"];
3959         ["equal"; "/equal/file1"; "/equal/file2"]]);
3960      InitScratchFS, Always, TestOutputFalse (
3961        [["mkdir"; "/equal2"];
3962         ["write"; "/equal2/file1"; "contents of a file"];
3963         ["write"; "/equal2/file2"; "contents of another file"];
3964         ["equal"; "/equal2/file1"; "/equal2/file2"]]);
3965      InitScratchFS, Always, TestLastFail (
3966        [["mkdir"; "/equal3"];
3967         ["equal"; "/equal3/file1"; "/equal3/file2"]])
3968    ];
3969    shortdesc = "test if two files have equal contents";
3970    longdesc = "\
3971This compares the two files C<file1> and C<file2> and returns
3972true if their content is exactly equal, or false otherwise.
3973
3974The external L<cmp(1)> program is used for the comparison." };
3975
3976  { defaults with
3977    name = "strings";
3978    style = RStringList "stringsout", [Pathname "path"], [];
3979    proc_nr = Some 94;
3980    protocol_limit_warning = true;
3981    tests = [
3982      InitISOFS, Always, TestOutputList (
3983        [["strings"; "/known-5"]], ["abcdefghi"; "jklmnopqr"]);
3984      InitISOFS, Always, TestOutputList (
3985        [["strings"; "/empty"]], []);
3986      (* Test for RHBZ#579608, absolute symbolic links. *)
3987      InitISOFS, Always, TestRun (
3988        [["strings"; "/abssymlink"]])
3989    ];
3990    shortdesc = "print the printable strings in a file";
3991    longdesc = "\
3992This runs the L<strings(1)> command on a file and returns
3993the list of printable strings found." };
3994
3995  { defaults with
3996    name = "strings_e";
3997    style = RStringList "stringsout", [String "encoding"; Pathname "path"], [];
3998    proc_nr = Some 95;
3999    protocol_limit_warning = true;
4000    tests = [
4001      InitISOFS, Always, TestOutputList (
4002        [["strings_e"; "b"; "/known-5"]], []);
4003      InitScratchFS, Always, TestOutputList (
4004        [["write"; "/strings_e"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"];
4005         ["strings_e"; "b"; "/strings_e"]], ["hello"; "world"])
4006    ];
4007    shortdesc = "print the printable strings in a file";
4008    longdesc = "\
4009This is like the C<guestfs_strings> command, but allows you to
4010specify the encoding of strings that are looked for in
4011the source file C<path>.
4012
4013Allowed encodings are:
4014
4015=over 4
4016
4017=item s
4018
4019Single 7-bit-byte characters like ASCII and the ASCII-compatible
4020parts of ISO-8859-X (this is what C<guestfs_strings> uses).
4021
4022=item S
4023
4024Single 8-bit-byte characters.
4025
4026=item b
4027
402816-bit big endian strings such as those encoded in
4029UTF-16BE or UCS-2BE.
4030
4031=item l (lower case letter L)
4032
403316-bit little endian such as UTF-16LE and UCS-2LE.
4034This is useful for examining binaries in Windows guests.
4035
4036=item B
4037
403832-bit big endian such as UCS-4BE.
4039
4040=item L
4041
404232-bit little endian such as UCS-4LE.
4043
4044=back
4045
4046The returned strings are transcoded to UTF-8." };
4047
4048  { defaults with
4049    name = "hexdump";
4050    style = RString "dump", [Pathname "path"], [];
4051    proc_nr = Some 96;
4052    protocol_limit_warning = true;
4053    tests = [
4054      InitISOFS, Always, TestOutput (
4055        [["hexdump"; "/known-4"]], "00000000  61 62 63 0a 64 65 66 0a  67 68 69                 |abc.def.ghi|\n0000000b\n");
4056      (* Test for RHBZ#501888c2 regression which caused large hexdump
4057       * commands to segfault.
4058       *)
4059      InitISOFS, Always, TestRun (
4060        [["hexdump"; "/100krandom"]]);
4061      (* Test for RHBZ#579608, absolute symbolic links. *)
4062      InitISOFS, Always, TestRun (
4063        [["hexdump"; "/abssymlink"]])
4064    ];
4065    shortdesc = "dump a file in hexadecimal";
4066    longdesc = "\
4067This runs C<hexdump -C> on the given C<path>.  The result is
4068the human-readable, canonical hex dump of the file." };
4069
4070  { defaults with
4071    name = "zerofree";
4072    style = RErr, [Device "device"], [];
4073    proc_nr = Some 97;
4074    optional = Some "zerofree";
4075    tests = [
4076      InitNone, Always, TestOutput (
4077        [["part_disk"; "/dev/sda"; "mbr"];
4078         ["mkfs"; "ext3"; "/dev/sda1"; ""; "NOARG"; ""; ""];
4079         ["mount_options"; ""; "/dev/sda1"; "/"];
4080         ["write"; "/new"; "test file"];
4081         ["umount"; "/dev/sda1"];
4082         ["zerofree"; "/dev/sda1"];
4083         ["mount_options"; ""; "/dev/sda1"; "/"];
4084         ["cat"; "/new"]], "test file")
4085    ];
4086    shortdesc = "zero unused inodes and disk blocks on ext2/3 filesystem";
4087    longdesc = "\
4088This runs the I<zerofree> program on C<device>.  This program
4089claims to zero unused inodes and disk blocks on an ext2/3
4090filesystem, thus making it possible to compress the filesystem
4091more effectively.
4092
4093You should B<not> run this program if the filesystem is
4094mounted.
4095
4096It is possible that using this program can damage the filesystem
4097or data on the filesystem." };
4098
4099  { defaults with
4100    name = "pvresize";
4101    style = RErr, [Device "device"], [];
4102    proc_nr = Some 98;
4103    optional = Some "lvm2";
4104    shortdesc = "resize an LVM physical volume";
4105    longdesc = "\
4106This resizes (expands or shrinks) an existing LVM physical
4107volume to match the new size of the underlying device." };
4108
4109  { defaults with
4110    name = "sfdisk_N";
4111    style = RErr, [Device "device"; Int "partnum";
4112                   Int "cyls"; Int "heads"; Int "sectors";
4113                   String "line"], [];
4114    proc_nr = Some 99;
4115    deprecated_by = Some "part_add";
4116    shortdesc = "modify a single partition on a block device";
4117    longdesc = "\
4118This runs L<sfdisk(8)> option to modify just the single
4119partition C<n> (note: C<n> counts from 1).
4120
4121For other parameters, see C<guestfs_sfdisk>.  You should usually
4122pass C<0> for the cyls/heads/sectors parameters.
4123
4124See also: C<guestfs_part_add>" };
4125
4126  { defaults with
4127    name = "sfdisk_l";
4128    style = RString "partitions", [Device "device"], [];
4129    proc_nr = Some 100;
4130    deprecated_by = Some "part_list";
4131    shortdesc = "display the partition table";
4132    longdesc = "\
4133This displays the partition table on C<device>, in the
4134human-readable output of the L<sfdisk(8)> command.  It is
4135not intended to be parsed.
4136
4137See also: C<guestfs_part_list>" };
4138
4139  { defaults with
4140    name = "sfdisk_kernel_geometry";
4141    style = RString "partitions", [Device "device"], [];
4142    proc_nr = Some 101;
4143    shortdesc = "display the kernel geometry";
4144    longdesc = "\
4145This displays the kernel's idea of the geometry of C<device>.
4146
4147The result is in human-readable format, and not designed to
4148be parsed." };
4149
4150  { defaults with
4151    name = "sfdisk_disk_geometry";
4152    style = RString "partitions", [Device "device"], [];
4153    proc_nr = Some 102;
4154    shortdesc = "display the disk geometry from the partition table";
4155    longdesc = "\
4156This displays the disk geometry of C<device> read from the
4157partition table.  Especially in the case where the underlying
4158block device has been resized, this can be different from the
4159kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
4160
4161The result is in human-readable format, and not designed to
4162be parsed." };
4163
4164  { defaults with
4165    name = "vg_activate_all";
4166    style = RErr, [Bool "activate"], [];
4167    proc_nr = Some 103;
4168    optional = Some "lvm2";
4169    shortdesc = "activate or deactivate all volume groups";
4170    longdesc = "\
4171This command activates or (if C<activate> is false) deactivates
4172all logical volumes in all volume groups.
4173
4174This command is the same as running C<vgchange -a y|n>" };
4175
4176  { defaults with
4177    name = "vg_activate";
4178    style = RErr, [Bool "activate"; StringList "volgroups"], [];
4179    proc_nr = Some 104;
4180    optional = Some "lvm2";
4181    shortdesc = "activate or deactivate some volume groups";
4182    longdesc = "\
4183This command activates or (if C<activate> is false) deactivates
4184all logical volumes in the listed volume groups C<volgroups>.
4185
4186This command is the same as running C<vgchange -a y|n volgroups...>
4187
4188Note that if C<volgroups> is an empty list then B<all> volume groups
4189are activated or deactivated." };
4190
4191  { defaults with
4192    name = "lvresize";
4193    style = RErr, [Device "device"; Int "mbytes"], [];
4194    proc_nr = Some 105;
4195    optional = Some "lvm2";
4196    tests = [
4197      InitNone, Always, TestOutput (
4198        [["part_disk"; "/dev/sda"; "mbr"];
4199         ["pvcreate"; "/dev/sda1"];
4200         ["vgcreate"; "VG"; "/dev/sda1"];
4201         ["lvcreate"; "LV"; "VG"; "10"];
4202         ["mkfs"; "ext2"; "/dev/VG/LV"; ""; "NOARG"; ""; ""];
4203         ["mount_options"; ""; "/dev/VG/LV"; "/"];
4204         ["write"; "/new"; "test content"];
4205         ["umount"; "/"];
4206         ["lvresize"; "/dev/VG/LV"; "20"];
4207         ["e2fsck_f"; "/dev/VG/LV"];
4208         ["e2fsck"; "/dev/VG/LV"; "true"; "false"];
4209         ["e2fsck"; "/dev/VG/LV"; "false"; "true"];
4210         ["resize2fs"; "/dev/VG/LV"];
4211         ["mount_options"; ""; "/dev/VG/LV"; "/"];
4212         ["cat"; "/new"]], "test content");
4213      InitNone, Always, TestRun (
4214        (* Make an LV smaller to test RHBZ#587484. *)
4215        [["part_disk"; "/dev/sda"; "mbr"];
4216         ["pvcreate"; "/dev/sda1"];
4217         ["vgcreate"; "VG"; "/dev/sda1"];
4218         ["lvcreate"; "LV"; "VG"; "20"];
4219         ["lvresize"; "/dev/VG/LV"; "10"]])
4220    ];
4221    shortdesc = "resize an LVM logical volume";
4222    longdesc = "\
4223This resizes (expands or shrinks) an existing LVM logical
4224volume to C<mbytes>.  When reducing, data in the reduced part
4225is lost." };
4226
4227  { defaults with
4228    name = "resize2fs";
4229    style = RErr, [Device "device"], [];
4230    proc_nr = Some 106;
4231    shortdesc = "resize an ext2, ext3 or ext4 filesystem";
4232    longdesc = "\
4233This resizes an ext2, ext3 or ext4 filesystem to match the size of
4234the underlying device.
4235
4236See also L<guestfs(3)/RESIZE2FS ERRORS>." };
4237
4238  { defaults with
4239    name = "find";
4240    style = RStringList "names", [Pathname "directory"], [];
4241    proc_nr = Some 107;
4242    protocol_limit_warning = true;
4243    tests = [
4244      InitBasicFS, Always, TestOutputList (
4245        [["find"; "/"]], ["lost+found"]);
4246      InitBasicFS, Always, TestOutputList (
4247        [["touch"; "/a"];
4248         ["mkdir"; "/b"];
4249         ["touch"; "/b/c"];
4250         ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
4251      InitScratchFS, Always, TestOutputList (
4252        [["mkdir_p"; "/find/b/c"];
4253         ["touch"; "/find/b/c/d"];
4254         ["find"; "/find/b/"]], ["c"; "c/d"])
4255    ];
4256    shortdesc = "find all files and directories";
4257    longdesc = "\
4258This command lists out all files and directories, recursively,
4259starting at C<directory>.  It is essentially equivalent to
4260running the shell command C<find directory -print> but some
4261post-processing happens on the output, described below.
4262
4263This returns a list of strings I<without any prefix>.  Thus
4264if the directory structure was:
4265
4266 /tmp/a
4267 /tmp/b
4268 /tmp/c/d
4269
4270then the returned list from C<guestfs_find> C</tmp> would be
42714 elements:
4272
4273 a
4274 b
4275 c
4276 c/d
4277
4278If C<directory> is not a directory, then this command returns
4279an error.
4280
4281The returned list is sorted.
4282
4283See also C<guestfs_find0>." };
4284
4285  { defaults with
4286    name = "e2fsck_f";
4287    style = RErr, [Device "device"], [];
4288    proc_nr = Some 108;
4289    deprecated_by = Some "e2fsck";
4290    shortdesc = "check an ext2/ext3 filesystem";
4291    longdesc = "\
4292This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
4293filesystem checker on C<device>, noninteractively (I<-p>),
4294even if the filesystem appears to be clean (I<-f>)." };
4295
4296  { defaults with
4297    name = "sleep";
4298    style = RErr, [Int "secs"], [];
4299    proc_nr = Some 109;
4300    tests = [
4301      InitNone, Always, TestRun (
4302        [["sleep"; "1"]])
4303    ];
4304    shortdesc = "sleep for some seconds";
4305    longdesc = "\
4306Sleep for C<secs> seconds." };
4307
4308  { defaults with
4309    name = "ntfs_3g_probe";
4310    style = RInt "status", [Bool "rw"; Device "device"], [];
4311    proc_nr = Some 110;
4312    optional = Some "ntfs3g";
4313    tests = [
4314      InitNone, Always, TestOutputInt (
4315        [["part_disk"; "/dev/sda"; "mbr"];
4316         ["mkfs"; "ntfs"; "/dev/sda1"; ""; "NOARG"; ""; ""];
4317         ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
4318      InitNone, Always, TestOutputInt (
4319        [["part_disk"; "/dev/sda"; "mbr"];
4320         ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""];
4321         ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)
4322    ];
4323    shortdesc = "probe NTFS volume";
4324    longdesc = "\
4325This command runs the L<ntfs-3g.probe(8)> command which probes
4326an NTFS C<device> for mountability.  (Not all NTFS volumes can
4327be mounted read-write, and some cannot be mounted at all).
4328
4329C<rw> is a boolean flag.  Set it to true if you want to test
4330if the volume can be mounted read-write.  Set it to false if
4331you want to test if the volume can be mounted read-only.
4332
4333The return value is an integer which C<0> if the operation
4334would succeed, or some non-zero value documented in the
4335L<ntfs-3g.probe(8)> manual page." };
4336
4337  { defaults with
4338    name = "sh";
4339    style = RString "output", [String "command"], [];
4340    proc_nr = Some 111;
4341    tests = [] (* XXX needs tests *);
4342    shortdesc = "run a command via the shell";
4343    longdesc = "\
4344This call runs a command from the guest filesystem via the
4345guest's C</bin/sh>.
4346
4347This is like C<guestfs_command>, but passes the command to:
4348
4349 /bin/sh -c \"command\"
4350
4351Depending on the guest's shell, this usually results in
4352wildcards being expanded, shell expressions being interpolated
4353and so on.
4354
4355All the provisos about C<guestfs_command> apply to this call." };
4356
4357  { defaults with
4358    name = "sh_lines";
4359    style = RStringList "lines", [String "command"], [];
4360    proc_nr = Some 112;
4361    tests = [] (* XXX needs tests *);
4362    shortdesc = "run a command via the shell returning lines";
4363    longdesc = "\
4364This is the same as C<guestfs_sh>, but splits the result
4365into a list of lines.
4366
4367See also: C<guestfs_command_lines>" };
4368
4369  { defaults with
4370    name = "glob_expand";
4371    (* Use Pathname here, and hence ABS_PATH (pattern,...) in
4372     * generated code in stubs.c, since all valid glob patterns must
4373     * start with "/".  There is no concept of "cwd" in libguestfs,
4374     * hence no "."-relative names.
4375     *)
4376    style = RStringList "paths", [Pathname "pattern"], [];
4377    proc_nr = Some 113;
4378    tests = [
4379      InitScratchFS, Always, TestOutputList (
4380        [["mkdir_p"; "/glob_expand/b/c"];
4381         ["touch"; "/glob_expand/b/c/d"];
4382         ["touch"; "/glob_expand/b/c/e"];
4383         ["glob_expand"; "/glob_expand/b/c/*"]], ["/glob_expand/b/c/d"; "/glob_expand/b/c/e"]);
4384      InitScratchFS, Always, TestOutputList (
4385        [["mkdir_p"; "/glob_expand2/b/c"];
4386         ["touch"; "/glob_expand2/b/c/d"];
4387         ["touch"; "/glob_expand2/b/c/e"];
4388         ["glob_expand"; "/glob_expand2/*/c/*"]], ["/glob_expand2/b/c/d"; "/glob_expand2/b/c/e"]);
4389      InitScratchFS, Always, TestOutputList (
4390        [["mkdir_p"; "/glob_expand3/b/c"];
4391         ["touch"; "/glob_expand3/b/c/d"];
4392         ["touch"; "/glob_expand3/b/c/e"];
4393         ["glob_expand"; "/glob_expand3/*/x/*"]], [])
4394    ];
4395    shortdesc = "expand a wildcard path";
4396    longdesc = "\
4397This command searches for all the pathnames matching
4398C<pattern> according to the wildcard expansion rules
4399used by the shell.
4400
4401If no paths match, then this returns an empty list
4402(note: not an error).
4403
4404It is just a wrapper around the C L<glob(3)> function
4405with flags C<GLOB_MARK|GLOB_BRACE>.
4406See that manual page for more details.
4407
4408Notice that there is no equivalent command for expanding a device
4409name (eg. C</dev/sd*>).  Use C<guestfs_list_devices>,
4410C<guestfs_list_partitions> etc functions instead." };
4411
4412  { defaults with
4413    name = "scrub_device";
4414    style = RErr, [Device "device"], [];
4415    proc_nr = Some 114;
4416    optional = Some "scrub";
4417    tests = [
4418      InitNone, Always, TestRun (	(* use /dev/sdc because it's smaller *)
4419        [["scrub_device"; "/dev/sdc"]])
4420    ];
4421    shortdesc = "scrub (securely wipe) a device";
4422    longdesc = "\
4423This command writes patterns over C<device> to make data retrieval
4424more difficult.
4425
4426It is an interface to the L<scrub(1)> program.  See that
4427manual page for more details." };
4428
4429  { defaults with
4430    name = "scrub_file";
4431    style = RErr, [Pathname "file"], [];
4432    proc_nr = Some 115;
4433    optional = Some "scrub";
4434    tests = [
4435      InitScratchFS, Always, TestRun (
4436        [["write"; "/scrub_file"; "content"];
4437         ["scrub_file"; "/scrub_file"]])
4438    ];
4439    shortdesc = "scrub (securely wipe) a file";
4440    longdesc = "\
4441This command writes patterns over a file to make data retrieval
4442more difficult.
4443
4444The file is I<removed> after scrubbing.
4445
4446It is an interface to the L<scrub(1)> program.  See that
4447manual page for more details." };
4448
4449  { defaults with
4450    name = "scrub_freespace";
4451    style = RErr, [Pathname "dir"], [];
4452    proc_nr = Some 116;
4453    optional = Some "scrub";
4454    tests = [] (* XXX needs testing *);
4455    shortdesc = "scrub (securely wipe) free space";
4456    longdesc = "\
4457This command creates the directory C<dir> and then fills it
4458with files until the filesystem is full, and scrubs the files
4459as for C<guestfs_scrub_file>, and deletes them.
4460The intention is to scrub any free space on the partition
4461containing C<dir>.
4462
4463It is an interface to the L<scrub(1)> program.  See that
4464manual page for more details." };
4465
4466  { defaults with
4467    name = "mkdtemp";
4468    style = RString "dir", [Pathname "tmpl"], [];
4469    proc_nr = Some 117;
4470    tests = [
4471      InitScratchFS, Always, TestRun (
4472        [["mkdir"; "/mkdtemp"];
4473         ["mkdtemp"; "/mkdtemp/tmpXXXXXX"]])
4474    ];
4475    shortdesc = "create a temporary directory";
4476    longdesc = "\
4477This command creates a temporary directory.  The
4478C<tmpl> parameter should be a full pathname for the
4479temporary directory name with the final six characters being
4480\"XXXXXX\".
4481
4482For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
4483the second one being suitable for Windows filesystems.
4484
4485The name of the temporary directory that was created
4486is returned.
4487
4488The temporary directory is created with mode 0700
4489and is owned by root.
4490
4491The caller is responsible for deleting the temporary
4492directory and its contents after use.
4493
4494See also: L<mkdtemp(3)>" };
4495
4496  { defaults with
4497    name = "wc_l";
4498    style = RInt "lines", [Pathname "path"], [];
4499    proc_nr = Some 118;
4500    tests = [
4501      InitISOFS, Always, TestOutputInt (
4502        [["wc_l"; "/10klines"]], 10000);
4503      (* Test for RHBZ#579608, absolute symbolic links. *)
4504      InitISOFS, Always, TestOutputInt (
4505        [["wc_l"; "/abssymlink"]], 10000)
4506    ];
4507    shortdesc = "count lines in a file";
4508    longdesc = "\
4509This command counts the lines in a file, using the
4510C<wc -l> external command." };
4511
4512  { defaults with
4513    name = "wc_w";
4514    style = RInt "words", [Pathname "path"], [];
4515    proc_nr = Some 119;
4516    tests = [
4517      InitISOFS, Always, TestOutputInt (
4518        [["wc_w"; "/10klines"]], 10000)
4519    ];
4520    shortdesc = "count words in a file";
4521    longdesc = "\
4522This command counts the words in a file, using the
4523C<wc -w> external command." };
4524
4525  { defaults with
4526    name = "wc_c";
4527    style = RInt "chars", [Pathname "path"], [];
4528    proc_nr = Some 120;
4529    tests = [
4530      InitISOFS, Always, TestOutputInt (
4531        [["wc_c"; "/100kallspaces"]], 102400)
4532    ];
4533    shortdesc = "count characters in a file";
4534    longdesc = "\
4535This command counts the characters in a file, using the
4536C<wc -c> external command." };
4537
4538  { defaults with
4539    name = "head";
4540    style = RStringList "lines", [Pathname "path"], [];
4541    proc_nr = Some 121;
4542    protocol_limit_warning = true;
4543    tests = [
4544      InitISOFS, Always, TestOutputList (
4545        [["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"]);
4546      (* Test for RHBZ#579608, absolute symbolic links. *)
4547      InitISOFS, Always, TestOutputList (
4548        [["head"; "/abssymlink"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])
4549    ];
4550    shortdesc = "return first 10 lines of a file";
4551    longdesc = "\
4552This command returns up to the first 10 lines of a file as
4553a list of strings." };
4554
4555  { defaults with
4556    name = "head_n";
4557    style = RStringList "lines", [Int "nrlines"; Pathname "path"], [];
4558    proc_nr = Some 122;
4559    protocol_limit_warning = true;
4560    tests = [
4561      InitISOFS, Always, TestOutputList (
4562        [["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
4563      InitISOFS, Always, TestOutputList (
4564        [["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
4565      InitISOFS, Always, TestOutputList (
4566        [["head_n"; "0"; "/10klines"]], [])
4567    ];
4568    shortdesc = "return first N lines of a file";
4569    longdesc = "\
4570If the parameter C<nrlines> is a positive number, this returns the first
4571C<nrlines> lines of the file C<path>.
4572
4573If the parameter C<nrlines> is a negative number, this returns lines
4574from the file C<path>, excluding the last C<nrlines> lines.
4575
4576If the parameter C<nrlines> is zero, this returns an empty list." };
4577
4578  { defaults with
4579    name = "tail";
4580    style = RStringList "lines", [Pathname "path"], [];
4581    proc_nr = Some 123;
4582    protocol_limit_warning = true;
4583    tests = [
4584      InitISOFS, Always, TestOutputList (
4585        [["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])
4586    ];
4587    shortdesc = "return last 10 lines of a file";
4588    longdesc = "\
4589This command returns up to the last 10 lines of a file as
4590a list of strings." };
4591
4592  { defaults with
4593    name = "tail_n";
4594    style = RStringList "lines", [Int "nrlines"; Pathname "path"], [];
4595    proc_nr = Some 124;
4596    protocol_limit_warning = true;
4597    tests = [
4598      InitISOFS, Always, TestOutputList (
4599        [["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
4600      InitISOFS, Always, TestOutputList (
4601        [["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
4602      InitISOFS, Always, TestOutputList (
4603        [["tail_n"; "0"; "/10klines"]], [])
4604    ];
4605    shortdesc = "return last N lines of a file";
4606    longdesc = "\
4607If the parameter C<nrlines> is a positive number, this returns the last
4608C<nrlines> lines of the file C<path>.
4609
4610If the parameter C<nrlines> is a negative number, this returns lines
4611from the file C<path>, starting with the C<-nrlines>th line.
4612
4613If the parameter C<nrlines> is zero, this returns an empty list." };
4614
4615  { defaults with
4616    name = "df";
4617    style = RString "output", [], [];
4618    proc_nr = Some 125;
4619    tests = [] (* XXX Tricky to test because it depends on the exact format
4620                * of the 'df' command and other imponderables.
4621                *);
4622    shortdesc = "report file system disk space usage";
4623    longdesc = "\
4624This command runs the C<df> command to report disk space used.
4625
4626This command is mostly useful for interactive sessions.  It
4627is I<not> intended that you try to parse the output string.
4628Use C<guestfs_statvfs> from programs." };
4629
4630  { defaults with
4631    name = "df_h";
4632    style = RString "output", [], [];
4633    proc_nr = Some 126;
4634    tests = [] (* XXX Tricky to test because it depends on the exact format
4635                * of the 'df' command and other imponderables.
4636                *);
4637    shortdesc = "report file system disk space usage (human readable)";
4638    longdesc = "\
4639This command runs the C<df -h> command to report disk space used
4640in human-readable format.
4641
4642This command is mostly useful for interactive sessions.  It
4643is I<not> intended that you try to parse the output string.
4644Use C<guestfs_statvfs> from programs." };
4645
4646  { defaults with
4647    name = "du";
4648    style = RInt64 "sizekb", [Pathname "path"], [];
4649    proc_nr = Some 127;
4650    progress = true;
4651    tests = [
4652      InitISOFS, Always, TestOutputInt (
4653        [["du"; "/directory"]], 2 (* ISO fs blocksize is 2K *))
4654    ];
4655    shortdesc = "estimate file space usage";
4656    longdesc = "\
4657This command runs the C<du -s> command to estimate file space
4658usage for C<path>.
4659
4660C<path> can be a file or a directory.  If C<path> is a directory
4661then the estimate includes the contents of the directory and all
4662subdirectories (recursively).
4663
4664The result is the estimated size in I<kilobytes>
4665(ie. units of 1024 bytes)." };
4666
4667  { defaults with
4668    name = "initrd_list";
4669    style = RStringList "filenames", [Pathname "path"], [];
4670    proc_nr = Some 128;
4671    tests = [
4672      InitISOFS, Always, TestOutputList (
4673        [["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3";"known-4"; "known-5"])
4674    ];
4675    shortdesc = "list files in an initrd";
4676    longdesc = "\
4677This command lists out files contained in an initrd.
4678
4679The files are listed without any initial C</> character.  The
4680files are listed in the order they appear (not necessarily
4681alphabetical).  Directory names are listed as separate items.
4682
4683Old Linux kernels (2.4 and earlier) used a compressed ext2
4684filesystem as initrd.  We I<only> support the newer initramfs
4685format (compressed cpio files)." };
4686
4687  { defaults with
4688    name = "mount_loop";
4689    style = RErr, [Pathname "file"; Pathname "mountpoint"], [];
4690    proc_nr = Some 129;
4691    shortdesc = "mount a file using the loop device";
4692    longdesc = "\
4693This command lets you mount C<file> (a filesystem image
4694in a file) on a mount point.  It is entirely equivalent to
4695the command C<mount -o loop file mountpoint>." };
4696
4697  { defaults with
4698    name = "mkswap";
4699    style = RErr, [Device "device"], [];
4700    proc_nr = Some 130;
4701    tests = [
4702      InitEmpty, Always, TestRun (
4703        [["part_disk"; "/dev/sda"; "mbr"];
4704         ["mkswap"; "/dev/sda1"]])
4705    ];
4706    shortdesc = "create a swap partition";
4707    longdesc = "\
4708Create a swap partition on C<device>." };
4709
4710  { defaults with
4711    name = "mkswap_L";
4712    style = RErr, [String "label"; Device "device"], [];
4713    proc_nr = Some 131;
4714    tests = [
4715      InitEmpty, Always, TestRun (
4716        [["part_disk"; "/dev/sda"; "mbr"];
4717         ["mkswap_L"; "hello"; "/dev/sda1"]])
4718    ];
4719    shortdesc = "create a swap partition with a label";
4720    longdesc = "\
4721Create a swap partition on C<device> with label C<label>.
4722
4723Note that you cannot attach a swap label to a block device
4724(eg. C</dev/sda>), just to a partition.  This appears to be
4725a limitation of the kernel or swap tools." };
4726
4727  { defaults with
4728    name = "mkswap_U";
4729    style = RErr, [String "uuid"; Device "device"], [];
4730    proc_nr = Some 132;
4731    optional = Some "linuxfsuuid";
4732    tests =
4733      (let uuid = uuidgen () in [
4734        InitEmpty, Always, TestRun (
4735          [["part_disk"; "/dev/sda"; "mbr"];
4736           ["mkswap_U"; uuid; "/dev/sda1"]])
4737       ]);
4738    shortdesc = "create a swap partition with an explicit UUID";
4739    longdesc = "\
4740Create a swap partition on C<device> with UUID C<uuid>." };
4741
4742  { defaults with
4743    name = "mknod";
4744    style = RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], [];
4745    proc_nr = Some 133;
4746    optional = Some "mknod";
4747    tests = [
4748      InitScratchFS, Always, TestOutputStruct (
4749        [["mknod"; "0o10777"; "0"; "0"; "/mknod"];
4750         (* NB: default umask 022 means 0777 -> 0755 in these tests *)
4751         ["stat"; "/mknod"]], [CompareWithInt ("mode", 0o10755)]);
4752      InitScratchFS, Always, TestOutputStruct (
4753        [["mknod"; "0o60777"; "66"; "99"; "/mknod2"];
4754         ["stat"; "/mknod2"]], [CompareWithInt ("mode", 0o60755)])
4755    ];
4756    shortdesc = "make block, character or FIFO devices";
4757    longdesc = "\
4758This call creates block or character special devices, or
4759named pipes (FIFOs).
4760
4761The C<mode> parameter should be the mode, using the standard
4762constants.  C<devmajor> and C<devminor> are the
4763device major and minor numbers, only used when creating block
4764and character special devices.
4765
4766Note that, just like L<mknod(2)>, the mode must be bitwise
4767OR'd with S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call
4768just creates a regular file).  These constants are
4769available in the standard Linux header files, or you can use
4770C<guestfs_mknod_b>, C<guestfs_mknod_c> or C<guestfs_mkfifo>
4771which are wrappers around this command which bitwise OR
4772in the appropriate constant for you.
4773
4774The mode actually set is affected by the umask." };
4775
4776  { defaults with
4777    name = "mkfifo";
4778    style = RErr, [Int "mode"; Pathname "path"], [];
4779    proc_nr = Some 134;
4780    optional = Some "mknod";
4781    tests = [
4782      InitScratchFS, Always, TestOutputStruct (
4783        [["mkfifo"; "0o777"; "/mkfifo"];
4784         ["stat"; "/mkfifo"]], [CompareWithInt ("mode", 0o10755)])
4785    ];
4786    shortdesc = "make FIFO (named pipe)";
4787    longdesc = "\
4788This call creates a FIFO (named pipe) called C<path> with
4789mode C<mode>.  It is just a convenient wrapper around
4790C<guestfs_mknod>.
4791
4792The mode actually set is affected by the umask." };
4793
4794  { defaults with
4795    name = "mknod_b";
4796    style = RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], [];
4797    proc_nr = Some 135;
4798    optional = Some "mknod";
4799    tests = [
4800      InitScratchFS, Always, TestOutputStruct (
4801        [["mknod_b"; "0o777"; "99"; "66"; "/mknod_b"];
4802         ["stat"; "/mknod_b"]], [CompareWithInt ("mode", 0o60755)])
4803    ];
4804    shortdesc = "make block device node";
4805    longdesc = "\
4806This call creates a block device node called C<path> with
4807mode C<mode> and device major/minor C<devmajor> and C<devminor>.
4808It is just a convenient wrapper around C<guestfs_mknod>.
4809
4810The mode actually set is affected by the umask." };
4811
4812  { defaults with
4813    name = "mknod_c";
4814    style = RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], [];
4815    proc_nr = Some 136;
4816    optional = Some "mknod";
4817    tests = [
4818      InitScratchFS, Always, TestOutputStruct (
4819        [["mknod_c"; "0o777"; "99"; "66"; "/mknod_c"];
4820         ["stat"; "/mknod_c"]], [CompareWithInt ("mode", 0o20755)])
4821    ];
4822    shortdesc = "make char device node";
4823    longdesc = "\
4824This call creates a char device node called C<path> with
4825mode C<mode> and device major/minor C<devmajor> and C<devminor>.
4826It is just a convenient wrapper around C<guestfs_mknod>.
4827
4828The mode actually set is affected by the umask." };
4829
4830  { defaults with
4831    name = "umask";
4832    style = RInt "oldmask", [Int "mask"], [];
4833    proc_nr = Some 137;
4834    fish_output = Some FishOutputOctal;
4835    tests = [
4836      InitEmpty, Always, TestOutputInt (
4837        [["umask"; "0o22"]], 0o22)
4838    ];
4839    shortdesc = "set file mode creation mask (umask)";
4840    longdesc = "\
4841This function sets the mask used for creating new files and
4842device nodes to C<mask & 0777>.
4843
4844Typical umask values would be C<022> which creates new files
4845with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and
4846C<002> which creates new files with permissions like
4847\"-rw-rw-r--\" or \"-rwxrwxr-x\".
4848
4849The default umask is C<022>.  This is important because it
4850means that directories and device nodes will be created with
4851C<0644> or C<0755> mode even if you specify C<0777>.
4852
4853See also C<guestfs_get_umask>,
4854L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
4855
4856This call returns the previous umask." };
4857
4858  { defaults with
4859    name = "readdir";
4860    style = RStructList ("entries", "dirent"), [Pathname "dir"], [];
4861    proc_nr = Some 138;
4862    shortdesc = "read directories entries";
4863    longdesc = "\
4864This returns the list of directory entries in directory C<dir>.
4865
4866All entries in the directory are returned, including C<.> and
4867C<..>.  The entries are I<not> sorted, but returned in the same
4868order as the underlying filesystem.
4869
4870Also this call returns basic file type information about each
4871file.  The C<ftyp> field will contain one of the following characters:
4872
4873=over 4
4874
4875=item 'b'
4876
4877Block special
4878
4879=item 'c'
4880
4881Char special
4882
4883=item 'd'
4884
4885Directory
4886
4887=item 'f'
4888
4889FIFO (named pipe)
4890
4891=item 'l'
4892
4893Symbolic link
4894
4895=item 'r'
4896
4897Regular file
4898
4899=item 's'
4900
4901Socket
4902
4903=item 'u'
4904
4905Unknown file type
4906
4907=item '?'
4908
4909The L<readdir(3)> call returned a C<d_type> field with an
4910unexpected value
4911
4912=back
4913
4914This function is primarily intended for use by programs.  To
4915get a simple list of names, use C<guestfs_ls>.  To get a printable
4916directory for human consumption, use C<guestfs_ll>." };
4917
4918  { defaults with
4919    name = "sfdiskM";
4920    style = RErr, [Device "device"; StringList "lines"], [];
4921    proc_nr = Some 139;
4922    deprecated_by = Some "part_add";
4923    shortdesc = "create partitions on a block device";
4924    longdesc = "\
4925This is a simplified interface to the C<guestfs_sfdisk>
4926command, where partition sizes are specified in megabytes
4927only (rounded to the nearest cylinder) and you don't need
4928to specify the cyls, heads and sectors parameters which
4929were rarely if ever used anyway.
4930
4931See also: C<guestfs_sfdisk>, the L<sfdisk(8)> manpage
4932and C<guestfs_part_disk>" };
4933
4934  { defaults with
4935    name = "zfile";
4936    style = RString "description", [String "meth"; Pathname "path"], [];
4937    proc_nr = Some 140;
4938    deprecated_by = Some "file";
4939    shortdesc = "determine file type inside a compressed file";
4940    longdesc = "\
4941This command runs C<file> after first decompressing C<path>
4942using C<method>.
4943
4944C<method> must be one of C<gzip>, C<compress> or C<bzip2>.
4945
4946Since 1.0.63, use C<guestfs_file> instead which can now
4947process compressed files." };
4948
4949  { defaults with
4950    name = "getxattrs";
4951    style = RStructList ("xattrs", "xattr"), [Pathname "path"], [];
4952    proc_nr = Some 141;
4953    optional = Some "linuxxattrs";
4954    shortdesc = "list extended attributes of a file or directory";
4955    longdesc = "\
4956This call lists the extended attributes of the file or directory
4957C<path>.
4958
4959At the system call level, this is a combination of the
4960L<listxattr(2)> and L<getxattr(2)> calls.
4961
4962See also: C<guestfs_lgetxattrs>, L<attr(5)>." };
4963
4964  { defaults with
4965    name = "lgetxattrs";
4966    style = RStructList ("xattrs", "xattr"), [Pathname "path"], [];
4967    proc_nr = Some 142;
4968    optional = Some "linuxxattrs";
4969    shortdesc = "list extended attributes of a file or directory";
4970    longdesc = "\
4971This is the same as C<guestfs_getxattrs>, but if C<path>
4972is a symbolic link, then it returns the extended attributes
4973of the link itself." };
4974
4975  { defaults with
4976    name = "setxattr";
4977    style = RErr, [String "xattr";
4978                   String "val"; Int "vallen"; (* will be BufferIn *)
4979                   Pathname "path"], [];
4980    proc_nr = Some 143;
4981    optional = Some "linuxxattrs";
4982    shortdesc = "set extended attribute of a file or directory";
4983    longdesc = "\
4984This call sets the extended attribute named C<xattr>
4985of the file C<path> to the value C<val> (of length C<vallen>).
4986The value is arbitrary 8 bit data.
4987
4988See also: C<guestfs_lsetxattr>, L<attr(5)>." };
4989
4990  { defaults with
4991    name = "lsetxattr";
4992    style = RErr, [String "xattr";
4993                   String "val"; Int "vallen"; (* will be BufferIn *)
4994                   Pathname "path"], [];
4995    proc_nr = Some 144;
4996    optional = Some "linuxxattrs";
4997    shortdesc = "set extended attribute of a file or directory";
4998    longdesc = "\
4999This is the same as C<guestfs_setxattr>, but if C<path>
5000is a symbolic link, then it sets an extended attribute
5001of the link itself." };
5002
5003  { defaults with
5004    name = "removexattr";
5005    style = RErr, [String "xattr"; Pathname "path"], [];
5006    proc_nr = Some 145;
5007    optional = Some "linuxxattrs";
5008    shortdesc = "remove extended attribute of a file or directory";
5009    longdesc = "\
5010This call removes the extended attribute named C<xattr>
5011of the file C<path>.
5012
5013See also: C<guestfs_lremovexattr>, L<attr(5)>." };
5014
5015  { defaults with
5016    name = "lremovexattr";
5017    style = RErr, [String "xattr"; Pathname "path"], [];
5018    proc_nr = Some 146;
5019    optional = Some "linuxxattrs";
5020    shortdesc = "remove extended attribute of a file or directory";
5021    longdesc = "\
5022This is the same as C<guestfs_removexattr>, but if C<path>
5023is a symbolic link, then it removes an extended attribute
5024of the link itself." };
5025
5026  { defaults with
5027    name = "mountpoints";
5028    style = RHashtable "mps", [], [];
5029    proc_nr = Some 147;
5030    shortdesc = "show mountpoints";
5031    longdesc = "\
5032This call is similar to C<guestfs_mounts>.  That call returns
5033a list of devices.  This one returns a hash table (map) of
5034device name to directory where the device is mounted." };
5035
5036  { defaults with
5037    name = "mkmountpoint";
5038    (* This is a special case: while you would expect a parameter
5039     * of type "Pathname", that doesn't work, because it implies
5040     * NEED_ROOT in the generated calling code in stubs.c, and
5041     * this function cannot use NEED_ROOT.
5042     *)
5043    style = RErr, [String "exemptpath"], [];
5044    proc_nr = Some 148;
5045    shortdesc = "create a mountpoint";
5046    longdesc = "\
5047C<guestfs_mkmountpoint> and C<guestfs_rmmountpoint> are
5048specialized calls that can be used to create extra mountpoints
5049before mounting the first filesystem.
5050
5051These calls are I<only> necessary in some very limited circumstances,
5052mainly the case where you want to mount a mix of unrelated and/or
5053read-only filesystems together.
5054
5055For example, live CDs often contain a \"Russian doll\" nest of
5056filesystems, an ISO outer layer, with a squashfs image inside, with
5057an ext2/3 image inside that.  You can unpack this as follows
5058in guestfish:
5059
5060 add-ro Fedora-11-i686-Live.iso
5061 run
5062 mkmountpoint /cd
5063 mkmountpoint /sqsh
5064 mkmountpoint /ext3fs
5065 mount /dev/sda /cd
5066 mount-loop /cd/LiveOS/squashfs.img /sqsh
5067 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
5068
5069The inner filesystem is now unpacked under the /ext3fs mountpoint.
5070
5071C<guestfs_mkmountpoint> is not compatible with C<guestfs_umount_all>.
5072You may get unexpected errors if you try to mix these calls.  It is
5073safest to manually unmount filesystems and remove mountpoints after use.
5074
5075C<guestfs_umount_all> unmounts filesystems by sorting the paths
5076longest first, so for this to work for manual mountpoints, you
5077must ensure that the innermost mountpoints have the longest
5078pathnames, as in the example code above.
5079
5080For more details see L<https://bugzilla.redhat.com/show_bug.cgi?id=599503>
5081
5082Autosync [see C<guestfs_set_autosync>, this is set by default on
5083handles] can cause C<guestfs_umount_all> to be called when the handle
5084is closed which can also trigger these issues." };
5085
5086  { defaults with
5087    name = "rmmountpoint";
5088    style = RErr, [String "exemptpath"], [];
5089    proc_nr = Some 149;
5090    shortdesc = "remove a mountpoint";
5091    longdesc = "\
5092This calls removes a mountpoint that was previously created
5093with C<guestfs_mkmountpoint>.  See C<guestfs_mkmountpoint>
5094for full details." };
5095
5096  { defaults with
5097    name = "read_file";
5098    style = RBufferOut "content", [Pathname "path"], [];
5099    proc_nr = Some 150;
5100    protocol_limit_warning = true;
5101    tests = [
5102      InitISOFS, Always, TestOutputBuffer (
5103        [["read_file"; "/known-4"]], "abc\ndef\nghi");
5104      (* Test various near large, large and too large files (RHBZ#589039). *)
5105      InitScratchFS, Always, TestLastFail (
5106        [["touch"; "/read_file"];
5107         ["truncate_size"; "/read_file"; "4194303"]; (* GUESTFS_MESSAGE_MAX - 1 *)
5108         ["read_file"; "/read_file"]]);
5109      InitScratchFS, Always, TestLastFail (
5110        [["touch"; "/read_file2"];
5111         ["truncate_size"; "/read_file2"; "4194304"]; (* GUESTFS_MESSAGE_MAX *)
5112         ["read_file"; "/read_file2"]]);
5113      InitScratchFS, Always, TestLastFail (
5114        [["touch"; "/read_file3"];
5115         ["truncate_size"; "/read_file3"; "41943040"]; (* GUESTFS_MESSAGE_MAX * 10 *)
5116         ["read_file"; "/read_file3"]])
5117    ];
5118    shortdesc = "read a file";
5119    longdesc = "\
5120This calls returns the contents of the file C<path> as a
5121buffer.
5122
5123Unlike C<guestfs_cat>, this function can correctly
5124handle files that contain embedded ASCII NUL characters.
5125However unlike C<guestfs_download>, this function is limited
5126in the total size of file that can be handled." };
5127
5128  { defaults with
5129    name = "grep";
5130    style = RStringList "lines", [String "regex"; Pathname "path"], [];
5131    proc_nr = Some 151;
5132    protocol_limit_warning = true;
5133    tests = [
5134      InitISOFS, Always, TestOutputList (
5135        [["grep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"]);
5136      InitISOFS, Always, TestOutputList (
5137        [["grep"; "nomatch"; "/test-grep.txt"]], []);
5138      (* Test for RHBZ#579608, absolute symbolic links. *)
5139      InitISOFS, Always, TestOutputList (
5140        [["grep"; "nomatch"; "/abssymlink"]], [])
5141    ];
5142    shortdesc = "return lines matching a pattern";
5143    longdesc = "\
5144This calls the external C<grep> program and returns the
5145matching lines." };
5146
5147  { defaults with
5148    name = "egrep";
5149    style = RStringList "lines", [String "regex"; Pathname "path"], [];
5150    proc_nr = Some 152;
5151    protocol_limit_warning = true;
5152    tests = [
5153      InitISOFS, Always, TestOutputList (
5154        [["egrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])
5155    ];
5156    shortdesc = "return lines matching a pattern";
5157    longdesc = "\
5158This calls the external C<egrep> program and returns the
5159matching lines." };
5160
5161  { defaults with
5162    name = "fgrep";
5163    style = RStringList "lines", [String "pattern"; Pathname "path"], [];
5164    proc_nr = Some 153;
5165    protocol_limit_warning = true;
5166    tests = [
5167      InitISOFS, Always, TestOutputList (
5168        [["fgrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])
5169    ];
5170    shortdesc = "return lines matching a pattern";
5171    longdesc = "\
5172This calls the external C<fgrep> program and returns the
5173matching lines." };
5174
5175  { defaults with
5176    name = "grepi";
5177    style = RStringList "lines", [String "regex"; Pathname "path"], [];
5178    proc_nr = Some 154;
5179    protocol_limit_warning = true;
5180    tests = [
5181      InitISOFS, Always, TestOutputList (
5182        [["grepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])
5183    ];
5184    shortdesc = "return lines matching a pattern";
5185    longdesc = "\
5186This calls the external C<grep -i> program and returns the
5187matching lines." };
5188
5189  { defaults with
5190    name = "egrepi";
5191    style = RStringList "lines", [String "regex"; Pathname "path"], [];
5192    proc_nr = Some 155;
5193    protocol_limit_warning = true;
5194    tests = [
5195      InitISOFS, Always, TestOutputList (
5196        [["egrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])
5197    ];
5198    shortdesc = "return lines matching a pattern";
5199    longdesc = "\
5200This calls the external C<egrep -i> program and returns the
5201matching lines." };
5202
5203  { defaults with
5204    name = "fgrepi";
5205    style = RStringList "lines", [String "pattern"; Pathname "path"], [];
5206    proc_nr = Some 156;
5207    protocol_limit_warning = true;
5208    tests = [
5209      InitISOFS, Always, TestOutputList (
5210        [["fgrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])
5211    ];
5212    shortdesc = "return lines matching a pattern";
5213    longdesc = "\
5214This calls the external C<fgrep -i> program and returns the
5215matching lines." };
5216
5217  { defaults with
5218    name = "zgrep";
5219    style = RStringList "lines", [String "regex"; Pathname "path"], [];
5220    proc_nr = Some 157;
5221    protocol_limit_warning = true;
5222    tests = [
5223      InitISOFS, Always, TestOutputList (
5224        [["zgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])
5225    ];
5226    shortdesc = "return lines matching a pattern";
5227    longdesc = "\
5228This calls the external C<zgrep> program and returns the
5229matching lines." };
5230
5231  { defaults with
5232    name = "zegrep";
5233    style = RStringList "lines", [String "regex"; Pathname "path"], [];
5234    proc_nr = Some 158;
5235    protocol_limit_warning = true;
5236    tests = [
5237      InitISOFS, Always, TestOutputList (
5238        [["zegrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])
5239    ];
5240    shortdesc = "return lines matching a pattern";
5241    longdesc = "\
5242This calls the external C<zegrep> program and returns the
5243matching lines." };
5244
5245  { defaults with
5246    name = "zfgrep";
5247    style = RStringList "lines", [String "pattern"; Pathname "path"], [];
5248    proc_nr = Some 159;
5249    protocol_limit_warning = true;
5250    tests = [
5251      InitISOFS, Always, TestOutputList (
5252        [["zfgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])
5253    ];
5254    shortdesc = "return lines matching a pattern";
5255    longdesc = "\
5256This calls the external C<zfgrep> program and returns the
5257matching lines." };
5258
5259  { defaults with
5260    name = "zgrepi";
5261    style = RStringList "lines", [String "regex"; Pathname "path"], [];
5262    proc_nr = Some 160;
5263    protocol_limit_warning = true;
5264    tests = [
5265      InitISOFS, Always, TestOutputList (
5266        [["zgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])
5267    ];
5268    shortdesc = "return lines matching a pattern";
5269    longdesc = "\
5270This calls the external C<zgrep -i> program and returns the
5271matching lines." };
5272
5273  { defaults with
5274    name = "zegrepi";
5275    style = RStringList "lines", [String "regex"; Pathname "path"], [];
5276    proc_nr = Some 161;
5277    protocol_limit_warning = true;
5278    tests = [
5279      InitISOFS, Always, TestOutputList (
5280        [["zegrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])
5281    ];
5282    shortdesc = "return lines matching a pattern";
5283    longdesc = "\
5284This calls the external C<zegrep -i> program and returns the
5285matching lines." };
5286
5287  { defaults with
5288    name = "zfgrepi";
5289    style = RStringList "lines", [String "pattern"; Pathname "path"], [];
5290    proc_nr = Some 162;
5291    protocol_limit_warning = true;
5292    tests = [
5293      InitISOFS, Always, TestOutputList (
5294        [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])
5295    ];
5296    shortdesc = "return lines matching a pattern";
5297    longdesc = "\
5298This calls the external C<zfgrep -i> program and returns the
5299matching lines." };
5300
5301  { defaults with
5302    name = "realpath";
5303    style = RString "rpath", [Pathname "path"], [];
5304    proc_nr = Some 163;
5305    optional = Some "realpath";
5306    tests = [
5307      InitISOFS, Always, TestOutput (
5308        [["realpath"; "/../directory"]], "/directory")
5309    ];
5310    shortdesc = "canonicalized absolute pathname";
5311    longdesc = "\
5312Return the canonicalized absolute pathname of C<path>.  The
5313returned path has no C<.>, C<..> or symbolic link path elements." };
5314
5315  { defaults with
5316    name = "ln";
5317    style = RErr, [String "target"; Pathname "linkname"], [];
5318    proc_nr = Some 164;
5319    tests = [
5320      InitScratchFS, Always, TestOutputStruct (
5321        [["mkdir"; "/ln"];
5322         ["touch"; "/ln/a"];
5323         ["ln"; "/ln/a"; "/ln/b"];
5324         ["stat"; "/ln/b"]], [CompareWithInt ("nlink", 2)])
5325    ];
5326    shortdesc = "create a hard link";
5327    longdesc = "\
5328This command creates a hard link using the C<ln> command." };
5329
5330  { defaults with
5331    name = "ln_f";
5332    style = RErr, [String "target"; Pathname "linkname"], [];
5333    proc_nr = Some 165;
5334    tests = [
5335      InitScratchFS, Always, TestOutputStruct (
5336        [["mkdir"; "/ln_f"];
5337         ["touch"; "/ln_f/a"];
5338         ["touch"; "/ln_f/b"];
5339         ["ln_f"; "/ln_f/a"; "/ln_f/b"];
5340         ["stat"; "/ln_f/b"]], [CompareWithInt ("nlink", 2)])
5341    ];
5342    shortdesc = "create a hard link";
5343    longdesc = "\
5344This command creates a hard link using the C<ln -f> command.
5345The I<-f> option removes the link (C<linkname>) if it exists already." };
5346
5347  { defaults with
5348    name = "ln_s";
5349    style = RErr, [String "target"; Pathname "linkname"], [];
5350    proc_nr = Some 166;
5351    tests = [
5352      InitScratchFS, Always, TestOutputStruct (
5353        [["mkdir"; "/ln_s"];
5354         ["touch"; "/ln_s/a"];
5355         ["ln_s"; "a"; "/ln_s/b"];
5356         ["lstat"; "/ln_s/b"]], [CompareWithInt ("mode", 0o120777)])
5357    ];
5358    shortdesc = "create a symbolic link";
5359    longdesc = "\
5360This command creates a symbolic link using the C<ln -s> command." };
5361
5362  { defaults with
5363    name = "ln_sf";
5364    style = RErr, [String "target"; Pathname "linkname"], [];
5365    proc_nr = Some 167;
5366    tests = [
5367      InitScratchFS, Always, TestOutput (
5368        [["mkdir_p"; "/ln_sf/b"];
5369         ["touch"; "/ln_sf/b/c"];
5370         ["ln_sf"; "../d"; "/ln_sf/b/c"];
5371         ["readlink"; "/ln_sf/b/c"]], "../d")
5372    ];
5373    shortdesc = "create a symbolic link";
5374    longdesc = "\
5375This command creates a symbolic link using the C<ln -sf> command,
5376The I<-f> option removes the link (C<linkname>) if it exists already." };
5377
5378  { defaults with
5379    name = "readlink";
5380    style = RString "link", [Pathname "path"], [];
5381    proc_nr = Some 168;
5382    shortdesc = "read the target of a symbolic link";
5383    longdesc = "\
5384This command reads the target of a symbolic link." };
5385
5386  { defaults with
5387    name = "fallocate";
5388    style = RErr, [Pathname "path"; Int "len"], [];
5389    proc_nr = Some 169;
5390    deprecated_by = Some "fallocate64";
5391    tests = [
5392      InitScratchFS, Always, TestOutputStruct (
5393        [["fallocate"; "/fallocate"; "1000000"];
5394         ["stat"; "/fallocate"]], [CompareWithInt ("size", 1_000_000)])
5395    ];
5396    shortdesc = "preallocate a file in the guest filesystem";
5397    longdesc = "\
5398This command preallocates a file (containing zero bytes) named
5399C<path> of size C<len> bytes.  If the file exists already, it
5400is overwritten.
5401
5402Do not confuse this with the guestfish-specific
5403C<alloc> command which allocates a file in the host and
5404attaches it as a device." };
5405
5406  { defaults with
5407    name = "swapon_device";
5408    style = RErr, [Device "device"], [];
5409    proc_nr = Some 170;
5410    tests = [
5411      InitPartition, Always, TestRun (
5412        [["mkswap"; "/dev/sda1"];
5413         ["swapon_device"; "/dev/sda1"];
5414         ["swapoff_device"; "/dev/sda1"]])
5415    ];
5416    shortdesc = "enable swap on device";
5417    longdesc = "\
5418This command enables the libguestfs appliance to use the
5419swap device or partition named C<device>.  The increased
5420memory is made available for all commands, for example
5421those run using C<guestfs_command> or C<guestfs_sh>.
5422
5423Note that you should not swap to existing guest swap
5424partitions unless you know what you are doing.  They may
5425contain hibernation information, or other information that
5426the guest doesn't want you to trash.  You also risk leaking
5427information about the host to the guest this way.  Instead,
5428attach a new host device to the guest and swap on that." };
5429
5430  { defaults with
5431    name = "swapoff_device";
5432    style = RErr, [Device "device"], [];
5433    proc_nr = Some 171;
5434    shortdesc = "disable swap on device";
5435    longdesc = "\
5436This command disables the libguestfs appliance swap
5437device or partition named C<device>.
5438See C<guestfs_swapon_device>." };
5439
5440  { defaults with
5441    name = "swapon_file";
5442    style = RErr, [Pathname "file"], [];
5443    proc_nr = Some 172;
5444    tests = [
5445      InitScratchFS, Always, TestRun (
5446        [["fallocate"; "/swapon_file"; "8388608"];
5447         ["mkswap_file"; "/swapon_file"];
5448         ["swapon_file"; "/swapon_file"];
5449         ["swapoff_file"; "/swapon_file"];
5450         ["rm"; "/swapon_file"]])
5451    ];
5452    shortdesc = "enable swap on file";
5453    longdesc = "\
5454This command enables swap to a file.
5455See C<guestfs_swapon_device> for other notes." };
5456
5457  { defaults with
5458    name = "swapoff_file";
5459    style = RErr, [Pathname "file"], [];
5460    proc_nr = Some 173;
5461    shortdesc = "disable swap on file";
5462    longdesc = "\
5463This command disables the libguestfs appliance swap on file." };
5464
5465  { defaults with
5466    name = "swapon_label";
5467    style = RErr, [String "label"], [];
5468    proc_nr = Some 174;
5469    tests = [
5470      InitEmpty, Always, TestRun (
5471        [["part_disk"; "/dev/sda"; "mbr"];
5472         ["mkswap_L"; "swapit"; "/dev/sda1"];
5473         ["swapon_label"; "swapit"];
5474         ["swapoff_label"; "swapit"];
5475         ["zero"; "/dev/sda"];
5476         ["blockdev_rereadpt"; "/dev/sda"]])
5477    ];
5478    shortdesc = "enable swap on labeled swap partition";
5479    longdesc = "\
5480This command enables swap to a labeled swap partition.
5481See C<guestfs_swapon_device> for other notes." };
5482
5483  { defaults with
5484    name = "swapoff_label";
5485    style = RErr, [String "label"], [];
5486    proc_nr = Some 175;
5487    shortdesc = "disable swap on labeled swap partition";
5488    longdesc = "\
5489This command disables the libguestfs appliance swap on
5490labeled swap partition." };
5491
5492  { defaults with
5493    name = "swapon_uuid";
5494    style = RErr, [String "uuid"], [];
5495    proc_nr = Some 176;
5496    optional = Some "linuxfsuuid";
5497    tests =
5498      (let uuid = uuidgen () in [
5499        InitEmpty, Always, TestRun (
5500          [["mkswap_U"; uuid; "/dev/sdc"];
5501           ["swapon_uuid"; uuid];
5502           ["swapoff_uuid"; uuid]])
5503       ]);
5504    shortdesc = "enable swap on swap partition by UUID";
5505    longdesc = "\
5506This command enables swap to a swap partition with the given UUID.
5507See C<guestfs_swapon_device> for other notes." };
5508
5509  { defaults with
5510    name = "swapoff_uuid";
5511    style = RErr, [String "uuid"], [];
5512    proc_nr = Some 177;
5513    optional = Some "linuxfsuuid";
5514    shortdesc = "disable swap on swap partition by UUID";
5515    longdesc = "\
5516This command disables the libguestfs appliance swap partition
5517with the given UUID." };
5518
5519  { defaults with
5520    name = "mkswap_file";
5521    style = RErr, [Pathname "path"], [];
5522    proc_nr = Some 178;
5523    tests = [
5524      InitScratchFS, Always, TestRun (
5525        [["fallocate"; "/mkswap_file"; "8388608"];
5526         ["mkswap_file"; "/mkswap_file"];
5527         ["rm"; "/mkswap_file"]])
5528    ];
5529    shortdesc = "create a swap file";
5530    longdesc = "\
5531Create a swap file.
5532
5533This command just writes a swap file signature to an existing
5534file.  To create the file itself, use something like C<guestfs_fallocate>." };
5535
5536  { defaults with
5537    name = "inotify_init";
5538    style = RErr, [Int "maxevents"], [];
5539    proc_nr = Some 179;
5540    optional = Some "inotify";
5541    tests = [
5542      InitISOFS, Always, TestRun (
5543        [["inotify_init"; "0"]])
5544    ];
5545    shortdesc = "create an inotify handle";
5546    longdesc = "\
5547This command creates a new inotify handle.
5548The inotify subsystem can be used to notify events which happen to
5549objects in the guest filesystem.
5550
5551C<maxevents> is the maximum number of events which will be
5552queued up between calls to C<guestfs_inotify_read> or
5553C<guestfs_inotify_files>.
5554If this is passed as C<0>, then the kernel (or previously set)
5555default is used.  For Linux 2.6.29 the default was 16384 events.
5556Beyond this limit, the kernel throws away events, but records
5557the fact that it threw them away by setting a flag
5558C<IN_Q_OVERFLOW> in the returned structure list (see
5559C<guestfs_inotify_read>).
5560
5561Before any events are generated, you have to add some
5562watches to the internal watch list.  See: C<guestfs_inotify_add_watch> and
5563C<guestfs_inotify_rm_watch>.
5564
5565Queued up events should be read periodically by calling
5566C<guestfs_inotify_read>
5567(or C<guestfs_inotify_files> which is just a helpful
5568wrapper around C<guestfs_inotify_read>).  If you don't
5569read the events out often enough then you risk the internal
5570queue overflowing.
5571
5572The handle should be closed after use by calling
5573C<guestfs_inotify_close>.  This also removes any
5574watches automatically.
5575
5576See also L<inotify(7)> for an overview of the inotify interface
5577as exposed by the Linux kernel, which is roughly what we expose
5578via libguestfs.  Note that there is one global inotify handle
5579per libguestfs instance." };
5580
5581  { defaults with
5582    name = "inotify_add_watch";
5583    style = RInt64 "wd", [Pathname "path"; Int "mask"], [];
5584    proc_nr = Some 180;
5585    optional = Some "inotify";
5586    tests = [
5587      InitScratchFS, Always, TestOutputList (
5588        [["mkdir"; "/inotify_add_watch"];
5589         ["inotify_init"; "0"];
5590         ["inotify_add_watch"; "/inotify_add_watch"; "1073741823"];
5591         ["touch"; "/inotify_add_watch/a"];
5592         ["touch"; "/inotify_add_watch/b"];
5593         ["inotify_files"]], ["a"; "b"])
5594    ];
5595    shortdesc = "add an inotify watch";
5596    longdesc = "\
5597Watch C<path> for the events listed in C<mask>.
5598
5599Note that if C<path> is a directory then events within that
5600directory are watched, but this does I<not> happen recursively
5601(in subdirectories).
5602
5603Note for non-C or non-Linux callers: the inotify events are
5604defined by the Linux kernel ABI and are listed in
5605C</usr/include/sys/inotify.h>." };
5606
5607  { defaults with
5608    name = "inotify_rm_watch";
5609    style = RErr, [Int(*XXX64*) "wd"], [];
5610    proc_nr = Some 181;
5611    optional = Some "inotify";
5612    shortdesc = "remove an inotify watch";
5613    longdesc = "\
5614Remove a previously defined inotify watch.
5615See C<guestfs_inotify_add_watch>." };
5616
5617  { defaults with
5618    name = "inotify_read";
5619    style = RStructList ("events", "inotify_event"), [], [];
5620    proc_nr = Some 182;
5621    optional = Some "inotify";
5622    shortdesc = "return list of inotify events";
5623    longdesc = "\
5624Return the complete queue of events that have happened
5625since the previous read call.
5626
5627If no events have happened, this returns an empty list.
5628
5629I<Note>: In order to make sure that all events have been
5630read, you must call this function repeatedly until it
5631returns an empty list.  The reason is that the call will
5632read events up to the maximum appliance-to-host message
5633size and leave remaining events in the queue." };
5634
5635  { defaults with
5636    name = "inotify_files";
5637    style = RStringList "paths", [], [];
5638    proc_nr = Some 183;
5639    optional = Some "inotify";
5640    shortdesc = "return list of watched files that had events";
5641    longdesc = "\
5642This function is a helpful wrapper around C<guestfs_inotify_read>
5643which just returns a list of pathnames of objects that were
5644touched.  The returned pathnames are sorted and deduplicated." };
5645
5646  { defaults with
5647    name = "inotify_close";
5648    style = RErr, [], [];
5649    proc_nr = Some 184;
5650    optional = Some "inotify";
5651    shortdesc = "close the inotify handle";
5652    longdesc = "\
5653This closes the inotify handle which was previously
5654opened by inotify_init.  It removes all watches, throws
5655away any pending events, and deallocates all resources." };
5656
5657  { defaults with
5658    name = "setcon";
5659    style = RErr, [String "context"], [];
5660    proc_nr = Some 185;
5661    optional = Some "selinux";
5662    shortdesc = "set SELinux security context";
5663    longdesc = "\
5664This sets the SELinux security context of the daemon
5665to the string C<context>.
5666
5667See the documentation about SELINUX in L<guestfs(3)>." };
5668
5669  { defaults with
5670    name = "getcon";
5671    style = RString "context", [], [];
5672    proc_nr = Some 186;
5673    optional = Some "selinux";
5674    shortdesc = "get SELinux security context";
5675    longdesc = "\
5676This gets the SELinux security context of the daemon.
5677
5678See the documentation about SELINUX in L<guestfs(3)>,
5679and C<guestfs_setcon>" };
5680
5681  { defaults with
5682    name = "mkfs_b";
5683    style = RErr, [String "fstype"; Int "blocksize"; Device "device"], [];
5684    proc_nr = Some 187;
5685    deprecated_by = Some "mkfs";
5686    tests = [
5687      InitEmpty, Always, TestOutput (
5688        [["part_disk"; "/dev/sda"; "mbr"];
5689         ["mkfs_b"; "ext2"; "4096"; "/dev/sda1"];
5690         ["mount_options"; ""; "/dev/sda1"; "/"];
5691         ["write"; "/new"; "new file contents"];
5692         ["cat"; "/new"]], "new file contents");
5693      InitEmpty, Always, TestRun (
5694        [["part_disk"; "/dev/sda"; "mbr"];
5695         ["mkfs_b"; "vfat"; "32768"; "/dev/sda1"]]);
5696      InitEmpty, Always, TestLastFail (
5697        [["part_disk"; "/dev/sda"; "mbr"];
5698         ["mkfs_b"; "vfat"; "32769"; "/dev/sda1"]]);
5699      InitEmpty, Always, TestLastFail (
5700        [["part_disk"; "/dev/sda"; "mbr"];
5701         ["mkfs_b"; "vfat"; "33280"; "/dev/sda1"]]);
5702      InitEmpty, IfAvailable "ntfsprogs", TestRun (
5703        [["part_disk"; "/dev/sda"; "mbr"];
5704         ["mkfs_b"; "ntfs"; "32768"; "/dev/sda1"]])
5705    ];
5706    shortdesc = "make a filesystem with block size";
5707    longdesc = "\
5708This call is similar to C<guestfs_mkfs>, but it allows you to
5709control the block size of the resulting filesystem.  Supported
5710block sizes depend on the filesystem type, but typically they
5711are C<1024>, C<2048> or C<4096> only.
5712
5713For VFAT and NTFS the C<blocksize> parameter is treated as
5714the requested cluster size." };
5715
5716  { defaults with
5717    name = "mke2journal";
5718    style = RErr, [Int "blocksize"; Device "device"], [];
5719    proc_nr = Some 188;
5720    tests = [
5721      InitEmpty, Always, TestOutput (
5722        [["part_init"; "/dev/sda"; "mbr"];
5723         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
5724         ["part_add"; "/dev/sda"; "p"; "204800"; "-64"];
5725         ["mke2journal"; "4096"; "/dev/sda1"];
5726         ["mke2fs_J"; "ext2"; "4096"; "/dev/sda2"; "/dev/sda1"];
5727         ["mount_options"; ""; "/dev/sda2"; "/"];
5728         ["write"; "/new"; "new file contents"];
5729         ["cat"; "/new"]], "new file contents")
5730    ];
5731    shortdesc = "make ext2/3/4 external journal";
5732    longdesc = "\
5733This creates an ext2 external journal on C<device>.  It is equivalent
5734to the command:
5735
5736 mke2fs -O journal_dev -b blocksize device" };
5737
5738  { defaults with
5739    name = "mke2journal_L";
5740    style = RErr, [Int "blocksize"; String "label"; Device "device"], [];
5741    proc_nr = Some 189;
5742    tests = [
5743      InitEmpty, Always, TestOutput (
5744        [["part_init"; "/dev/sda"; "mbr"];
5745         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
5746         ["part_add"; "/dev/sda"; "p"; "204800"; "-64"];
5747         ["mke2journal_L"; "4096"; "JOURNAL"; "/dev/sda1"];
5748         ["mke2fs_JL"; "ext2"; "4096"; "/dev/sda2"; "JOURNAL"];
5749         ["mount_options"; ""; "/dev/sda2"; "/"];
5750         ["write"; "/new"; "new file contents"];
5751         ["cat"; "/new"]], "new file contents")
5752    ];
5753    shortdesc = "make ext2/3/4 external journal with label";
5754    longdesc = "\
5755This creates an ext2 external journal on C<device> with label C<label>." };
5756
5757  { defaults with
5758    name = "mke2journal_U";
5759    style = RErr, [Int "blocksize"; String "uuid"; Device "device"], [];
5760    proc_nr = Some 190;
5761    optional = Some "linuxfsuuid";
5762    tests =
5763      (let uuid = uuidgen () in [
5764        InitEmpty, Always, TestOutput (
5765          [["part_init"; "/dev/sda"; "mbr"];
5766           ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
5767           ["part_add"; "/dev/sda"; "p"; "204800"; "-64"];
5768           ["mke2journal_U"