guestfs_mount (g, "/dev/sda1", "/");
guestfs_touch (g, "/hello");
guestfs_umount (g, "/");
- guestfs_sync (g);
guestfs_close (g);
cc prog.c -o prog -lguestfs
Libguestfs is a large API because it can do many things. For a gentle
introduction, please read the L</API OVERVIEW> section next.
+There are also some example programs in the L<guestfs-examples(3)>
+manual page.
+
=head1 API OVERVIEW
This section provides a gentler overview of the libguestfs API. We
* disk image.
*/
guestfs_touch (g, "/hello");
-
- /* You only need to call guestfs_sync if you have made
- * changes to the guest image. (But if you've made changes
- * then you *must* sync). See also: guestfs_umount and
- * guestfs_umount_all calls.
+
+ /* 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.
*/
guestfs_sync (g);
functions that return pointers return C<NULL> on error. See section
L</ERROR HANDLING> below for how to handle errors, and consult the
documentation for each function call below to see precisely how they
-return error indications.
+return error indications. See L<guestfs-examples(3)> for fully worked
+examples.
=head2 DISK IMAGES
=back
+=head2 UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
+
+Calls like L</guestfs_upload>, L</guestfs_download>,
+L</guestfs_tar_in>, L</guestfs_tar_out> etc appear to only take
+filenames as arguments, so it appears you can only upload and download
+to files. However many Un*x-like hosts let you use the special device
+files C</dev/stdin>, C</dev/stdout>, C</dev/stderr> and C</dev/fd/N>
+to read and write from stdin, stdout, stderr, and arbitrary file
+descriptor N.
+
+For example, L<virt-cat(1)> writes its output to stdout by
+doing:
+
+ guestfs_download (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);
+
=head2 LISTING FILES
L</guestfs_ll> is just designed for humans to read (mainly when using
Libguestfs can mount NTFS partitions. It does this using the
L<http://www.ntfs-3g.org/> driver.
+=head3 DRIVE LETTERS AND PATHS
+
DOS and Windows still use drive letters, and the filesystems are
always treated as case insensitive by Windows itself, and therefore
you might find a Windows configuration file referring to a path like
Where we can help is in resolving the case insensitivity of paths.
For this, call L</guestfs_case_sensitive_path>.
+=head3 ACCESSING THE WINDOWS REGISTRY
+
Libguestfs also provides some help for decoding Windows Registry
"hive" files, through the library C<hivex> which is part of the
libguestfs project although ships as a separate tarball. You have to
L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-reg(1)> for more help
on this issue.
+=head3 SYMLINKS ON NTFS-3G FILESYSTEMS
+
+Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links"
+to provide something which looks like a Linux symlink. The way it
+tries to do the rewriting is described here:
+
+L<http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/>
+
+The essential problem is that ntfs-3g simply does not have enough
+information to do a correct job. NTFS links can contain drive letters
+and references to external device GUIDs that ntfs-3g has no way of
+resolving. It is almost certainly the case that libguestfs callers
+should ignore what ntfs-3g does (ie. don't use L</guestfs_readlink> on
+NTFS volumes).
+
+Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
+L</guestfs_lgetxattr> to read the C<system.ntfs_reparse_data> extended
+attribute, and read the raw reparse data from that (you can find the
+format documented in various places around the web).
+
+=head3 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
+
+There are other useful extended attributes that can be read from
+ntfs-3g filesystems (using L</guestfs_getxattr>). See:
+
+L<http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/>
+
=head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
Although we don't want to discourage you from using the C API, we will
=item B<OCaml>
-For documentation see the file C<guestfs.mli>.
+For documentation see L<guestfs-ocaml(3)>.
=item B<Perl>
=item B<Python>
-For documentation do:
-
- $ python
- >>> import guestfs
- >>> help (guestfs)
+For documentation see L<guestfs-python(3)>.
=item B<Ruby>
-Use the Guestfs module. There is no Ruby-specific documentation, but
-you can find examples written in Ruby in the libguestfs source.
+For documentation see L<guestfs-ruby(3)>.
=item B<shell scripts>
to a structured file (for example, use HTML escaping if creating a web
page).
+Guest configuration may be altered in unusual ways by the
+administrator of the virtual machine, and may not reflect reality
+(particularly for untrusted or actively malicious guests). For
+example we parse the hostname from configuration files like
+C</etc/sysconfig/network> that we find in the guest, but the guest
+administrator can easily manipulate these files to provide the wrong
+hostname.
+
The inspection API parses guest configuration using two external
libraries: Augeas (Linux configuration) and hivex (Windows Registry).
Both are designed to be robust in the face of malicious data, although
how the receiver knows what type of args structure to expect, or none
at all.
+For functions that take optional arguments, the optional arguments are
+encoded in the C<guestfs_I<foo>_args> structure in the same way as
+ordinary arguments. A bitmask in the header indicates which optional
+arguments are meaningful. The bitmask is also checked to see if it
+contains bits set which the daemon does not know about (eg. if more
+optional arguments were added in a later version of the library), and
+this causes the call to be rejected.
+
The reply message for ordinary functions is:
total length (header + ret,
=head1 SEE ALSO
+L<guestfs-examples(3)>,
+L<guestfs-ocaml(3)>,
+L<guestfs-python(3)>,
+L<guestfs-ruby(3)>,
L<guestfish(1)>,
L<guestmount(1)>,
L<virt-cat(1)>,
L<virt-df(1)>,
L<virt-edit(1)>,
+L<virt-filesystems(1)>,
L<virt-inspector(1)>,
L<virt-list-filesystems(1)>,
L<virt-list-partitions(1)>,
git.annexia.org / libguestfs.git / blobdiff