python/guestfs.py

   1 # libguestfs generated file
   2 # WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.
   3 # ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.
   4 #
   5 # Copyright (C) 2009 Red Hat Inc.
   6 #
   7 # This library is free software; you can redistribute it and/or
   8 # modify it under the terms of the GNU Lesser General Public
   9 # License as published by the Free Software Foundation; either
  10 # version 2 of the License, or (at your option) any later version.
  11 #
  12 # This library is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 # Lesser General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU Lesser General Public
  18 # License along with this library; if not, write to the Free Software
  19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  20
  21 u"""Python bindings for libguestfs
  22
  23 import guestfs
  24 g = guestfs.GuestFS ()
  25 g.add_drive ("guest.img")
  26 g.launch ()
  27 g.wait_ready ()
  28 parts = g.list_partitions ()
  29
  30 The guestfs module provides a Python binding to the libguestfs API
  31 for examining and modifying virtual machine disk images.
  32
  33 Amongst the things this is good for: making batch configuration
  34 changes to guests, getting disk used/free statistics (see also:
  35 virt-df), migrating between virtualization systems (see also:
  36 virt-p2v), performing partial backups, performing partial guest
  37 clones, cloning guests and changing registry/UUID/hostname info, and
  38 much else besides.
  39
  40 Libguestfs uses Linux kernel and qemu code, and can access any type of
  41 guest filesystem that Linux and qemu can, including but not limited
  42 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
  43 schemes, qcow, qcow2, vmdk.
  44
  45 Libguestfs provides ways to enumerate guest storage (eg. partitions,
  46 LVs, what filesystem is in each LV, etc.).  It can also run commands
  47 in the context of the guest.  Also you can access filesystems over FTP.
  48
  49 Errors which happen while using the API are turned into Python
  50 RuntimeError exceptions.
  51
  52 To create a guestfs handle you usually have to perform the following
  53 sequence of calls:
  54
  55 # Create the handle, call add_drive at least once, and possibly
  56 # several times if the guest has multiple block devices:
  57 g = guestfs.GuestFS ()
  58 g.add_drive ("guest.img")
  59
  60 # Launch the qemu subprocess and wait for it to become ready:
  61 g.launch ()
  62 g.wait_ready ()
  63
  64 # Now you can issue commands, for example:
  65 logvols = g.lvs ()
  66
  67 """
  68
  69 import libguestfsmod
  70
  71 class GuestFS:
  72     """Instances of this class are libguestfs API handles."""
  73
  74     def __init__ (self):
  75         """Create a new libguestfs handle."""
  76         self._o = libguestfsmod.create ()
  77
  78     def __del__ (self):
  79         libguestfsmod.close (self._o)
  80
  81     def launch (self):
  82         u"""Internally libguestfs is implemented by running a
  83         virtual machine using qemu(1).
  84
  85         You should call this after configuring the handle (eg.
  86         adding drives) but before performing any actions.
  87         """
  88         return libguestfsmod.launch (self._o)
  89
  90     def wait_ready (self):
  91         u"""Internally libguestfs is implemented by running a
  92         virtual machine using qemu(1).
  93
  94         You should call this after "g.launch" to wait for the
  95         launch to complete.
  96         """
  97         return libguestfsmod.wait_ready (self._o)
  98
  99     def kill_subprocess (self):
 100         u"""This kills the qemu subprocess. You should never need to
 101         call this.
 102         """
 103         return libguestfsmod.kill_subprocess (self._o)
 104
 105     def add_drive (self, filename):
 106         u"""This function adds a virtual machine disk image
 107         "filename" to the guest. The first time you call this
 108         function, the disk appears as IDE disk 0 ("/dev/sda") in
 109         the guest, the second time as "/dev/sdb", and so on.
 110
 111         You don't necessarily need to be root when using
 112         libguestfs. However you obviously do need sufficient
 113         permissions to access the filename for whatever
 114         operations you want to perform (ie. read access if you
 115         just want to read the image or write access if you want
 116         to modify the image).
 117
 118         This is equivalent to the qemu parameter "-drive
 119         file=filename".
 120         """
 121         return libguestfsmod.add_drive (self._o, filename)
 122
 123     def add_cdrom (self, filename):
 124         u"""This function adds a virtual CD-ROM disk image to the
 125         guest.
 126
 127         This is equivalent to the qemu parameter "-cdrom
 128         filename".
 129         """
 130         return libguestfsmod.add_cdrom (self._o, filename)
 131
 132     def config (self, qemuparam, qemuvalue):
 133         u"""This can be used to add arbitrary qemu command line
 134         parameters of the form "-param value". Actually it's not
 135         quite arbitrary - we prevent you from setting some
 136         parameters which would interfere with parameters that we
 137         use.
 138
 139         The first character of "param" string must be a "-"
 140         (dash).
 141
 142         "value" can be NULL.
 143         """
 144         return libguestfsmod.config (self._o, qemuparam, qemuvalue)
 145
 146     def set_qemu (self, qemu):
 147         u"""Set the qemu binary that we will use.
 148
 149         The default is chosen when the library was compiled by
 150         the configure script.
 151
 152         You can also override this by setting the
 153         "LIBGUESTFS_QEMU" environment variable.
 154
 155         The string "qemu" is stashed in the libguestfs handle,
 156         so the caller must make sure it remains valid for the
 157         lifetime of the handle.
 158
 159         Setting "qemu" to "NULL" restores the default qemu
 160         binary.
 161         """
 162         return libguestfsmod.set_qemu (self._o, qemu)
 163
 164     def get_qemu (self):
 165         u"""Return the current qemu binary.
 166
 167         This is always non-NULL. If it wasn't set already, then
 168         this will return the default qemu binary name.
 169         """
 170         return libguestfsmod.get_qemu (self._o)
 171
 172     def set_path (self, path):
 173         u"""Set the path that libguestfs searches for kernel and
 174         initrd.img.
 175
 176         The default is "$libdir/guestfs" unless overridden by
 177         setting "LIBGUESTFS_PATH" environment variable.
 178
 179         The string "path" is stashed in the libguestfs handle,
 180         so the caller must make sure it remains valid for the
 181         lifetime of the handle.
 182
 183         Setting "path" to "NULL" restores the default path.
 184         """
 185         return libguestfsmod.set_path (self._o, path)
 186
 187     def get_path (self):
 188         u"""Return the current search path.
 189
 190         This is always non-NULL. If it wasn't set already, then
 191         this will return the default path.
 192         """
 193         return libguestfsmod.get_path (self._o)
 194
 195     def set_autosync (self, autosync):
 196         u"""If "autosync" is true, this enables autosync. Libguestfs
 197         will make a best effort attempt to run "g.umount_all"
 198         followed by "g.sync" when the handle is closed (also if
 199         the program exits without closing handles).
 200
 201         This is disabled by default (except in guestfish where
 202         it is enabled by default).
 203         """
 204         return libguestfsmod.set_autosync (self._o, autosync)
 205
 206     def get_autosync (self):
 207         u"""Get the autosync flag.
 208         """
 209         return libguestfsmod.get_autosync (self._o)
 210
 211     def set_verbose (self, verbose):
 212         u"""If "verbose" is true, this turns on verbose messages (to
 213         "stderr").
 214
 215         Verbose messages are disabled unless the environment
 216         variable "LIBGUESTFS_DEBUG" is defined and set to 1.
 217         """
 218         return libguestfsmod.set_verbose (self._o, verbose)
 219
 220     def get_verbose (self):
 221         u"""This returns the verbose messages flag.
 222         """
 223         return libguestfsmod.get_verbose (self._o)
 224
 225     def is_ready (self):
 226         u"""This returns true iff this handle is ready to accept
 227         commands (in the "READY" state).
 228
 229         For more information on states, see guestfs(3).
 230         """
 231         return libguestfsmod.is_ready (self._o)
 232
 233     def is_config (self):
 234         u"""This returns true iff this handle is being configured
 235         (in the "CONFIG" state).
 236
 237         For more information on states, see guestfs(3).
 238         """
 239         return libguestfsmod.is_config (self._o)
 240
 241     def is_launching (self):
 242         u"""This returns true iff this handle is launching the
 243         subprocess (in the "LAUNCHING" state).
 244
 245         For more information on states, see guestfs(3).
 246         """
 247         return libguestfsmod.is_launching (self._o)
 248
 249     def is_busy (self):
 250         u"""This returns true iff this handle is busy processing a
 251         command (in the "BUSY" state).
 252
 253         For more information on states, see guestfs(3).
 254         """
 255         return libguestfsmod.is_busy (self._o)
 256
 257     def get_state (self):
 258         u"""This returns the current state as an opaque integer.
 259         This is only useful for printing debug and internal
 260         error messages.
 261
 262         For more information on states, see guestfs(3).
 263         """
 264         return libguestfsmod.get_state (self._o)
 265
 266     def set_busy (self):
 267         u"""This sets the state to "BUSY". This is only used when
 268         implementing actions using the low-level API.
 269
 270         For more information on states, see guestfs(3).
 271         """
 272         return libguestfsmod.set_busy (self._o)
 273
 274     def set_ready (self):
 275         u"""This sets the state to "READY". This is only used when
 276         implementing actions using the low-level API.
 277
 278         For more information on states, see guestfs(3).
 279         """
 280         return libguestfsmod.set_ready (self._o)
 281
 282     def end_busy (self):
 283         u"""This sets the state to "READY", or if in "CONFIG" then
 284         it leaves the state as is. This is only used when
 285         implementing actions using the low-level API.
 286
 287         For more information on states, see guestfs(3).
 288         """
 289         return libguestfsmod.end_busy (self._o)
 290
 291     def mount (self, device, mountpoint):
 292         u"""Mount a guest disk at a position in the filesystem.
 293         Block devices are named "/dev/sda", "/dev/sdb" and so
 294         on, as they were added to the guest. If those block
 295         devices contain partitions, they will have the usual
 296         names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style
 297         names can be used.
 298
 299         The rules are the same as for mount(2): A filesystem
 300         must first be mounted on "/" before others can be
 301         mounted. Other filesystems can only be mounted on
 302         directories which already exist.
 303
 304         The mounted filesystem is writable, if we have
 305         sufficient permissions on the underlying device.
 306
 307         The filesystem options "sync" and "noatime" are set with
 308         this call, in order to improve reliability.
 309         """
 310         return libguestfsmod.mount (self._o, device, mountpoint)
 311
 312     def sync (self):
 313         u"""This syncs the disk, so that any writes are flushed
 314         through to the underlying disk image.
 315
 316         You should always call this if you have modified a disk
 317         image, before closing the handle.
 318         """
 319         return libguestfsmod.sync (self._o)
 320
 321     def touch (self, path):
 322         u"""Touch acts like the touch(1) command. It can be used to
 323         update the timestamps on a file, or, if the file does
 324         not exist, to create a new zero-length file.
 325         """
 326         return libguestfsmod.touch (self._o, path)
 327
 328     def cat (self, path):
 329         u"""Return the contents of the file named "path".
 330
 331         Note that this function cannot correctly handle binary
 332         files (specifically, files containing "\\0" character
 333         which is treated as end of string). For those you need
 334         to use the "g.download" function which has a more
 335         complex interface.
 336
 337         Because of the message protocol, there is a transfer
 338         limit of somewhere between 2MB and 4MB. To transfer
 339         large files you should use FTP.
 340         """
 341         return libguestfsmod.cat (self._o, path)
 342
 343     def ll (self, directory):
 344         u"""List the files in "directory" (relative to the root
 345         directory, there is no cwd) in the format of 'ls -la'.
 346
 347         This command is mostly useful for interactive sessions.
 348         It is *not* intended that you try to parse the output
 349         string.
 350         """
 351         return libguestfsmod.ll (self._o, directory)
 352
 353     def ls (self, directory):
 354         u"""List the files in "directory" (relative to the root
 355         directory, there is no cwd). The '.' and '..' entries
 356         are not returned, but hidden files are shown.
 357
 358         This command is mostly useful for interactive sessions.
 359         Programs should probably use "g.readdir" instead.
 360
 361         This function returns a list of strings.
 362         """
 363         return libguestfsmod.ls (self._o, directory)
 364
 365     def list_devices (self):
 366         u"""List all the block devices.
 367
 368         The full block device names are returned, eg. "/dev/sda"
 369
 370         This function returns a list of strings.
 371         """
 372         return libguestfsmod.list_devices (self._o)
 373
 374     def list_partitions (self):
 375         u"""List all the partitions detected on all block devices.
 376
 377         The full partition device names are returned, eg.
 378         "/dev/sda1"
 379
 380         This does not return logical volumes. For that you will
 381         need to call "g.lvs".
 382
 383         This function returns a list of strings.
 384         """
 385         return libguestfsmod.list_partitions (self._o)
 386
 387     def pvs (self):
 388         u"""List all the physical volumes detected. This is the
 389         equivalent of the pvs(8) command.
 390
 391         This returns a list of just the device names that
 392         contain PVs (eg. "/dev/sda2").
 393
 394         See also "g.pvs_full".
 395
 396         This function returns a list of strings.
 397         """
 398         return libguestfsmod.pvs (self._o)
 399
 400     def vgs (self):
 401         u"""List all the volumes groups detected. This is the
 402         equivalent of the vgs(8) command.
 403
 404         This returns a list of just the volume group names that
 405         were detected (eg. "VolGroup00").
 406
 407         See also "g.vgs_full".
 408
 409         This function returns a list of strings.
 410         """
 411         return libguestfsmod.vgs (self._o)
 412
 413     def lvs (self):
 414         u"""List all the logical volumes detected. This is the
 415         equivalent of the lvs(8) command.
 416
 417         This returns a list of the logical volume device names
 418         (eg. "/dev/VolGroup00/LogVol00").
 419
 420         See also "g.lvs_full".
 421
 422         This function returns a list of strings.
 423         """
 424         return libguestfsmod.lvs (self._o)
 425
 426     def pvs_full (self):
 427         u"""List all the physical volumes detected. This is the
 428         equivalent of the pvs(8) command. The "full" version
 429         includes all fields.
 430
 431         This function returns a list of PVs. Each PV is
 432         represented as a dictionary.
 433         """
 434         return libguestfsmod.pvs_full (self._o)
 435
 436     def vgs_full (self):
 437         u"""List all the volumes groups detected. This is the
 438         equivalent of the vgs(8) command. The "full" version
 439         includes all fields.
 440
 441         This function returns a list of VGs. Each VG is
 442         represented as a dictionary.
 443         """
 444         return libguestfsmod.vgs_full (self._o)
 445
 446     def lvs_full (self):
 447         u"""List all the logical volumes detected. This is the
 448         equivalent of the lvs(8) command. The "full" version
 449         includes all fields.
 450
 451         This function returns a list of LVs. Each LV is
 452         represented as a dictionary.
 453         """
 454         return libguestfsmod.lvs_full (self._o)
 455
 456     def read_lines (self, path):
 457         u"""Return the contents of the file named "path".
 458
 459         The file contents are returned as a list of lines.
 460         Trailing "LF" and "CRLF" character sequences are *not*
 461         returned.
 462
 463         Note that this function cannot correctly handle binary
 464         files (specifically, files containing "\\0" character
 465         which is treated as end of line). For those you need to
 466         use the "g.read_file" function which has a more complex
 467         interface.
 468
 469         This function returns a list of strings.
 470         """
 471         return libguestfsmod.read_lines (self._o, path)
 472
 473     def aug_init (self, root, flags):
 474         u"""Create a new Augeas handle for editing configuration
 475         files. If there was any previous Augeas handle
 476         associated with this guestfs session, then it is closed.
 477
 478         You must call this before using any other "g.aug_*"
 479         commands.
 480
 481         "root" is the filesystem root. "root" must not be NULL,
 482         use "/" instead.
 483
 484         The flags are the same as the flags defined in
 485         <augeas.h>, the logical *or* of the following integers:
 486
 487         "AUG_SAVE_BACKUP" = 1
 488         Keep the original file with a ".augsave" extension.
 489
 490         "AUG_SAVE_NEWFILE" = 2
 491         Save changes into a file with extension ".augnew",
 492         and do not overwrite original. Overrides
 493         "AUG_SAVE_BACKUP".
 494
 495         "AUG_TYPE_CHECK" = 4
 496         Typecheck lenses (can be expensive).
 497
 498         "AUG_NO_STDINC" = 8
 499         Do not use standard load path for modules.
 500
 501         "AUG_SAVE_NOOP" = 16
 502         Make save a no-op, just record what would have been
 503         changed.
 504
 505         "AUG_NO_LOAD" = 32
 506         Do not load the tree in "g.aug_init".
 507
 508         To close the handle, you can call "g.aug_close".
 509
 510         To find out more about Augeas, see <http://augeas.net/>.
 511         """
 512         return libguestfsmod.aug_init (self._o, root, flags)
 513
 514     def aug_close (self):
 515         u"""Close the current Augeas handle and free up any
 516         resources used by it. After calling this, you have to
 517         call "g.aug_init" again before you can use any other
 518         Augeas functions.
 519         """
 520         return libguestfsmod.aug_close (self._o)
 521
 522     def aug_defvar (self, name, expr):
 523         u"""Defines an Augeas variable "name" whose value is the
 524         result of evaluating "expr". If "expr" is NULL, then
 525         "name" is undefined.
 526
 527         On success this returns the number of nodes in "expr",
 528         or 0 if "expr" evaluates to something which is not a
 529         nodeset.
 530         """
 531         return libguestfsmod.aug_defvar (self._o, name, expr)
 532
 533     def aug_defnode (self, name, expr, val):
 534         u"""Defines a variable "name" whose value is the result of
 535         evaluating "expr".
 536
 537         If "expr" evaluates to an empty nodeset, a node is
 538         created, equivalent to calling "g.aug_set" "expr",
 539         "value". "name" will be the nodeset containing that
 540         single node.
 541
 542         On success this returns a pair containing the number of
 543         nodes in the nodeset, and a boolean flag if a node was
 544         created.
 545
 546         This function returns a tuple (int, bool).
 547         """
 548         return libguestfsmod.aug_defnode (self._o, name, expr, val)
 549
 550     def aug_get (self, path):
 551         u"""Look up the value associated with "path". If "path"
 552         matches exactly one node, the "value" is returned.
 553         """
 554         return libguestfsmod.aug_get (self._o, path)
 555
 556     def aug_set (self, path, val):
 557         u"""Set the value associated with "path" to "value".
 558         """
 559         return libguestfsmod.aug_set (self._o, path, val)
 560
 561     def aug_insert (self, path, label, before):
 562         u"""Create a new sibling "label" for "path", inserting it
 563         into the tree before or after "path" (depending on the
 564         boolean flag "before").
 565
 566         "path" must match exactly one existing node in the tree,
 567         and "label" must be a label, ie. not contain "/", "*" or
 568         end with a bracketed index "[N]".
 569         """
 570         return libguestfsmod.aug_insert (self._o, path, label, before)
 571
 572     def aug_rm (self, path):
 573         u"""Remove "path" and all of its children.
 574
 575         On success this returns the number of entries which were
 576         removed.
 577         """
 578         return libguestfsmod.aug_rm (self._o, path)
 579
 580     def aug_mv (self, src, dest):
 581         u"""Move the node "src" to "dest". "src" must match exactly
 582         one node. "dest" is overwritten if it exists.
 583         """
 584         return libguestfsmod.aug_mv (self._o, src, dest)
 585
 586     def aug_match (self, path):
 587         u"""Returns a list of paths which match the path expression
 588         "path". The returned paths are sufficiently qualified so
 589         that they match exactly one node in the current tree.
 590
 591         This function returns a list of strings.
 592         """
 593         return libguestfsmod.aug_match (self._o, path)
 594
 595     def aug_save (self):
 596         u"""This writes all pending changes to disk.
 597
 598         The flags which were passed to "g.aug_init" affect
 599         exactly how files are saved.
 600         """
 601         return libguestfsmod.aug_save (self._o)
 602
 603     def aug_load (self):
 604         u"""Load files into the tree.
 605
 606         See "aug_load" in the Augeas documentation for the full
 607         gory details.
 608         """
 609         return libguestfsmod.aug_load (self._o)
 610
 611     def aug_ls (self, path):
 612         u"""This is just a shortcut for listing "g.aug_match"
 613         "path/*" and sorting the resulting nodes into
 614         alphabetical order.
 615
 616         This function returns a list of strings.
 617         """
 618         return libguestfsmod.aug_ls (self._o, path)
 619
 620     def rm (self, path):
 621         u"""Remove the single file "path".
 622         """
 623         return libguestfsmod.rm (self._o, path)
 624
 625     def rmdir (self, path):
 626         u"""Remove the single directory "path".
 627         """
 628         return libguestfsmod.rmdir (self._o, path)
 629
 630     def rm_rf (self, path):
 631         u"""Remove the file or directory "path", recursively
 632         removing the contents if its a directory. This is like
 633         the "rm -rf" shell command.
 634         """
 635         return libguestfsmod.rm_rf (self._o, path)
 636
 637     def mkdir (self, path):
 638         u"""Create a directory named "path".
 639         """
 640         return libguestfsmod.mkdir (self._o, path)
 641
 642     def mkdir_p (self, path):
 643         u"""Create a directory named "path", creating any parent
 644         directories as necessary. This is like the "mkdir -p"
 645         shell command.
 646         """
 647         return libguestfsmod.mkdir_p (self._o, path)
 648
 649     def chmod (self, mode, path):
 650         u"""Change the mode (permissions) of "path" to "mode". Only
 651         numeric modes are supported.
 652         """
 653         return libguestfsmod.chmod (self._o, mode, path)
 654
 655     def chown (self, owner, group, path):
 656         u"""Change the file owner to "owner" and group to "group".
 657
 658         Only numeric uid and gid are supported. If you want to
 659         use names, you will need to locate and parse the
 660         password file yourself (Augeas support makes this
 661         relatively easy).
 662         """
 663         return libguestfsmod.chown (self._o, owner, group, path)
 664
 665     def exists (self, path):
 666         u"""This returns "true" if and only if there is a file,
 667         directory (or anything) with the given "path" name.
 668
 669         See also "g.is_file", "g.is_dir", "g.stat".
 670         """
 671         return libguestfsmod.exists (self._o, path)
 672
 673     def is_file (self, path):
 674         u"""This returns "true" if and only if there is a file with
 675         the given "path" name. Note that it returns false for
 676         other objects like directories.
 677
 678         See also "g.stat".
 679         """
 680         return libguestfsmod.is_file (self._o, path)
 681
 682     def is_dir (self, path):
 683         u"""This returns "true" if and only if there is a directory
 684         with the given "path" name. Note that it returns false
 685         for other objects like files.
 686
 687         See also "g.stat".
 688         """
 689         return libguestfsmod.is_dir (self._o, path)
 690
 691     def pvcreate (self, device):
 692         u"""This creates an LVM physical volume on the named
 693         "device", where "device" should usually be a partition
 694         name such as "/dev/sda1".
 695         """
 696         return libguestfsmod.pvcreate (self._o, device)
 697
 698     def vgcreate (self, volgroup, physvols):
 699         u"""This creates an LVM volume group called "volgroup" from
 700         the non-empty list of physical volumes "physvols".
 701         """
 702         return libguestfsmod.vgcreate (self._o, volgroup, physvols)
 703
 704     def lvcreate (self, logvol, volgroup, mbytes):
 705         u"""This creates an LVM volume group called "logvol" on the
 706         volume group "volgroup", with "size" megabytes.
 707         """
 708         return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes)
 709
 710     def mkfs (self, fstype, device):
 711         u"""This creates a filesystem on "device" (usually a
 712         partition or LVM logical volume). The filesystem type is
 713         "fstype", for example "ext3".
 714         """
 715         return libguestfsmod.mkfs (self._o, fstype, device)
 716
 717     def sfdisk (self, device, cyls, heads, sectors, lines):
 718         u"""This is a direct interface to the sfdisk(8) program for
 719         creating partitions on block devices.
 720
 721         "device" should be a block device, for example
 722         "/dev/sda".
 723
 724         "cyls", "heads" and "sectors" are the number of
 725         cylinders, heads and sectors on the device, which are
 726         passed directly to sfdisk as the *-C*, *-H* and *-S*
 727         parameters. If you pass 0 for any of these, then the
 728         corresponding parameter is omitted. Usually for 'large'
 729         disks, you can just pass 0 for these, but for small
 730         (floppy-sized) disks, sfdisk (or rather, the kernel)
 731         cannot work out the right geometry and you will need to
 732         tell it.
 733
 734         "lines" is a list of lines that we feed to "sfdisk". For
 735         more information refer to the sfdisk(8) manpage.
 736
 737         To create a single partition occupying the whole disk,
 738         you would pass "lines" as a single element list, when
 739         the single element being the string "," (comma).
 740
 741         This command is dangerous. Without careful use you can
 742         easily destroy all your data.
 743         """
 744         return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines)
 745
 746     def write_file (self, path, content, size):
 747         u"""This call creates a file called "path". The contents of
 748         the file is the string "content" (which can contain any
 749         8 bit data), with length "size".
 750
 751         As a special case, if "size" is 0 then the length is
 752         calculated using "strlen" (so in this case the content
 753         cannot contain embedded ASCII NULs).
 754
 755         *NB.* Owing to a bug, writing content containing ASCII
 756         NUL characters does *not* work, even if the length is
 757         specified. We hope to resolve this bug in a future
 758         version. In the meantime use "g.upload".
 759
 760         Because of the message protocol, there is a transfer
 761         limit of somewhere between 2MB and 4MB. To transfer
 762         large files you should use FTP.
 763         """
 764         return libguestfsmod.write_file (self._o, path, content, size)
 765
 766     def umount (self, pathordevice):
 767         u"""This unmounts the given filesystem. The filesystem may
 768         be specified either by its mountpoint (path) or the
 769         device which contains the filesystem.
 770         """
 771         return libguestfsmod.umount (self._o, pathordevice)
 772
 773     def mounts (self):
 774         u"""This returns the list of currently mounted filesystems.
 775         It returns the list of devices (eg. "/dev/sda1",
 776         "/dev/VG/LV").
 777
 778         Some internal mounts are not shown.
 779
 780         This function returns a list of strings.
 781         """
 782         return libguestfsmod.mounts (self._o)
 783
 784     def umount_all (self):
 785         u"""This unmounts all mounted filesystems.
 786
 787         Some internal mounts are not unmounted by this call.
 788         """
 789         return libguestfsmod.umount_all (self._o)
 790
 791     def lvm_remove_all (self):
 792         u"""This command removes all LVM logical volumes, volume
 793         groups and physical volumes.
 794
 795         This command is dangerous. Without careful use you can
 796         easily destroy all your data.
 797         """
 798         return libguestfsmod.lvm_remove_all (self._o)
 799
 800     def file (self, path):
 801         u"""This call uses the standard file(1) command to determine
 802         the type or contents of the file. This also works on
 803         devices, for example to find out whether a partition
 804         contains a filesystem.
 805
 806         The exact command which runs is "file -bsL path". Note
 807         in particular that the filename is not prepended to the
 808         output (the "-b" option).
 809         """
 810         return libguestfsmod.file (self._o, path)
 811
 812     def command (self, arguments):
 813         u"""This call runs a command from the guest filesystem. The
 814         filesystem must be mounted, and must contain a
 815         compatible operating system (ie. something Linux, with
 816         the same or compatible processor architecture).
 817
 818         The single parameter is an argv-style list of arguments.
 819         The first element is the name of the program to run.
 820         Subsequent elements are parameters. The list must be
 821         non-empty (ie. must contain a program name).
 822
 823         The return value is anything printed to *stdout* by the
 824         command.
 825
 826         If the command returns a non-zero exit status, then this
 827         function returns an error message. The error message
 828         string is the content of *stderr* from the command.
 829
 830         The $PATH environment variable will contain at least
 831         "/usr/bin" and "/bin". If you require a program from
 832         another location, you should provide the full path in
 833         the first parameter.
 834
 835         Shared libraries and data files required by the program
 836         must be available on filesystems which are mounted in
 837         the correct places. It is the caller's responsibility to
 838         ensure all filesystems that are needed are mounted at
 839         the right locations.
 840
 841         Because of the message protocol, there is a transfer
 842         limit of somewhere between 2MB and 4MB. To transfer
 843         large files you should use FTP.
 844         """
 845         return libguestfsmod.command (self._o, arguments)
 846
 847     def command_lines (self, arguments):
 848         u"""This is the same as "g.command", but splits the result
 849         into a list of lines.
 850
 851         This function returns a list of strings.
 852
 853         Because of the message protocol, there is a transfer
 854         limit of somewhere between 2MB and 4MB. To transfer
 855         large files you should use FTP.
 856         """
 857         return libguestfsmod.command_lines (self._o, arguments)
 858
 859     def stat (self, path):
 860         u"""Returns file information for the given "path".
 861
 862         This is the same as the stat(2) system call.
 863
 864         This function returns a dictionary, with keys matching
 865         the various fields in the stat structure.
 866         """
 867         return libguestfsmod.stat (self._o, path)
 868
 869     def lstat (self, path):
 870         u"""Returns file information for the given "path".
 871
 872         This is the same as "g.stat" except that if "path" is a
 873         symbolic link, then the link is stat-ed, not the file it
 874         refers to.
 875
 876         This is the same as the lstat(2) system call.
 877
 878         This function returns a dictionary, with keys matching
 879         the various fields in the stat structure.
 880         """
 881         return libguestfsmod.lstat (self._o, path)
 882
 883     def statvfs (self, path):
 884         u"""Returns file system statistics for any mounted file
 885         system. "path" should be a file or directory in the
 886         mounted file system (typically it is the mount point
 887         itself, but it doesn't need to be).
 888
 889         This is the same as the statvfs(2) system call.
 890
 891         This function returns a dictionary, with keys matching
 892         the various fields in the statvfs structure.
 893         """
 894         return libguestfsmod.statvfs (self._o, path)
 895
 896     def tune2fs_l (self, device):
 897         u"""This returns the contents of the ext2, ext3 or ext4
 898         filesystem superblock on "device".
 899
 900         It is the same as running "tune2fs -l device". See
 901         tune2fs(8) manpage for more details. The list of fields
 902         returned isn't clearly defined, and depends on both the
 903         version of "tune2fs" that libguestfs was built against,
 904         and the filesystem itself.
 905
 906         This function returns a dictionary.
 907         """
 908         return libguestfsmod.tune2fs_l (self._o, device)
 909
 910     def blockdev_setro (self, device):
 911         u"""Sets the block device named "device" to read-only.
 912
 913         This uses the blockdev(8) command.
 914         """
 915         return libguestfsmod.blockdev_setro (self._o, device)
 916
 917     def blockdev_setrw (self, device):
 918         u"""Sets the block device named "device" to read-write.
 919
 920         This uses the blockdev(8) command.
 921         """
 922         return libguestfsmod.blockdev_setrw (self._o, device)
 923
 924     def blockdev_getro (self, device):
 925         u"""Returns a boolean indicating if the block device is
 926         read-only (true if read-only, false if not).
 927
 928         This uses the blockdev(8) command.
 929         """
 930         return libguestfsmod.blockdev_getro (self._o, device)
 931
 932     def blockdev_getss (self, device):
 933         u"""This returns the size of sectors on a block device.
 934         Usually 512, but can be larger for modern devices.
 935
 936         (Note, this is not the size in sectors, use
 937         "g.blockdev_getsz" for that).
 938
 939         This uses the blockdev(8) command.
 940         """
 941         return libguestfsmod.blockdev_getss (self._o, device)
 942
 943     def blockdev_getbsz (self, device):
 944         u"""This returns the block size of a device.
 945
 946         (Note this is different from both *size in blocks* and
 947         *filesystem block size*).
 948
 949         This uses the blockdev(8) command.
 950         """
 951         return libguestfsmod.blockdev_getbsz (self._o, device)
 952
 953     def blockdev_setbsz (self, device, blocksize):
 954         u"""This sets the block size of a device.
 955
 956         (Note this is different from both *size in blocks* and
 957         *filesystem block size*).
 958
 959         This uses the blockdev(8) command.
 960         """
 961         return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
 962
 963     def blockdev_getsz (self, device):
 964         u"""This returns the size of the device in units of 512-byte
 965         sectors (even if the sectorsize isn't 512 bytes ...
 966         weird).
 967
 968         See also "g.blockdev_getss" for the real sector size of
 969         the device, and "g.blockdev_getsize64" for the more
 970         useful *size in bytes*.
 971
 972         This uses the blockdev(8) command.
 973         """
 974         return libguestfsmod.blockdev_getsz (self._o, device)
 975
 976     def blockdev_getsize64 (self, device):
 977         u"""This returns the size of the device in bytes.
 978
 979         See also "g.blockdev_getsz".
 980
 981         This uses the blockdev(8) command.
 982         """
 983         return libguestfsmod.blockdev_getsize64 (self._o, device)
 984
 985     def blockdev_flushbufs (self, device):
 986         u"""This tells the kernel to flush internal buffers
 987         associated with "device".
 988
 989         This uses the blockdev(8) command.
 990         """
 991         return libguestfsmod.blockdev_flushbufs (self._o, device)
 992
 993     def blockdev_rereadpt (self, device):
 994         u"""Reread the partition table on "device".
 995
 996         This uses the blockdev(8) command.
 997         """
 998         return libguestfsmod.blockdev_rereadpt (self._o, device)
 999
1000     def upload (self, filename, remotefilename):
1001         u"""Upload local file "filename" to "remotefilename" on the
1002         filesystem.
1003
1004         "filename" can also be a named pipe.
1005
1006         See also "g.download".
1007         """
1008         return libguestfsmod.upload (self._o, filename, remotefilename)
1009
1010     def download (self, remotefilename, filename):
1011         u"""Download file "remotefilename" and save it as "filename"
1012         on the local machine.
1013
1014         "filename" can also be a named pipe.
1015
1016         See also "g.upload", "g.cat".
1017         """
1018         return libguestfsmod.download (self._o, remotefilename, filename)
1019
1020     def checksum (self, csumtype, path):
1021         u"""This call computes the MD5, SHAx or CRC checksum of the
1022         file named "path".
1023
1024         The type of checksum to compute is given by the
1025         "csumtype" parameter which must have one of the
1026         following values:
1027
1028         "crc"
1029         Compute the cyclic redundancy check (CRC) specified
1030         by POSIX for the "cksum" command.
1031
1032         "md5"
1033         Compute the MD5 hash (using the "md5sum" program).
1034
1035         "sha1"
1036         Compute the SHA1 hash (using the "sha1sum" program).
1037
1038         "sha224"
1039         Compute the SHA224 hash (using the "sha224sum"
1040         program).
1041
1042         "sha256"
1043         Compute the SHA256 hash (using the "sha256sum"
1044         program).
1045
1046         "sha384"
1047         Compute the SHA384 hash (using the "sha384sum"
1048         program).
1049
1050         "sha512"
1051         Compute the SHA512 hash (using the "sha512sum"
1052         program).
1053
1054         The checksum is returned as a printable string.
1055         """
1056         return libguestfsmod.checksum (self._o, csumtype, path)
1057
1058     def tar_in (self, tarfile, directory):
1059         u"""This command uploads and unpacks local file "tarfile"
1060         (an *uncompressed* tar file) into "directory".
1061
1062         To upload a compressed tarball, use "g.tgz_in".
1063         """
1064         return libguestfsmod.tar_in (self._o, tarfile, directory)
1065
1066     def tar_out (self, directory, tarfile):
1067         u"""This command packs the contents of "directory" and
1068         downloads it to local file "tarfile".
1069
1070         To download a compressed tarball, use "g.tgz_out".
1071         """
1072         return libguestfsmod.tar_out (self._o, directory, tarfile)
1073
1074     def tgz_in (self, tarball, directory):
1075         u"""This command uploads and unpacks local file "tarball" (a
1076         *gzip compressed* tar file) into "directory".
1077
1078         To upload an uncompressed tarball, use "g.tar_in".
1079         """
1080         return libguestfsmod.tgz_in (self._o, tarball, directory)
1081
1082     def tgz_out (self, directory, tarball):
1083         u"""This command packs the contents of "directory" and
1084         downloads it to local file "tarball".
1085
1086         To download an uncompressed tarball, use "g.tar_out".
1087         """
1088         return libguestfsmod.tgz_out (self._o, directory, tarball)
1089
1090     def mount_ro (self, device, mountpoint):
1091         u"""This is the same as the "g.mount" command, but it mounts
1092         the filesystem with the read-only (*-o ro*) flag.
1093         """
1094         return libguestfsmod.mount_ro (self._o, device, mountpoint)
1095
1096     def mount_options (self, options, device, mountpoint):
1097         u"""This is the same as the "g.mount" command, but it allows
1098         you to set the mount options as for the mount(8) *-o*
1099         flag.
1100         """
1101         return libguestfsmod.mount_options (self._o, options, device, mountpoint)
1102
1103     def mount_vfs (self, options, vfstype, device, mountpoint):
1104         u"""This is the same as the "g.mount" command, but it allows
1105         you to set both the mount options and the vfstype as for
1106         the mount(8) *-o* and *-t* flags.
1107         """
1108         return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint)
1109
1110     def debug (self, subcmd, extraargs):
1111         u"""The "g.debug" command exposes some internals of
1112         "guestfsd" (the guestfs daemon) that runs inside the
1113         qemu subprocess.
1114
1115         There is no comprehensive help for this command. You
1116         have to look at the file "daemon/debug.c" in the
1117         libguestfs source to find out what you can do.
1118         """
1119         return libguestfsmod.debug (self._o, subcmd, extraargs)
1120
1121     def lvremove (self, device):
1122         u"""Remove an LVM logical volume "device", where "device" is
1123         the path to the LV, such as "/dev/VG/LV".
1124
1125         You can also remove all LVs in a volume group by
1126         specifying the VG name, "/dev/VG".
1127         """
1128         return libguestfsmod.lvremove (self._o, device)
1129
1130     def vgremove (self, vgname):
1131         u"""Remove an LVM volume group "vgname", (for example "VG").
1132
1133         This also forcibly removes all logical volumes in the
1134         volume group (if any).
1135         """
1136         return libguestfsmod.vgremove (self._o, vgname)
1137
1138     def pvremove (self, device):
1139         u"""This wipes a physical volume "device" so that LVM will
1140         no longer recognise it.
1141
1142         The implementation uses the "pvremove" command which
1143         refuses to wipe physical volumes that contain any volume
1144         groups, so you have to remove those first.
1145         """
1146         return libguestfsmod.pvremove (self._o, device)
1147
1148     def set_e2label (self, device, label):
1149         u"""This sets the ext2/3/4 filesystem label of the
1150         filesystem on "device" to "label". Filesystem labels are
1151         limited to 16 characters.
1152
1153         You can use either "g.tune2fs_l" or "g.get_e2label" to
1154         return the existing label on a filesystem.
1155         """
1156         return libguestfsmod.set_e2label (self._o, device, label)
1157
1158     def get_e2label (self, device):
1159         u"""This returns the ext2/3/4 filesystem label of the
1160         filesystem on "device".
1161         """
1162         return libguestfsmod.get_e2label (self._o, device)
1163
1164     def set_e2uuid (self, device, uuid):
1165         u"""This sets the ext2/3/4 filesystem UUID of the filesystem
1166         on "device" to "uuid". The format of the UUID and
1167         alternatives such as "clear", "random" and "time" are
1168         described in the tune2fs(8) manpage.
1169
1170         You can use either "g.tune2fs_l" or "g.get_e2uuid" to
1171         return the existing UUID of a filesystem.
1172         """
1173         return libguestfsmod.set_e2uuid (self._o, device, uuid)
1174
1175     def get_e2uuid (self, device):
1176         u"""This returns the ext2/3/4 filesystem UUID of the
1177         filesystem on "device".
1178         """
1179         return libguestfsmod.get_e2uuid (self._o, device)
1180
1181     def fsck (self, fstype, device):
1182         u"""This runs the filesystem checker (fsck) on "device"
1183         which should have filesystem type "fstype".
1184
1185         The returned integer is the status. See fsck(8) for the
1186         list of status codes from "fsck".
1187
1188         Notes:
1189
1190         *   Multiple status codes can be summed together.
1191
1192         *   A non-zero return code can mean "success", for
1193         example if errors have been corrected on the
1194         filesystem.
1195
1196         *   Checking or repairing NTFS volumes is not supported
1197         (by linux-ntfs).
1198
1199         This command is entirely equivalent to running "fsck -a
1200         -t fstype device".
1201         """
1202         return libguestfsmod.fsck (self._o, fstype, device)
1203
1204     def zero (self, device):
1205         u"""This command writes zeroes over the first few blocks of
1206         "device".
1207
1208         How many blocks are zeroed isn't specified (but it's
1209         *not* enough to securely wipe the device). It should be
1210         sufficient to remove any partition tables, filesystem
1211         superblocks and so on.
1212         """
1213         return libguestfsmod.zero (self._o, device)
1214
1215     def grub_install (self, root, device):
1216         u"""This command installs GRUB (the Grand Unified
1217         Bootloader) on "device", with the root directory being
1218         "root".
1219         """
1220         return libguestfsmod.grub_install (self._o, root, device)
1221
1222     def cp (self, src, dest):
1223         u"""This copies a file from "src" to "dest" where "dest" is
1224         either a destination filename or destination directory.
1225         """
1226         return libguestfsmod.cp (self._o, src, dest)
1227
1228     def cp_a (self, src, dest):
1229         u"""This copies a file or directory from "src" to "dest"
1230         recursively using the "cp -a" command.
1231         """
1232         return libguestfsmod.cp_a (self._o, src, dest)
1233
1234     def mv (self, src, dest):
1235         u"""This moves a file from "src" to "dest" where "dest" is
1236         either a destination filename or destination directory.
1237         """
1238         return libguestfsmod.mv (self._o, src, dest)
1239
1240     def drop_caches (self, whattodrop):
1241         u"""This instructs the guest kernel to drop its page cache,
1242         and/or dentries and inode caches. The parameter
1243         "whattodrop" tells the kernel what precisely to drop,
1244         see <http://linux-mm.org/Drop_Caches>
1245
1246         Setting "whattodrop" to 3 should drop everything.
1247
1248         This automatically calls sync(2) before the operation,
1249         so that the maximum guest memory is freed.
1250         """
1251         return libguestfsmod.drop_caches (self._o, whattodrop)
1252
1253     def dmesg (self):
1254         u"""This returns the kernel messages ("dmesg" output) from
1255         the guest kernel. This is sometimes useful for extended
1256         debugging of problems.
1257
1258         Another way to get the same information is to enable
1259         verbose messages with "g.set_verbose" or by setting the
1260         environment variable "LIBGUESTFS_DEBUG=1" before running
1261         the program.
1262         """
1263         return libguestfsmod.dmesg (self._o)
1264
1265     def ping_daemon (self):
1266         u"""This is a test probe into the guestfs daemon running
1267         inside the qemu subprocess. Calling this function checks
1268         that the daemon responds to the ping message, without
1269         affecting the daemon or attached block device(s) in any
1270         other way.
1271         """
1272         return libguestfsmod.ping_daemon (self._o)
1273
1274     def equal (self, file1, file2):
1275         u"""This compares the two files "file1" and "file2" and
1276         returns true if their content is exactly equal, or false
1277         otherwise.
1278
1279         The external cmp(1) program is used for the comparison.
1280         """
1281         return libguestfsmod.equal (self._o, file1, file2)
1282
1283     def strings (self, path):
1284         u"""This runs the strings(1) command on a file and returns
1285         the list of printable strings found.
1286
1287         This function returns a list of strings.
1288
1289         Because of the message protocol, there is a transfer
1290         limit of somewhere between 2MB and 4MB. To transfer
1291         large files you should use FTP.
1292         """
1293         return libguestfsmod.strings (self._o, path)
1294
1295     def strings_e (self, encoding, path):
1296         u"""This is like the "g.strings" command, but allows you to
1297         specify the encoding.
1298
1299         See the strings(1) manpage for the full list of
1300         encodings.
1301
1302         Commonly useful encodings are "l" (lower case L) which
1303         will show strings inside Windows/x86 files.
1304
1305         The returned strings are transcoded to UTF-8.
1306
1307         This function returns a list of strings.
1308
1309         Because of the message protocol, there is a transfer
1310         limit of somewhere between 2MB and 4MB. To transfer
1311         large files you should use FTP.
1312         """
1313         return libguestfsmod.strings_e (self._o, encoding, path)
1314
1315     def hexdump (self, path):
1316         u"""This runs "hexdump -C" on the given "path". The result
1317         is the human-readable, canonical hex dump of the file.
1318
1319         Because of the message protocol, there is a transfer
1320         limit of somewhere between 2MB and 4MB. To transfer
1321         large files you should use FTP.
1322         """
1323         return libguestfsmod.hexdump (self._o, path)
1324