rename, renameat, renameat2 - den Namen oder die Lage einer Datei
ändern
ÜBERSICHT
#include <stdio.h>
int rename(const char *oldpath, const char *newpath);
#include <fcntl.h> /* Definition der AT_*-Konstanten */
#include <stdio.h>
int renameat(int olddirfd, const char *oldpath,
int newdirfd, const char *newpath);
int renameat2(int olddirfd, const char *oldpath,
int newdirfd, const char *newpath, unsigned int flags);
Hinweis: Es gibt keinen Glibc-Wrapper für
renameat2(); siehe ANMERKUNGEN.
Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):
renameat():
rename() benennt eine Datei um und verschiebt sie in ein
anderes Verzeichnis, wenn nötig. Alle anderen Hard Links (erstellt
mittels link(2)) sind nicht betroffen, ebenso offene
Dateideskriptoren für oldpath.
Verschiedene Einschränkungen bestimmen, ob die
Umbenennungsaktion erfolgreich ist oder nicht; siehe FEHLER unten.
Falls newpath schon existiert, wird er in einem atomaren
Schritt überschrieben, so dass ein anderer Prozess jederzeit auf
newpath zugreifen kann. Allerdings wird es wahrscheinlich ein Fenster
geben, in dem sowohl oldpath als auch newpath sich auf die
umzubenennende Datei beziehen.
Falls oldpath und newpath bestehende Hard Links zu
derselben Datei sind, tut rename() nichts und meldet eine
erfolgreiche Ausführung.
Wenn newpath schon existiert, aber das Umbenennen aus
irgendeinem Grund fehlschlägt, garantiert rename(), dass
newpath an Ort und Stelle erhalten bleibt.
oldpath kann ein Verzeichnis angeben. In diesem Fall darf
newpath nicht existieren oder muss ein leeres Verzeichnis
angeben.
Falls oldpath auf einen symbolischen Link zeigt, wird der
Link umbenannt; falls newpath auf einen symbolischen Link zeigt, wird
der Link überschrieben.
Der Systemaufruf renameat() funktioniert genauso wie
rename(), außer den hier beschriebenen Unterschieden.
Falls der in oldpath übergebene Pfadname relativ ist
wird er als relativ zu dem im Dateideskriptor olddirfd referenzierten
Verzeichnis interpretiert (statt relativ zum aktuellen Arbeitsverzeichnis
des aufrufenden Prozesses, wie es bei rename() für einen
relativen Pfadnamen erfolgt).
Falls oldpath relativ ist und olddirfd den
besonderen Wert AT_FDCWD annimmt wird oldpath als relativ zum
aktuellen Arbeitsverzeichnis des aufrufenden Prozesses interpretiert (wie
rename()).
Falls oldpath absolut ist wird olddirfd
ignoriert.
Die Interpretation von newpath ist wie bei oldpath,
außer dass ein relativer Pfadname als relativ zu dem Verzeichnis
interpretiert wird, auf das der Dateideskriptor newdirfd
verweist.
Lesen Sie openat(2) für eine Beschreibung der
Notwendigkeit von renameat().
renameat2() hat ein zusätzliches Argument
flags. Ein Aufruf von renameat2() mit einem leeren Argument
flags ist äquivalent zu renameat().
Das Argument flags ist eine Bitmaske, die aus null oder
mehr der folgenden Schalter besteht:
- RENAME_EXCHANGE
- tauscht oldpath und newpath atomisch aus. Beide Pfadnamen
müssen existieren, können aber verschiedenen Typs sein.
Beispielsweise kann ein Pfad ein nicht-leeres Verzeichnis und der andere
ein symbolischer Link sein.
- RENAME_NOREPLACE
- überschreibt newpath beim Umbenennen nicht. Ein Fehler wird
zurückgegeben, wenn newpath bereits existiert.
- RENAME_NOREPLACE kann nicht zusammen mit RENAME_EXCHANGE
eingesetzt werden.
- RENAME_WHITEOUT
(seit Linux 3.18)
- This operation makes sense only for overlay/union filesystem
implementations.
- Durch Angabe von RENAME_WHITEOUT wird ein
»whiteout«-Objekt bei der Quelle der Umbenennung zum
gleichen Zeitpunkt der Durchführung der Umbenennung erzeugt. Die
gesamte Aktion ist atomar, so dass der Whiteout erstellt sein wird, wenn
die Umbenennung erfolgreich war.
- A "whiteout" is an object that has special meaning in
union/overlay filesystem constructs. In these constructs, multiple layers
exist and only the top one is ever modified. A whiteout on an upper layer
will effectively hide a matching file in the lower layer, making it appear
as if the file didn't exist.
- Wenn eine Datei auf einer unteren Ebene umbenannt wird, wird die Datei
zuerst hochkopiert (falls sie nicht bereits auf der oberen Ebene ist) und
dann auf der oberen, lese-schreibbaren Ebene umbenannt. Gleichzeitig muss
die Quelldatei »whiteouted« werden (so dass die Version der
Quelldatei in der unteren Ebene unsichtbar gemacht wird). Die gesamte
Aktion muss atomar sein.
- When not part of a union/overlay, the whiteout appears as a character
device with a {0,0} device number.
- RENAME_WHITEOUT benötigt die gleichen Privilegien wie zum
Erstellen eines Geräteknotens (d.h. die Capability
CAP_MKNOD).
- RENAME_WHITEOUT kann nicht zusammen mit RENAME_EXCHANGE
eingesetzt werden.
- RENAME_WHITEOUT benötigt die Unterstützung vom
darunterliegenden Dateisystem. Unter den Dateisystemen, die die
Unterstützung anbieten, sind Shmem (seit Linux 3.18), Ext4 (seit
Linux 3.18) und XFS (seit Linux 4.1).
Bei Erfolg wird Null zurückgegeben. Bei einem Fehler wird
-1 zurückgegeben und errno entsprechend gesetzt.
- EACCES
- Für das Verzeichnis, das oldpath oder newpath
enthält, wurden Schreibrechte verweigert oder für eines der
Verzeichnisse im Pfad-Präfix von oldpath oder newpath
wurde nicht gestattet, dort zu suchen oder oldpath ist ein
Verzeichnis und verwehrt die Schreiberlaubnis (benötigt, um den
Eintrag .. zu aktualisieren). (Siehe auch
path_resolution(7).)
- EBUSY
- Das Umbenennen scheitert, weil oldpath oder newpath ein
Verzeichnis ist, das von einem anderen Prozess (vielleicht als aktuelles
Arbeitsverzeichnis oder als Root-Verzeichnis oder weil es zum Lesen
geöffnet ist) oder vom System genutzt wird (zum Beispiel als
Einhängepunkt) und das System dies als Fehler betrachtet. (Beachten
Sie, dass es keine Verpflichtung gibt, in solchen Fällen
EBUSY zurückzugeben – es ist nichts falsch daran, die
Umbenennung trotzdem durchzuführen – aber es ist erlaubt,
EBUSY zurückzugeben, wenn das System solche Situationen
nicht anderweitig verarbeiten kann.)
- EDQUOT
- Das Quota (Plattenkontingent) des Benutzers an Plattenblöcken auf
dem Dateisystem ist erschöpft.
- EFAULT
- alterpfad oder neuerpfad zeigt aus dem für Sie
zugänglichen Adressraum heraus.
- EINVAL
- Der neue Pfadname enthielt ein Pfad-Präfix des alten, oder
allgemeiner, es wurde versucht, ein Verzeichnis als Unterverzeichnis von
sich selbst zu erzeugen.
- EISDIR
- newpath ist ein existierendes Verzeichnis, aber oldpath ist
kein Verzeichnis.
- ELOOP
- Bei der Auflösung von oldpath oder newpath wurden zu
viele symbolische Links gefunden.
- EMLINK
- oldpath hat schon die maximale Anzahl Links, oder es war ein
Verzeichnis und das Verzeichnis, welches newpath enthält,
hat schon die maximale Anzahl Links.
- ENAMETOOLONG
- oldpath oder newpath war zu lang.
- ENOENT
- Der von oldpath angegebene Link existiert nicht oder eine
Verzeichniskomponente von newpath existiert nicht oder
oldpath oder newpath ist eine leere Zeichenkette.
- ENOMEM
- Es war nicht genügend Kernelspeicher verfügbar.
- ENOSPC
- Das Gerät, das die die Datei enthält, hat keinen Platz
für einen neuen Verzeichniseintrag.
- ENOTDIR
- Eine als Verzeichnis benutzte Komponente von oldpath oder
newpath ist in der Tat kein Verzeichnis. Oder oldpath ist
ein Verzeichnis und newpath existiert, ist aber kein
Verzeichnis.
- ENOTEMPTY
oder EEXIST
- newpath ist ein nicht leeres Verzeichnis, d.h. es enthält
außer ».« und »..« weitere
Einträge.
- EPERM oder
EACCES
- Das Verzeichnis, das oldpath enthält, hat das Sticky-Bit
(S_ISVTX) gesetzt und die effektive Benutzerkennung des Prozesses
ist weder die Benutzerkennung der zu löschenden Datei noch die des
beinhaltenden Verzeichnisses und der Prozess ist nicht privilegiert
(Linux: verfügt nicht über die
CAP_FOWNER-Capability); oder newpath ist eine vorhandene
Datei und ihr übergeordnetes Verzeichnis hat das Sticky-Bit gesetzt
und die effektive Benutzerkennung des Prozesses ist weder die
Benutzerkennung der zu ersetzenden Datei noch des beherbergenden
Verzeichnisses und der Prozess ist nicht privilegiert (Linux:
verfügt nicht über die CAP_FOWNER-Capability) oder
das pathname beherbergende Dateisystem unterstützt nicht die
Umbenennung des angeforderten Typs.
- EROFS
- Die Datei befindet sich auf einem nur lesbaren Dateisystem.
- EXDEV
- oldpath und newpath befinden sich nicht auf demselben
eingehängten Dateisystem. (Linux erlaubt es Dateisystemen, an
mehreren Stellen eingehängt zu sein, aber rename()
funktioniert nicht über verschiedene Einhängepunkte hinweg,
selbst falls dasselbe Dateisystem an beiden Stellen eingehängt
ist.)
Die folgenden zusätzlichen Fehler können bei
renameat() und renameat2() auftreten:
- EBADF
- olddirfd oder newdirfd ist kein zulässiger
Dateideskriptor.
- ENOTDIR
- oldpath ist relativ und olddirfd ist ein Dateideskriptor,
der sich auf eine Datei bezieht, die kein Verzeichnis ist; gilt analog
für newpath and newdirfd.
Die folgenden zusätzlichen Fehler können bei
renameat2() auftreten:
- EEXIST
- flags enthält RENAME_NOREPLACE und newpath
existiert bereits.
- EINVAL
- In flags wurde ein ungültiger Schalter angegeben.
- EINVAL
- Sowohl RENAME_NOREPLACE als auch RENAME_EXCHANGE wurden in
flags angegeben.
- EINVAL
- Sowohl RENAME_WHITEOUT als auch RENAME_EXCHANGE wurden in
flags angegeben.
- EINVAL
- Das Dateisystem unterstützt einen der Schalter in flags
nicht.
- ENOENT
- flags enthält RENAME_EXCHANGE und newpath
existiert nicht.
- EPERM
- RENAME_WHITEOUT wurde in flags festgelegt, aber der
Aufrufende verfügte nicht über die Capability
CAP_MKNOD.
renameat() wurde zu Linux in Kernel 2.6.16
hinzugefügt; Bibliotheksunterstützung wurde zu Glibc in
Version 2.4 hinzugefügt.
renameat2() wurde zu Linux in Kernel 3.15
hinzugefügt.
rename(): 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.
renameat(): POSIX.1-2008.
renameat2() ist Linux-spezifisch.
Glibc stellt keinen Wrapper für den Systemaufruf
renameat2() bereit; rufen Sie ihn mittels syscall(2) auf.
Mit älteren Kerneln, wenn renameat() nicht
verfügbar ist, weicht die Glibc-Wrapper-Funktion auf rename()
aus. Wenn oldpath und newpath relative Pfadnamen sind,
konstruiert die Glibc Pfadnamen auf Basis der symbolischen Links in
/proc/self/fd, die den Argumenten olddirfd und newdirfd
entsprechen.
Auf NFS-Dateisystemen kann bei einer fehlgeschlagenen Operation
nicht davon ausgegangen werden, dass die Datei nicht umbenannt wurde. Falls
der Server die Datei umbenennt und dann abstürzt, gibt der erneut
übertragene RPC, der nach dem Wiederanlaufen des Servers verarbeitet
wird, einen Fehler zurück. Von der Anwendung wird erwartet, dies zu
berücksichtigen. Siehe link(2) für ein ähnliches
Problem.
Diese Seite ist Teil der Veröffentlichung 4.16 des Projekts
Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie
Fehler gemeldet werden können sowie die aktuelle Version dieser Seite
finden sich unter https://www.kernel.org/doc/man-pages/.
ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von
Elmar Jansen <ej@pumuckel.gun.de>, Martin Eberhard Schauer
<Martin.E.Schauer@gmx.de>, Helge Kreutzmann
<debian@helgefjell.de> und Mario Blättermann
<mario.blaettermann@gmail.com> erstellt.
Diese Übersetzung ist Freie Dokumentation; lesen Sie die
GNU General Public License Version 3 oder neuer bezüglich der
Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.
Wenn Sie Fehler in der Übersetzung dieser Handbuchseite
finden, schicken Sie bitte eine E-Mail an
<debian-l10n-german@lists.debian.org>.