X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=c537ae96f643e89f5cbcaf7f872004ea15dfc1bc;hp=91c6b330d319b0ce227131bb81166e4acbba6ac3;hb=108d7a134c5d26b967fa7162d9b80b40112c2869;hpb=05dbe09a5c5be3d5f68dc6eb033c4f642fbac8bf diff --git a/src/guestfs.pod b/src/guestfs.pod index 91c6b33..c537ae9 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 @@ -1786,6 +1769,20 @@ 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 @@ -2760,6 +2757,97 @@ 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. + +=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