rename, _wrename

Renomeie um arquivo ou diretório.

Sintaxe

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

Parâmetros

oldname
Ponteiro para o nome antigo.

newname
Ponteiro para o novo nome.

Retornar valor

Cada uma dessas funções retornará 0 se for bem-sucedida. Em caso de erro, a função retorna um valor diferente de zero e define errno para um dos seguintes valores:

errno valor	Condição
EACCES	Arquivo ou diretório especificado por newname já existe ou não pôde ser criado (caminho inválido) ou oldname é um diretório e newname especifica um caminho diferente.
ENOENT	O arquivo ou caminho especificado por oldnamenão foi encontrado.
EINVAL	Nome contém caracteres inválidos.

Para outros possíveis valores retornados, confira _doserrno, _errno, syserrlist e _sys_nerr.

Comentários

A função rename renomeia o arquivo ou o diretório especificado por oldname para o nome fornecido por newname. O nome antigo deve ser o caminho de um arquivo ou diretório existente. O novo nome não pode ser o nome de um arquivo ou diretório existente. Você pode usar rename para mover um arquivo de um diretório ou dispositivo para outro fornecendo um caminho diferente no argumento newname. No entanto, você não pode usar rename para mover um diretório. Diretórios podem ser renomeados, mas não movidos.

_wrename é uma versão de caractere largo de _rename; os argumentos para _wrename são cadeias de caracteres largas. Caso contrário, _wrename e _rename se comportam de forma idêntica.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_trename	rename	rename	_wrename

Requisitos

Rotina	Cabeçalho necessário
rename	<io.h> ou <stdio.h>
_wrename	<stdio.h> ou <wchar.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Bibliotecas

Todas as versões das bibliotecas em tempo de execução C.

Exemplo

// 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 );
}

Saída

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

Confira também

Manipulação de arquivos