!standard A.16(59/2) 10-11-19 AI05-0231-1/02 !standard A.16(67/2) !standard A.16(125/2) !class binding interpretation 10-10-25 !status Amendment 2012 10-11-19 !status ARG Approved 8-0-2 10-10-29 !status work item 10-10-25 !status received 10-07-13 !priority Low !difficulty Easy !qualifier Omission !subject Issues in Ada.Directories !summary Name_Error can be raised by Rename if the New_Name cannot identify a file. If the pattern of a search is malformed, Name_Error is raised, not Use_Error. Use_Error is raised when an attempt to delete non-empty directory with Delete_Directory is made. !question (1) The description of Rename (A.16(67)) says "The exception Name_Error is propagated if the string given as Old_Name does not identify an existing external file", and that Use_Error is raised in other failing cases. However, it should be possible for New_Name to cause a Name_Error also, e.g. (on Unix) Rename ("myfile.txt", "../bakcup_files/myfile.txt"); where ../bakcup_files doesn't exist because it's misspelled (note that AARM A.16(67.a) encourages implementors to support renaming across directories). Raising Use_Error instead of Name_Error in this case is inconsistent with operations like Create_Directory, Copy_File, and Ada.Text_IO.Create. Should this be fixed? (Yes.) (2) A.16(104) says "After a successful call on Start_Search, the object Search may have entries available, but it may have no entries available if no files or directories match Pattern and Filter. The exception Name_Error is propagated if the string given by Directory does not identify an existing directory, or if Pattern does not allow the identification of any possible external file or directory". The last part is the same as "the pattern is malformed". However, A.16(125) says that Start_Search should raise Use_Error if the pattern is malformed. Which is it? (Name_Error). (3) The definition of Delete_Directory says: Deletes an existing empty directory with name Directory. The exception Name_Error is propagated if the string given as Directory does not identify an existing directory. The exception Use_Error is propagated if the external environment does not support the deletion of the directory (or some portion of its contents) with the given name (in the absence of Name_Error). The first sentence makes it clear that the directory must be empty, but the definition doesn't say what is supposed to happen if the directory exists but is not empty. The third sentence may not apply (depending on the target system). What is intended? (Raise Use_Error). !wording Modify A.16(59/2): Deletes an existing empty directory with name Directory. The exception Name_Error is propagated if the string given as Directory does not identify an existing directory. The exception Use_Error is propagated if the {directory is not empty or the} external environment does not support the deletion of the directory [(or some portion of its contents)] with the given name (in the absence of Name_Error). Modify A.16(67/2): Renames an existing external file (including directories) with name Old_Name to New_Name. The exception Name_Error is propagated if the string given as Old_Name does not identify an existing external file{ or if the string given as New_Name does not allow the identification of an external file}. The exception Use_Error is propagated if the external environment does not support the renaming of the file with the given name (in the absence of Name_Error). In particular, Use_Error is propagated if a file or directory already exists with name New_Name. Modify A.16(125/2): Start_Search and Search should raise {Name_Error}[Use_Error] if Pattern is malformed, but not if it could represent a file in the directory but does not actually do so. !discussion For (2), we either need to delete the part about malformed patterns in A.16(104/2) and A.16(112/2), or change the exception in A.16(125/2) to Name_Error. We do the latter because it's a smaller change. For (3), the existing wording clearly was a cut-and-paste of too much text. The wording includes "(or some portion of its contents)" which makes no sense for an empty directory. We drop that wording. !corrigendum A.16(59/2) @drepl @xindent @dby @xindent !corrigendum A.16(67/2) @drepl @xindent @dby @xindent !corrigendum A.16(125/2) @drepl Start_Search and Search should raise Use_Error if Pattern is malformed, but not if it could represent a file in the directory but does not actually do so. @dby Start_Search and Search should raise Name_Error if Pattern is malformed, but not if it could represent a file in the directory but does not actually do so. !ACATS Test No need to change ACATS test for these changes. !ASIS There is no impact on ASIS by these changes. !appendix !topic Errors in Ada.Directories specification !reference A.16 !from Adam Beneschan 10-07-13 !discussion The following are (I think) errors in A.16. (But I understand that these might not be considered important enough to affect RM2012.) (1) The description of Rename (A.16(67)) says "The exception Name_Error is propagated if the string given as Old_Name does not identify an existing external file", and that Use_Error is raised in other failing cases. However, it should be possible for New_Name to cause a Name_Error also, e.g. (on Unix) Rename ("myfile.txt", "../bakcup_files/myfile.txt"); where ../bakcup_files doesn't exist because it's misspelled (note that AARM A.16(67.a) encourages implementors to support renaming across directories). Raising Use_Error instead of Name_Error in this case is inconsistent with operations like Create_Directory, Copy_File, and Ada.Text_IO.Create. I think that the wording ", or if the string given as New_Name does not allow the identification of an external file" (similar to the wording in A.16(69) for Copy_File). (2) A.16(104): "After a successful call on Start_Search, the object Search may have entries available, but it may have no entries avaliable if no files or directories match Pattern and Filter. The exception Name_Error is propagated if the string given by Directory does not identify an existing directory, or if Pattern does not allow the identification of any possible external file or directory". My interpretation is that if Directory exists, but no files in Directory match Pattern, the call is supposed to be successful but More_Entries will return False right away. If that's correct, then the only way "Pattern does not allow the identification of any possible external file or directlry" could be true is if Pattern itself is malformed. However, A.16(125) says that Start_Search should raise Use_Error if the pattern is malformed. So it seems like there's a contradiction in the RM; at any rate, it's confusing. Assuming Directory names an existing directory, under what circumstances would Start_Search raise Name_Error? Are there any? **************************************************************** !topic Omission in Ada.Directories.Delete_Directory definition !reference A.16(58/2) !from Adam Beneschan 10-10-05 !discussion The definition of Delete_Directory says: Deletes an existing empty directory with name Directory. The exception Name_Error is propagated if the string given as Directory does not identify an existing directory. The exception Use_Error is propagated if the external environment does not support the deletion of the directory (or some portion of its contents) with the given name (in the absence of Name_Error). The first sentence makes it clear that the directory must be empty, but the definition doesn't say what is supposed to happen if the directory exists but is not empty. Clearly the second sentence doesn't apply. It's not clear that the third sentence applies either. (On Unix, for instance, rmdir() won't delete a nonempty directory, but that doesn't mean that the external environment "doesn't support" such a deletion; you could certainly delete it in other ways, e.g. by spawning an "rm -rf" command.) And other systems may have system calls that wipe out entire directories along with all their contents. I think the intent is that Use_Error should be raised, but the definition should say so: Deletes an existing empty directory with name Directory. The exception Name_Error is propagated if the string given as Directory does not identify an existing directory. The exception Use_Error is propagated if Directory identifies an existing directory that is not empty, or if the external environment does not support the deletion of the directory (or some portion of its contents) with the given name (in the absence of Name_Error). ****************************************************************