Provided by: manpages-fr-dev_4.13-4_all 
NOM
copy_file_range - Copier une plage de données d'un fichier vers un autre
SYNOPSIS
#define _GNU_SOURCE
#include <unistd.h>
ssize_t copy_file_range(int fd_in, loff_t *off_in,
int fd_out, loff_t *off_out,
size_t len, unsigned int flags);
DESCRIPTION
L'appel système copy_file_range() effectue une copie interne au noyau entre deux
descripteurs de fichier sans devoir en plus transférer des données du noyau à l'espace
utilisateur puis revenir au noyau. Jusqu'à len octets de données sont transférés du
descripteur de fichier fd_in au descripteur de fichier fd_out, écrasant toute donnée se
trouvant dans la plage du fichier cible sollicité.
La sémantique suivante s'applique à off_in et des déclarations identiques s'appliquent à
off_out :
– Si off_in est NULL, les octets sont lus dans fd_in à partir de la position du fichier,
laquelle est ajustée par le nombre d'octets copiés.
– Si off_in n'est pas NULL, off_in doit pointer vers un tampon qui indique le point de
départ à partir duquel les octets de fd_in seront lus. La position du fichier de fd_in
n'est pas modifiée mais off_in est ajusté correctement.
fd_in et fd_out peuvent se rapporter au même fichier. Dans ce cas, les plages de la source
et de la cible ne sont pas autorisées à se chevaucher.
L'argument flags est fourni pour de futures extensions et doit être positionné
actuellement sur 0.
VALEUR RENVOYÉE
En cas de succès, copy_file_range() renverra le nombre d'octets copiés entre les fichiers.
Il pourrait être inférieur à la taille demandée au départ. Si la position du fichier de
fd_in est à la fin du fichier ou au-delà, aucun octet n'est copié et copy_file_range()
renvoie zéro.
En cas d'erreur, copy_file_range() renvoie -1 et errno est configuré 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 écriture.
EBADF L'attribut O_APPEND est configuré pour une description d'un fichier ouvert (voir
open(2)) auquel renvoie le descripteur de fichier fd_out.
EFBIG Tentative d'écriture sur une position dépassant la position maximale du fichier
gérée par le noyau.
EFBIG Tentative d'écriture d'une plage dépassant la taille maximale d'un fichier permise.
La taille maximale d'un fichier varie selon les implémentations de système de
fichiers et peut être différente de la position du fichier maximale autorisée.
EFBIG Tentative d'écriture au-delà de la limite de ressource de la taille du fichier du
processus. Cela peut aussi avoir pour conséquence la réception, par le processus,
d'un signal SIGXFSZ.
EINVAL Le paramètre flags ne vaut pas 0.
EINVAL fd_in et fd_out se rapportent au même 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 à un répertoire.
ENOMEM Plus assez de mémoire.
ENOSPC Il n'y a pas assez d'espace sur le système de fichiers cible pour terminer la
copie.
EOVERFLOW
La plage source ou de destination demandée est trop grande pour être représentée
dans les types de données indiqués.
EPERM fd_out se rapporte à un fichier immuable.
ETXTBSY
fd_in ou fd_out se rapporte à un fichier d'échange actif.
EXDEV Les fichiers auxquels se rapportent fd_in et fd_out ne sont pas sur le même système
de fichiers monté (avant Linux 5.3).
VERSIONS
L'appel système copy_file_range() est apparu pour la première fois dans Linux 4.5, mais la
glibc 2.27 offre une émulation dans l'espace utilisateur s'il n'est pas disponible.
L'implémentation du noyau a été profondément retravaillée dans la version 5.3. Les zones
de l'API qui n'étaient pas clairement définies ont été clarifiées et les limites de l'API
sont vérifiées beaucoup plus strictement que sur les noyaux précédents. Les applications
devraient cibler le comportement et les exigences des noyaux 5.3.
Une première prise en charge des copies entre plusieurs systèmes de fichiers a été
introduite dans Linux 5.3. Les anciens noyaux renverront -EXDEV si on tente des copies
entre systèmes de fichiers.
CONFORMITÉ
L'appel système copy_file_range() est une extension GNU et un non standard de Linux.
NOTES
Si fd_in est un fichier éparpillé, il se peut que copy_file_range() agrandisse les trous
existant dans la plage demandée. Les utilisateurs peuvent bénéficier d'un appel à
copy_file_range() dans une boucle et utiliser les opérations SEEK_DATA et SEEK_HOLE de
lseek(2) pour chercher des emplacements de segments de données.
copy_file_range() donne aux systèmes de fichiers la possibilité d'implémenter des
techniques de « copie accélérée » telles que l'utilisation de reflink (c'est-à-dire deux
ou plusieurs i-nœuds partageant des pointeurs avec les mêmes blocs de disque
copy-on-write) ou server-side-copy (dans le cas de NFS).
EXEMPLES
#define _GNU_SOURCE
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>
#include <sys/syscall.h>
#include <unistd.h>
/* Sur les versions de la glibc antérieures à 2.27, il faut
appeler copy_file_range() en utilisant syscall(2) */
static loff_t
copy_file_range(int fd_in, loff_t *off_in, int fd_out,
loff_t *off_out, size_t len, unsigned int flags)
{
return syscall(__NR_copy_file_range, fd_in, off_in, fd_out,
off_out, len, flags);
}
int
main(int argc, char **argv)
{
int fd_in, fd_out;
struct stat stat;
loff_t len, ret;
if (argc != 3) {
fprintf(stderr, "Utilisation : %s <source> <destination>\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)
COLOPHON
Cette page fait partie de la publication 5.10 du projet man-pages Linux. Une description
du projet et des instructions pour signaler des anomalies et la dernière version de cette
page peuvent être trouvées à l'adresse https://www.kernel.org/doc/man-pages/.
TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess
<https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry
Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>,
Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-
luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis
Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Philippe MENGUAL
<jpmengual@debian.org>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General
Public License version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ concernant les
conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
message à debian-l10n-french@lists.debian.org ⟨⟩.