{{page>en:templates:dosint}}

====== Int 21H, AH=56H ======

===== Version =====

2 and higher

===== Brief =====

"RENAME" - RENAME FILE

===== Family API =====


===== Input =====

	AH = 56h
	DS:DX -> ASCIZ filename of existing file (no wildcards, but see below)
	ES:DI -> ASCIZ new filename (no wildcards)
	CL = attribute mask (server call only, see below)

===== Return =====

  CF clear if successful
	CF set on error
	    AX = error code (02h,03h,05h,11h) (see #01680)

===== Notes =====

allows move between directories on same logical volume

this function does not set the archive attribute (see #01420 at AX=4301h), which results in incremental backups not backing up the file under its new name

open files should not be renamed

(DOS 2.x only) this function renames file by creating a new directory entry with the new name, then marking the old entry deleted

(DOS 3.0+) allows renaming of directories

(DOS 3.1+) wildcards are allowed if invoked via AX=5D00h, in which case error 12h (no more files) is returned on success, and both source and destination specs must be canonical (as returned by AH=60h). Wildcards in the destination are replaced by the corresponding char of each source file being renamed.  Under DOS 3.x, the call will fail if the destination wildcard is *.* or equivalent; under DR DOS 5.0, the call will fail with error code 03h if any wildcards are used. When invoked via AX=5D00h, only those files matching the attribute mask in CL are renamed.

under the FlashTek X-32 DOS extender, the old-name pointer is in DS:EDX and the new-name pointer is in ES:EDI (DS must equal ES)

BUG: (DR DOS 3.41) when invoked via AX=5D00h, this function will generate a new directory entry with the new name (including any wildcards) which can only be removed with a sector editor
          
===== See also =====

AH=[[en:docs:dos:api:int21:17|17h]],AX=[[en:docs:dos:api:int21:43:01|4301h]],AX=[[en:docs:dos:api:int21:43:ff|43FFh]]/BP=5053h,AX=[[en:docs:dos:api:int21:5d:00|5D00h]],AH=[[en:docs:dos:api:int21:60|60h]],AX=[[en:docs:dos:api:int21:71:56|7156h]]

===== Note =====

Text based on [[http://www.cs.cmu.edu/~ralf/files.html|Ralf Brown Interrupt List Release 61]]

{{page>en:templates:int}}

{{page>en:templates:fapi}}