From 38d8943009e3a637e56af6adb43f6c12a7a357c7 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Fri, 13 Nov 2009 14:13:31 +0000 Subject: [PATCH] Docs: Add/extend API overview. --- guestfs.pod | 468 ++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 316 insertions(+), 152 deletions(-) diff --git a/guestfs.pod b/guestfs.pod index 9424ec2..2ebcc09 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -42,180 +42,159 @@ or Haskell). You can also use it from shell scripts or the command line. You don't need to be root to use libguestfs, although obviously you do need enough permissions to access the disk images. -=head1 CONNECTION MANAGEMENT +Libguestfs is a large API because it can do many things. For a gentle +introduction, please read the L section next. + +=head1 API OVERVIEW + +This section provides a gentler overview of the libguestfs API. We +also try to group API calls together, where that may not be obvious +from reading about the individual calls below. + +=head2 HANDLES -If you are using the high-level API, then you should call the -functions in the following order: +Before you can use libguestfs calls, you have to create a handle. +Then you must add at least one disk image to the handle, followed by +launching the handle, then performing whatever operations you want, +and finally closing the handle. So the general structure of all +libguestfs-using programs looks like this: guestfs_h *handle = guestfs_create (); - guestfs_add_drive (handle, "guest.img"); - /* call guestfs_add_drive additional times if the guest has - * multiple disks + /* Call guestfs_add_drive additional times if there are + * multiple disk images. */ + guestfs_add_drive (handle, "guest.img"); + /* Most manipulation calls won't work until you've launched + * the handle. You have to do this _after_ adding drives + * and _before_ other commands. + */ guestfs_launch (handle); - /* now you can examine what partitions, LVs etc are available - * you have to mount / at least + /* Now you can examine what partitions, LVs etc are available. + */ + char **partitions = guestfs_list_partitions (handle); + char **logvols = guestfs_lvs (handle); + + /* To access a filesystem in the image, you must mount it. */ guestfs_mount (handle, "/dev/sda1", "/"); - /* now you can perform actions on the guest disk image */ + /* Now you can perform filesystem actions on the guest disk image. */ guestfs_touch (handle, "/hello"); - /* you only need to call guestfs_sync if you have made - * changes to the guest image + /* You only need to call guestfs_sync if you have made + * changes to the guest image. */ guestfs_sync (handle); + /* Close the handle. */ guestfs_close (handle); -C and all of the actions including C -are blocking calls. - -All functions that return integers, return C<-1> on error. See -section L below for how to handle errors. - -=head2 guestfs_h * - -C is the opaque type representing a connection handle. -Create a handle by calling C. Call C -to free the handle and release all resources used. - -For information on using multiple handles and threads, see the section -L below. - -=head2 guestfs_create - - guestfs_h *guestfs_create (void); - -Create a connection handle. - -You have to call C on the handle at least once. - -This function returns a non-NULL pointer to a handle on success or -NULL on error. - -After configuring the handle, you have to call C. - -You may also want to configure error handling for the handle. See -L section below. - -=head2 guestfs_close - - void guestfs_close (guestfs_h *handle); - -This closes the connection handle and frees up all resources used. - -=head1 ERROR HANDLING +The code above doesn't include any error checking. In real code you +should check return values carefully for errors. In general all +functions that return integers return C<-1> on error, and all +functions that return pointers return C on error. See section +L below for how to handle errors, and consult the +documentation for each function call below to see precisely how they +return error indications. -The convention in all functions that return C is that they return -C<-1> to indicate an error. You can get additional information on -errors by calling C and/or by setting up an error -handler with C. +=head2 DISK IMAGES -The default error handler prints the information string to C. - -Out of memory errors are handled differently. The default action is -to call L. If this is undesirable, then you can set a -handler using C. - -=head2 guestfs_last_error - - const char *guestfs_last_error (guestfs_h *handle); +The image filename (C<"guest.img"> in the example above) could be a +disk image from a virtual machine, a L copy of a physical block +device, an actual block device, or simply an empty file of zeroes that +you have created through L. Libguestfs lets you +do useful things to all of these. -This returns the last error message that happened on C. If -there has not been an error since the handle was created, then this -returns C. +You can add a disk read-only using C, in which +case libguestfs won't modify the file. -The lifetime of the returned string is until the next error occurs, or -C is called. +Be extremely cautious if the disk image is in use, eg. if it is being +used by a virtual machine. Adding it read-write will almost certainly +cause disk corruption, but adding it read-only is safe. -The error string is not localized (ie. is always in English), because -this makes searching for error messages in search engines give the -largest number of results. +You must add at least one disk image, and you may add multiple disk +images. In the API, the disk images are usually referred to as +C (for the first one you added), C (for the second +one you added), etc. -=head2 guestfs_set_error_handler +Once C has been called you cannot add any more images. +You can call C to get a list of the device +names, in the order that you added them. See also L below. - typedef void (*guestfs_error_handler_cb) (guestfs_h *handle, - void *data, - const char *msg); - void guestfs_set_error_handler (guestfs_h *handle, - guestfs_error_handler_cb cb, - void *data); +=head2 MOUNTING -The callback C will be called if there is an error. The -parameters passed to the callback are an opaque data pointer and the -error message string. +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 C. 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: -Note that the message string C is freed as soon as the callback -function returns, so if you want to stash it somewhere you must make -your own copy. - -The default handler prints messages on C. - -If you set C to C then I handler is called. - -=head2 guestfs_get_error_handler - - guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle, - void **data_rtn); + guestfs_mount (handle, "/dev/sda1", "/"); -Returns the current error handler callback. +where C means literally the first partition (C<1>) of the +first disk image that we added (C). If the disk contains +Linux LVM2 logical volumes you could refer to those instead (eg. C). -=head2 guestfs_set_out_of_memory_handler +If you are given a disk image and you don't know what it contains then +you have to find out. Libguestfs can also do that: use +C and C to list possible +partitions and LVs, and either try mounting each to see what is +mountable, or else examine them with C. But you might +find it easier to look at higher level programs built on top of +libguestfs, in particular L. - typedef void (*guestfs_abort_cb) (void); - int guestfs_set_out_of_memory_handler (guestfs_h *handle, - guestfs_abort_cb); +To mount a disk image read-only, use C. There are +several other variations of the C call. -The callback C will be called if there is an out of memory -situation. I. +=head2 FILESYSTEM ACCESS AND MODIFICATION -The default is to call L. +The majority of the libguestfs API consists of fairly low-level calls +for accessing and modifying the files, directories, symlinks etc on +mounted filesystems. There are over a hundred such calls which you +can find listed in detail below in this man page, and we don't even +pretend to cover them all in this overview. -You cannot set C to C. You can't ignore out of memory -situations. +Specify filenames as full paths including the mount point. -=head2 guestfs_get_out_of_memory_handler +For example, if you mounted a filesystem at C<"/"> and you want to +read the file called C<"etc/passwd"> then you could do: - guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *handle); + char *data = guestfs_cat (handle, "/etc/passwd"); -This returns the current out of memory handler. +This would return C as a newly allocated buffer containing the +full content of that file (with some conditions: see also +L below), or C if there was an error. -=head1 PATH +As another example, to create a top-level directory on that filesystem +called C<"var"> you would do: -Libguestfs needs a kernel and initrd.img, which it finds by looking -along an internal path. + guestfs_mkdir (handle, "/var"); -By default it looks for these in the directory C<$libdir/guestfs> -(eg. C or C). +To create a symlink you could do: -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. + guestfs_ln_s (handle, "/etc/init.d/portmap", + "/etc/rc3.d/S30portmap"); -=head1 API OVERVIEW +Libguestfs will reject attempts to use relative paths. There is no +concept of a current working directory. Libguestfs can return errors +in many situations: for example if the filesystem isn't writable, or +if a file or directory that you requested doesn't exist. If you are +using the C API (documented here) you have to check for those error +conditions after each call. (Other language bindings turn these +errors into exceptions). -This section provides additional documentation for groups of API -calls, which may not be obvious from reading about the individual -calls below. - -=head2 LVM2 - -Libguestfs provides access to a large part of the LVM2 API. It won't -make much sense unless you familiarize yourself with the concepts of -physical volumes, volume groups and logical volumes. - -This author strongly recommends reading the LVM HOWTO, online at -L. +File writes are affected by the per-handle umask, set by calling +C and defaulting to 022. =head2 PARTITIONING +Libguestfs contains API calls to read, create and modify partition +tables on disk images. + In the common case where you want to create a single partition covering the whole disk, you should use the C call: @@ -225,6 +204,9 @@ call: parttype = "gpt"; guestfs_part_disk (g, "/dev/sda", parttype); +Obviously this effectively wipes anything that was on that disk image +before. + In general MBR partitions are both unnecessarily complicated and depend on archaic details, namely the Cylinder-Head-Sector (CHS) geometry of the disk. C can be used to @@ -238,10 +220,40 @@ probably don't want to know about. My advice: make a single partition to cover the whole disk, then use LVM on top. +=head2 LVM2 + +Libguestfs provides access to a large part of the LVM2 API, such as +C and C. It won't make much sense +unless you familiarize yourself with the concepts of physical volumes, +volume groups and logical volumes. + +This author strongly recommends reading the LVM HOWTO, online at +L. + +=head2 DOWNLOADING + +Use C 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. + +C can be used to read files which contain +arbitrary 8 bit data, since it returns a (pointer, size) pair. +However it is still limited to "small" files, less than 2 MB. + +C can be used to download any file, with no +limits on content or size (even files larger than 4 GB). + +To download multiple files, see C and +C. + =head2 UPLOADING -For small, single files, use C. In some versions -of libguestfs there was a bug which limited this call to text files +It's often the case that you want to write a file or files to the disk +image. + +For small, single files, use C. This call +currently contains a bug which limited the call to plain text files (not containing ASCII NUL characters). To upload a single file, use C. This call has no @@ -260,22 +272,19 @@ non-portable between kernel versions, and they don't support labels or UUIDs. If you want to pre-build an image or you need to mount it using a label or UUID, use an ISO image instead. -=head2 DOWNLOADING +=head2 LISTING FILES -Use C 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. +C is just designed for humans to read (mainly when using +the L-equivalent command C). -C can be used to read files which contain -arbitrary 8 bit data, since it returns a (pointer, size) pair. -However it is still limited to "small" files, less than 2 MB. +C is a quick way to get a list of files in a directory +from programs, as a flat list of strings. -C can be used to download any file, with no -limits on content or size (even files larger than 4 GB). +C is a programmatic way to get a list of files in a +directory, plus additional information about each one. It is more +equivalent to using the L call on a local filesystem. -To download multiple files, see C and -C. +C can be used to recursively list files. =head2 RUNNING COMMANDS @@ -323,18 +332,20 @@ C (there are also variations). The difference is that C runs commands using the shell, so any shell globs, redirections, etc will work. -=head2 LISTING FILES +=head2 CONFIGURATION FILES -C is just designed for humans to read (mainly when using -the L-equivalent command C). +To read and write configuration files in Linux guest filesystems, we +strongly recommend using Augeas. For example, Augeas understands how +to read and write, say, a Linux shadow password file or X.org +configuration file, and so avoids you having to write that code. -C is a quick way to get a list of files in a directory -from programs. - -C is a programmatic way to get a list of files in a -directory, plus additional information about each one. +The main Augeas calls are bound through the C APIs. We +don't document Augeas itself here because there is excellent +documentation on the L website. -C can be used to recursively list files. +If you don't want to use Augeas (you fool!) then try calling +C to get the file as a list of lines which +you can iterate over. =head2 SELINUX @@ -377,6 +388,159 @@ When new files are created, you may need to label them explicitly, for example by running the external command C. +=head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS + +Libguestfs can mount NTFS partitions. It does this using the +L driver. + +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 +C. When the filesystem is mounted in libguestfs, +that directory might be referred to as C. + +Drive letter mappings are outside the scope of libguestfs. You have +to use libguestfs to read the appropriate Windows Registry and +configuration files, to determine yourself how drives are mapped (see +also L). + +Replacing backslash characters with forward slash characters is also +outside the scope of libguestfs, but something that you can easily do. + +Where we can help is in resolving the case insensitivity of paths. +For this, call C. + +Libguestfs also provides some help for decoding Windows Registry +"hive" files, through the library C which is part of +libguestfs. You have to locate and download the hive file(s) +yourself, and then pass them to C functions. See also the +programs L, L and L for more +help on this issue. + +=head1 CONNECTION MANAGEMENT + +=head2 guestfs_h * + +C is the opaque type representing a connection handle. +Create a handle by calling C. Call C +to free the handle and release all resources used. + +For information on using multiple handles and threads, see the section +L below. + +=head2 guestfs_create + + guestfs_h *guestfs_create (void); + +Create a connection handle. + +You have to call C on the handle at least once. + +This function returns a non-NULL pointer to a handle on success or +NULL on error. + +After configuring the handle, you have to call C. + +You may also want to configure error handling for the handle. See +L section below. + +=head2 guestfs_close + + void guestfs_close (guestfs_h *handle); + +This closes the connection handle and frees up all resources used. + +=head1 ERROR HANDLING + +The convention in all functions that return C is that they return +C<-1> to indicate an error. You can get additional information on +errors by calling C and/or by setting up an error +handler with C. + +The default error handler prints the information string to C. + +Out of memory errors are handled differently. The default action is +to call L. If this is undesirable, then you can set a +handler using C. + +=head2 guestfs_last_error + + const char *guestfs_last_error (guestfs_h *handle); + +This returns the last error message that happened on C. If +there has not been an error since the handle was created, then this +returns C. + +The lifetime of the returned string is until the next error occurs, or +C is called. + +The error string is not localized (ie. is always in English), because +this makes searching for error messages in search engines give the +largest number of results. + +=head2 guestfs_set_error_handler + + typedef void (*guestfs_error_handler_cb) (guestfs_h *handle, + void *data, + const char *msg); + void guestfs_set_error_handler (guestfs_h *handle, + guestfs_error_handler_cb cb, + void *data); + +The callback C will be called if there is an error. The +parameters passed to the callback are an opaque data pointer and the +error message string. + +Note that the message string C is freed as soon as the callback +function returns, so if you want to stash it somewhere you must make +your own copy. + +The default handler prints messages on C. + +If you set C to C then I handler is called. + +=head2 guestfs_get_error_handler + + guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle, + void **data_rtn); + +Returns the current error handler callback. + +=head2 guestfs_set_out_of_memory_handler + + typedef void (*guestfs_abort_cb) (void); + int guestfs_set_out_of_memory_handler (guestfs_h *handle, + guestfs_abort_cb); + +The callback C will be called if there is an out of memory +situation. I. + +The default is to call L. + +You cannot set C to C. You can't ignore out of memory +situations. + +=head2 guestfs_get_out_of_memory_handler + + guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *handle); + +This returns the current out of memory handler. + +=head1 PATH + +Libguestfs needs a kernel and initrd.img, which it finds by looking +along an internal path. + +By default it looks for these in the directory C<$libdir/guestfs> +(eg. C or 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. + =head1 HIGH-LEVEL API ACTIONS =head2 ABI GUARANTEE -- 1.8.3.1