====== rename() ======

''rename()'' ist definiert in der ''[[start|stdio]]'', die in C über ''stdio.h'', bzw. in C++ über ''cstdio'' eingebunden wird.


===== Funktion =====
''rename()'' gibt einer Datei einen neuen Namen, bzw. verschiebt sie in ein anderes Verzeichnis.
Abhängig vom Betriebssystem wird eine eventuell bereits existierende Datei überschrieben, wenn der Name der Datei als neuer Dateiname angegeben wird oder es wird ein Fehler zurückgeliefert.

===== Signatur =====

<code cpp>
#include <stdio.h>
int rename( char const * oldName, char const * newName );</code>

**oldName**: Die umzubenennende Datei. Die Datei muss entsprechend der Betriebssystemvorgaben beschrieben sein und darf einen Pfad enthalten, sofern das Betriebssystem Pfade unterstützt. \\
**newName**: Der neue Name der Datei. Die Datei kann - sofern das Betriebssystem es unterstützt - gleichzeitig in ein anderes Verzeichnis verschoben werden.

**Return Value**: Bei Erfolg wird 0 zurückgegeben. Ist der Wert ungleich 0, so muss ''[[c:lib:errno:errno|errno]]'' ausgelesen werden.

===== Fehlerquellen =====

Häufig werden Pfade im falschen Format angegeben, zum Beispiel Unix-Pfade (''/home/user/file.txt'') statt eines Windows-Pfads (''C:\Directory\file.txt'').\\ 
Bei Windowspfaden wird häufig vergessen, dass ein Backslash ('\') in C doppelt geschrieben werden muss, also beispielsweise (''char * filename = "C:\\Directory\\file.txt"'')

Da die Funktion Betriebssystemabhängigkeiten hat, sollte zunächst überprüft werden, ob bereits eine Datei unter dem neuen Dateinamen existiert, um sicher zu stellen, dass sie nicht versehentlich überschrieben wird. Für den Fall, dass sie überschrieben werden sollte, muss sie zuerst per ''[[remove()]]'' gelöscht werden.

===== Beispiel =====

<code cpp>
#include <stdlib.h>
#include <stdio.h>

int main( void )
{
  char const * oldName = "old.txt";
  char const * newName = "new.txt";

  if( !rename( oldName, newName ) )
    printf( "Datei '%s' wurde in '%s' umbenannt.\n", oldName, newName );
  else
    printf( "Datei '%s' konnte nicht in '%s' umbenannt werden.\n", oldName, newName );

  return EXIT_SUCCESS; 
}
</code>

**Ausgabe**:\\ 
Abhängig davon, ob die Datei 'old.txt' existierte (und wir die notwendigen Rechte haben, sie zu modifizieren und sie unter dem neuen Namen anzulegen) wird der entsprechende Satz geschrieben.

===== siehe auch =====

[[c:lib:stdio:start|stdio]]: [[c:lib:stdio:printf()]], [[c:lib:stdio:remove()]]