FALLOCATE

Manuel du programmeur Linux (2)
8 mai 2014

NOM

fallocate - Manipuler un espace de fichier

SYNOPSIS

#define _GNU_SOURCE             /* Consultez feature_test_macros(7) */
#include <fcntl.h>

int fallocate(int fd, int mode, off_t offset, off_t len);

DESCRIPTION

C'est un appel système spécifique à Linux et non portable. Pour la méthode portable, spécifiée par POSIX.1, pour assurer que de l'espace est alloué pour un fichier, consultez posix_fallocate(3).

fallocate() permet à l'appelant de manipuler directement l'espace disque alloué pour le fichier référencé par fd pour la plage d'octets débutant à offset et de longueur len octets.

Le paramètre mode définit l'opération à effectuer sur la plage donnée. Les sous-sections suivantes apportent des précisions sur les opérations prises en charge.

Allocation d'espace disque.

L'opération par défaut (c'est-à-dire si mode est zéro) de fallocate() alloue l'espace disque dans l'intervalle indiqué par offset et len. La taille du fichier (comme indiquée par stat(2)) sera modifiée si offset+len est supérieur à la taille du fichier. Toute sous-région dans l'intervalle indiqué par offset et len sera initialisée à zéro si elle ne contient pas de données au moment de l'appel. Ce comportement par défaut ressemble beaucoup au comportement de la fonction de bibliothèque posix_fallocate(3), et est conçu comme une méthode d'implémentation optimisée de cette fonction.

Après un appel réussi, les écritures suivantes dans l'intervalle indiqué par offset et len seront garanties sans échec dû à un manque d'espace disque.

Si l'attribut FALLOC_FL_KEEP_SIZE est indiqué dans mode, le comportement de l'appel est similaire, mais la taille du fichier ne sera pas modifiée si offset+len est supérieur à la taille du fichier. L'allocation préalable de blocs mis à zéro après la fin du fichier de cette façon permet d'optimiser la charge de travail d'ajout.

Parce que l'allocation est effectuée en fragments de taille de blocs, fallocate() peut allouer un espace de disque plus grand que celui qui a été indiqué.

Désallocation d'espace de fichier

Indiquer le paramètre FALLOC_FL_PUNCH_HOLE (disponible depuis Linux 2.6.38) dans mode désalloue l'espace (c'est-à-dire crée un trou) dans l'intervalle d'octets commençant à offset et continuant pendant len octets. Dans l'espace indiqué, les blocs partiels de systèmes de fichiers sont mis à zéro et les blocs complets de systèmes de fichiers sont retirés du fichier. Après un appel réussi, les lectures suivantes dans cet intervalle renverront des zéros.

Le paramètre FALLOC_FL_PUNCH_HOLE doit être inclus avec FALLOC_FL_KEEP_SIZE dans mode (avec un OU binaire) ; autrement dit, même en faisant des trous après la fin du fichier, la taille du fichier (comme indiquée par stat(2)) ne changera pas.

Les systèmes de fichiers ne prennent pas tous FALLOC_FL_PUNCH_HOLE en charge ; si un système de fichiers n'accepte pas l'opération, une erreur est renvoyée. L'opération est prise en charge notamment par les systèmes de fichiers suivants :

*: XFS (depuis Linux 2.6.38)
*: ext4 (depuis Linux 3.0)
*: Btrfs (depuis Linux 3.7)
*: tmpfs (depuis Linux 3.5)

Réduction d'espace de fichier

Indiquer le paramètre FALLOC_FL_COLLAPSE_RANGE (disponible depuis Linux 3.15) dans mode supprime un intervalle d'octets d'un fichier sans laisser de trou. L'intervalle commence à offset et continue pendant len octets. Une fois l'opération terminée, les contenus du fichier au-délà de offset+len seront déplacés à l'emplacement offset, le fichier sera alors alors len octets plus court.

Un système de fichier peut limiter la granularité de l'opération, pour conserver une mise en œuvre efficace. Typiquement, offset et len doivent être multiples de la taille de bloc du système de fichier, qui est fonction du type de système de fichier et de sa configuration. Si cette exigence est applicable au système de fichier mais n'est pas remplie, fallocate() échouera avec l'erreur EINVAL.

Si la plage définie par offset et len atteint ou dépasse la fin du fichier, une erreur est renvoyée. Le fichier devrait être tronqué avec ftruncate(2).

Aucun autre attribut de ne peut être indiqué dans mode en plus de FALLOC_FL_COLLAPSE_RANGE.

Linux 3.15 prend en charge FALLOC_FL_COLLAPSE_RANGE pour ext4 (seulement pour les fichiers à base de domaines ou « extent ») et XFS.

Initialisation d'espace de fichier

Indiquer le paramètre FALLOC_FL_ZERO_RANGE (disponible depuis Linux 3.14) dans mode initialise l'intervalle d'octets commençant à offset et continuant pendant len octets. Dans l'espace indiqué, les blocs sont préalloués pour les zones qui couvrent les trous du fichier. Après un appel réussi, les lectures suivantes dans cet intervalle renverront des zéros.

L’initialisation est réalisée dans le système de fichier de préférence en convertissant l’intervalle en « extents » non écrits. Cette approche signifie que l’intervalle indiqué ne sera pas physiquement initialisé sur le périphérique (à part les blocs partiels aux extrémités de l’intervalle) et qu’une E/S n’est (sinon) nécessaire que pour mettre à jour les métadonnées.

Si l'attribut FALLOC_FL_KEEP_SIZE est également indiqué dans mode, le comportement de l'appel est similaire, mais la taille du fichier ne sera pas modifiée si offset+len est supérieur à la taille du fichier. Le comportement est le même lorsque de l'espace est préalloué et que FALLOC_FL_KEEP_SIZE est indiqué.

Les systèmes de fichiers ne prennent pas tous FALLOC_FL_ZERO_RANGE en charge ; si un système de fichiers n'accepte pas l'opération, une erreur est renvoyée. L'opération est prise en charge notamment par les systèmes de fichiers suivants :

*: XFS (depuis Linux 3.14)
*: ext4, pour les fichiers à base de domaines (« extent ») (depuis Linux 3.0)

VALEUR RENVOYÉE

En cas de succès, fallocate() renvoie 0. En cas d'erreur, -1 est renvoyé et errno contient le code d'erreur.

ERREURS

EBADF: fd n'est pas un descripteur de fichier valable ou n'est pas ouvert en écriture.
EFBIG: offset+len excède la taille maximum de fichier.
EINTR: Un signal a été capturé pendant l'exécution.
EINVAL: offset était inférieur à 0, ou len était inférieur ou égal à 0.
EINVAL: mode vaut FALLOC_FL_COLLAPSE_RANGE et la plage indiquée par offset et len atteint ou dépasse la fin du fichier.
EINVAL: mode vaut FALLOC_FL_COLLAPSE_RANGE, mais offset ou len n'est pas un multiple de la taille du bloc du système de fichiers.
EINVAL: mode contient FALLOC_FL_COLLAPSE_RANGE ainsi que d'autres attributs, mais aucun autre attribut n'est autorisé avec FALLOC_FL_COLLAPSE_RANGE.
EINVAL: mode vaut FALLOC_FL_COLLAPSE_RANGE ou FALLOC_FL_ZERO_RANGE, mais le fichier référencé par fd n'est pas un fichier normal.
EIO: Une erreur d'entrée-sortie s'est produite durant la lecture ou l'écriture sur un système de fichiers.
ENODEV: fd ne fait pas référence à un fichier régulier ou un répertoire (si fd est un tube ou une FIFO, une erreur différente en résultera).
ENOSPC: Il n'y a pas suffisamment d'espace disponible sur le périphérique où se trouve le fichier référencé par fd.
ENOSYS: Ce noyau ne met pas en œuvre fallocate().
EOPNOTSUPP: Le système de fichiers contenant le fichier référencé par fd ne gère pas cette opération, ou le mode n'est pas pris en charge par le système de fichiers contenant le fichier référencé par fd.
EPERM: Le fichier indiqué par fd est marqué immuable (consultez chattr(1)). Ou : mode indique FALLOC_FL_PUNCH_HOLE ou FALLOC_FL_COLLAPSE_RANGE et le fichier indiqué par fd est marqué en ajout uniquement (consulter chattr(1)).
ESPIPE: fd fait référence à un tube ou une FIFO.
ETXTBSY: mode indique FALLOC_FL_COLLAPSE_RANGE, mais le fichier référencé par fd est en cours d'exécution.

VERSIONS

fallocate() est disponible dans Linux depuis le noyau 2.6.23. La glibc le prend en charge depuis la version 2.10. Les paramètres FALLOC_FL_* ne sont définis dans les en-têtes de la glibc que depuis la version 2.18.

CONFORMITÉ

fallocate() est spécifique à Linux.

VOIR AUSSI

fallocate(1), ftruncate(2), posix_fadvise(3), posix_fallocate(3)

COLOPHON

Cette page fait partie de la publication 3.66 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse http://www.kernel.org/doc/man-pages/.

TRADUCTION

Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <perkamon-fr@traduc.org>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».

Index

NOM

SYNOPSIS

DESCRIPTION

Allocation d'espace disque.
Désallocation d'espace de fichier
Réduction d'espace de fichier
Initialisation d'espace de fichier

This document was created by man2html, using the manual pages.
Time: 21:52:34 GMT, July 12, 2014