PageRenderTime 77ms CodeModel.GetById 19ms app.highlight 31ms RepoModel.GetById 3ms app.codeStats 2ms

/libguestfs-1.19.22/generator/generator_actions.ml

#
OCaml | 9342 lines | 8738 code | 454 blank | 150 comment | 1 complexity | e6a678e96285aaeab3f4f9d219dc8f30 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   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  { def

Large files files are truncated, but you can click here to view the full file