rename

RENAME(2)                   Linux-Programmierhandbuch                  RENAME(2)



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
       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 Wurzelverzeichnis 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 Plattenkontingent (Quota) 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.

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.

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.

SIEHE AUCH
       mv(1), rename(1), chmod(2), link(2), symlink(2), unlink(2),
       path_resolution(7), symlink(7)

KOLOPHON
       Diese Seite ist Teil der Veröffentlichung 5.08 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>.



Linux                             9. Juni 2020                         RENAME(2)