rename, renameat - Dateiname ändern

Definition	#include <stdio.h> int rename(const char *old, const char *new); int renameat(int oldfd, const char *old, int newfd, const char *new);
Beschreibung	rename() ändert den Namen einer Datei. old zeigt auf den Pfadnamen der Datei, die umbenannt werden soll. new zeigt auf den neuen Pfadnamen der Datei. Wenn sowohl old als auch new auf dieselbe existierende Datei verweisen, kehrt die Funktion rename() erfolgreich zurück und führt keine weitere Aktion aus. Wenn old auf den Pfadnamen einer Datei zeigt, die kein Dateiverzeichnis ist, darf new nicht auf den Pfadnamen eines Dateiverzeichnisses zeigen. Wenn der Verweis existiert, der durch das Argument new angegeben wird, wird er entfernt und old wird in new umbenannt. In diesem Fall bleibt ein Verweis new während der umbenannten Operation sichtbar für andere Prozesse und bezieht sich auf die Datei, auf die sich entweder new oder old bezogen hat, bevor die Operation begann. Sowohl für das Dateiverzeichnis, das old enthält, als auch für das Dateiverzeichnis, das new enthält, wird das Schreibrecht benötigt. Wenn old auf den Pfadnamen eines Dateiverzeichnisses zeigt, dann darf new nicht auf den Pfadnamen einer Datei zeigen, die kein Dateiverzeichnis ist. Wenn das Dateiverzeichnis existiert, das durch new angegeben wird, dann wird es entfernt und old wird in new umbenannt. In diesem Fall existiert ein Verweis new während der umbenannten Operation und bezieht sich auf die Datei, auf die sich entweder new oder old bezogen hat, bevor die Operation begann. Wenn daher new ein existierendes Dateiverzeichnis angibt, muss dieses ein leeres Dateiverzeichnis sein. Der Pfadnamen-Anfang von new darf nicht identisch sein mit old. Das Schreibrecht wird sowohl für das Dateiverzeichnis, das old enthält, als auch für das Dateiverzeichnis, das new enthält, benötigt. Wenn old auf den Pfadnamen eines Dateiverzeichnisses zeigt, kann das Schreibrecht für das durch old angegebene Dateiverzeichnis benötigt werden und, falls es existiert, für das Dateiverzeichnis, das durch new angegeben wird. Wenn der Verweis existiert, der durch new angegeben wird, und der Verweiszähler der Datei durch das Entfernen dieser Datei gleich 0 wird und falls außerdem kein Prozess diese Datei geöffnet hat, wird der Platz freigegeben, der durch diese Datei belegt wird, und auf die Datei kann nicht länger zugegriffen werden. Falls einer oder mehrere Prozesse die Datei geöffnet haben, während der letzte Verweis entfernt wird, wird der Verweis entfernt, bevor rename() zurückkehrt, aber die Entfernung der Datei wird aufgeschoben, bis alle Referenzen auf diese Datei geschlossen sind. Bei erfolgreicher Beendigung kennzeichnet rename() die Felder st_ctime und st_mtime des übergeordneten Dateiverzeichnisses jeder der beiden Dateien zum Aktualisieren. BS2000 rename() ist auch auf Dateien mit Satz-Ein-/Ausgabe unverändert anwendbar. (Ende) Die Funktion renameat() ist äquivalent zu der Funktion rename(), außer wenn der Parameter old oder new einen relativen Pfad spezifiziert. Spezifiziert old einen relativen Pfadnamen, wird die Datei, die umbenannt werden soll, nicht im aktuellen Dateiverzeichnis, sondern in dem mit dem Dateideskriptor oldfd verbundenen Dateiverzeichnis gesucht. Spezifiziert new einen relativen Pfad, geschieht das Gleiche relativ zu dem mit dem Dateideskriptor newfd verbundenen Dateiverzeichnis. Wurde ein Dateideskriptor ohne O_SEARCH geöffnet, prüft die Funktion, ob eine Suche im verbundenen Dateiverzeichnis mit den dem Dateiverzeichnis zugrunde liegenden Berechtigungen erlaubt ist. Wurde der Dateideskriptor mit O_SEARCH geöffnet, unterbleibt die Prüfung. Wenn der Funktion renameat() für den Parameter oldfd oder newfd der Wert AT_FDCWD übergeben wird, wird das aktuelle Dateiverzeichnis für die Ermittlung der Datei des entsprechenden Pfades verwendet.
Returnwert	0	bei Erfolg.
	-1	bei Fehler, errno wird gesetzt, um den Fehler anzuzeigen. Keine der durch old oder new benannten Dateien wird geändert oder erzeugt. BS2000 errno wird auf EMACRO gesetzt. Wenn old und new auf Dateien aus verschiedenen Dateisystemen zeigen, wird nichts verändert. errno wird auf EXDEV gesetzt. (Ende)
Fehler	rename() und renameat() schlagen fehl, wenn gilt:
	EACCES	Für eine Komponente eines Pfades existiert kein Suchrecht oder für eines der Dateiverzeichnisse, die old oder new enthalten, existiert kein Schreibrecht; oder das Schreibrecht für eines der Dateiverzeichnisse, auf die old oder new zeigen, wird benötigt, existiert aber nicht.
	EBUSY	Eines der Dateiverzeichnisse die durch old oder new angegeben werden, wird zurzeit durch das System oder einen anderen Prozess verwendet, und die Implementierung nimmt dies als einen Fehler an.
	Erweiterung
	EDQUOT	Das Verzeichnis, in dem sich der Eintrag mit dem neuen Namen befindet, kann nicht erweitert werden, da der Benutzer die Anzahl der zulässigen Blöcke im Dateisystem, in dem sich das Verzeichnis befindet, überschritten hat. (Ende)
	EEXIST oder ENOTEMPTY
		Der Verweis, der durch new angegeben wird, ist ein Dateiverzeichnis, das nicht leer ist.
	Erweiterung
	EFAULT	old oder new zeigen außerhalb des allokierten Adressbereichs des Prozesses.
	EINTR	Während der Ausführung des Systemaufrufs rename() wurde ein Signal empfangen. (Ende)
	EINVAL	Der Dateiverzeichnis-Pfadname new enthält einen Pfadnamen-Anfang, der das Dateiverzeichnis old bezeichnet (siehe auch „Hinweis“).
	Erweiterung
	EIO	Beim Anlegen und Aktualisieren eines Verzeichniseintrags trat ein Ein-/Ausgabe-Fehler auf. (Ende)
	EISDIR	Das Argument new zeigt auf ein Dateiverzeichnis, und das Argument old zeigt auf eine Datei, die kein Dateiverzeichnis ist.
	Erweiterung
	ELOOP	Zu viele symbolische Verweise traten bei der Übersetzung von old oder new auf. (Ende)
	BS2000
	EMACRO	Es existiert keine Datei mit dem Namen old oder es ist bereits eine Datei unter dem Namen new katalogisiert oder die umzubenennende Datei ist durch ein Programm geöffnet. (Ende)
	EMLINK	old zeigt auf ein Dateiverzeichnis, und der Verweiszähler des Dateiverzeichnisses, das new übergeordneten ist, ist größer als {LINK_MAX}.
	ENAMETOOLONG
		Die Länge von old oder new überschreitet {PATH_MAX}, oder eine Komponente des Pfades ist länger als {NAME_MAX}.
	ENOENT	Der Verweis, der durch old bezeichnet wird, existiert nicht, oder old bzw. new zeigt auf eine leere Zeichenkette.
	ENOSPC	Das Dateiverzeichnis, das new enthalten würde, kann nicht erweitert werden.
	ENOTDIR	Eine Komponente des Pfades ist kein Dateiverzeichnis; oder das Argument  old bezeichnet ein Dateiverzeichnis, und das Argument new bezeichnet eine Datei, die kein Dateiverzeichnis ist.
	EROFS	Die angeforderte Operation fordert das Schreiben in ein Dateiverzeichnis, das sich in einem nur zum Lesen eingehängten Dateisystem befindet.
	EXDEV	Die durch new und old bezeichneten Verweise befinden sich in verschiedenen Dateisystemen.
	Zusätzlich schlägt renameat() fehl, wenn gilt:
	EACCES	Der Dateideskriptor oldfd oder newfd wurde nicht mit O_SEARCH geöffnet und die dem Dateiverzeichnis zugrunde liegenden Berechtigungen erlauben nicht das Durchsuchen des Dateiverzeichnisses.
	EBADF	Der Parameter old spezifiziert keinen absoluten Pfadnamen und der Parameter oldfd hat weder den Wert AT_FDCWD, noch enthält er einen gültigen zum Lesen oder Suchen geöffneten Dateideskriptor, oder der Parameter new spezifiziert keinen absoluten Pfadnamen und der Parameter newfd hat weder den Wert AT_FDCWD, noch enthält er einen gültigen zum Lesen oder Suchen geöffneten Dateideskriptor.
	ENOTDIR	Der Parameter old oder new spezifiziert keinen absoluten Pfadnamen und der entsprechende Dateideskriptor oldfd bzw. newfd ist nicht mit einem Dateiverzeichnis verbunden.
Hinweise	Mit rename() kann keine Datei aus POSIX in das BS2000 verlagert werden oder umgekehrt. Zum Beispiel führt die nachstehende Anweisung zum Fehler EINVAL: rename(/BS2/hugo, *POSIX(hugo)) Ob rename() für eine BS2000- oder eine POSIX-Datei ausgeführt wird, hängt von der Programmumgebung ab.
Siehe auch	link(), rmdir(), unlink(), fcntl.h, stdio.h.