SPLICE(2)

NOM
splice - Copier des données vers/depuis un tube

SYNOPSIS
#define _GNU_SOURCE
#include <fcntl.h>
long splice(int fd_in, off_t *off_in, int fd_out,
            off_t *off_out, size_t len, unsigned int flags);

DESCRIPTION
splice() déplace des données entre deux descripteurs de fichier sans les copier entre l'espace d'adressage noyau et l'espace d'adressage utilisateur. Il transfère jusqu'à len octets de données à partir du descripteur de fichier fd_in vers le descripteur de fichier fd_out, où l'un des deux descripteurs doit faire référence à un tube. Si fd_in fait référence à un tube, off_in doit être NULL. Si fd_in ne fait pas référence à un tube et si off_in est NULL, les octets sont lus dans fd_in à partir de la position courante de la tête de lecture sur le fichier, celle-ci étant mise à jour de manière appropriée. Si fd_in ne fait pas référence à un tube et si off_in n'est pas NULL, off_in doit pointer sur un tampon qui spécifie la position à partir de laquelle seront lus les octets dans fd_in ; dans ce cas, la position courante de la tête de lecture de fd_in n'est pas modifiée. Cela s'applique également à fd_out et off_out. L'argument flags est un masque de bits constitué par un OU binaire entre zéro ou plusieurs des valeurs suivantes :

SPLICE_F_MOVE
    Essayer de déplacer les pages au lieu de les copier. Ce n'est qu'un conseil du noyau : les pages peuvent quand même être copiées si le noyau ne peut pas déplacer les pages du tube ou si les tampons du tube ne font pas référence à des pages complètes.

SPLICE_F_NONBLOCK
    Ne pas bloquer sur les E/S. Cela rend les opérations de copie sur le tube non bloquantes, mais splice() peut tout de même bloquer car les descripteurs de fichier mis en jeu peuvent bloquer (sauf s'ils ont l'attribut O_NONBLOCK défini).

SPLICE_F_MORE
    Des données supplémentaires seront copiées plus tard. C'est une indication utile lorsque fd_out fait référence à une socket (voir aussi la description de MSG_MORE dans send(2), et la description de TCP_CORK dans tcp(7))

SPLICE_F_GIFT
    Non utilisé pour splice() ; voir vmsplice(2).

VALEUR RENVOYÉE
En cas de réussite, splice() renvoie le nombre d'octets copiés de ou vers le tube. Une valeur de retour nulle signifie qu'il n'y avait pas de donnée à transférer, et qu'il n'y aurait aucun sens à bloquer étant donné qu'il n'y a pas d'écrivain connecté du coté écriture du tube référencé par fd_in. En cas d'erreur, splice() renvoie -1 et errno est positionnée en conséquence pour indiquer l'erreur.

ERREURS

EBADF
    Au moins un des deux descripteurs de fichier n'est pas valide ou bien n'a pas le mode de lecture/écriture approprié.

EINVAL
    Le système de fichiers cible ne prend pas en charge la copie ; aucun des descripteurs ne fait référence à un tube ; la tête de lecture fournie l'est pour un périphérique sur lequel le déplacement n'est pas possible.

ENOMEM
    Pas assez de mémoire.

ESPIPE
    Soit off_in soit off_out n'était pas NULL, mais le descripteur de fichier correspondant faisait référence à un tube.

VERSIONS
L'appel système splice(2) est apparu pour la première fois dans Linux 2.6.17.

CONFORMITÉ
Cet appel système est spécifique à Linux.

NOTES
Les trois appels système splice(2), vmsplice(2) et tee(2) fournissent aux programmes en espace utilisateur le contrôle complet d'un tampon arbitraire du noyau, implémenté dans le noyau en utilisant le même type de tampon que pour les tubes. Ces appels système effectuent les tâches suivantes :

splice()
    déplace des données depuis le tampon vers un descripteur de fichier, ou vice versa, ou bien d'un tampon vers un autre.

tee(2)
    « copie » les données d'un tampon vers un autre.

vmsplice(2)
    « copie » les données de l'espace utilisateur vers un tampon.

Bien que nous parlions de copie, les vraies copies sont évitées. Le noyau réalise cela en implémentant un tampon de tube comme un ensemble de pointeurs vers des pages de mémoire du noyau pouvant être référencées plusieurs fois. Le noyau crée des « copies » des pages dans un tampon en créant de nouveaux pointeurs (pour le tampon de sortie) référençant ces pages, et en incrémentant les compteurs de référence des pages : seuls les pointeurs sont copiés, pas les pages du tampon.

EXEMPLE
Voir tee(2).

VOIR AUSSI
sendfile(2), splice(2), tee(2), feature_test_macros(7)

TRADUCTION

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 24 octobre 2007 et révisée le 22 décembre 2007.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 2 splice ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.