X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=842b0e4fd23164b35c99497c5f3f8f08f5306f21;hp=a847a5f34e7600329c2b24c342e0d8a2ad86c4a2;hb=f3ada2c7653866f2529c9f18aaa99f76cd984844;hpb=1541f3a564f8ff14c1a63298120e4dc618ea3274 diff --git a/src/guestfs.pod b/src/guestfs.pod index a847a5f..842b0e4 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -354,7 +354,7 @@ doing: guestfs_download (g, filename, "/dev/stdout"); -and you can write tar output to a pipe C by doing: +and you can write tar output to a file descriptor C by doing: char devfd[64]; snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd); @@ -641,16 +641,15 @@ 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 and L). +Drive letter mappings can be found using inspection +(see L and L) -Replacing backslash characters with forward slash characters is also -outside the scope of libguestfs, but something that you can easily do. +Dealing with separator characters (backslash vs forward slash) is +outside the scope of libguestfs, but usually a simple character +replacement will work. -Where we can help is in resolving the case insensitivity of paths. -For this, call L. +To resolve the case insensitivity of paths, call +L. =head3 ACCESSING THE WINDOWS REGISTRY @@ -776,6 +775,9 @@ them. =item Autosync / forgetting to sync. +I Autosync is enabled by default for all API users starting +from libguestfs 1.5.24. This section only applies to older versions. + When modifying a filesystem from C or another language, you B unmount all filesystems and call L explicitly before you close the libguestfs handle. You can also call: @@ -794,9 +796,6 @@ Note that in L autosync is the default. So quick and dirty guestfish scripts that forget to sync will work just fine, which can make this very puzzling if you are trying to debug a problem. -Update: Autosync is enabled by default for all API users starting from -libguestfs 1.5.24. - =item Mount option C<-o sync> should not be the default. If you use L, then C<-o sync,noatime> are added @@ -880,29 +879,6 @@ representation. Also consider how it might work in guestfish. =back -=head2 PROTOCOL LIMITS - -Internally libguestfs uses a message-based protocol to pass API calls -and their responses to and from a small "appliance" (see L -for plenty more detail about this). The maximum message size used by -the protocol is slightly less than 4 MB. For some API calls you may -need to be aware of this limit. The API calls which may be affected -are individually documented, with a link back to this section of the -documentation. - -A simple call such as L returns its result (the file -data) in a simple string. Because this string is at some point -internally encoded as a message, the maximum size that it can return -is slightly under 4 MB. If the requested file is larger than this -then you will get an error. - -In order to transfer large files into and out of the guest filesystem, -you need to use particular calls that support this. The sections -L and L document how to do this. - -You might also consider mounting the disk image using our FUSE -filesystem support (L). - =head2 KEYS AND PASSPHRASES Certain libguestfs calls take a parameter that contains sensitive key @@ -1309,7 +1285,7 @@ Create a handle by calling L. Call L to free the handle and release all resources used. For information on using multiple handles and threads, see the section -L below. +L above. =head2 guestfs_create @@ -1317,15 +1293,16 @@ L below. Create a connection handle. -You have to call L (or one of the equivalent -calls) on the handle at least once. +On success this returns a non-NULL pointer to a handle. On error it +returns NULL. -This function returns a non-NULL pointer to a handle on success or -NULL on error. +You have to "configure" the handle after creating it. This includes +calling L (or one of the equivalent calls) on +the handle at least once. After configuring the handle, you have to call L. -You may also want to configure error handling for the handle. See +You may also want to configure error handling for the handle. See the L section below. =head2 guestfs_close @@ -1334,6 +1311,12 @@ L section below. This closes the connection handle and frees up all resources used. +If autosync was set on the handle and the handle was launched, then +this implicitly calls various functions to unmount filesystems and +sync the disk. See L for more details. + +If a close callback was set on the handle, then it is called. + =head1 ERROR HANDLING API functions can return errors. For example, almost all functions @@ -1689,7 +1672,8 @@ old functions C, C, C, C and C are no longer documented in this -manual page. +manual page. Because of the ABI guarantee, the old functions continue +to work. Handles generate events when certain things happen, such as log messages being generated, progress messages during long-running @@ -1779,12 +1763,27 @@ indicator which shows the ratio of C:C. =item * If any progress notification is sent during a call, then a final -progress notification is always sent when C = C. +progress notification is always sent when C = C +(I 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 requiring special code to detect this case. +=item * + +For some calls we are unable to estimate the progress of the call, but +we can still generate progress messages to indicate activity. This is +known as "pulse mode", and is directly supported by certain progress +bar implementations (eg. GtkProgressBar). + +For these calls, zero or more progress messages are generated with +C and C, followed by a final message with +C. + +As noted above, if the call fails with an error then the final message +may not be generated. + =back The callback also receives the procedure number (C) and @@ -1963,12 +1962,13 @@ To attach a named piece of data, use the following call: C is the name to associate with this data, and C is an arbitrary pointer (which can be C). Any previous item with the -same name is overwritten. +same key is overwritten. -You can use any C you want, but names beginning with an -underscore character are reserved for internal libguestfs purposes -(for implementing language bindings). It is recommended to prefix the -name with some unique string to avoid collisions with other users. +You can use any C you want, but your key should I start with +an underscore character. Keys beginning with an underscore character +are reserved for internal libguestfs purposes (eg. for implementing +language bindings). It is recommended that you prefix the key with +some unique string to avoid collisions with other users. To retrieve the pointer, use: @@ -2658,6 +2658,11 @@ Automated tests of the C API. The L, L and L commands and documentation. +=item C + +Safety and liveness tests of components that libguestfs depends upon +(not of libguestfs itself). Mainly this is for qemu and the kernel. + =item C Outside contributions, experimental parts. @@ -2671,6 +2676,10 @@ actions. L command and documentation. +=item C + +L command and documentation. + =item C C API example code. @@ -2759,6 +2768,106 @@ Language bindings. =back +=head1 LIMITS + +=head2 PROTOCOL LIMITS + +Internally libguestfs uses a message-based protocol to pass API calls +and their responses to and from a small "appliance" (see L +for plenty more detail about this). The maximum message size used by +the protocol is slightly less than 4 MB. For some API calls you may +need to be aware of this limit. The API calls which may be affected +are individually documented, with a link back to this section of the +documentation. + +A simple call such as L returns its result (the file +data) in a simple string. Because this string is at some point +internally encoded as a message, the maximum size that it can return +is slightly under 4 MB. If the requested file is larger than this +then you will get an error. + +In order to transfer large files into and out of the guest filesystem, +you need to use particular calls that support this. The sections +L and L document how to do this. + +You might also consider mounting the disk image using our FUSE +filesystem support (L). + +=head2 MAXIMUM NUMBER OF DISKS + +When using virtio disks (the default) the current limit is B<25> +disks. + +Virtio itself consumes 1 virtual PCI slot per disk, and PCI is limited +to 31 slots. However febootstrap only understands disks with names +C through C (26 letters) and it reserves one disk +for its own purposes. + +We are working to substantially raise this limit in future versions +but it requires complex changes to qemu. + +In future versions of libguestfs it should also be possible to "hot +plug" disks (add and remove disks after calling L). +This also requires changes to qemu. + +=head2 MAXIMUM NUMBER OF PARTITIONS PER DISK + +Virtio limits the maximum number of partitions per disk to B<15>. + +This is because it reserves 4 bits for the minor device number (thus +C, and C through C). + +If you attach a disk with more than 15 partitions, the extra +partitions are ignored by libguestfs. + +=head2 MAXIMUM SIZE OF A DISK + +Probably the limit is between 2**63-1 and 2**64-1 bytes. + +We have tested block devices up to 1 exabyte (2**60 or +1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS +host filesystem. + +Although libguestfs probably does not impose any limit, the underlying +host storage will. If you store disk images on a host ext4 +filesystem, then the maximum size will be limited by the maximum ext4 +file size (currently 16 TB). If you store disk images as host logical +volumes then you are limited by the maximum size of an LV. + +For the hugest disk image files, we recommend using XFS on the host +for storage. + +=head2 MAXIMUM SIZE OF A PARTITION + +The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector +numbers. Assuming a 512 byte sector size, this means that MBR cannot +address a partition located beyond 2 TB on the disk. + +It is recommended that you use GPT partitions on disks which are +larger than this size. GPT uses 64 bit sector numbers and so can +address partitions which are theoretically larger than the largest +disk we could support. + +=head2 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES + +This depends on the filesystem type. libguestfs itself does not +impose any known limit. Consult Wikipedia or the filesystem +documentation to find out what these limits are. + +=head2 MAXIMUM UPLOAD AND DOWNLOAD + +The API functions L, L, +L, L and the like allow unlimited +sized uploads and downloads. + +=head2 INSPECTION LIMITS + +The inspection code has several arbitrary limits on things like the +size of Windows Registry hive it will read, and the length of product +name. These are intended to stop a malicious guest from consuming +arbitrary amounts of memory and disk space on the host, and should not +be reached in practice. See the source code for more information. + =head1 ENVIRONMENT VARIABLES =over 4 @@ -2885,7 +2994,7 @@ Richard W.M. Jones (C) =head1 COPYRIGHT -Copyright (C) 2009-2010 Red Hat Inc. +Copyright (C) 2009-2011 Red Hat Inc. L This library is free software; you can redistribute it and/or