rename(2) System Calls Manual rename(2) NOM rename, renameat, renameat2 - Changer le nom ou l'emplacement d'un fichier BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include int rename(const char *oldpath, const char *newpath); #include /* Definition des constantes AT_* */ #include 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); Exigences de macros de test de fonctionnalites pour la glibc (consulter feature_test_macros(7)) : renameat(): Depuis la 2.10: _POSIX_C_SOURCE >= 200809L Avant la glibc 2.10: _ATFILE_SOURCE renameat2(): _GNU_SOURCE DESCRIPTION rename() renomme un fichier, en le deplacant dans un autre repertoire si necessaire. Tous les autres liens physiques vers le fichier (comme crees avec link(2)) sont inchanges. Les descripteurs de fichier ouverts sur oldpath ne sont pas non plus affectes. Diverses restrictions determinent si l'operation de renommage a reussie. Consulter le paragraphe ERREURS ci-apres. Si newpath existe deja, il sera remplace de maniere atomique, de maniere a ce qu'a aucun moment, un autre processus tentant d'acceder a newpath ne le voie absent. Cependant, il existera probablement un creneau pendant lequel oldpath et newpath se refereront au fichier en cours de renommage. Si oldpath et newpath sont des liens physiques existants correspondant au meme fichier, rename() ne fait rien et renvoie un code de succes. Si newpath existe mais que l'operation echoue pour une raison quelconque, rename() garantit la presence d'une instance de newpath en place. oldpath peut etre un repertoire. Dans ce cas, newpath doit etre soit absent, soit un repertoire vide. Si oldpath correspond a un lien symbolique, le lien est renomme ; si newpath correspond a un lien symbolique, le lien est ecrase. renameat() L'appel systeme renameat() fonctionne exactement comme rename(), les seules differences etant decrites ici. Si le chemin donne dans oldpath est relatif, il est interprete par rapport au repertoire reference par le descripteur de fichier olddirfd (plutot que par rapport au repertoire de travail du processus, comme c'est le cas pour rename()). Si oldpath est un chemin relatif, et si olddirfd a la valeur speciale AT_FDCWD, alors oldpath est interprete par rapport au repertoire de travail du processus (comme pour rename()). Si oldpath est un chemin absolu, olddirfd est ignore. L'interpretation de newpath est identique a celle de oldpath, excepte qu'un chemin relatif est interprete par rapport au repertoire correspondant a newdirfd. Consultez openat(2) pour une explication de la necessite de renameat(). renameat2() renameat2() possede un argument additionnel, flags. Un appel a renameat2() sans passer de valeur a l'argument flags equivaut a un appel a renameat(). L'argument flags est un masque de bits eventuellement vide ou contenant un ou plusieurs des attributs suivants : RENAME_EXCHANGE Echange oldpath et newpath par une operation atomique. Les deux chemins doivent exister mais peuvent etre de differentes natures (par exemple, l'un peut etre un repertoire non vide et l'autre un lien symbolique). RENAME_NOREPLACE Ne pas ecraser newpath lors du renommage. Renvoi d'une erreur si newpath existe deja. RENAME_NOREPLACE ne peut etre employer en meme temps que RENAME_EXCHANGE. RENAME_NOREPLACE necessite une prise en charge par le systeme de fichiers sous-jacent. Cette prise en charge pour divers systemes de fichiers a ete ajoutee comme suit : - ext4 (Linux 3.15) ; - btrfs, tmpfs et cifs (Linux 3.17) ; - xfs (Linux 4.0) ; - la prise en charge par plusieurs autres systemes de fichiers a ete ajoutee dans Linux 4.9, dont ext2, minix, reiserfs, jfs, vfat et bpf. RENAME_WHITEOUT (depuis Linux 3.18) Cette operation n'a de sens que pour les implementations de systeme de fichiers overlay/union. L'indication de RENAME_WHITEOUT cree un objet de << whiteout >> (simulation d'effacement) a la source du renommage en meme temps que la realisation de ce renommage. Toute l'operation est atomique, de telle facon que si le renommage reussit, alors le whiteout est aussi cree. Un << whiteout >> est un objet de signification speciale dans les constructions de systeme de fichiers union/overlay. Dans ces constructions, plusieurs couches existent et seule la plus haute est toujours modifiee. Un whiteout sur la couche superieure cachera de fait un fichier apparie dans la couche inferieure, donnant l'impression que le fichier n'existe pas. Lorsqu'un fichier existant dans la couche inferieure est renomme, le fichier est d'abord copie au niveau superieur (s'il n'existe pas deja sur ce niveau) puis est renomme sur la couche en lecture-ecriture superieure. Au meme moment, le fichier source doit etre mis << whiteout >> (de facon que la version dans la couche inferieure soit rendue invisible). Toute l'operation doit etre realisee de maniere atomique. Lorsqu'il ne fait pas partie d'une union/overlay, le whiteout apparait comme un peripherique caractere avec un numero de peripherique. (Il est a remarquer que les implementations union/overlay peuvent employer des methodes differentes pour stocker les entrees whiteout. Precisement, les unions de montage BSD utilisent un type d'inode distinct, DT_WHT, lesquels, tout en etant geres par certains systemes de fichiers disponibles dans Linux, tels que CODA et XFS, sont ignores par le code de prise en charge du noyau pour whiteout, comme pour au moins, Linux 4.19.) RENAME_WHITEOUT necessite les memes droits que pour la creation d'un noeud de peripherique (c'est-a-dire, la capacite CAP_MKNOD). RENAME_WHITEOUT ne peut etre employe en meme temps que RENAME_EXCHANGE. RENAME_WHITEOUT necessite une prise en charge par le systeme de fichiers sous-jacent. Entre autres les systemes de fichiers tmpfs (depuis Linux 3.18), ext4 (depuis Linux 3.18), XFS (depuis Linux 4.1), f2fs (depuis Linux 4.2), btrfs (depuis Linux 4.7) et ubifs (depuis Linux 4.9) le prennent en charge. VALEUR RENVOYEE En cas de succes, zero est renvoye. En cas d'erreur, -1 est renvoye et errno est definie pour preciser l'erreur. ERREURS EACCES La permission d'ecrire est refusee dans le repertoire contenant oldpath ou newpath, ou la permission de parcours est refusee pour l'un des repertoires dans le chemin d'acces a oldpath ou newpath, ou encore oldpath est un repertoire et ne permet pas l'ecriture (necessaire pour mettre a jour l'entree ..). (Consultez aussi path_resolution(7).) EBUSY Le renommage a echoue car oldpath ou newpath est un repertoire utilise par un processus (peut-etre comme repertoire de travail, ou comme repertoire racine, ou ouvert en lecture), ou il est utilise par le systeme (comme point de montage par exemple). Le systeme a donc considere qu'il y avait une erreur. (Notez qu'il n'est pas indispensable de renvoyer EBUSY dans un tel cas -- rien n'empeche d'effectuer le renommage malgre tout -- mais il est permis de retourner EBUSY si le systeme n'arrive pas a gerer une telle situation). EDQUOT Le quota de blocs de disque de l'utilisateur sur le systeme de fichiers a ete atteint. EFAULT oldpath ou newpath pointent en dehors de l'espace d'adressage accessible. EINVAL Le nouveau chemin contient un prefixe de chemin de l'ancien, ou plus generalement, un repertoire ne peut pas etre deplace dans ses propres sous-repertoires. EISDIR newpath est un repertoire existant mais oldpath n'est pas un repertoire ELOOP Trop de liens symboliques ont ete rencontres en parcourant oldpath ou newpath. EMLINK oldpath a deja un nombre maximal de liens, ou bien c'est un repertoire, et le repertoire contenant newpath a le nombre maximal de liens. ENAMETOOLONG oldpath ou newpath est trop long. ENOENT Le lien indique par oldpath n'existe pas, ou bien un repertoire du chemin newpath n'existe pas, ou bien oldpath ou newpath est une chaine vide. ENOMEM La memoire disponible du noyau n'etait pas suffisante. ENOSPC Le peripherique contenant le fichier n'a pas de place pour une nouvelle entree de repertoire. ENOTDIR Un element utilise comme repertoire dans oldpath ou newpath n'est pas un repertoire, ou bien oldpath est un repertoire et newpath existe mais n'est pas un repertoire. ENOTEMPTY ou EEXIST newpath est un repertoire non vide (contient autre chose que << . >> et << .. >>). EPERM ou EACCES Le repertoire contenant oldpath a le sticky bit (S_ISVTX) positionne, et l'UID effectif du processus n'est ni celui de l'UID du fichier a deplacer, ni celui du repertoire le contenant, et le processus n'est pas privilegie (sous Linux : n'a pas la capacite CAP_FOWNER ; ou newpath est un fichier existant et le repertoire le contenant a son sticky bit positionne et l'UID effectif du processus n'est ni celui du fichier a deplacer, ni celui du repertoire le contenant, et le processus n'est pas privilegie (sous Linux : n'a pas la capacite CAP_FOWNER ; ou alors le systeme de fichiers contenant oldpath ne permet pas le renommage du type demande. EROFS Le fichier se trouve sur un systeme de fichiers en lecture seule. EXDEV oldpath et newpath ne sont pas sur le meme systeme de fichiers monte. (Linux permet de monter un systeme de fichiers a plusieurs endroits, mais rename() ne fonctionne pas a travers des points de montage differents, meme si le systeme de fichiers est monte sur les deux.) Les erreurs supplementaires suivantes peuvent egalement se produire pour renameat() et renameat2() : EBADF oldpath (newpath) est relatif, mais olddirfd (newdirfd n'est pas un descripteur de fichier valable. ENOTDIR oldpath est un chemin relatif, et olddirfd est un descripteur de fichier ne referencant pas un repertoire ; ou bien c'est le cas pour newpath et newdirfd. Les erreurs supplementaires suivantes peuvent egalement se produire pour renameat2() : EEXIST flags contient l'attribut RENAME_NOREPLACE et newpath existe deja. EINVAL flags contient un drapeau non valable. EINVAL RENAME_NOREPLACE et RENAME_EXCHANGE sont tous les deux indiques dans flags. EINVAL RENAME_WHITEOUT et RENAME_EXCHANGE sont tous les deux indiques dans flags. EINVAL Le systeme de fichiers ne prend pas en charge l'un des attributs de flags. ENOENT flags contient RENAME_EXCHANGE et newpath n'existe pas. EPERM RENAME_WHITEOUT est indique dans flags mais l'appelant n'a pas la capacite CAP_MKNOD. STANDARDS rename() C11, POSIX.1-2008. renameat() POSIX.1-2008. renameat2() Linux. HISTORIQUE rename() 4.3BSD, C89, POSIX.1-2001. renameat() Linux 2.6.16, glibc 2.4. renameat2() Linux 3.15, glibc 2.28. Notes de la glibc Dans les anciens noyaux ou renameat() n'est pas disponible, les fonctions d'enveloppe de la glibc renvoient a l'utilisation de rename(). Quand oldpath et newpath sont des noms de chemin relatif, la glibc construit les noms de chemin bases sur les liens symboliques dans /proc/self/fd qui correspondent aux arguments olddirfd et newdirfd. BOGUES Sur les systemes de fichiers NFS, ce n'est pas parce que l'operation a echoue que le fichier n'a pas ete renomme. Si le serveur effectue le renommage et se plante, la RPC transmise qui sera traitee lorsque le serveur sera a nouveau en etat va entrainer un echec. L'application doit gerer ce genre de probleme. Consultez link(2) pour un probleme similaire. VOIR AUSSI mv(1), rename(1), chmod(2), link(2), symlink(2), unlink(2), path_resolution(7), symlink(7) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot , Frederic Hantrais et Jean- Paul Guillonneau Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 rename(2)