copy_file_range(2) System Calls Manual copy_file_range(2) NOM copy_file_range - Copier une plage de donnees d'un fichier vers un autre BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #define _GNU_SOURCE #define _FILE_OFFSET_BITS 64 #include ssize_t copy_file_range(int fd_in, off_t *_Nullable off_in, int fd_out, off_t *_Nullable off_out, size_t len, unsigned int flags); DESCRIPTION L'appel systeme copy_file_range() effectue une copie interne au noyau entre deux descripteurs de fichier sans devoir en plus transferer des donnees du noyau a l'espace utilisateur puis revenir au noyau. Jusqu'a len octets de donnees sont transferes du descripteur de fichier fd_in au descripteur de fichier fd_out, ecrasant toute donnee se trouvant dans la plage du fichier cible sollicite. La semantique suivante s'applique a off_in et des declarations identiques s'appliquent a off_out : - Si off_in est NULL, les octets sont lus dans fd_in a partir de la position du fichier, laquelle est ajustee par le nombre d'octets copies. - Si off_in n'est pas NULL, off_in doit pointer vers un tampon qui indique le point de depart a partir duquel les octets de fd_in seront lus. La position du fichier de fd_in n'est pas modifiee mais off_in est ajuste correctement. fd_in et fd_out peuvent se rapporter au meme fichier. Dans ce cas, les plages de la source et de la cible ne sont pas autorisees a se chevaucher. L'argument flags est fourni pour de futures extensions et doit etre positionne actuellement sur 0. VALEUR RENVOYEE En cas de succes, copy_file_range() renverra le nombre d'octets copies entre les fichiers. Il pourrait etre inferieur a la taille demandee au depart. Si la position du fichier de fd_in est a la fin du fichier ou au-dela, aucun octet n'est copie et copy_file_range() renvoie zero. En cas d'erreur, copy_file_range() renvoie -1 et errno est configure pour indiquer l'erreur. ERREURS EBADF Un ou plusieurs descripteurs de fichier ne sont pas valables. EBADF fd_in n'est pas ouvert en lecture ou fd_out n'est pas ouvert en ecriture. EBADF L'attribut O_APPEND est configure pour une description d'un fichier ouvert (voir open(2)) auquel renvoie le descripteur de fichier fd_out. EFBIG Tentative d'ecriture sur une position depassant la position maximale du fichier geree par le noyau. EFBIG Tentative d'ecriture d'une plage depassant la taille maximale d'un fichier permise. La taille maximale d'un fichier varie selon les implementations de systeme de fichiers et peut etre differente de la position du fichier maximale autorisee. EFBIG Tentative d'ecriture au-dela de la limite de ressource de la taille du fichier du processus. Cela peut aussi avoir pour consequence la reception, par le processus, d'un signal SIGXFSZ. EINVAL Le parametre flags ne vaut pas 0. EINVAL fd_in et fd_out se rapportent au meme fichier et les plages de la source et de la cible se chevauchent. EINVAL fd_in ou fd_out n'est pas un fichier normal. EIO Une erreur E/S de bas niveau s'est produite lors de la copie. EISDIR fd_in ou fd_out se rapporte a un repertoire. ENOMEM Plus assez de memoire. ENOSPC Il n'y a pas assez d'espace sur le systeme de fichiers cible pour terminer la copie. EOPNOTSUPP (depuis Linux 5.19) Le systeme de fichiers ne prend pas en charge cette operation. EOVERFLOW La plage source ou de destination demandee est trop grande pour etre representee dans les types de donnees indiques. EPERM fd_out se rapporte a un fichier immuable. ETXTBSY fd_in ou fd_out se rapporte a un fichier d'echange actif. EXDEV (depuis Linux 5.3) Les fichiers auxquels se rapportent fd_in et fd_out ne sont pas sur le meme systeme de fichiers. EXDEV (depuis Linux 5.19) Les fichiers auxquels se rapportent fd_in et fd_out ne sont pas sur le meme systeme de fichiers et les systemes de fichiers source et cible ne sont pas du meme type ou ne prennent pas en charge la copie entre systemes de fichiers. VERSIONS L'implementation du noyau a ete profondement retravaillee dans Linux 5.3. Les zones de l'API qui n'etaient pas clairement definies ont ete clarifiees et les limites de l'API sont verifiees beaucoup plus strictement que sur les noyaux precedents. Les applications devraient cibler le comportement et les exigences des noyaux 5.3. Depuis Linux 5.19, les copies entre systemes de fichiers peuvent se faire quand les deux systemes de fichiers sont du meme type et si le systeme de fichiers le prend en charge. Voir BOGUES pour le comportement avant la 5.19. Les applications devraient cibler le comportement et les exigences de Linux 5.3 qui ont aussi ete retroportes dans les noyaux stable plus recents. STANDARDS Linux, GNU. HISTORIQUE Linux 4.5, mais la glibc 2.27 offre une emulation dans l'espace utilisateur s'il n'est pas disponible. NOTES Si fd_in est un fichier eparpille, il se peut que copy_file_range() agrandisse les trous existant dans la plage demandee. Les utilisateurs peuvent beneficier d'un appel a copy_file_range() dans une boucle et utiliser les operations SEEK_DATA et SEEK_HOLE de lseek(2) pour chercher des emplacements de segments de donnees. copy_file_range() donne aux systemes de fichiers la possibilite d'implementer des techniques de << copie acceleree >> telles que l'utilisation de reflink (c'est-a-dire deux ou plusieurs i-noeuds partageant des pointeurs avec les memes blocs de disque copy-on-write) ou server-side-copy (dans le cas de NFS). _FILE_OFFSET_BITS devrait etre defini pour etre 64 dans le code qui utilise off_in ou off_out non NULL ou qui obtient l'adresse de copy_file_range, si le code est destine a etre portable sur les plateformes x86 32 bits et ARM traditionnelles ou la taille par defaut de off_t est de 32 bits. BOGUES De Linux 5.3 a Linux 5.18, les copies entre systeme de fichiers etaient implementees par le noyau si l'operation n'etait pas geree par les systemes de fichiers eux-memes. Cependant, sur certains systemes de fichiers virtuels, le code n'arrivait pas a faire la copie mais la presentait comme reussie. EXEMPLES #define _GNU_SOURCE #define _FILE_OFFSET_BITS 64 #include #include #include #include #include int main(int argc, char *argv[]) { int fd_in, fd_out; off_t len, ret; struct stat stat; if (argc != 3) { fprintf(stderr, "Utilisation : %s \n", argv[0]); exit(EXIT_FAILURE); } fd_in = open(argv[1], O_RDONLY); if (fd_in == -1) { perror("open (argv[1])"); exit(EXIT_FAILURE); } if (fstat(fd_in, &stat) == -1) { perror("fstat"); exit(EXIT_FAILURE); } len = stat.st_size; fd_out = open(argv[2], O_CREAT | O_WRONLY | O_TRUNC, 0644); if (fd_out == -1) { perror("open (argv[2])"); exit(EXIT_FAILURE); } do { ret = copy_file_range(fd_in, NULL, fd_out, NULL, len, 0); if (ret == -1) { perror("copy_file_range"); exit(EXIT_FAILURE); } len -= ret; } while (len > 0 && ret > 0); close(fd_in); close(fd_out); exit(EXIT_SUCCESS); } VOIR AUSSI lseek(2), sendfile(2), splice(2) 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 et Jean-Philippe MENGUAL 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 copy_file_range(2)