rename, _wrename
Rename a file or directory.
 
int rename( const char *oldname, const char *newname );
 
int _wrename( const wchar_t *oldname, const wchar_t *newname );
 
Routine Required Header Compatibility  
rename <io.h> or <stdio.h> ANSI, Win 95, Win NT  
_wrename <stdio.h> or <wchar.h> Win NT  
 
 
For additional compatibility information, see Compatibility in the Introduction.
 
Libraries
 
LIBC.LIB Single thread static library, retail version  
LIBCMT.LIB Multithread static library, retail version  
MSVCRT.LIB Import library for MSVCRT.DLL, retail version  
 
 
Return Value
 
Each of these functions returns 0 if it is successful. On an error, the function  returns a nonzero value and sets errno to one of the following values:
 
EACCES
 
File or directory specified by newname already exists or could not be created (invalid path); or oldname is a directory and newname specifies a different path.
 
ENOENT
 
File or path specified by oldname not found.
 
EINVAL
 
Name contains invalid characters.
 
For other possible return values, see _doserrno, _errno, syserrlist, and _sys_nerr.
 
 
Parameters
 
oldname
 
Pointer to old name
 
newname
 
Pointer to new name
 
Remarks
 
The rename function renames the file or directory specified by oldname to the name given by newname. The old name must be the path of an existing file or directory. The new name must not be the name of an existing file or directory. You can use rename to move a file from one directory or device to another by giving a different path in the newname argument. However, you cannot use rename to move a directory. Directories can be renamed, but not moved.
 
_wrename is a wide-character version of _rename; the arguments to _wrename are wide-character strings. _wrename and _rename behave identically otherwise.
 
Generic-Text Routine Mappings
 
TCHAR.H Routine  _UNICODE & _MBCS Not Defined _MBCS Defined _UNICODE Defined  
_trename rename rename _wrename  
 
 
Example
 
/* RENAMER.C: This program attempts to rename a file
 * named RENAMER.OBJ to RENAMER.JBO. For this operation
 * to succeed, a file named RENAMER.OBJ must exist and
 * a file named RENAMER.JBO must not exist.
 */
 
#include <stdio.h>
 
void main( void )
{
   int  result;
   char old[] = "RENAMER.OBJ", new[] = "RENAMER.JBO";
 
   /* Attempt to rename file: */
   result = rename( old, new );
   if( result != 0 )
      printf( "Could not rename '%s'\n", old );
   else
      printf( "File '%s' renamed to '%s'\n", old, new );
}
 
 
Output
 
File 'RENAMER.OBJ' renamed to 'RENAMER.JBO'
 
 
File Handling Routines