Ubuntu Manpage: fallocate - Manipuler un espace de fichier

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.

Si l'attribut FALLOC_FL_UNSHARE est indiqué dans mode, les extensions de données du
fichier partagé seront privées pour le fichier afin de garantir que l'écriture suivante
n'échouera pas du fait d'un manque d'espace. Généralement, cela se fera par une opération
copy-on-write sur toutes les données partagées du fichier. Cet attribut peut ne pas être
pris en charge par tous les systèmes de fichiers.

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 incomplets du
système de fichiers sont mis à zéro et tous les blocs du système 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(5) (depuis Linux 3.5)

– gfs2(5) (depuis Linux 4.16)

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, le contenu du
fichier au-delà de offset+len est déplacé à l'emplacement offset, le fichier sera alors
len octets plus court.

Un système de fichiers peut limiter la granularité de l'opération, pour garantir une
implémentation efficace. Typiquement, offset et len doivent être multiples de la taille de
bloc du système de fichiers, qui est en fonction du type de système de fichiers et de sa
configuration. Si cette exigence est applicable au système de fichiers 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.15) dans mode met à
zéro l'espace dans l'intervalle d'octets commençant à offset et continuant pendant
len octets. Dans l'intervalle 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 fichiers 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 entrée ou sortie 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.15)

– ext4, pour les fichiers à base de domaines (« extent ») (depuis Linux 3.15)

– SMB3 (depuis Linux 3.17)

– Btrfs (depuis Linux 4.16)

Augmenter l'espace de fichier
Indiquer le paramètre FALLOC_FL_INSERT_RANGE (disponible depuis Linux 4.1) dans mode
augmente l'espace d'un fichier en insérant un trou dans la taille du fichier sans effacer
de données. Le trou commencera à offset et continuera pendant len octets. Lors de
l'insertion d'un trou dans un fichier, le contenu du fichier à partir de offset sera
décalé vers le haut (à savoir vers la position du fichier supérieure) de len octets.
L'insertion d'un trou dans un fichier augmente sa taille de len octets.

Ce mode a les mêmes limites que FALLOC_FL_COLLAPSE_RANGE concernant la granularité des
opérations. Si les exigences de granularité ne sont pas satisfaites, fallocate() échoue
avec l'erreur EINVAL. Si offset est égal ou supérieur à la fin du fichier, une erreur est
renvoyée. Pour de telles opérations (à savoir l'insertion d'un trou à la fin du fichier),
ftruncate(2) doit être utilisé.

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

FALLOC_FL_INSERT_RANGE requiert une prise en charge par le système de fichiers. Les
systèmes de fichiers qui gèrent cette opération comprennent XFS (dans Linux 4.1) et ext4
(depuis Linux 4.2).

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 maximale du fichier.

EFBIG mode vaut FALLOC_FL_INSERT_RANGE et la taille du fichier + len dépasse la taille
maximale du fichier.

EINTR Un signal a été capturé pendant l'exécution ; voir signal(7).

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_INSERT_RANGE et la plage indiquée par offset atteint ou dépasse
la fin du fichier.

EINVAL mode vaut FALLOC_FL_COLLAPSE_RANGE ou FALLOC_FL_INSERT_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 ou FALLOC_FL_INSERT_RANGE ainsi que d'autres
attributs, mais aucun autre attribut n'est autorisé avec FALLOC_FL_COLLAPSE_RANGE
ou FALLOC_FL_INSERT_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 auquel se réfère fd est marqué comme immuable (voir chattr(1)).

EPERM mode indique FALLOC_FL_PUNCH_HOLE, FALLOC_FL_COLLAPSE_RANGE ou
FALLOC_FL_INSERT_RANGE et le fichier auquel se réfère fd est marqué en ajout
uniquement (consulter chattr(1)).

EPERM La lecture a été interrompue par un signal ; consultez fnctl(2).

ESPIPE fd fait référence à un tube ou une FIFO.

ETXTBSY
mode indique FALLOC_FL_COLLAPSE_RANGE ou FALLOC_FL_INSERT_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 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 ⟨⟩.