Version 1.2 of ai05s/ai05-0231-1.txt

Unformatted version of ai05s/ai05-0231-1.txt version 1.2
Other versions for file ai05s/ai05-0231-1.txt

!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)
Replace the paragraph:
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).
by:
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 with the given name (in the absence of Name_Error).
!corrigendum A.16(67/2)
Replace the paragraph:
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. 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.
by:
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.
!corrigendum A.16(125/2)
Replace the paragraph:
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.
by:
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).

****************************************************************

Questions? Ask the ACAA Technical Agent