* disk image.
*/
guestfs_touch (g, "/hello");
-
+
/* This is only needed for libguestfs < 1.5.24. Since then
* it is done automatically when you close the handle. See
* discussion of autosync in this page.
Before you can read or write files, create directories and so on in a
disk image that contains filesystems, you have to mount those
-filesystems using L</guestfs_mount>. If you already know that a disk
-image contains (for example) one partition with a filesystem on that
-partition, then you can mount it directly:
+filesystems using L</guestfs_mount_options> or L</guestfs_mount_ro>.
+If you already know that a disk image contains (for example) one
+partition with a filesystem on that partition, then you can mount it
+directly:
- guestfs_mount (g, "/dev/sda1", "/");
+ guestfs_mount_options (g, "", "/dev/sda1", "/");
where C</dev/sda1> means literally the first partition (C<1>) of the
first disk image that we added (C</dev/sda>). If the disk contains
-Linux LVM2 logical volumes you could refer to those instead (eg. C</dev/VG/LV>).
+Linux LVM2 logical volumes you could refer to those instead
+(eg. C</dev/VG/LV>). Note that these are libguestfs virtual devices,
+and are nothing to do with host devices.
If you are given a disk image and you don't know what it contains then
you have to find out. Libguestfs can do that too: use
L</guestfs_list_partitions> and L</guestfs_lvs> to list possible
partitions and LVs, and either try mounting each to see what is
mountable, or else examine them with L</guestfs_vfs_type> or
-L</guestfs_file>. Libguestfs also has a set of APIs for inspection of
-disk images (see L</INSPECTION> below). But you might find it easier
-to look at higher level programs built on top of libguestfs, in
+L</guestfs_file>. To list just filesystems, use
+L</guestfs_list_filesystems>.
+
+Libguestfs also has a set of APIs for inspection of unknown disk
+images (see L</INSPECTION> below). But you might find it easier to
+look at higher level programs built on top of libguestfs, in
particular L<virt-inspector(1)>.
-To mount a disk image read-only, use L</guestfs_mount_ro>. There are
+To mount a filesystem read-only, use L</guestfs_mount_ro>. There are
several other variations of the C<guestfs_mount_*> call.
=head2 FILESYSTEM ACCESS AND MODIFICATION
=head2 DOWNLOADING
-Use L</guestfs_cat> to download small, text only files. This call
-is limited to files which are less than 2 MB and which cannot contain
-any ASCII NUL (C<\0>) characters. However it has a very simple
-to use API.
+Use L</guestfs_cat> to download small, text only files. This call is
+limited to files which are less than 2 MB and which cannot contain any
+ASCII NUL (C<\0>) characters. However the API is very simple to use.
L</guestfs_read_file> can be used to read files which contain
arbitrary 8 bit data, since it returns a (pointer, size) pair.
For example, L<virt-cat(1)> writes its output to stdout by
doing:
- guestfs_download (filename, "/dev/stdout");
+ guestfs_download (g, filename, "/dev/stdout");
and you can write tar output to a pipe C<fd> by doing:
char devfd[64];
snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
- guestfs_tar_out ("/", devfd);
+ guestfs_tar_out (g, "/", devfd);
=head2 LISTING FILES
mention here that the same API is also available in other languages.
The API is broadly identical in all supported languages. This means
-that the C call C<guestfs_mount(g,path)> is
-C<$g-E<gt>mount($path)> in Perl, C<g.mount(path)> in Python,
-and C<Guestfs.mount g path> in OCaml. In other words, a
+that the C call C<guestfs_add_drive_ro(g,file)> is
+C<$g-E<gt>add_drive_ro($file)> in Perl, C<g.add_drive_ro(file)> in Python,
+and C<g#add_drive_ro file> in OCaml. In other words, a
straightforward, predictable isomorphism between each language.
Error messages are automatically transformed
=item B<OCaml>
-For documentation see L<guestfs-ocaml(3)>.
+See L<guestfs-ocaml(3)>.
=item B<Perl>
-For documentation see L<Sys::Guestfs(3)>.
+See L<Sys::Guestfs(3)>.
=item B<PHP>
=item B<Python>
-For documentation see L<guestfs-python(3)>.
+See L<guestfs-python(3)>.
=item B<Ruby>
-For documentation see L<guestfs-ruby(3)>.
+See L<guestfs-ruby(3)>.
=item B<shell scripts>
-For documentation see L<guestfish(1)>.
+See L<guestfish(1)>.
=back
=head2 PATH
-Libguestfs needs a kernel and initrd.img, which it finds by looking
-along an internal path.
+Libguestfs needs a supermin appliance, which it finds by looking along
+an internal path.
By default it looks for these in the directory C<$libdir/guestfs>
(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
=item *
If any progress notification is sent during a call, then a final
-progress notification is always sent when C<position> = C<total>.
+progress notification is always sent when C<position> = C<total>
+(I<unless> the call fails with an error).
This is to simplify caller code, so callers can easily set the
progress indicator to "100%" at the end of the operation, without
=item LIBGUESTFS_PATH
-Set the path that libguestfs uses to search for kernel and initrd.img.
-See the discussion of paths in section PATH above.
+Set the path that libguestfs uses to search for a supermin appliance.
+See the discussion of paths in section L</PATH> above.
=item LIBGUESTFS_QEMU
git.annexia.org / libguestfs.git / blobdiff