rename(2) System Calls Manual rename(2) BEZEICHNUNG rename, renameat, renameat2 - den Namen oder die Lage einer Datei andern BIBLIOTHEK Standard-C-Bibliothek (libc, -lc) UBERSICHT #include int rename(const char *alterpfad, const char *neuerpfad); #include /* Definition der AT_*-Konstanten */ #include int renameat(int altVerzdd, const char *alterpfad, int neuVerzdd, const char *neuerpfad); int renameat2(int altVerzdd, const char *alterpfad, int neuVerzdd, const char *neuerpfad, unsigned int Schalter); Mit Glibc erforderliche Feature-Test-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 notig. Alle anderen Hardlinks (erstellt mittels link(2)) sind nicht betroffen, ebenso offene Dateideskriptoren fur alterpfad. Verschiedene Einschrankungen bestimmen, ob die Umbenennungsaktion erfolgreich ist oder nicht; siehe FEHLER unten. Falls neuerpfad schon existiert, wird er in einem atomaren Schritt uberschrieben, so dass ein anderer Prozess jederzeit auf neuerpfad zugreifen kann. Allerdings wird es wahrscheinlich ein Fenster geben, in dem sowohl alterpfad als auch neuerpfad sich auf die umzubenennende Datei beziehen. Falls alterpfad und neuerpfad bestehende Hardlinks zu derselben Datei sind, tut rename() nichts und meldet eine erfolgreiche Ausfuhrung. Wenn neuerpfad schon existiert, aber das Umbenennen aus irgendeinem Grund fehlschlagt, garantiert rename(), dass neuerpfad an Ort und Stelle erhalten bleibt. alterpfad kann ein Verzeichnis angeben. In diesem Fall darf neuerpfad nicht existieren oder muss ein leeres Verzeichnis angeben. Falls alterpfad auf einen symbolischen Link zeigt, wird der Link umbenannt; falls neuerpfad auf einen symbolischen Link zeigt, wird der Link uberschrieben. renameat() Der Systemaufruf renameat() funktioniert genauso wie rename(), ausser den hier beschriebenen Unterschieden. Falls der in alterpfad ubergebene Pfadname relativ ist wird er als relativ zu dem im Dateideskriptor altVerzdd referenzierten Verzeichnis interpretiert (statt relativ zum aktuellen Arbeitsverzeichnis des aufrufenden Prozesses, wie es bei rename() fur einen relativen Pfadnamen erfolgt). Falls alterpfad relativ ist und altVerzdd den besonderen Wert AT_FDCWD annimmt wird alterpfad als relativ zum aktuellen Arbeitsverzeichnis des aufrufenden Prozesses interpretiert (wie rename()). Falls alterpfad absolut ist wird altVerzdd ignoriert. Die Interpretation von neuerpfad ist wie bei alterpfad, ausser dass ein relativer Pfadname als relativ zu dem Verzeichnis interpretiert wird, auf das der Dateideskriptor neuVerzdd verweist. Lesen Sie openat(2) fur eine Beschreibung der Notwendigkeit von renameat(). renameat2() renameat2() hat ein zusatzliches Argument Schalter. Ein Aufruf von renameat2() mit einem leeren Argument Schalter ist aquivalent zu renameat(). Das Argument Schalter ist eine Bitmaske, die aus null oder mehr der folgenden Schalter besteht: RENAME_EXCHANGE tauscht alterpfad und neuerpfad atomisch aus. Beide Pfadnamen mussen existieren, konnen aber verschiedenen Typs sein. Beispielsweise kann ein Pfad ein nicht-leeres Verzeichnis und der andere ein symbolischer Link sein. RENAME_NOREPLACE uberschreibt neuerpfad beim Umbenennen nicht. Ein Fehler wird zuruckgegeben, wenn neuerpfad bereits existiert. RENAME_NOREPLACE kann nicht zusammen mit RENAME_EXCHANGE eingesetzt werden. RENAME_NOREPLACE benotigt Unterstutzung vom zugrundeliegenden Dateisystem. Die Unterstutzung fur verschiedene Dateisysteme wurde wie folgt hinzugefugt: o Ext4 (Linux 3.15); o Btrfs, Tmpfs und Cifs (Linux 3.17); o XFS (Linux 4.0); o Die Unterstutzung fur viele andere Dateisysteme wurde in Linux 4.9 hinzugefugt, einschliesslich Ext2, Minix, Reiserfs, Jfs, Vfat und Bpf. RENAME_WHITEOUT (seit Linux 3.18) Diese Aktion ergibt nur fur Implementierungen von Overlay/Union-Dateisystemen Sinn. Durch Angabe von RENAME_WHITEOUT wird ein >>whiteout<<-Objekt bei der Quelle der Umbenennung zum gleichen Zeitpunkt der Durchfuhrung der Umbenennung erzeugt. Die gesamte Aktion ist atomar, so dass der Whiteout erstellt sein wird, wenn die Umbenennung erfolgreich war. Ein >>Whiteout<< ist ein Objekt, das in Union/Overlay-Dateisystemkonstrukten eine besondere Bedeutung hat. In diesen Konstrukten existieren mehrere Ebenen, wobei jedoch nur die oberste Ebene jemals verandert wird. Ein >>Whiteout<< in einer der oberen Ebenen versteckt eine entsprechende Datei in der unteren Ebene, wodurch es so aussieht, als wurde die Datei nicht existieren. 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. Wenn es nicht Teil eines Union/Overlay-Dateisystems ist, dann erscheint ein >>Whiteout<< als zeichenorientiertes Gerat mit einer Geratenummer {0,0}. Beachten Sie, dass andere Union/Overlay-Implementierungen anders mit der Speicherung von >>Whiteout<<-Eintragen umgehen konnten. Insbesondere verwendet >>Union mount<< auf BSD-Systemen einen separaten Inode-Typ DT_WHT. Dieser wird - zumindest in Linux 4.19 - vom >>Whiteout<<-Support-Code des Kernels ignoriert, obwohl er von einigen unter Linux verfugbaren Dateisystemen, wie CODA und XFS, dennoch unterstutzt wird RENAME_WHITEOUT benotigt die gleichen Privilegien wie zum Erstellen eines Gerateknotens (d.h. die Capability CAP_MKNOD). RENAME_WHITEOUT kann nicht zusammen mit RENAME_EXCHANGE eingesetzt werden. RENAME_WHITEOUT benotigt die Unterstutzung vom darunterliegenden Dateisystem. Unter den Dateisystemen, die die Unterstutzung 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). RUCKGABEWERT Bei Erfolg wird Null zuruckgegeben. Bei einem Fehler wird -1 zuruckgegeben und errno gesetzt, um den Fehler anzuzeigen. FEHLER EACCES Fur das Verzeichnis, das alterpfad oder neuerpfad enthalt, wurden Schreibrechte verweigert oder fur eines der Verzeichnisse im Pfad-Prafix von alterpfad oder neuerpfad wurde nicht gestattet, dort zu suchen oder alterpfad ist ein Verzeichnis und verwehrt die Schreiberlaubnis (benotigt, um den Eintrag .. zu aktualisieren). (Siehe auch path_resolution(7).) EBUSY Das Umbenennen scheitert, weil alterpfad oder neuerpfad ein Verzeichnis ist, das von einem anderen Prozess (vielleicht als aktuelles Arbeitsverzeichnis oder als Wurzelverzeichnis oder weil es zum Lesen geoffnet ist) oder vom System genutzt wird (zum Beispiel als Einhangepunkt) und das System dies als Fehler betrachtet. (Beachten Sie, dass es keine Verpflichtung gibt, in solchen Fallen EBUSY zuruckzugeben - es ist nichts falsch daran, die Umbenennung trotzdem durchzufuhren - aber es ist erlaubt, EBUSY zuruckzugeben, wenn das System solche Situationen nicht anderweitig verarbeiten kann.) EDQUOT Das Plattenkontingent (Quota) des Benutzers an Plattenblocken auf dem Dateisystem ist erschopft. EFAULT alterpfad oder neuerpfad zeigt aus dem fur Sie zuganglichen Adressraum heraus. EINVAL Der neue Pfadname enthielt ein Pfad-Prafix des alten, oder allgemeiner, es wurde versucht, ein Verzeichnis als Unterverzeichnis von sich selbst zu erzeugen. EISDIR neuerpfad ist ein existierendes Verzeichnis, aber alterpfad ist kein Verzeichnis. ELOOP Bei der Auflosung von alterpfad oder neuerpfad wurden zu viele symbolische Links gefunden. EMLINK alterpfad hat schon die maximale Anzahl Links, oder es war ein Verzeichnis und das Verzeichnis, welches neuerpfad enthalt, hat schon die maximale Anzahl Links. ENAMETOOLONG alterpfad oder neuerpfad war zu lang. ENOENT Der von alterpfad angegebene Link existiert nicht oder eine Verzeichniskomponente von neuerpfad existiert nicht oder alterpfad oder neuerpfad ist eine leere Zeichenkette. ENOMEM Es war nicht genugend Kernelspeicher verfugbar. ENOSPC Das Gerat, das die die Datei enthalt, hat keinen Platz fur einen neuen Verzeichniseintrag. ENOTDIR Eine als Verzeichnis benutzte Komponente von alterpfad oder neuerpfad ist in der Tat kein Verzeichnis. Oder alterpfad ist ein Verzeichnis und neuerpfad existiert, ist aber kein Verzeichnis. ENOTEMPTY oder EEXIST neuerpfad ist ein nicht leeres Verzeichnis, d.h. es enthalt ausser >>.<< und >>..<< weitere Eintrage. EPERM oder EACCES Das Verzeichnis, das alterpfad enthalt, hat das Sticky-Bit (S_ISVTX) gesetzt und die effektive Benutzerkennung des Prozesses ist weder die Benutzerkennung der zu loschenden Datei noch die des beinhaltenden Verzeichnisses und der Prozess ist nicht privilegiert (Linux: verfugt nicht uber die CAP_FOWNER-Capability); oder neuerpfad ist eine vorhandene Datei und ihr ubergeordnetes 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: verfugt nicht uber die CAP_FOWNER-Capability) oder das alterpfad beherbergende Dateisystem unterstutzt nicht die Umbenennung des angeforderten Typs. EROFS Die Datei befindet sich auf einem nur lesbaren Dateisystem. EXDEV alterpfad und neuerpfad befinden sich nicht auf demselben eingehangten Dateisystem. (Linux erlaubt es Dateisystemen, an mehreren Stellen eingehangt zu sein, aber rename() funktioniert nicht uber verschiedene Einhangepunkte hinweg, selbst falls dasselbe Dateisystem an beiden Stellen eingehangt ist.) Die folgenden zusatzlichen Fehler konnen bei renameat() und renameat2() auftreten: EBADF alterpfad (neuerpfad) ist relativ, aber altVerzdd (neuVerzdd) ist kein zulassiger Dateideskriptor. ENOTDIR alterpfad ist relativ und altVerzdd ist ein Dateideskriptor, der sich auf eine Datei bezieht, die kein Verzeichnis ist; gilt analog fur neuerpfad und neuVerzdd. Die folgenden zusatzlichen Fehler konnen bei renameat2() auftreten: EEXIST Schalter enthalt RENAME_NOREPLACE und neuerpfad existiert bereits. EINVAL In Schalter wurde ein ungultiger Schalter angegeben. EINVAL Sowohl RENAME_NOREPLACE als auch RENAME_EXCHANGE wurden in Schalter angegeben. EINVAL Sowohl RENAME_WHITEOUT als auch RENAME_EXCHANGE wurden in Schalter angegeben. EINVAL Das Dateisystem unterstutzt einen der Schalter in Schalter nicht. ENOENT Schalter enthalt RENAME_EXCHANGE und neuerpfad existiert nicht. EPERM RENAME_WHITEOUT wurde in Schalter angegeben, aber der Aufrufende verfugte nicht uber die Capability CAP_MKNOD. STANDARDS rename() C11, POSIX.1-2008. renameat() POSIX.1-2008. renameat2() Linux. GESCHICHTE rename() 4.3BSD, C89, POSIX.1-2001. renameat() Linux 2.6.16, Glibc 2.4. renameat2() Linux 3.15, Glibc 2.28. Anmerkungen zur Glibc Mit alteren Kerneln, wenn renameat() nicht verfugbar ist, weicht die Glibc-Wrapper-Funktion auf rename() aus. Wenn alterpfad und neuerpfad relative Pfadnamen sind, konstruiert die Glibc Pfadnamen auf Basis der symbolischen Links in /proc/self/fd, die den Argumenten altVerzdd und neuVerzdd entsprechen. 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 absturzt, gibt der erneut ubertragene RPC, der nach dem Wiederanlaufen des Servers verarbeitet wird, einen Fehler zuruck. Von der Anwendung wird erwartet, dies zu berucksichtigen. Siehe link(2) fur ein ahnliches Problem. SIEHE AUCH mv(1), rename(1), chmod(2), link(2), symlink(2), unlink(2), path_resolution(7), symlink(7) UBERSETZUNG Die deutsche Ubersetzung dieser Handbuchseite wurde von Elmar Jansen , Martin Eberhard Schauer , Helge Kreutzmann und Mario Blattermann erstellt. Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezuglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG ubernommen. Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Ubersetzer . Linux man-pages 6.8 2. Mai 2024 rename(2)