AI22-0108-1

!standard A.16(126/2)                                    24-08-07  AI22-0108-1/03

!class Binding Interpretation  24-06-13

!status Revision-202Y  24-07-18

!status WG9 Approved 24-10-10

!status ARG Approved  8-0-1  24-07-18

!status work item 24-06-13

!status received 24-06-13

!priority Low

!difficulty Easy

!qualifier Clarification

!subject Usage Advice about File Renaming

!summary

Improve the advice on how to portably move a file using Ada.Directories.

!issue

AI22-0055-1 moved A.16 (131/5) to be Usage rather than a Note. But the explanation of that advice is given in AARM A.16(131.a/2-131.b). That explanation should be part of the advice.

!recommendation

Add the last sentence of (131.a/2) starting with „To move a file“ and (131.b) to the RM itself.

!wording

Add after the new paragraph after A.16(126/2):

To move a file totally portably, it's necessary to handle failure of the Rename and fall back to Copy_File and Delete:

begin                                               
   Rename (Source, Target);
exception
   when Use_Error =>
      Copy_File (Source, Target);
      Delete (Source);
end;

Modify A.16 (131.a/2):

Discussion: While Rename is only guaranteed to work for name changes within a single directory, it{'}s unlikely that implementers would purposely prevent functionality present in the underlying system from working. [To move a file totally portably, it's necessary to handle failure of the Rename and fall back to Copy_File and Delete:]

Delete AARM A.16(131.b):

begin                                               
   Rename (Source, Target);
exception
   when Use_Error =>
      Copy_File (Source, Target);
      Delete (Source);
end;

!discussion

This is part of the creation of the new RM header Usage by AI22-0055-1 and AI22-0097-1.

!corrigendum A.16(126/2)

@dinsa

Rename should be supported at least when both New_Name and Old_Name are simple

names and New_Name does not identify an existing external file.

@dinst

@s8{@i{Usage}}

To move a file or directory to a different location, use Rename. Most target

systems will allow renaming of files from one directory to another. If the

target file or directory can already exist, it should be deleted first.

To move a file totally portably, it's necessary to handle failure of the Rename

and fall back to Copy_File and Delete:

@xcode{@b{begin}

   Rename (Source, Target);

@b{exception}

   @b{when} Use_Error =>

          Copy_File (Source, Target);

          Delete (Source);

@b{end};}

!ACATS test

None needed, only wording rearranged.

!appendix

This AI follows a recommendation by Randy Brukardt.