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>
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)>,