io.files: document potential if-file-exists race condition

diff --git a/core/io/files/files-docs.factor b/core/io/files/files-docs.factor
index e3b54ada9e0f6aead4317f5302d98e547065099a..774c1b784dccdaefcd5ea77a6ade91a2005cd97f 100644 (file)
--- a/core/io/files/files-docs.factor
+++ b/core/io/files/files-docs.factor
@@ -117,14 +117,17 @@ HELP: file-exists?
 
 HELP: if-file-exists
 { $values { "path" "a pathname string" } { "true" { $quotation ( ..a path -- ..b ) } } { "false" { $quotation ( ..a path -- ..b ) } } }
-{ $description "If " { $snippet "path" } " is a file that exists, calls the " { $snippet "true" } " quotation, otherwise calls the " { $snippet "false" } " quotation." } ;
+{ $description "If " { $snippet "path" } " is a file that exists, calls the " { $snippet "true" } " quotation, otherwise calls the " { $snippet "false" } " quotation." }
+{ $notes "It is possible for the file to be created or deleted after the call to " { $link file-exists? } " but before running " { $snippet "true" } " or " { $snippet "false" } ". If that is a concern, you might want to open the file for reading or writing, as needed." } ;
 
 HELP: when-file-exists
 { $values { "path" "a pathname string" } { "quot" { $quotation ( ... path -- ... ) } } }
-{ $description "If " { $snippet "path" } " is a file that exists, calls the " { $snippet "quot" } " quotation." } ;
+{ $description "If " { $snippet "path" } " is a file that exists, calls the " { $snippet "quot" } " quotation." }
+{ $notes "It is possible for the file to be created or deleted after the call to " { $link file-exists? } " but before running " { $snippet "quot" } ". If that is a concern, you might want to open the file for reading or writing, as needed." } ;
 
 HELP: unless-file-exists
 { $values { "path" "a pathname string" } { "quot" { $quotation ( ... path -- ... ) } } }
-{ $description "If " { $snippet "path" } " is a file that does not exist, calls the " { $snippet "quot" } " quotation." } ;
+{ $description "If " { $snippet "path" } " is a file that does not exist, calls the " { $snippet "quot" } " quotation." }
+{ $notes "It is possible for the file to be created or deleted after the call to " { $link file-exists? } " but before running " { $snippet "quot" } ". If that is a concern, you might want to open the file for reading or writing, as needed." } ;
 
 { if-file-exists when-file-exists unless-file-exists } related-words