fallocate

NOM

BIBLIOTHÈQUE

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

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.

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

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

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

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

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

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 + size 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.

STANDARDS

HISTORIQUE

fallocate()

Linux 2.6.23, glibc 2.10.

FALLOC_FL_*

glibc 2.18.

VOIR AUSSI

TRADUCTION

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 à

Index

NOM

BIBLIOTHÈQUE

SYNOPSIS

DESCRIPTION

Allocation d'espace disque.

Désallocation d'espace de fichier

Réduction d'espace de fichier

Initialisation d'espace de fichier

Augmenter l'espace de fichier

VALEUR RENVOYÉE

ERREURS

STANDARDS

HISTORIQUE

VOIR AUSSI

TRADUCTION