fallocate - Manipuler un espace de fichier
Bibliothèque C standard (
libc,
-lc)
#define _GNU_SOURCE /* Consultez feature_test_macros(7) */
#include <fcntl.h>
int fallocate(int fd, int mode, off_t offset, off_t len);
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.
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é.
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)
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.
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)
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).
En cas de succès,
fallocate() renvoie
0. En cas d'erreur,
-1 est renvoyé et
errno contient le code d'erreur.
- 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,
FALLOC_FL_ZERO_RANGE ou FALLOC_FL_INSERT_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.
fallocate() est disponible depuis Linux 2.6.23. Une prise en
charge est fournie par la glibc 2.10. Les attributs
FALLOC_FL_*
ne sont définis dans les en-têtes de la glibc que depuis la
glibc 2.18.
fallocate() est spécifique à Linux.
fallocate(1),
ftruncate(2),
posix_fadvise(3),
posix_fallocate(3)
La traduction française de cette page de manuel a été
créée par Christophe Blaess
<
https://www.blaess.fr/christophe/>, Stéphan Rafin
<
[email protected]>, Thierry Vignaud
<
[email protected]>, François Micaux, Alain Portal
<
[email protected]>, Jean-Philippe Guérard
<
[email protected]>, Jean-Luc Coulon (f5ibh)
<
[email protected]>, Julien Cristau
<
[email protected]>, Thomas Huriaux <
[email protected]>,
Nicolas François <
[email protected]>, Florentin
Duneau <
[email protected]>, Simon Paillard
<
[email protected]>, Denis Barbier
<
[email protected]>, David Prévot <
[email protected]> et
Jean-Philippe MENGUAL <
[email protected]>
Cette traduction est une documentation libre ; veuillez vous reporter
à la
GNU
General Public License version 3 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 à
[email protected]