rename, _wrename

Cambia el nombre de un archivo o de un directorio.

Sintaxis

int rename(
   const char *oldname,
   const char *newname
);
int _wrename(
   const wchar_t *oldname,
   const wchar_t *newname
);

Parámetros

oldname
Puntero al nombre anterior.

newname
Puntero al nombre nuevo.

Valor devuelto

Cada una de estas funciones devuelve 0 si se realiza correctamente. Si se produce un error, la función devuelve un valor distinto de cero y establece errno en uno de los siguientes valores:

Valor de errno	Condición
EACCES	El archivo o directorio especificado por newname ya existe o no se pudo crear (ruta de acceso no válida); o oldname es un directorio y newname especifica una ruta de acceso diferente.
ENOENT	No se ha encontrado el archivo o la ruta de acceso que especifica oldname.
EINVAL	El nombre contiene caracteres no válidos.

Para conocer otros valores devueltos posibles, vea _doserrno, _errno, syserrlist y _sys_nerr.

Comentarios

La función rename cambia el nombre del archivo o directorio que oldname especifica por el nombre proporcionado por newname. El nombre anterior debe ser la ruta de acceso de un archivo o directorio existente. El nombre nuevo no debe ser el nombre de un archivo o directorio existente. Puede usar rename para mover un archivo de un directorio o dispositivo a otro mediante la indicación de una ruta de acceso diferente en el argumento newname. Sin embargo, no puede usar rename para mover un directorio. Se puede cambiar el nombre de los directorios, pero estos no se pueden mover.

_wrename es una versión con caracteres anchos de _rename; los argumentos a _wrename son cadenas de caracteres anchos. Por lo demás,_wrename y _rename se comportan de forma idéntica.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_trename	rename	rename	_wrename

Requisitos

Routine	Encabezado necesario
rename	<io.h> o <stdio.h>
_wrename	<stdio.h> o <wchar.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Bibliotecas

Todas las versiones de las bibliotecas en tiempo de ejecución de C.

Ejemplo

// crt_renamer.c
/* This program attempts to rename a file named
* CRT_RENAMER.OBJ to CRT_RENAMER.JBO. For this operation
* to succeed, a file named CRT_RENAMER.OBJ must exist and
* a file named CRT_RENAMER.JBO must not exist.
*/

#include <stdio.h>

int main( void )
{
   int  result;
   char old[] = "CRT_RENAMER.OBJ", new[] = "CRT_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 );
}

Salida

File 'CRT_RENAMER.OBJ' renamed to 'CRT_RENAMER.JBO'

Consulte también

Control de archivos