/libguestfs-1.19.22/generator/generator_actions.ml
OCaml | 9342 lines | 8738 code | 454 blank | 150 comment | 1 complexity | e6a678e96285aaeab3f4f9d219dc8f30 MD5 | raw 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 { 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"