Mac OS X: Fix HAVE_GNU_CALLOC so it works when __GLIBC__ is not defined.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 84eec63..d005257 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -33,7 +33,8 @@ 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
 
 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 access filesystems over FTP.
+in the context of the guest.  Also you can access filesystems over
+FUSE.

 
 Libguestfs is a library that can be linked with C and C++ management
 programs (or management programs written in OCaml, Perl, Python, Ruby,
 
 Libguestfs is a library that can be linked with C and C++ management
 programs (or management programs written in OCaml, Perl, Python, Ruby,


@@ -449,10 +450,10 @@ Where we can help is in resolving the case insensitivity of paths.
 For this, call C<guestfs_case_sensitive_path>.
 
 Libguestfs also provides some help for decoding Windows Registry
 For this, call C<guestfs_case_sensitive_path>.
 
 Libguestfs also provides some help for decoding Windows Registry

-"hive" files, through the library C<libhivex> which is part of
-libguestfs.  You have to locate and download the hive file(s)
-yourself, and then pass them to C<libhivex> functions.  See also the
-programs L<hivexml(1)>, L<hivexget(1)> and L<virt-win-reg(1)> for more
+"hive" files, through the library C<hivex> which is part of the
+libguestfs project.  You have to locate and download the hive file(s)
+yourself, and then pass them to C<hivex> functions.  See also the
+programs L<hivexml(1)>, L<hivexsh(1)> and L<virt-win-reg(1)> for more

 help on this issue.
 
 =head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
 help on this issue.
 
 =head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES


@@ -558,6 +559,15 @@ Note that in L<guestfish(3)> I<autosync is the default>.  So quick and
 dirty guestfish scripts that forget to sync will work just fine, which
 can make this extra-puzzling if you are trying to debug a problem.
 
 dirty guestfish scripts that forget to sync will work just fine, which
 can make this extra-puzzling if you are trying to debug a problem.
 

+=item Mount option C<-o sync> should not be the default.
+
+If you use C<guestfs_mount>, then C<-o sync,noatime> are added
+implicitly.  However C<-o sync> does not add any reliability benefit,
+but does have a very large performance impact.
+
+The work around is to use C<guestfs_mount_options> and set the mount
+options that you actually want to use.
+

 =item Read-only should be the default.
 
 In L<guestfish(3)>, I<--ro> should be the default, and you should
 =item Read-only should be the default.
 
 In L<guestfish(3)>, I<--ro> should be the default, and you should


@@ -579,6 +589,29 @@ C<guestfish -c command> to run commands.
 
 =back
 
 
 =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</INTERNALS>
+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 C<guestfs_cat> 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</UPLOADING> and L</DOWNLOADING> document how to do this.
+
+You might also consider mounting the disk image using our FUSE
+filesystem support (L<guestmount(1)>).
+

 =head1 CONNECTION MANAGEMENT
 
 =head2 guestfs_h *
 =head1 CONNECTION MANAGEMENT
 
 =head2 guestfs_h *


@@ -774,7 +807,7 @@ need the compile time check as well):
    dl = dlopen (NULL, RTLD_LAZY);
    if (!dl) {
      fprintf (stderr, "dlopen: %s\n", dlerror ());
    dl = dlopen (NULL, RTLD_LAZY);
    if (!dl) {
      fprintf (stderr, "dlopen: %s\n", dlerror ());

-     exit (1);
+     exit (EXIT_FAILURE);

    }
    has_function = dlsym (dl, "guestfs_dd") != NULL;
    dlclose (dl);
    }
    has_function = dlsym (dl, "guestfs_dd") != NULL;
    dlclose (dl);