X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;ds=inline;f=src%2Fguestfs.pod;h=7d2f91c81ffee9831a405d7930d23100594e2155;hb=acd25281bfa31b78fd03e25b495f66138a4dd987;hp=9cf66f3c6d88aa259102b089457666c1fc047a4c;hpb=df5ae67129dcbb16e2437b65b4557dfe73c1782d;p=libguestfs.git

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 9cf66f3..7d2f91c 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -334,6 +334,27 @@ Use L</guestfs_download>.  See L</DOWNLOADING> above.
 
 =back
 
+=head2 UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
+
+Calls like L</guestfs_upload>, L</guestfs_download>,
+L</guestfs_tar_in>, L</guestfs_tar_out> etc appear to only take
+filenames as arguments, so it appears you can only upload and download
+to files.  However many Un*x-like hosts let you use the special device
+files C</dev/stdin>, C</dev/stdout>, C</dev/stderr> and C</dev/fd/N>
+to read and write from stdin, stdout, stderr, and arbitrary file
+descriptor N.
+
+For example, L<virt-cat(1)> writes its output to stdout by
+doing:
+
+ guestfs_download (filename, "/dev/stdout");
+
+and you can write tar output to a pipe C<fd> by doing:
+
+ char devfd[64];
+ snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
+ guestfs_tar_out ("/", devfd);
+
 =head2 LISTING FILES
 
 L</guestfs_ll> is just designed for humans to read (mainly when using
@@ -587,6 +608,8 @@ documentation for that function for details).
 Libguestfs can mount NTFS partitions.  It does this using the
 L<http://www.ntfs-3g.org/> driver.
 
+=head3 DRIVE LETTERS AND PATHS
+
 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
@@ -604,6 +627,8 @@ 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 L</guestfs_case_sensitive_path>.
 
+=head3 ACCESSING THE WINDOWS REGISTRY
+
 Libguestfs also provides some help for decoding Windows Registry
 "hive" files, through the library C<hivex> which is part of the
 libguestfs project although ships as a separate tarball.  You have to
@@ -612,6 +637,33 @@ C<hivex> functions.  See also the programs L<hivexml(1)>,
 L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-reg(1)> for more help
 on this issue.
 
+=head3 SYMLINKS ON NTFS-3G FILESYSTEMS
+
+Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links"
+to provide something which looks like a Linux symlink.  The way it
+tries to do the rewriting is described here:
+
+L<http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/>
+
+The essential problem is that ntfs-3g simply does not have enough
+information to do a correct job.  NTFS links can contain drive letters
+and references to external device GUIDs that ntfs-3g has no way of
+resolving.  It is almost certainly the case that libguestfs callers
+should ignore what ntfs-3g does (ie. don't use L</guestfs_readlink> on
+NTFS volumes).
+
+Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
+L</guestfs_lgetxattr> to read the C<system.ntfs_reparse_data> extended
+attribute, and read the raw reparse data from that (you can find the
+format documented in various places around the web).
+
+=head3 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
+
+There are other useful extended attributes that can be read from
+ntfs-3g filesystems (using L</guestfs_getxattr>).  See:
+
+L<http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/>
+
 =head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
 
 Although we don't want to discourage you from using the C API, we will