X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=7396644d4648e73ef13d7b015389151a332fa247;hp=b0fa5f29a7c75738414ca02b5e6ea415c2a42151;hb=73d6932ab2dd3f9120a1f4a532621c07cb174705;hpb=163e399a001a300a53a4c99887742608d23e09ad diff --git a/guestfs.pod b/guestfs.pod index b0fa5f2..7396644 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -34,8 +34,7 @@ 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 mount guest filesystems on -the host (requires root privs and NFS). +in the context of the guest. Also you can access filesystems over FTP. Libguestfs is a library that can be linked with C and C++ management programs (or management programs written in other languages, if people @@ -238,66 +237,84 @@ situations. This returns the current out of memory handler. -=head1 VERBOSE MESSAGES +=head1 PATH -=head2 guestfs_set_verbose +Libguestfs needs a kernel and initrd.img, which it finds by looking +along an internal path. - void guestfs_set_verbose (guestfs_h *handle, int verbose); +By default it looks for these in the directory C<$libdir/guestfs> +(eg. C or C). -If C is true, this turns on verbose messages (to C). +Use C or set the environment variable +C to change the directories that libguestfs will +search in. The value is a colon-separated list of paths. The current +directory is I searched unless the path contains an empty element +or C<.>. For example C would +search the current directory and then C. -Verbose messages are disabled unless the environment variable -C is defined and set to C<1>. +=head2 guestfs_set_path -=head2 guestfs_get_verbose + void guestfs_set_path (guestfs_h *handle, const char *path); - int guestfs_get_verbose (guestfs_h *handle); +Set the path that libguestfs searches for kernel and initrd.img. -This returns the verbose messages flag. +The default is C<$libdir/guestfs> unless overridden by setting +C environment variable. -=head1 HIGH-LEVEL API ACTIONS +The string C is stashed in the libguestfs handle, so the caller +must make sure it remains valid for the lifetime of the handle. -=head2 guestfs_sync +Setting C to C restores the default path. - int guestfs_sync (guestfs_h *handle); +=head2 guestfs_get_path -This syncs the disk, so that any writes are flushed through to the -underlying disk image. + const char *guestfs_get_path (guestfs_h *handle); -You should always call this if you have modified a disk image, before -calling C. +Return the current search path. -XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +This is always non-NULL. If it wasn't set already, then this will +return the default path. -Documentation will be auto-generated from here, including for -guestfs_sync. +=head1 AUTOSYNC -XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +=head2 guestfs_set_autosync - do_[action] ([parameters]) - { - guestfs_set_reply_callback (handle, [action]_cb, data); - guestfs_nb_[action] (handle, [parameters ...]); + void guestfs_set_autosync (guestfs_h *handle, int autosync); - guestfs_main_loop_run (); /* --> blocks, then calls my_cb */ - } +If C is true, this enables autosync. Libguestfs will make a +best effort attempt to run C when the handle is closed +(also if the program exits without closing handles). - [action]_cb (guestfs_h *handle, void *data) - { - retval = guestfs_nb_[action]_r (handle); - /* ... */ - guestfs_main_loop_quit (); - return retval; - } +=head2 guestfs_get_autosync -XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + int guestfs_get_autosync (guestfs_h *handle); +Get the autosync flag. +=head1 VERBOSE MESSAGES +=head2 guestfs_set_verbose + void guestfs_set_verbose (guestfs_h *handle, int verbose); +If C is true, this turns on verbose messages (to C). +Verbose messages are disabled unless the environment variable +C is defined and set to C<1>. + +=head2 guestfs_get_verbose + + int guestfs_get_verbose (guestfs_h *handle); + +This returns the verbose messages flag. + +=head1 HIGH-LEVEL API ACTIONS + +@ACTIONS@ +=head1 STRUCTURES + +@STRUCTS@ =head1 STATE MACHINE AND LOW-LEVEL EVENT API @@ -399,6 +416,8 @@ this function with C set to C. =head2 NON-BLOCKING ACTIONS +XXX NOT IMPLEMENTED YET XXX + C is the most interesting callback to play with, since it allows you to perform actions without blocking. @@ -424,8 +443,7 @@ For example: } There are C and C functions -corresponding to (very nearly) every C action in the -high-level API. +corresponding to every C action in the high-level API. =head2 guestfs_set_reply_callback @@ -438,6 +456,10 @@ The callback function C will be called whenever a reply is received from the child process. (This corresponds to a transition from the BUSY state to the READY state). +Note that the C that you get in the callback is in C +mode, and you need to consume it before you return from the callback +function (since it gets destroyed after). + =head2 guestfs_set_log_message_callback typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, @@ -570,13 +592,28 @@ function, eg. C. In those cases, ignore this call. This isn't documented. Please see the libguestfs-select and libguestfs-glib implementations. -=head1 SEE ALSO +=head1 ENVIRONMENT VARIABLES + +=over 4 + +=item LIBGUESTFS_DEBUG -L +Set C to enable verbose messages. This +has the same effect as calling C. +=item LIBGUESTFS_PATH +Set the path that libguestfs uses to search for kernel and initrd.img. +See the discussion of paths in C above. +=back + +=head1 SEE ALSO +L, +L, +L, +L. =head1 AUTHORS