mirrors/libguestfs
1
0
Fork 0
mirror of https://github.com/libguestfs/libguestfs.git synced 2026-03-21 22:53:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Added Python documentation.

Browse Source
This commit is contained in:
Richard Jones
2009-04-16 11:39:22 +01:00
parent 7e47aaa137
commit 3eba057f5a
2 changed files with 774 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

624
python/guestfs.py
View File

@@ -18,243 +18,867 @@
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
u"""Python bindings for libguestfs
import guestfs
g = guestfs.GuestFS ()
g.add_drive ("guest.img")
g.launch ()
g.wait_ready ()
parts = g.list_partitions ()
The guestfs module provides a Python binding to the libguestfs API
for examining and modifying virtual machine disk images.
Amongst the things this is good for: making batch configuration
changes to guests, getting disk used/free statistics (see also:
virt-df), migrating between virtualization systems (see also:
virt-p2v), performing partial backups, performing partial guest
clones, cloning guests and changing registry/UUID/hostname info, and
much else besides.
Libguestfs uses Linux kernel and qemu code, and can access any type of
guest filesystem that Linux and qemu can, including but not limited
to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
schemes, qcow, qcow2, vmdk.
Libguestfs provides ways to enumerate guest storage (eg. partitions,
LVs, what filesystem is in each LV, etc.). It can also run commands
in the context of the guest. Also you can access filesystems over FTP.
Errors which happen while using the API are turned into Python
RuntimeError exceptions.
To create a guestfs handle you usually have to perform the following
sequence of calls:
# Create the handle, call add_drive at least once, and possibly
# several times if the guest has multiple block devices:
g = guestfs.GuestFS ()
g.add_drive ("guest.img")
# Launch the qemu subprocess and wait for it to become ready:
g.launch ()
g.wait_ready ()
# Now you can issue commands, for example:
logvols = g.lvs ()
"""
import libguestfsmod
class GuestFS:
"""Instances of this class are libguestfs API handles."""
def __init__ (self):
"""Create a new libguestfs handle."""
self._o = libguestfsmod.create ()
def __del__ (self):
libguestfsmod.close (self._o)
def launch (self):
u"""Internally libguestfs is implemented by running a
virtual machine using qemu(1).
You should call this after configuring the handle (eg.
adding drives) but before performing any actions.
"""
return libguestfsmod.launch (self._o)
def wait_ready (self):
u"""Internally libguestfs is implemented by running a
virtual machine using qemu(1).
You should call this after "g.launch" to wait for the
launch to complete.
"""
return libguestfsmod.wait_ready (self._o)
def kill_subprocess (self):
u"""This kills the qemu subprocess. You should never need to
call this.
"""
return libguestfsmod.kill_subprocess (self._o)
def add_drive (self, filename):
u"""This function adds a virtual machine disk image
"filename" to the guest. The first time you call this
function, the disk appears as IDE disk 0 ("/dev/sda") in
the guest, the second time as "/dev/sdb", and so on.
You don't necessarily need to be root when using
libguestfs. However you obviously do need sufficient
permissions to access the filename for whatever
operations you want to perform (ie. read access if you
just want to read the image or write access if you want
to modify the image).
This is equivalent to the qemu parameter "-drive
file=filename".
"""
return libguestfsmod.add_drive (self._o, filename)
def add_cdrom (self, filename):
u"""This function adds a virtual CD-ROM disk image to the
guest.
This is equivalent to the qemu parameter "-cdrom
filename".
"""
return libguestfsmod.add_cdrom (self._o, filename)
def config (self, qemuparam, qemuvalue):
u"""This can be used to add arbitrary qemu command line
parameters of the form "-param value". Actually it's not
quite arbitrary - we prevent you from setting some
parameters which would interfere with parameters that we
use.
The first character of "param" string must be a "-"
(dash).
"value" can be NULL.
"""
return libguestfsmod.config (self._o, qemuparam, qemuvalue)
def set_path (self, path):
u"""Set the path that libguestfs searches for kernel and
initrd.img.
The default is "$libdir/guestfs" unless overridden by
setting "LIBGUESTFS_PATH" environment variable.
The string "path" is stashed in the libguestfs handle,
so the caller must make sure it remains valid for the
lifetime of the handle.
Setting "path" to "NULL" restores the default path.
"""
return libguestfsmod.set_path (self._o, path)
def get_path (self):
u"""Return the current search path.
This is always non-NULL. If it wasn't set already, then
this will return the default path.
"""
return libguestfsmod.get_path (self._o)
def set_autosync (self, autosync):
u"""If "autosync" is true, this enables autosync. Libguestfs
will make a best effort attempt to run "g.sync" when the
handle is closed (also if the program exits without
closing handles).
"""
return libguestfsmod.set_autosync (self._o, autosync)
def get_autosync (self):
u"""Get the autosync flag.
"""
return libguestfsmod.get_autosync (self._o)
def set_verbose (self, verbose):
u"""If "verbose" is true, this turns on verbose messages (to
"stderr").
Verbose messages are disabled unless the environment
variable "LIBGUESTFS_DEBUG" is defined and set to 1.
"""
return libguestfsmod.set_verbose (self._o, verbose)
def get_verbose (self):
u"""This returns the verbose messages flag.
"""
return libguestfsmod.get_verbose (self._o)
def mount (self, device, mountpoint):
u"""Mount a guest disk at a position in the filesystem.
Block devices are named "/dev/sda", "/dev/sdb" and so
on, as they were added to the guest. If those block
devices contain partitions, they will have the usual
names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style
names can be used.
The rules are the same as for mount(2): A filesystem
must first be mounted on "/" before others can be
mounted. Other filesystems can only be mounted on
directories which already exist.
The mounted filesystem is writable, if we have
sufficient permissions on the underlying device.
The filesystem options "sync" and "noatime" are set with
this call, in order to improve reliability.
"""
return libguestfsmod.mount (self._o, device, mountpoint)
def sync (self):
u"""This syncs the disk, so that any writes are flushed
through to the underlying disk image.
You should always call this if you have modified a disk
image, before closing the handle.
"""
return libguestfsmod.sync (self._o)
def touch (self, path):
u"""Touch acts like the touch(1) command. It can be used to
update the timestamps on a file, or, if the file does
not exist, to create a new zero-length file.
"""
return libguestfsmod.touch (self._o, path)
def cat (self, path):
u"""Return the contents of the file named "path".
Note that this function cannot correctly handle binary
files (specifically, files containing "\\0" character
which is treated as end of string). For those you need
to use the "g.read_file" function which has a more
complex interface.
Because of the message protocol, there is a transfer
limit of somewhere between 2MB and 4MB. To transfer
large files you should use FTP.
"""
return libguestfsmod.cat (self._o, path)
def ll (self, directory):
u"""List the files in "directory" (relative to the root
directory, there is no cwd) in the format of 'ls -la'.
This command is mostly useful for interactive sessions.
It is *not* intended that you try to parse the output
string.
"""
return libguestfsmod.ll (self._o, directory)
def ls (self, directory):
u"""List the files in "directory" (relative to the root
directory, there is no cwd). The '.' and '..' entries
are not returned, but hidden files are shown.
This command is mostly useful for interactive sessions.
Programs should probably use "g.readdir" instead.
This function returns a list of strings.
"""
return libguestfsmod.ls (self._o, directory)
def list_devices (self):
u"""List all the block devices.
The full block device names are returned, eg. "/dev/sda"
This function returns a list of strings.
"""
return libguestfsmod.list_devices (self._o)
def list_partitions (self):
u"""List all the partitions detected on all block devices.
The full partition device names are returned, eg.
"/dev/sda1"
This does not return logical volumes. For that you will
need to call "g.lvs".
This function returns a list of strings.
"""
return libguestfsmod.list_partitions (self._o)
def pvs (self):
u"""List all the physical volumes detected. This is the
equivalent of the pvs(8) command.
This returns a list of just the device names that
contain PVs (eg. "/dev/sda2").
See also "g.pvs_full".
This function returns a list of strings.
"""
return libguestfsmod.pvs (self._o)
def vgs (self):
u"""List all the volumes groups detected. This is the
equivalent of the vgs(8) command.
This returns a list of just the volume group names that
were detected (eg. "VolGroup00").
See also "g.vgs_full".
This function returns a list of strings.
"""
return libguestfsmod.vgs (self._o)
def lvs (self):
u"""List all the logical volumes detected. This is the
equivalent of the lvs(8) command.
This returns a list of the logical volume device names
(eg. "/dev/VolGroup00/LogVol00").
See also "g.lvs_full".
This function returns a list of strings.
"""
return libguestfsmod.lvs (self._o)
def pvs_full (self):
u"""List all the physical volumes detected. This is the
equivalent of the pvs(8) command. The "full" version
includes all fields.
This function returns a list of PVs. Each PV is
represented as a dictionary.
"""
return libguestfsmod.pvs_full (self._o)
def vgs_full (self):
u"""List all the volumes groups detected. This is the
equivalent of the vgs(8) command. The "full" version
includes all fields.
This function returns a list of VGs. Each VG is
represented as a dictionary.
"""
return libguestfsmod.vgs_full (self._o)
def lvs_full (self):
u"""List all the logical volumes detected. This is the
equivalent of the lvs(8) command. The "full" version
includes all fields.
This function returns a list of LVs. Each LV is
represented as a dictionary.
"""
return libguestfsmod.lvs_full (self._o)
def read_lines (self, path):
u"""Return the contents of the file named "path".
The file contents are returned as a list of lines.
Trailing "LF" and "CRLF" character sequences are *not*
returned.
Note that this function cannot correctly handle binary
files (specifically, files containing "\\0" character
which is treated as end of line). For those you need to
use the "g.read_file" function which has a more complex
interface.
This function returns a list of strings.
"""
return libguestfsmod.read_lines (self._o, path)
def aug_init (self, root, flags):
u"""Create a new Augeas handle for editing configuration
files. If there was any previous Augeas handle
associated with this guestfs session, then it is closed.
You must call this before using any other "g.aug_*"
commands.
"root" is the filesystem root. "root" must not be NULL,
use "/" instead.
The flags are the same as the flags defined in
<augeas.h>, the logical *or* of the following integers:
"AUG_SAVE_BACKUP" = 1
Keep the original file with a ".augsave" extension.
"AUG_SAVE_NEWFILE" = 2
Save changes into a file with extension ".augnew",
and do not overwrite original. Overrides
"AUG_SAVE_BACKUP".
"AUG_TYPE_CHECK" = 4
Typecheck lenses (can be expensive).
"AUG_NO_STDINC" = 8
Do not use standard load path for modules.
"AUG_SAVE_NOOP" = 16
Make save a no-op, just record what would have been
changed.
"AUG_NO_LOAD" = 32
Do not load the tree in "g.aug_init".
To close the handle, you can call "g.aug_close".
To find out more about Augeas, see <http://augeas.net/>.
"""
return libguestfsmod.aug_init (self._o, root, flags)
def aug_close (self):
u"""Close the current Augeas handle and free up any
resources used by it. After calling this, you have to
call "g.aug_init" again before you can use any other
Augeas functions.
"""
return libguestfsmod.aug_close (self._o)
def aug_defvar (self, name, expr):
u"""Defines an Augeas variable "name" whose value is the
result of evaluating "expr". If "expr" is NULL, then
"name" is undefined.
On success this returns the number of nodes in "expr",
or 0 if "expr" evaluates to something which is not a
nodeset.
"""
return libguestfsmod.aug_defvar (self._o, name, expr)
def aug_defnode (self, name, expr, val):
u"""Defines a variable "name" whose value is the result of
evaluating "expr".
If "expr" evaluates to an empty nodeset, a node is
created, equivalent to calling "g.aug_set" "expr",
"value". "name" will be the nodeset containing that
single node.
On success this returns a pair containing the number of
nodes in the nodeset, and a boolean flag if a node was
created.
This function returns a tuple (int, bool).
"""
return libguestfsmod.aug_defnode (self._o, name, expr, val)
def aug_get (self, path):
u"""Look up the value associated with "path". If "path"
matches exactly one node, the "value" is returned.
"""
return libguestfsmod.aug_get (self._o, path)
def aug_set (self, path, val):
u"""Set the value associated with "path" to "value".
"""
return libguestfsmod.aug_set (self._o, path, val)
def aug_insert (self, path, label, before):
u"""Create a new sibling "label" for "path", inserting it
into the tree before or after "path" (depending on the
boolean flag "before").
"path" must match exactly one existing node in the tree,
and "label" must be a label, ie. not contain "/", "*" or
end with a bracketed index "[N]".
"""
return libguestfsmod.aug_insert (self._o, path, label, before)
def aug_rm (self, path):
u"""Remove "path" and all of its children.
On success this returns the number of entries which were
removed.
"""
return libguestfsmod.aug_rm (self._o, path)
def aug_mv (self, src, dest):
u"""Move the node "src" to "dest". "src" must match exactly
one node. "dest" is overwritten if it exists.
"""
return libguestfsmod.aug_mv (self._o, src, dest)
def aug_match (self, path):
u"""Returns a list of paths which match the path expression
"path". The returned paths are sufficiently qualified so
that they match exactly one node in the current tree.
This function returns a list of strings.
"""
return libguestfsmod.aug_match (self._o, path)
def aug_save (self):
u"""This writes all pending changes to disk.
The flags which were passed to "g.aug_init" affect
exactly how files are saved.
"""
return libguestfsmod.aug_save (self._o)
def aug_load (self):
u"""Load files into the tree.
See "aug_load" in the Augeas documentation for the full
gory details.
"""
return libguestfsmod.aug_load (self._o)
def aug_ls (self, path):
u"""This is just a shortcut for listing "g.aug_match"
"path/*" and sorting the resulting nodes into
alphabetical order.
This function returns a list of strings.
"""
return libguestfsmod.aug_ls (self._o, path)
def rm (self, path):
u"""Remove the single file "path".
"""
return libguestfsmod.rm (self._o, path)
def rmdir (self, path):
u"""Remove the single directory "path".
"""
return libguestfsmod.rmdir (self._o, path)
def rm_rf (self, path):
u"""Remove the file or directory "path", recursively
removing the contents if its a directory. This is like
the "rm -rf" shell command.
"""
return libguestfsmod.rm_rf (self._o, path)
def mkdir (self, path):
u"""Create a directory named "path".
"""
return libguestfsmod.mkdir (self._o, path)
def mkdir_p (self, path):
u"""Create a directory named "path", creating any parent
directories as necessary. This is like the "mkdir -p"
shell command.
"""
return libguestfsmod.mkdir_p (self._o, path)
def chmod (self, mode, path):
u"""Change the mode (permissions) of "path" to "mode". Only
numeric modes are supported.
"""
return libguestfsmod.chmod (self._o, mode, path)
def chown (self, owner, group, path):
u"""Change the file owner to "owner" and group to "group".
Only numeric uid and gid are supported. If you want to
use names, you will need to locate and parse the
password file yourself (Augeas support makes this
relatively easy).
"""
return libguestfsmod.chown (self._o, owner, group, path)
def exists (self, path):
u"""This returns "true" if and only if there is a file,
directory (or anything) with the given "path" name.
See also "g.is_file", "g.is_dir", "g.stat".
"""
return libguestfsmod.exists (self._o, path)
def is_file (self, path):
u"""This returns "true" if and only if there is a file with
the given "path" name. Note that it returns false for
other objects like directories.
See also "g.stat".
"""
return libguestfsmod.is_file (self._o, path)
def is_dir (self, path):
u"""This returns "true" if and only if there is a directory
with the given "path" name. Note that it returns false
for other objects like files.
See also "g.stat".
"""
return libguestfsmod.is_dir (self._o, path)
def pvcreate (self, device):
u"""This creates an LVM physical volume on the named
"device", where "device" should usually be a partition
name such as "/dev/sda1".
"""
return libguestfsmod.pvcreate (self._o, device)
def vgcreate (self, volgroup, physvols):
u"""This creates an LVM volume group called "volgroup" from
the non-empty list of physical volumes "physvols".
"""
return libguestfsmod.vgcreate (self._o, volgroup, physvols)
def lvcreate (self, logvol, volgroup, mbytes):
u"""This creates an LVM volume group called "logvol" on the
volume group "volgroup", with "size" megabytes.
"""
return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes)
def mkfs (self, fstype, device):
u"""This creates a filesystem on "device" (usually a
partition of LVM logical volume). The filesystem type is
"fstype", for example "ext3".
"""
return libguestfsmod.mkfs (self._o, fstype, device)
def sfdisk (self, device, cyls, heads, sectors, lines):
u"""This is a direct interface to the sfdisk(8) program for
creating partitions on block devices.
"device" should be a block device, for example
"/dev/sda".
"cyls", "heads" and "sectors" are the number of
cylinders, heads and sectors on the device, which are
passed directly to sfdisk as the *-C*, *-H* and *-S*
parameters. If you pass 0 for any of these, then the
corresponding parameter is omitted. Usually for 'large'
disks, you can just pass 0 for these, but for small
(floppy-sized) disks, sfdisk (or rather, the kernel)
cannot work out the right geometry and you will need to
tell it.
"lines" is a list of lines that we feed to "sfdisk". For
more information refer to the sfdisk(8) manpage.
To create a single partition occupying the whole disk,
you would pass "lines" as a single element list, when
the single element being the string "," (comma).
This command is dangerous. Without careful use you can
easily destroy all your data.
"""
return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines)
def write_file (self, path, content, size):
u"""This call creates a file called "path". The contents of
the file is the string "content" (which can contain any
8 bit data), with length "size".
As a special case, if "size" is 0 then the length is
calculated using "strlen" (so in this case the content
cannot contain embedded ASCII NULs).
Because of the message protocol, there is a transfer
limit of somewhere between 2MB and 4MB. To transfer
large files you should use FTP.
"""
return libguestfsmod.write_file (self._o, path, content, size)
def umount (self, pathordevice):
u"""This unmounts the given filesystem. The filesystem may
be specified either by its mountpoint (path) or the
device which contains the filesystem.
"""
return libguestfsmod.umount (self._o, pathordevice)
def mounts (self):
u"""This returns the list of currently mounted filesystems.
It returns the list of devices (eg. "/dev/sda1",
"/dev/VG/LV").
Some internal mounts are not shown.
This function returns a list of strings.
"""
return libguestfsmod.mounts (self._o)
def umount_all (self):
u"""This unmounts all mounted filesystems.
Some internal mounts are not unmounted by this call.
"""
return libguestfsmod.umount_all (self._o)
def lvm_remove_all (self):
u"""This command removes all LVM logical volumes, volume
groups and physical volumes.
This command is dangerous. Without careful use you can
easily destroy all your data.
"""
return libguestfsmod.lvm_remove_all (self._o)
def file (self, path):
u"""This call uses the standard file(1) command to determine
the type or contents of the file. This also works on
devices, for example to find out whether a partition
contains a filesystem.
The exact command which runs is "file -bsL path". Note
in particular that the filename is not prepended to the
output (the "-b" option).
"""
return libguestfsmod.file (self._o, path)
def command (self, arguments):
u"""This call runs a command from the guest filesystem. The
filesystem must be mounted, and must contain a
compatible operating system (ie. something Linux, with
the same or compatible processor architecture).
The single parameter is an argv-style list of arguments.
The first element is the name of the program to run.
Subsequent elements are parameters. The list must be
non-empty (ie. must contain a program name).
The $PATH environment variable will contain at least
"/usr/bin" and "/bin". If you require a program from
another location, you should provide the full path in
the first parameter.
Shared libraries and data files required by the program
must be available on filesystems which are mounted in
the correct places. It is the caller's responsibility to
ensure all filesystems that are needed are mounted at
the right locations.
"""
return libguestfsmod.command (self._o, arguments)
def command_lines (self, arguments):
u"""This is the same as "g.command", but splits the result
into a list of lines.
This function returns a list of strings.
"""
return libguestfsmod.command_lines (self._o, arguments)
def stat (self, path):
u"""Returns file information for the given "path".
This is the same as the stat(2) system call.
This function returns a dictionary, with keys matching
the various fields in the stat structure.
"""
return libguestfsmod.stat (self._o, path)
def lstat (self, path):
u"""Returns file information for the given "path".
This is the same as "g.stat" except that if "path" is a
symbolic link, then the link is stat-ed, not the file it
refers to.
This is the same as the lstat(2) system call.
This function returns a dictionary, with keys matching
the various fields in the stat structure.
"""
return libguestfsmod.lstat (self._o, path)
def statvfs (self, path):
u"""Returns file system statistics for any mounted file
system. "path" should be a file or directory in the
mounted file system (typically it is the mount point
itself, but it doesn't need to be).
This is the same as the statvfs(2) system call.
This function returns a dictionary, with keys matching
the various fields in the statvfs structure.
"""
return libguestfsmod.statvfs (self._o, path)
def tune2fs_l (self, device):
u"""This returns the contents of the ext2 or ext3 filesystem
superblock on "device".
It is the same as running "tune2fs -l device". See
tune2fs(8) manpage for more details. The list of fields
returned isn't clearly defined, and depends on both the
version of "tune2fs" that libguestfs was built against,
and the filesystem itself.
This function returns a dictionary.
"""
return libguestfsmod.tune2fs_l (self._o, device)
def blockdev_setro (self, device):
u"""Sets the block device named "device" to read-only.
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_setro (self._o, device)
def blockdev_setrw (self, device):
u"""Sets the block device named "device" to read-write.
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_setrw (self._o, device)
def blockdev_getro (self, device):
u"""Returns a boolean indicating if the block device is
read-only (true if read-only, false if not).
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_getro (self._o, device)
def blockdev_getss (self, device):
u"""This returns the size of sectors on a block device.
Usually 512, but can be larger for modern devices.
(Note, this is not the size in sectors, use
"g.blockdev_getsz" for that).
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_getss (self._o, device)
def blockdev_getbsz (self, device):
u"""This returns the block size of a device.
(Note this is different from both *size in blocks* and
*filesystem block size*).
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_getbsz (self._o, device)
def blockdev_setbsz (self, device, blocksize):
u"""This sets the block size of a device.
(Note this is different from both *size in blocks* and
*filesystem block size*).
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
def blockdev_getsz (self, device):
u"""This returns the size of the device in units of 512-byte
sectors (even if the sectorsize isn't 512 bytes ...
weird).
See also "g.blockdev_getss" for the real sector size of
the device, and "g.blockdev_getsize64" for the more
useful *size in bytes*.
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_getsz (self._o, device)
def blockdev_getsize64 (self, device):
u"""This returns the size of the device in bytes.
See also "g.blockdev_getsz".
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_getsize64 (self._o, device)
def blockdev_flushbufs (self, device):
u"""This tells the kernel to flush internal buffers
associated with "device".
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_flushbufs (self._o, device)
def blockdev_rereadpt (self, device):
u"""Reread the partition table on "device".
This uses the blockdev(8) command.
"""
return libguestfsmod.blockdev_rereadpt (self._o, device)

160
src/generator.ml
View File

@@ -1322,6 +1322,31 @@ let replace_char s c1 c2 =
done;
if not !r then s else s2
let isspace c =
c = ' '
(* || c = '\f' *) || c = '\n' || c = '\r' || c = '\t' (* || c = '\v' *)
let triml ?(test = isspace) str =
let i = ref 0 in
let n = ref (String.length str) in
while !n > 0 && test str.[!i]; do
decr n;
incr i
done;
if !i = 0 then str
else String.sub str !i !n
let trimr ?(test = isspace) str =
let n = ref (String.length str) in
while !n > 0 && test str.[!n-1]; do
decr n
done;
if !n = String.length str then str
else String.sub str 0 !n
let trim ?(test = isspace) str =
trimr ~test (triml ~test str)
let rec find s sub =
let len = String.length s in
let sublen = String.length sub in
@@ -4701,27 +4726,142 @@ initlibguestfsmod (void)
and generate_python_py () =
generate_header HashStyle LGPLv2;
pr "import libguestfsmod\n";
pr "\n";
pr "class GuestFS:\n";
pr " def __init__ (self):\n";
pr " self._o = libguestfsmod.create ()\n";
pr "\n";
pr " def __del__ (self):\n";
pr " libguestfsmod.close (self._o)\n";
pr "\n";
pr "\
u\"\"\"Python bindings for libguestfs
import guestfs
g = guestfs.GuestFS ()
g.add_drive (\"guest.img\")
g.launch ()
g.wait_ready ()
parts = g.list_partitions ()
The guestfs module provides a Python binding to the libguestfs API
for examining and modifying virtual machine disk images.
Amongst the things this is good for: making batch configuration
changes to guests, getting disk used/free statistics (see also:
virt-df), migrating between virtualization systems (see also:
virt-p2v), performing partial backups, performing partial guest
clones, cloning guests and changing registry/UUID/hostname info, and
much else besides.
Libguestfs uses Linux kernel and qemu code, and can access any type of
guest filesystem that Linux and qemu can, including but not limited
to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
schemes, qcow, qcow2, vmdk.
Libguestfs provides ways to enumerate guest storage (eg. partitions,
LVs, what filesystem is in each LV, etc.). It can also run commands
in the context of the guest. Also you can access filesystems over FTP.
Errors which happen while using the API are turned into Python
RuntimeError exceptions.
To create a guestfs handle you usually have to perform the following
sequence of calls:
# Create the handle, call add_drive at least once, and possibly
# several times if the guest has multiple block devices:
g = guestfs.GuestFS ()
g.add_drive (\"guest.img\")
# Launch the qemu subprocess and wait for it to become ready:
g.launch ()
g.wait_ready ()
# Now you can issue commands, for example:
logvols = g.lvs ()
\"\"\"
import libguestfsmod
class GuestFS:
\"\"\"Instances of this class are libguestfs API handles.\"\"\"
def __init__ (self):
\"\"\"Create a new libguestfs handle.\"\"\"
self._o = libguestfsmod.create ()
def __del__ (self):
libguestfsmod.close (self._o)
";
List.iter (
fun (name, style, _, _, _, _, _) ->
fun (name, style, _, flags, _, _, longdesc) ->
let doc = replace_str longdesc "C<guestfs_" "C<g." in
let doc =
match fst style with
| RErr | RInt _ | RInt64 _ | RBool _ | RConstString _
| RString _ -> doc
| RStringList _ ->
doc ^ "\n\nThis function returns a list of strings."
| RIntBool _ ->
doc ^ "\n\nThis function returns a tuple (int, bool).\n"
| RPVList _ ->
doc ^ "\n\nThis function returns a list of PVs. Each PV is represented as a dictionary."
| RVGList _ ->
doc ^ "\n\nThis function returns a list of VGs. Each VG is represented as a dictionary."
| RLVList _ ->
doc ^ "\n\nThis function returns a list of LVs. Each LV is represented as a dictionary."
| RStat _ ->
doc ^ "\n\nThis function returns a dictionary, with keys matching the various fields in the stat structure."
| RStatVFS _ ->
doc ^ "\n\nThis function returns a dictionary, with keys matching the various fields in the statvfs structure."
| RHashtable _ ->
doc ^ "\n\nThis function returns a dictionary." in
let doc =
if List.mem ProtocolLimitWarning flags then
doc ^ "\n\n" ^ protocol_limit_warning
else doc in
let doc =
if List.mem DangerWillRobinson flags then
doc ^ "\n\n" ^ danger_will_robinson
else doc in
let doc = pod2text ~width:60 name doc in
let doc = List.map (fun line -> replace_str line "\\" "\\\\") doc in
let doc = String.concat "\n " doc in
pr " def %s " name;
generate_call_args ~handle:"self" style;
pr ":\n";
pr " u\"\"\"%s\"\"\"\n" doc;
pr " return libguestfsmod.%s " name;
generate_call_args ~handle:"self._o" style;
pr "\n";
pr "\n";
) all_functions
(* Useful if you need the longdesc POD text as plain text. Returns a
* list of lines.
*)
and pod2text ~width name longdesc =
let filename, chan = Filename.open_temp_file "gen" ".tmp" in
fprintf chan "=head1 %s\n\n%s\n" name longdesc;
close_out chan;
let cmd = sprintf "pod2text -w %d %s" width (Filename.quote filename) in
let chan = Unix.open_process_in cmd in
let lines = ref [] in
let rec loop i =
let line = input_line chan in
if i = 1 then (* discard the first line of output *)
loop (i+1)
else (
let line = triml line in
lines := line :: !lines;
loop (i+1)
) in
let lines = try loop 1 with End_of_file -> List.rev !lines in
Unix.unlink filename;
match Unix.close_process_in chan with
| Unix.WEXITED 0 -> lines
| Unix.WEXITED i ->
failwithf "pod2text: process exited with non-zero status (%d)" i
| Unix.WSIGNALED i | Unix.WSTOPPED i ->
failwithf "pod2text: process signalled or stopped by signal %d" i
let output_to filename =
let filename_new = filename ^ ".new" in
chan := open_out filename_new;