From 12e0e3fb0948d9e2975f2bfa596d068d83b717fa Mon Sep 17 00:00:00 2001
From: Matthew Booth <mbooth@redhat.com>
Date: Tue, 29 Oct 2013 13:27:30 +0000
Subject: [PATCH] docs: guestfs_case_sensitive_path returns error on
 non-existent path

---
 generator/actions.ml | 31 +++++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/generator/actions.ml b/generator/actions.ml
index c73a319be..cb6d137f1 100644
--- a/generator/actions.ml
+++ b/generator/actions.ml
@@ -7150,13 +7150,32 @@ a problem.
 Bug or feature?  You decide:
 L<http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
 
-This function resolves the true case of each element in the
-path and returns the case-sensitive path.
+C<guestfs_case_sensitive_path> attempts to resolve the true case of
+each element in the path. It will return a resolved path if either the
+full path or its parent directory exists. If the parent directory
+exists but the full path does not, the case of the parent directory
+will be correctly resolved, and the remainder appended unmodified. For
+example, if the file C<\"/Windows/System32/netkvm.sys\"> exists:
 
-Thus C<guestfs_case_sensitive_path> (\"/Windows/System32\")
-might return C<\"/WINDOWS/system32\"> (the exact return value
-would depend on details of how the directories were originally
-created under Windows).
+=over 4
+
+=item C<guestfs_case_sensitive_path> (\"/windows/system32/netkvm.sys\")
+
+\"Windows/System32/netkvm.sys\"
+
+=item C<guestfs_case_sensitive_path> (\"/windows/system32/NoSuchFile\")
+
+\"Windows/System32/NoSuchFile\"
+
+=item C<guestfs_case_sensitive_path> (\"/windows/system33/netkvm.sys\")
+
+I<ERROR>
+
+=back
+
+I<Note>:
+Because of the above behaviour, C<guestfs_case_sensitive_path> cannot
+be used to check for the existence of a file.
 
 I<Note>:
 This function does not handle drive names, backslashes etc.