FANOTIFY_INIT

Manuel du programmeur Linux (2)
24 avril 2014

NOM

fanotify_init - Créer et initialiser un groupe fanotify

SYNOPSIS

#include <fcntl.h>
#include <sys/fanotify.h>

int fanotify_init(unsigned int flags, unsigned int event_f_flags);

DESCRIPTION

Pour un aperçu de l’interface de programmation fanotify, consultez fanotify(7).

fanotify_init() initialise un nouveau groupe fanotify et renvoie un descripteur de fichier pour la file d’événements associée au groupe.

Le descripteur de fichier est utilisé dans les appels de fanotify_mark(2) pour indiquer les fichiers, répertoires et points de montage pour lesquels les événements fanotify seront créés. Ces événements sont reçus en lisant le descripteur de fichier. Certains événements ne sont qu’informatifs, indiquant qu’un fichier doit être accédé. D’autres événements peuvent être utilisés pour déterminer si une autre application a le droit d’accéder à un fichier ou répertoire. Le droit d’accéder aux objets de système de fichiers est accordé en écrivant dans le descripteur de fichier.

Plusieurs programmes peuvent utiliser l’interface fanotify en même temps pour surveiller les mêmes fichiers.

Dans l’implémentation actuelle, le nombre de groupes fanotify par utilisateur est limité à 128. Cette limite ne peut pas être écrasée.

Appeler fanotify_init() nécessite la capacité CAP_SYS_ADMIN. Cette contrainte pourrait être levée dans les prochaines versions de l’interface de programmation. Par conséquent, certaines vérifications supplémentaires de capacité ont été mises en place comme indiqué ci-dessous.

L’argument flags contient un champ multibit définissant la classe de notification de l’application écoutant et d’autres champs monobits indiquant le comportement du descripteur de fichier.

Si plusieurs écoutants d’événements de permission existent, la classe de notification est utilisée pour établir l’ordre dans lequel les écoutants reçoivent les événements.

Une seule des classes de notification suivantes peut être indiquée dans flags.

FAN_CLASS_PRE_CONTENT: Cette valeur permet de recevoir des événements notifiant qu’un fichier a été accédé et les événements de décisions de permission si un fichier peut être accédé. Elle est conçue pour les écoutants d’événement qui doivent accéder aux fichiers avant qu’ils ne contiennent leurs données finales. Cette classe de notification pourrait être utilisée par exemple par des gestionnaires de stockage hiérarchisé.
FAN_CLASS_CONTENT: Cette valeur permet de recevoir des événements notifiant qu’un fichier a été accédé et les événements de décisions de permission si un fichier peut être accédé. Elle est conçue pour les écoutants d’événement qui doivent accéder aux fichiers quand ils contiennent déjà leur contenu final. Cette classe de notification pourrait être utilisée par exemple par des programmes de détection de logiciels malveillants.
FAN_CLASS_NOTIF: C’est la valeur par défaut. Elle n’a pas besoin d’être indiquée. Cette valeur ne permet de recevoir que des événements notifiant qu’un fichier a été accédé. Les décisions de permission avant que le fichier ne soit accédé ne sont pas possibles.

Les écoutant avec différentes classes de notification recevront les événements dans l’ordre FAN_CLASS_PRE_CONTENT, FAN_CLASS_CONTENT, FAN_CLASS_NOTIF. L’ordre de notification pour les écoutants dans la même classe de notification n’est pas défini.

Les bits suivants peuvent de plus être définis dans flags.

FAN_CLOEXEC: Placer l'attribut « close-on-exec » (FD_CLOEXEC) sur le nouveau descripteur de fichier. Consultez la description de l'attribut O_CLOEXEC dans open(2).
FAN_NONBLOCK: Activer l’attribut non bloquant (O_NONBLOCK) pour le descripteur de fichier. La lecture du descripteur de fichier ne bloquera pas. À la place, si aucune donnée n’est disponible, read échouera avec l’erreur EAGAIN.
FAN_UNLIMITED_QUEUE: Supprimer la limite de 16384 événements pour la file d’événements. L’utilisation de cet attribut nécessite la capacité CAP_SYS_ADMIN.
FAN_UNLIMITED_MARKS: Supprimer la limite de 8192 marques. L’utilisation de cet attribut nécessite la capacité CAP_SYS_ADMIN.

L’argument event_f_flags définit les attributs d’état de fichier qui seront définis sur les descriptions de fichier ouvertes qui sont créées pour les événements fanotify. Pour plus de précisions sur ces attributs, consultez la description des valeurs de flags dans open. Les valeurs utiles sont les suivantes.

O_RDONLY: Cette valeur permet l’accès en lecture seule.
O_WRONLY: Cette valeur permet l’accès en écriture seule.
O_RDWR: Cette valeur permet l’accès en lecture et écriture.
O_CLOEXEC: Activer l’attribut « close-on-exec » pour le descripteur de fichier.
O_LARGEFILE: Activer la prise en charge de fichiers dépassant 2 Go. Sans cet attribut, une erreur EOVERFLOW surviendra lors d’une tentative d’ouverture d’un gros fichier surveillé par un groupe fanotify sur un système 32 bits.

VALEUR RENVOYÉE

S'il réussit, fanotify_init() renvoie un nouveau descripteur de fichier. En cas d'erreur, il renvoie -1 et errno contient le code d'erreur.

ERREURS

EINVAL: Une valeur incorrecte a été passée dans flags. FAN_ALL_INIT_FLAGS définit tous les bits permis.
EMFILE: Le nombre de groupes fanotify pour cet utilisateur dépasse 128.
ENOMEM: Échec d’allocation mémoire pour le groupe de notification.
ENOSYS: Ce noyau n’implémente pas fanotify_init(). L’interface de programmation fanotify n'est disponible que si le noyau a été configuré avec CONFIG_FANOTIFY.
EPERM: L’opération n’est pas permise car l’appelant n’a pas la capacité CAP_SYS_ADMIN.

VERSIONS

fanotify_init() a été introduit dans la version 2.6.36 du noyau Linux et activé dans la version 2.6.37.

CONFORMITÉ

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

BOGUES

Dans Linux 3.15, le bogue suivant existe :

-: l’argument event_f_flags n’est pas vérifié pour les attribut incorrects. Les attributs qui ne sont conçus que pour une utilisation interne, comme FMODE_EXEC, peuvent être définis, et seront ensuite définis pour les descripteurs de fichier renvoyés lors de la lecture depuis le descripteur de fichier fanotify.

VOIR AUSSI

fanotify_mark(2), fanotify(7)

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/>.

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> ».

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