Add test-bootbootboot.sh script to EXTRA_DIST.
[libguestfs.git] / 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         Setting "qemu" to "NULL" restores the default qemu
156         binary.
157         """
158         return libguestfsmod.set_qemu (self._o, qemu)
159
160     def get_qemu (self):
161         u"""Return the current qemu binary.
162         
163         This is always non-NULL. If it wasn't set already, then
164         this will return the default qemu binary name.
165         """
166         return libguestfsmod.get_qemu (self._o)
167
168     def set_path (self, path):
169         u"""Set the path that libguestfs searches for kernel and
170         initrd.img.
171         
172         The default is "$libdir/guestfs" unless overridden by
173         setting "LIBGUESTFS_PATH" environment variable.
174         
175         Setting "path" to "NULL" restores the default path.
176         """
177         return libguestfsmod.set_path (self._o, path)
178
179     def get_path (self):
180         u"""Return the current search path.
181         
182         This is always non-NULL. If it wasn't set already, then
183         this will return the default path.
184         """
185         return libguestfsmod.get_path (self._o)
186
187     def set_append (self, append):
188         u"""This function is used to add additional options to the
189         guest kernel command line.
190         
191         The default is "NULL" unless overridden by setting
192         "LIBGUESTFS_APPEND" environment variable.
193         
194         Setting "append" to "NULL" means *no* additional options
195         are passed (libguestfs always adds a few of its own).
196         """
197         return libguestfsmod.set_append (self._o, append)
198
199     def get_append (self):
200         u"""Return the additional kernel options which are added to
201         the guest kernel command line.
202         
203         If "NULL" then no options are added.
204         """
205         return libguestfsmod.get_append (self._o)
206
207     def set_autosync (self, autosync):
208         u"""If "autosync" is true, this enables autosync. Libguestfs
209         will make a best effort attempt to run "g.umount_all"
210         followed by "g.sync" when the handle is closed (also if
211         the program exits without closing handles).
212         
213         This is disabled by default (except in guestfish where
214         it is enabled by default).
215         """
216         return libguestfsmod.set_autosync (self._o, autosync)
217
218     def get_autosync (self):
219         u"""Get the autosync flag.
220         """
221         return libguestfsmod.get_autosync (self._o)
222
223     def set_verbose (self, verbose):
224         u"""If "verbose" is true, this turns on verbose messages (to
225         "stderr").
226         
227         Verbose messages are disabled unless the environment
228         variable "LIBGUESTFS_DEBUG" is defined and set to 1.
229         """
230         return libguestfsmod.set_verbose (self._o, verbose)
231
232     def get_verbose (self):
233         u"""This returns the verbose messages flag.
234         """
235         return libguestfsmod.get_verbose (self._o)
236
237     def is_ready (self):
238         u"""This returns true iff this handle is ready to accept
239         commands (in the "READY" state).
240         
241         For more information on states, see guestfs(3).
242         """
243         return libguestfsmod.is_ready (self._o)
244
245     def is_config (self):
246         u"""This returns true iff this handle is being configured
247         (in the "CONFIG" state).
248         
249         For more information on states, see guestfs(3).
250         """
251         return libguestfsmod.is_config (self._o)
252
253     def is_launching (self):
254         u"""This returns true iff this handle is launching the
255         subprocess (in the "LAUNCHING" state).
256         
257         For more information on states, see guestfs(3).
258         """
259         return libguestfsmod.is_launching (self._o)
260
261     def is_busy (self):
262         u"""This returns true iff this handle is busy processing a
263         command (in the "BUSY" state).
264         
265         For more information on states, see guestfs(3).
266         """
267         return libguestfsmod.is_busy (self._o)
268
269     def get_state (self):
270         u"""This returns the current state as an opaque integer.
271         This is only useful for printing debug and internal
272         error messages.
273         
274         For more information on states, see guestfs(3).
275         """
276         return libguestfsmod.get_state (self._o)
277
278     def set_busy (self):
279         u"""This sets the state to "BUSY". This is only used when
280         implementing actions using the low-level API.
281         
282         For more information on states, see guestfs(3).
283         """
284         return libguestfsmod.set_busy (self._o)
285
286     def set_ready (self):
287         u"""This sets the state to "READY". This is only used when
288         implementing actions using the low-level API.
289         
290         For more information on states, see guestfs(3).
291         """
292         return libguestfsmod.set_ready (self._o)
293
294     def end_busy (self):
295         u"""This sets the state to "READY", or if in "CONFIG" then
296         it leaves the state as is. This is only used when
297         implementing actions using the low-level API.
298         
299         For more information on states, see guestfs(3).
300         """
301         return libguestfsmod.end_busy (self._o)
302
303     def mount (self, device, mountpoint):
304         u"""Mount a guest disk at a position in the filesystem.
305         Block devices are named "/dev/sda", "/dev/sdb" and so
306         on, as they were added to the guest. If those block
307         devices contain partitions, they will have the usual
308         names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style
309         names can be used.
310         
311         The rules are the same as for mount(2): A filesystem
312         must first be mounted on "/" before others can be
313         mounted. Other filesystems can only be mounted on
314         directories which already exist.
315         
316         The mounted filesystem is writable, if we have
317         sufficient permissions on the underlying device.
318         
319         The filesystem options "sync" and "noatime" are set with
320         this call, in order to improve reliability.
321         """
322         return libguestfsmod.mount (self._o, device, mountpoint)
323
324     def sync (self):
325         u"""This syncs the disk, so that any writes are flushed
326         through to the underlying disk image.
327         
328         You should always call this if you have modified a disk
329         image, before closing the handle.
330         """
331         return libguestfsmod.sync (self._o)
332
333     def touch (self, path):
334         u"""Touch acts like the touch(1) command. It can be used to
335         update the timestamps on a file, or, if the file does
336         not exist, to create a new zero-length file.
337         """
338         return libguestfsmod.touch (self._o, path)
339
340     def cat (self, path):
341         u"""Return the contents of the file named "path".
342         
343         Note that this function cannot correctly handle binary
344         files (specifically, files containing "\\0" character
345         which is treated as end of string). For those you need
346         to use the "g.download" function which has a more
347         complex interface.
348         
349         Because of the message protocol, there is a transfer
350         limit of somewhere between 2MB and 4MB. To transfer
351         large files you should use FTP.
352         """
353         return libguestfsmod.cat (self._o, path)
354
355     def ll (self, directory):
356         u"""List the files in "directory" (relative to the root
357         directory, there is no cwd) in the format of 'ls -la'.
358         
359         This command is mostly useful for interactive sessions.
360         It is *not* intended that you try to parse the output
361         string.
362         """
363         return libguestfsmod.ll (self._o, directory)
364
365     def ls (self, directory):
366         u"""List the files in "directory" (relative to the root
367         directory, there is no cwd). The '.' and '..' entries
368         are not returned, but hidden files are shown.
369         
370         This command is mostly useful for interactive sessions.
371         Programs should probably use "g.readdir" instead.
372         
373         This function returns a list of strings.
374         """
375         return libguestfsmod.ls (self._o, directory)
376
377     def list_devices (self):
378         u"""List all the block devices.
379         
380         The full block device names are returned, eg. "/dev/sda"
381         
382         This function returns a list of strings.
383         """
384         return libguestfsmod.list_devices (self._o)
385
386     def list_partitions (self):
387         u"""List all the partitions detected on all block devices.
388         
389         The full partition device names are returned, eg.
390         "/dev/sda1"
391         
392         This does not return logical volumes. For that you will
393         need to call "g.lvs".
394         
395         This function returns a list of strings.
396         """
397         return libguestfsmod.list_partitions (self._o)
398
399     def pvs (self):
400         u"""List all the physical volumes detected. This is the
401         equivalent of the pvs(8) command.
402         
403         This returns a list of just the device names that
404         contain PVs (eg. "/dev/sda2").
405         
406         See also "g.pvs_full".
407         
408         This function returns a list of strings.
409         """
410         return libguestfsmod.pvs (self._o)
411
412     def vgs (self):
413         u"""List all the volumes groups detected. This is the
414         equivalent of the vgs(8) command.
415         
416         This returns a list of just the volume group names that
417         were detected (eg. "VolGroup00").
418         
419         See also "g.vgs_full".
420         
421         This function returns a list of strings.
422         """
423         return libguestfsmod.vgs (self._o)
424
425     def lvs (self):
426         u"""List all the logical volumes detected. This is the
427         equivalent of the lvs(8) command.
428         
429         This returns a list of the logical volume device names
430         (eg. "/dev/VolGroup00/LogVol00").
431         
432         See also "g.lvs_full".
433         
434         This function returns a list of strings.
435         """
436         return libguestfsmod.lvs (self._o)
437
438     def pvs_full (self):
439         u"""List all the physical volumes detected. This is the
440         equivalent of the pvs(8) command. The "full" version
441         includes all fields.
442         
443         This function returns a list of PVs. Each PV is
444         represented as a dictionary.
445         """
446         return libguestfsmod.pvs_full (self._o)
447
448     def vgs_full (self):
449         u"""List all the volumes groups detected. This is the
450         equivalent of the vgs(8) command. The "full" version
451         includes all fields.
452         
453         This function returns a list of VGs. Each VG is
454         represented as a dictionary.
455         """
456         return libguestfsmod.vgs_full (self._o)
457
458     def lvs_full (self):
459         u"""List all the logical volumes detected. This is the
460         equivalent of the lvs(8) command. The "full" version
461         includes all fields.
462         
463         This function returns a list of LVs. Each LV is
464         represented as a dictionary.
465         """
466         return libguestfsmod.lvs_full (self._o)
467
468     def read_lines (self, path):
469         u"""Return the contents of the file named "path".
470         
471         The file contents are returned as a list of lines.
472         Trailing "LF" and "CRLF" character sequences are *not*
473         returned.
474         
475         Note that this function cannot correctly handle binary
476         files (specifically, files containing "\\0" character
477         which is treated as end of line). For those you need to
478         use the "g.read_file" function which has a more complex
479         interface.
480         
481         This function returns a list of strings.
482         """
483         return libguestfsmod.read_lines (self._o, path)
484
485     def aug_init (self, root, flags):
486         u"""Create a new Augeas handle for editing configuration
487         files. If there was any previous Augeas handle
488         associated with this guestfs session, then it is closed.
489         
490         You must call this before using any other "g.aug_*"
491         commands.
492         
493         "root" is the filesystem root. "root" must not be NULL,
494         use "/" instead.
495         
496         The flags are the same as the flags defined in
497         <augeas.h>, the logical *or* of the following integers:
498         
499         "AUG_SAVE_BACKUP" = 1
500         Keep the original file with a ".augsave" extension.
501         
502         "AUG_SAVE_NEWFILE" = 2
503         Save changes into a file with extension ".augnew",
504         and do not overwrite original. Overrides
505         "AUG_SAVE_BACKUP".
506         
507         "AUG_TYPE_CHECK" = 4
508         Typecheck lenses (can be expensive).
509         
510         "AUG_NO_STDINC" = 8
511         Do not use standard load path for modules.
512         
513         "AUG_SAVE_NOOP" = 16
514         Make save a no-op, just record what would have been
515         changed.
516         
517         "AUG_NO_LOAD" = 32
518         Do not load the tree in "g.aug_init".
519         
520         To close the handle, you can call "g.aug_close".
521         
522         To find out more about Augeas, see <http://augeas.net/>.
523         """
524         return libguestfsmod.aug_init (self._o, root, flags)
525
526     def aug_close (self):
527         u"""Close the current Augeas handle and free up any
528         resources used by it. After calling this, you have to
529         call "g.aug_init" again before you can use any other
530         Augeas functions.
531         """
532         return libguestfsmod.aug_close (self._o)
533
534     def aug_defvar (self, name, expr):
535         u"""Defines an Augeas variable "name" whose value is the
536         result of evaluating "expr". If "expr" is NULL, then
537         "name" is undefined.
538         
539         On success this returns the number of nodes in "expr",
540         or 0 if "expr" evaluates to something which is not a
541         nodeset.
542         """
543         return libguestfsmod.aug_defvar (self._o, name, expr)
544
545     def aug_defnode (self, name, expr, val):
546         u"""Defines a variable "name" whose value is the result of
547         evaluating "expr".
548         
549         If "expr" evaluates to an empty nodeset, a node is
550         created, equivalent to calling "g.aug_set" "expr",
551         "value". "name" will be the nodeset containing that
552         single node.
553         
554         On success this returns a pair containing the number of
555         nodes in the nodeset, and a boolean flag if a node was
556         created.
557         
558         This function returns a tuple (int, bool).
559         """
560         return libguestfsmod.aug_defnode (self._o, name, expr, val)
561
562     def aug_get (self, path):
563         u"""Look up the value associated with "path". If "path"
564         matches exactly one node, the "value" is returned.
565         """
566         return libguestfsmod.aug_get (self._o, path)
567
568     def aug_set (self, path, val):
569         u"""Set the value associated with "path" to "value".
570         """
571         return libguestfsmod.aug_set (self._o, path, val)
572
573     def aug_insert (self, path, label, before):
574         u"""Create a new sibling "label" for "path", inserting it
575         into the tree before or after "path" (depending on the
576         boolean flag "before").
577         
578         "path" must match exactly one existing node in the tree,
579         and "label" must be a label, ie. not contain "/", "*" or
580         end with a bracketed index "[N]".
581         """
582         return libguestfsmod.aug_insert (self._o, path, label, before)
583
584     def aug_rm (self, path):
585         u"""Remove "path" and all of its children.
586         
587         On success this returns the number of entries which were
588         removed.
589         """
590         return libguestfsmod.aug_rm (self._o, path)
591
592     def aug_mv (self, src, dest):
593         u"""Move the node "src" to "dest". "src" must match exactly
594         one node. "dest" is overwritten if it exists.
595         """
596         return libguestfsmod.aug_mv (self._o, src, dest)
597
598     def aug_match (self, path):
599         u"""Returns a list of paths which match the path expression
600         "path". The returned paths are sufficiently qualified so
601         that they match exactly one node in the current tree.
602         
603         This function returns a list of strings.
604         """
605         return libguestfsmod.aug_match (self._o, path)
606
607     def aug_save (self):
608         u"""This writes all pending changes to disk.
609         
610         The flags which were passed to "g.aug_init" affect
611         exactly how files are saved.
612         """
613         return libguestfsmod.aug_save (self._o)
614
615     def aug_load (self):
616         u"""Load files into the tree.
617         
618         See "aug_load" in the Augeas documentation for the full
619         gory details.
620         """
621         return libguestfsmod.aug_load (self._o)
622
623     def aug_ls (self, path):
624         u"""This is just a shortcut for listing "g.aug_match"
625         "path/*" and sorting the resulting nodes into
626         alphabetical order.
627         
628         This function returns a list of strings.
629         """
630         return libguestfsmod.aug_ls (self._o, path)
631
632     def rm (self, path):
633         u"""Remove the single file "path".
634         """
635         return libguestfsmod.rm (self._o, path)
636
637     def rmdir (self, path):
638         u"""Remove the single directory "path".
639         """
640         return libguestfsmod.rmdir (self._o, path)
641
642     def rm_rf (self, path):
643         u"""Remove the file or directory "path", recursively
644         removing the contents if its a directory. This is like
645         the "rm -rf" shell command.
646         """
647         return libguestfsmod.rm_rf (self._o, path)
648
649     def mkdir (self, path):
650         u"""Create a directory named "path".
651         """
652         return libguestfsmod.mkdir (self._o, path)
653
654     def mkdir_p (self, path):
655         u"""Create a directory named "path", creating any parent
656         directories as necessary. This is like the "mkdir -p"
657         shell command.
658         """
659         return libguestfsmod.mkdir_p (self._o, path)
660
661     def chmod (self, mode, path):
662         u"""Change the mode (permissions) of "path" to "mode". Only
663         numeric modes are supported.
664         """
665         return libguestfsmod.chmod (self._o, mode, path)
666
667     def chown (self, owner, group, path):
668         u"""Change the file owner to "owner" and group to "group".
669         
670         Only numeric uid and gid are supported. If you want to
671         use names, you will need to locate and parse the
672         password file yourself (Augeas support makes this
673         relatively easy).
674         """
675         return libguestfsmod.chown (self._o, owner, group, path)
676
677     def exists (self, path):
678         u"""This returns "true" if and only if there is a file,
679         directory (or anything) with the given "path" name.
680         
681         See also "g.is_file", "g.is_dir", "g.stat".
682         """
683         return libguestfsmod.exists (self._o, path)
684
685     def is_file (self, path):
686         u"""This returns "true" if and only if there is a file with
687         the given "path" name. Note that it returns false for
688         other objects like directories.
689         
690         See also "g.stat".
691         """
692         return libguestfsmod.is_file (self._o, path)
693
694     def is_dir (self, path):
695         u"""This returns "true" if and only if there is a directory
696         with the given "path" name. Note that it returns false
697         for other objects like files.
698         
699         See also "g.stat".
700         """
701         return libguestfsmod.is_dir (self._o, path)
702
703     def pvcreate (self, device):
704         u"""This creates an LVM physical volume on the named
705         "device", where "device" should usually be a partition
706         name such as "/dev/sda1".
707         """
708         return libguestfsmod.pvcreate (self._o, device)
709
710     def vgcreate (self, volgroup, physvols):
711         u"""This creates an LVM volume group called "volgroup" from
712         the non-empty list of physical volumes "physvols".
713         """
714         return libguestfsmod.vgcreate (self._o, volgroup, physvols)
715
716     def lvcreate (self, logvol, volgroup, mbytes):
717         u"""This creates an LVM volume group called "logvol" on the
718         volume group "volgroup", with "size" megabytes.
719         """
720         return libguestfsmod.lvcreate (self._o, logvol, volgroup, mbytes)
721
722     def mkfs (self, fstype, device):
723         u"""This creates a filesystem on "device" (usually a
724         partition or LVM logical volume). The filesystem type is
725         "fstype", for example "ext3".
726         """
727         return libguestfsmod.mkfs (self._o, fstype, device)
728
729     def sfdisk (self, device, cyls, heads, sectors, lines):
730         u"""This is a direct interface to the sfdisk(8) program for
731         creating partitions on block devices.
732         
733         "device" should be a block device, for example
734         "/dev/sda".
735         
736         "cyls", "heads" and "sectors" are the number of
737         cylinders, heads and sectors on the device, which are
738         passed directly to sfdisk as the *-C*, *-H* and *-S*
739         parameters. If you pass 0 for any of these, then the
740         corresponding parameter is omitted. Usually for 'large'
741         disks, you can just pass 0 for these, but for small
742         (floppy-sized) disks, sfdisk (or rather, the kernel)
743         cannot work out the right geometry and you will need to
744         tell it.
745         
746         "lines" is a list of lines that we feed to "sfdisk". For
747         more information refer to the sfdisk(8) manpage.
748         
749         To create a single partition occupying the whole disk,
750         you would pass "lines" as a single element list, when
751         the single element being the string "," (comma).
752         
753         See also: "g.sfdisk_l", "g.sfdisk_N"
754         
755         This command is dangerous. Without careful use you can
756         easily destroy all your data.
757         """
758         return libguestfsmod.sfdisk (self._o, device, cyls, heads, sectors, lines)
759
760     def write_file (self, path, content, size):
761         u"""This call creates a file called "path". The contents of
762         the file is the string "content" (which can contain any
763         8 bit data), with length "size".
764         
765         As a special case, if "size" is 0 then the length is
766         calculated using "strlen" (so in this case the content
767         cannot contain embedded ASCII NULs).
768         
769         *NB.* Owing to a bug, writing content containing ASCII
770         NUL characters does *not* work, even if the length is
771         specified. We hope to resolve this bug in a future
772         version. In the meantime use "g.upload".
773         
774         Because of the message protocol, there is a transfer
775         limit of somewhere between 2MB and 4MB. To transfer
776         large files you should use FTP.
777         """
778         return libguestfsmod.write_file (self._o, path, content, size)
779
780     def umount (self, pathordevice):
781         u"""This unmounts the given filesystem. The filesystem may
782         be specified either by its mountpoint (path) or the
783         device which contains the filesystem.
784         """
785         return libguestfsmod.umount (self._o, pathordevice)
786
787     def mounts (self):
788         u"""This returns the list of currently mounted filesystems.
789         It returns the list of devices (eg. "/dev/sda1",
790         "/dev/VG/LV").
791         
792         Some internal mounts are not shown.
793         
794         This function returns a list of strings.
795         """
796         return libguestfsmod.mounts (self._o)
797
798     def umount_all (self):
799         u"""This unmounts all mounted filesystems.
800         
801         Some internal mounts are not unmounted by this call.
802         """
803         return libguestfsmod.umount_all (self._o)
804
805     def lvm_remove_all (self):
806         u"""This command removes all LVM logical volumes, volume
807         groups and physical volumes.
808         
809         This command is dangerous. Without careful use you can
810         easily destroy all your data.
811         """
812         return libguestfsmod.lvm_remove_all (self._o)
813
814     def file (self, path):
815         u"""This call uses the standard file(1) command to determine
816         the type or contents of the file. This also works on
817         devices, for example to find out whether a partition
818         contains a filesystem.
819         
820         The exact command which runs is "file -bsL path". Note
821         in particular that the filename is not prepended to the
822         output (the "-b" option).
823         """
824         return libguestfsmod.file (self._o, path)
825
826     def command (self, arguments):
827         u"""This call runs a command from the guest filesystem. The
828         filesystem must be mounted, and must contain a
829         compatible operating system (ie. something Linux, with
830         the same or compatible processor architecture).
831         
832         The single parameter is an argv-style list of arguments.
833         The first element is the name of the program to run.
834         Subsequent elements are parameters. The list must be
835         non-empty (ie. must contain a program name).
836         
837         The return value is anything printed to *stdout* by the
838         command.
839         
840         If the command returns a non-zero exit status, then this
841         function returns an error message. The error message
842         string is the content of *stderr* from the command.
843         
844         The $PATH environment variable will contain at least
845         "/usr/bin" and "/bin". If you require a program from
846         another location, you should provide the full path in
847         the first parameter.
848         
849         Shared libraries and data files required by the program
850         must be available on filesystems which are mounted in
851         the correct places. It is the caller's responsibility to
852         ensure all filesystems that are needed are mounted at
853         the right locations.
854         
855         Because of the message protocol, there is a transfer
856         limit of somewhere between 2MB and 4MB. To transfer
857         large files you should use FTP.
858         """
859         return libguestfsmod.command (self._o, arguments)
860
861     def command_lines (self, arguments):
862         u"""This is the same as "g.command", but splits the result
863         into a list of lines.
864         
865         This function returns a list of strings.
866         
867         Because of the message protocol, there is a transfer
868         limit of somewhere between 2MB and 4MB. To transfer
869         large files you should use FTP.
870         """
871         return libguestfsmod.command_lines (self._o, arguments)
872
873     def stat (self, path):
874         u"""Returns file information for the given "path".
875         
876         This is the same as the stat(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.stat (self._o, path)
882
883     def lstat (self, path):
884         u"""Returns file information for the given "path".
885         
886         This is the same as "g.stat" except that if "path" is a
887         symbolic link, then the link is stat-ed, not the file it
888         refers to.
889         
890         This is the same as the lstat(2) system call.
891         
892         This function returns a dictionary, with keys matching
893         the various fields in the stat structure.
894         """
895         return libguestfsmod.lstat (self._o, path)
896
897     def statvfs (self, path):
898         u"""Returns file system statistics for any mounted file
899         system. "path" should be a file or directory in the
900         mounted file system (typically it is the mount point
901         itself, but it doesn't need to be).
902         
903         This is the same as the statvfs(2) system call.
904         
905         This function returns a dictionary, with keys matching
906         the various fields in the statvfs structure.
907         """
908         return libguestfsmod.statvfs (self._o, path)
909
910     def tune2fs_l (self, device):
911         u"""This returns the contents of the ext2, ext3 or ext4
912         filesystem superblock on "device".
913         
914         It is the same as running "tune2fs -l device". See
915         tune2fs(8) manpage for more details. The list of fields
916         returned isn't clearly defined, and depends on both the
917         version of "tune2fs" that libguestfs was built against,
918         and the filesystem itself.
919         
920         This function returns a dictionary.
921         """
922         return libguestfsmod.tune2fs_l (self._o, device)
923
924     def blockdev_setro (self, device):
925         u"""Sets the block device named "device" to read-only.
926         
927         This uses the blockdev(8) command.
928         """
929         return libguestfsmod.blockdev_setro (self._o, device)
930
931     def blockdev_setrw (self, device):
932         u"""Sets the block device named "device" to read-write.
933         
934         This uses the blockdev(8) command.
935         """
936         return libguestfsmod.blockdev_setrw (self._o, device)
937
938     def blockdev_getro (self, device):
939         u"""Returns a boolean indicating if the block device is
940         read-only (true if read-only, false if not).
941         
942         This uses the blockdev(8) command.
943         """
944         return libguestfsmod.blockdev_getro (self._o, device)
945
946     def blockdev_getss (self, device):
947         u"""This returns the size of sectors on a block device.
948         Usually 512, but can be larger for modern devices.
949         
950         (Note, this is not the size in sectors, use
951         "g.blockdev_getsz" for that).
952         
953         This uses the blockdev(8) command.
954         """
955         return libguestfsmod.blockdev_getss (self._o, device)
956
957     def blockdev_getbsz (self, device):
958         u"""This returns the block size of a device.
959         
960         (Note this is different from both *size in blocks* and
961         *filesystem block size*).
962         
963         This uses the blockdev(8) command.
964         """
965         return libguestfsmod.blockdev_getbsz (self._o, device)
966
967     def blockdev_setbsz (self, device, blocksize):
968         u"""This sets the block size of a device.
969         
970         (Note this is different from both *size in blocks* and
971         *filesystem block size*).
972         
973         This uses the blockdev(8) command.
974         """
975         return libguestfsmod.blockdev_setbsz (self._o, device, blocksize)
976
977     def blockdev_getsz (self, device):
978         u"""This returns the size of the device in units of 512-byte
979         sectors (even if the sectorsize isn't 512 bytes ...
980         weird).
981         
982         See also "g.blockdev_getss" for the real sector size of
983         the device, and "g.blockdev_getsize64" for the more
984         useful *size in bytes*.
985         
986         This uses the blockdev(8) command.
987         """
988         return libguestfsmod.blockdev_getsz (self._o, device)
989
990     def blockdev_getsize64 (self, device):
991         u"""This returns the size of the device in bytes.
992         
993         See also "g.blockdev_getsz".
994         
995         This uses the blockdev(8) command.
996         """
997         return libguestfsmod.blockdev_getsize64 (self._o, device)
998
999     def blockdev_flushbufs (self, device):
1000         u"""This tells the kernel to flush internal buffers
1001         associated with "device".
1002         
1003         This uses the blockdev(8) command.
1004         """
1005         return libguestfsmod.blockdev_flushbufs (self._o, device)
1006
1007     def blockdev_rereadpt (self, device):
1008         u"""Reread the partition table on "device".
1009         
1010         This uses the blockdev(8) command.
1011         """
1012         return libguestfsmod.blockdev_rereadpt (self._o, device)
1013
1014     def upload (self, filename, remotefilename):
1015         u"""Upload local file "filename" to "remotefilename" on the
1016         filesystem.
1017         
1018         "filename" can also be a named pipe.
1019         
1020         See also "g.download".
1021         """
1022         return libguestfsmod.upload (self._o, filename, remotefilename)
1023
1024     def download (self, remotefilename, filename):
1025         u"""Download file "remotefilename" and save it as "filename"
1026         on the local machine.
1027         
1028         "filename" can also be a named pipe.
1029         
1030         See also "g.upload", "g.cat".
1031         """
1032         return libguestfsmod.download (self._o, remotefilename, filename)
1033
1034     def checksum (self, csumtype, path):
1035         u"""This call computes the MD5, SHAx or CRC checksum of the
1036         file named "path".
1037         
1038         The type of checksum to compute is given by the
1039         "csumtype" parameter which must have one of the
1040         following values:
1041         
1042         "crc"
1043         Compute the cyclic redundancy check (CRC) specified
1044         by POSIX for the "cksum" command.
1045         
1046         "md5"
1047         Compute the MD5 hash (using the "md5sum" program).
1048         
1049         "sha1"
1050         Compute the SHA1 hash (using the "sha1sum" program).
1051         
1052         "sha224"
1053         Compute the SHA224 hash (using the "sha224sum"
1054         program).
1055         
1056         "sha256"
1057         Compute the SHA256 hash (using the "sha256sum"
1058         program).
1059         
1060         "sha384"
1061         Compute the SHA384 hash (using the "sha384sum"
1062         program).
1063         
1064         "sha512"
1065         Compute the SHA512 hash (using the "sha512sum"
1066         program).
1067         
1068         The checksum is returned as a printable string.
1069         """
1070         return libguestfsmod.checksum (self._o, csumtype, path)
1071
1072     def tar_in (self, tarfile, directory):
1073         u"""This command uploads and unpacks local file "tarfile"
1074         (an *uncompressed* tar file) into "directory".
1075         
1076         To upload a compressed tarball, use "g.tgz_in".
1077         """
1078         return libguestfsmod.tar_in (self._o, tarfile, directory)
1079
1080     def tar_out (self, directory, tarfile):
1081         u"""This command packs the contents of "directory" and
1082         downloads it to local file "tarfile".
1083         
1084         To download a compressed tarball, use "g.tgz_out".
1085         """
1086         return libguestfsmod.tar_out (self._o, directory, tarfile)
1087
1088     def tgz_in (self, tarball, directory):
1089         u"""This command uploads and unpacks local file "tarball" (a
1090         *gzip compressed* tar file) into "directory".
1091         
1092         To upload an uncompressed tarball, use "g.tar_in".
1093         """
1094         return libguestfsmod.tgz_in (self._o, tarball, directory)
1095
1096     def tgz_out (self, directory, tarball):
1097         u"""This command packs the contents of "directory" and
1098         downloads it to local file "tarball".
1099         
1100         To download an uncompressed tarball, use "g.tar_out".
1101         """
1102         return libguestfsmod.tgz_out (self._o, directory, tarball)
1103
1104     def mount_ro (self, device, mountpoint):
1105         u"""This is the same as the "g.mount" command, but it mounts
1106         the filesystem with the read-only (*-o ro*) flag.
1107         """
1108         return libguestfsmod.mount_ro (self._o, device, mountpoint)
1109
1110     def mount_options (self, options, device, mountpoint):
1111         u"""This is the same as the "g.mount" command, but it allows
1112         you to set the mount options as for the mount(8) *-o*
1113         flag.
1114         """
1115         return libguestfsmod.mount_options (self._o, options, device, mountpoint)
1116
1117     def mount_vfs (self, options, vfstype, device, mountpoint):
1118         u"""This is the same as the "g.mount" command, but it allows
1119         you to set both the mount options and the vfstype as for
1120         the mount(8) *-o* and *-t* flags.
1121         """
1122         return libguestfsmod.mount_vfs (self._o, options, vfstype, device, mountpoint)
1123
1124     def debug (self, subcmd, extraargs):
1125         u"""The "g.debug" command exposes some internals of
1126         "guestfsd" (the guestfs daemon) that runs inside the
1127         qemu subprocess.
1128         
1129         There is no comprehensive help for this command. You
1130         have to look at the file "daemon/debug.c" in the
1131         libguestfs source to find out what you can do.
1132         """
1133         return libguestfsmod.debug (self._o, subcmd, extraargs)
1134
1135     def lvremove (self, device):
1136         u"""Remove an LVM logical volume "device", where "device" is
1137         the path to the LV, such as "/dev/VG/LV".
1138         
1139         You can also remove all LVs in a volume group by
1140         specifying the VG name, "/dev/VG".
1141         """
1142         return libguestfsmod.lvremove (self._o, device)
1143
1144     def vgremove (self, vgname):
1145         u"""Remove an LVM volume group "vgname", (for example "VG").
1146         
1147         This also forcibly removes all logical volumes in the
1148         volume group (if any).
1149         """
1150         return libguestfsmod.vgremove (self._o, vgname)
1151
1152     def pvremove (self, device):
1153         u"""This wipes a physical volume "device" so that LVM will
1154         no longer recognise it.
1155         
1156         The implementation uses the "pvremove" command which
1157         refuses to wipe physical volumes that contain any volume
1158         groups, so you have to remove those first.
1159         """
1160         return libguestfsmod.pvremove (self._o, device)
1161
1162     def set_e2label (self, device, label):
1163         u"""This sets the ext2/3/4 filesystem label of the
1164         filesystem on "device" to "label". Filesystem labels are
1165         limited to 16 characters.
1166         
1167         You can use either "g.tune2fs_l" or "g.get_e2label" to
1168         return the existing label on a filesystem.
1169         """
1170         return libguestfsmod.set_e2label (self._o, device, label)
1171
1172     def get_e2label (self, device):
1173         u"""This returns the ext2/3/4 filesystem label of the
1174         filesystem on "device".
1175         """
1176         return libguestfsmod.get_e2label (self._o, device)
1177
1178     def set_e2uuid (self, device, uuid):
1179         u"""This sets the ext2/3/4 filesystem UUID of the filesystem
1180         on "device" to "uuid". The format of the UUID and
1181         alternatives such as "clear", "random" and "time" are
1182         described in the tune2fs(8) manpage.
1183         
1184         You can use either "g.tune2fs_l" or "g.get_e2uuid" to
1185         return the existing UUID of a filesystem.
1186         """
1187         return libguestfsmod.set_e2uuid (self._o, device, uuid)
1188
1189     def get_e2uuid (self, device):
1190         u"""This returns the ext2/3/4 filesystem UUID of the
1191         filesystem on "device".
1192         """
1193         return libguestfsmod.get_e2uuid (self._o, device)
1194
1195     def fsck (self, fstype, device):
1196         u"""This runs the filesystem checker (fsck) on "device"
1197         which should have filesystem type "fstype".
1198         
1199         The returned integer is the status. See fsck(8) for the
1200         list of status codes from "fsck".
1201         
1202         Notes:
1203         
1204         *   Multiple status codes can be summed together.
1205         
1206         *   A non-zero return code can mean "success", for
1207         example if errors have been corrected on the
1208         filesystem.
1209         
1210         *   Checking or repairing NTFS volumes is not supported
1211         (by linux-ntfs).
1212         
1213         This command is entirely equivalent to running "fsck -a
1214         -t fstype device".
1215         """
1216         return libguestfsmod.fsck (self._o, fstype, device)
1217
1218     def zero (self, device):
1219         u"""This command writes zeroes over the first few blocks of
1220         "device".
1221         
1222         How many blocks are zeroed isn't specified (but it's
1223         *not* enough to securely wipe the device). It should be
1224         sufficient to remove any partition tables, filesystem
1225         superblocks and so on.
1226         """
1227         return libguestfsmod.zero (self._o, device)
1228
1229     def grub_install (self, root, device):
1230         u"""This command installs GRUB (the Grand Unified
1231         Bootloader) on "device", with the root directory being
1232         "root".
1233         """
1234         return libguestfsmod.grub_install (self._o, root, device)
1235
1236     def cp (self, src, dest):
1237         u"""This copies a file from "src" to "dest" where "dest" is
1238         either a destination filename or destination directory.
1239         """
1240         return libguestfsmod.cp (self._o, src, dest)
1241
1242     def cp_a (self, src, dest):
1243         u"""This copies a file or directory from "src" to "dest"
1244         recursively using the "cp -a" command.
1245         """
1246         return libguestfsmod.cp_a (self._o, src, dest)
1247
1248     def mv (self, src, dest):
1249         u"""This moves a file from "src" to "dest" where "dest" is
1250         either a destination filename or destination directory.
1251         """
1252         return libguestfsmod.mv (self._o, src, dest)
1253
1254     def drop_caches (self, whattodrop):
1255         u"""This instructs the guest kernel to drop its page cache,
1256         and/or dentries and inode caches. The parameter
1257         "whattodrop" tells the kernel what precisely to drop,
1258         see <http://linux-mm.org/Drop_Caches>
1259         
1260         Setting "whattodrop" to 3 should drop everything.
1261         
1262         This automatically calls sync(2) before the operation,
1263         so that the maximum guest memory is freed.
1264         """
1265         return libguestfsmod.drop_caches (self._o, whattodrop)
1266
1267     def dmesg (self):
1268         u"""This returns the kernel messages ("dmesg" output) from
1269         the guest kernel. This is sometimes useful for extended
1270         debugging of problems.
1271         
1272         Another way to get the same information is to enable
1273         verbose messages with "g.set_verbose" or by setting the
1274         environment variable "LIBGUESTFS_DEBUG=1" before running
1275         the program.
1276         """
1277         return libguestfsmod.dmesg (self._o)
1278
1279     def ping_daemon (self):
1280         u"""This is a test probe into the guestfs daemon running
1281         inside the qemu subprocess. Calling this function checks
1282         that the daemon responds to the ping message, without
1283         affecting the daemon or attached block device(s) in any
1284         other way.
1285         """
1286         return libguestfsmod.ping_daemon (self._o)
1287
1288     def equal (self, file1, file2):
1289         u"""This compares the two files "file1" and "file2" and
1290         returns true if their content is exactly equal, or false
1291         otherwise.
1292         
1293         The external cmp(1) program is used for the comparison.
1294         """
1295         return libguestfsmod.equal (self._o, file1, file2)
1296
1297     def strings (self, path):
1298         u"""This runs the strings(1) command on a file and returns
1299         the list of printable strings found.
1300         
1301         This function returns a list of strings.
1302         
1303         Because of the message protocol, there is a transfer
1304         limit of somewhere between 2MB and 4MB. To transfer
1305         large files you should use FTP.
1306         """
1307         return libguestfsmod.strings (self._o, path)
1308
1309     def strings_e (self, encoding, path):
1310         u"""This is like the "g.strings" command, but allows you to
1311         specify the encoding.
1312         
1313         See the strings(1) manpage for the full list of
1314         encodings.
1315         
1316         Commonly useful encodings are "l" (lower case L) which
1317         will show strings inside Windows/x86 files.
1318         
1319         The returned strings are transcoded to UTF-8.
1320         
1321         This function returns a list of strings.
1322         
1323         Because of the message protocol, there is a transfer
1324         limit of somewhere between 2MB and 4MB. To transfer
1325         large files you should use FTP.
1326         """
1327         return libguestfsmod.strings_e (self._o, encoding, path)
1328
1329     def hexdump (self, path):
1330         u"""This runs "hexdump -C" on the given "path". The result
1331         is the human-readable, canonical hex dump of the file.
1332         
1333         Because of the message protocol, there is a transfer
1334         limit of somewhere between 2MB and 4MB. To transfer
1335         large files you should use FTP.
1336         """
1337         return libguestfsmod.hexdump (self._o, path)
1338
1339     def zerofree (self, device):
1340         u"""This runs the *zerofree* program on "device". This
1341         program claims to zero unused inodes and disk blocks on
1342         an ext2/3 filesystem, thus making it possible to
1343         compress the filesystem more effectively.
1344         
1345         You should not run this program if the filesystem is
1346         mounted.
1347         
1348         It is possible that using this program can damage the
1349         filesystem or data on the filesystem.
1350         """
1351         return libguestfsmod.zerofree (self._o, device)
1352
1353     def pvresize (self, device):
1354         u"""This resizes (expands or shrinks) an existing LVM
1355         physical volume to match the new size of the underlying
1356         device.
1357         """
1358         return libguestfsmod.pvresize (self._o, device)
1359
1360     def sfdisk_N (self, device, n, cyls, heads, sectors, line):
1361         u"""This runs sfdisk(8) option to modify just the single
1362         partition "n" (note: "n" counts from 1).
1363         
1364         For other parameters, see "g.sfdisk". You should usually
1365         pass 0 for the cyls/heads/sectors parameters.
1366         
1367         This command is dangerous. Without careful use you can
1368         easily destroy all your data.
1369         """
1370         return libguestfsmod.sfdisk_N (self._o, device, n, cyls, heads, sectors, line)
1371
1372     def sfdisk_l (self, device):
1373         u"""This displays the partition table on "device", in the
1374         human-readable output of the sfdisk(8) command. It is
1375         not intended to be parsed.
1376         """
1377         return libguestfsmod.sfdisk_l (self._o, device)
1378
1379     def sfdisk_kernel_geometry (self, device):
1380         u"""This displays the kernel's idea of the geometry of
1381         "device".
1382         
1383         The result is in human-readable format, and not designed
1384         to be parsed.
1385         """
1386         return libguestfsmod.sfdisk_kernel_geometry (self._o, device)
1387
1388     def sfdisk_disk_geometry (self, device):
1389         u"""This displays the disk geometry of "device" read from
1390         the partition table. Especially in the case where the
1391         underlying block device has been resized, this can be
1392         different from the kernel's idea of the geometry (see
1393         "g.sfdisk_kernel_geometry").
1394         
1395         The result is in human-readable format, and not designed
1396         to be parsed.
1397         """
1398         return libguestfsmod.sfdisk_disk_geometry (self._o, device)
1399
1400     def vg_activate_all (self, activate):
1401         u"""This command activates or (if "activate" is false)
1402         deactivates all logical volumes in all volume groups. If
1403         activated, then they are made known to the kernel, ie.
1404         they appear as "/dev/mapper" devices. If deactivated,
1405         then those devices disappear.
1406         
1407         This command is the same as running "vgchange -a y|n"
1408         """
1409         return libguestfsmod.vg_activate_all (self._o, activate)
1410
1411     def vg_activate (self, activate, volgroups):
1412         u"""This command activates or (if "activate" is false)
1413         deactivates all logical volumes in the listed volume
1414         groups "volgroups". If activated, then they are made
1415         known to the kernel, ie. they appear as "/dev/mapper"
1416         devices. If deactivated, then those devices disappear.
1417         
1418         This command is the same as running "vgchange -a y|n
1419         volgroups..."
1420         
1421         Note that if "volgroups" is an empty list then all
1422         volume groups are activated or deactivated.
1423         """
1424         return libguestfsmod.vg_activate (self._o, activate, volgroups)
1425
1426     def lvresize (self, device, mbytes):
1427         u"""This resizes (expands or shrinks) an existing LVM
1428         logical volume to "mbytes". When reducing, data in the
1429         reduced part is lost.
1430         """
1431         return libguestfsmod.lvresize (self._o, device, mbytes)
1432
1433     def resize2fs (self, device):
1434         u"""This resizes an ext2 or ext3 filesystem to match the
1435         size of the underlying device.
1436         
1437         *Note:* It is sometimes required that you run
1438         "g.e2fsck_f" on the "device" before calling this
1439         command. For unknown reasons "resize2fs" sometimes gives
1440         an error about this and sometimes not. In any case, it
1441         is always safe to call "g.e2fsck_f" before calling this
1442         function.
1443         """
1444         return libguestfsmod.resize2fs (self._o, device)
1445
1446     def find (self, directory):
1447         u"""This command lists out all files and directories,
1448         recursively, starting at "directory". It is essentially
1449         equivalent to running the shell command "find directory
1450         -print" but some post-processing happens on the output,
1451         described below.
1452         
1453         This returns a list of strings *without any prefix*.
1454         Thus if the directory structure was:
1455         
1456         /tmp/a
1457         /tmp/b
1458         /tmp/c/d
1459         
1460         then the returned list from "g.find" "/tmp" would be 4
1461         elements:
1462         
1463         a
1464         b
1465         c
1466         c/d
1467         
1468         If "directory" is not a directory, then this command
1469         returns an error.
1470         
1471         The returned list is sorted.
1472         
1473         This function returns a list of strings.
1474         """
1475         return libguestfsmod.find (self._o, directory)
1476
1477     def e2fsck_f (self, device):
1478         u"""This runs "e2fsck -p -f device", ie. runs the ext2/ext3
1479         filesystem checker on "device", noninteractively ("-p"),
1480         even if the filesystem appears to be clean ("-f").
1481         
1482         This command is only needed because of "g.resize2fs"
1483         (q.v.). Normally you should use "g.fsck".
1484         """
1485         return libguestfsmod.e2fsck_f (self._o, device)
1486