Linux repositories inspector
Linux
15. September 2017
Aliases: renameat(2), renameat(2), renameat(2), renameat(2), renameat(2), renameat(2), renameat(2), renameat(2), renameat2(2), renameat2(2), renameat2(2), renameat2(2), renameat2(2), renameat2(2), renameat2(2)

manpages-de-dev

German development manpages

man-pages-de

German Linux man pages

manpages-dev

Manual pages about using GNU/Linux for development

man-pages

Linux kernel and C library user-space interface documentation

BEZEICHNUNG

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);
Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):
renameat():
Seit Glibc 2.10:
_POSIX_C_SOURCE >= 200809L
Vor Glibc 2.10:
_ATFILE_SOURCE
renameat2():
_GNU_SOURCE

BESCHREIBUNG

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.

renameat()

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()

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_NOREPLACE benötigt Unterstützung vom zugrundeliegenden Dateisystem. Die Unterstützung für verschiedene Dateisysteme wurde wie folgt hinzugefügt:
* Ext4 (Linux 3.15);
* Btrfs, Shmem und Cifs (Linux 3.17);
* XFS (Linux 4.0);
* Die Unterstützung für viele andere Dateisysteme wurde in Linux 4.9 hinzugefügt, einschließlich Ext2, Minix, Reiserfs, Jfs, Vfat und Bpf.
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. (Note that other union/overlay implementations may employ different methods for storing whiteout entries; specifically, BSD union mount employs a separate inode type, DT_WHT, which, while supported by some filesystems available in Linux, such as CODA and XFS, is ignored by the kernel’s whiteout support code, as of Linux 4.19, at least.)
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 Tmpfs (seit Linux 3.18), Ext4 (seit Linux 3.18), XFS (seit Linux 4.1), F2fs (seit Linux 4.2), Btrfs (seit Linux 4.7) und Ubifs (seit Linux 4.9).

RÜCKGABEWERT

Bei Erfolg wird Null zurückgegeben. Bei einem Fehler wird -1 zurückgegeben und errno entsprechend gesetzt.

FEHLER

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.

VERSIONEN

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; Bibliotheksunterstützung wurde zu Glibc 2.28 hinzugefügt.

KONFORM ZU

rename(): 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.
renameat(): POSIX.1-2008.
renameat2() ist Linux-spezifisch.

ANMERKUNGEN

Anmerkungen zur Glibc

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.

KOLOPHON

Diese Seite ist Teil der Veröffentlichung 5.03 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 <>, Martin Eberhard Schauer <>, Helge Kreutzmann <> und Mario Blättermann <> 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 <>.
⇧ Top