fcntl − Manipuler un descripteur de fichier.

#include <unistd.h>
#include <fcntl.h>

int fcntl(int fd, int cmd);
int fcntl(int fd, int cmd, long arg);
int fcntl(int fd, int cmd, struct flock *lock);

La fonction fcntl permet de se livrer à diverses opérations sur le descripteur de fichier fd. L’opération en question est déterminée par la valeur de l’argument cmd :

F_DUPFD

effectue une copie de fd, dans arg en fermant d’abord arg si besoin est.

On peut effectuer la même chose plus aisément en utilisant dup2(2).

Le nouveau descripteur et l’ancien peuvent être utilises de manière interchangeable. Ils partagent le même verrou, le même position de tête de lecture/écriture, et les mêmes attributs. Par exemple, si la tête de lecture/écriture est déplacée en utilisant lseek sur l’un des deux descripteurs, la position sera également modifiée pour l’autre.

Les deux descripteurs ne partagent toutefois pas l’attribut Close−on−exec. L’attribut Close−on−exec de la copie est désactivé.

En cas de réussite, le nouveau descripteur est renvoyé par la fonction fcntl.

F_GETFD

retourne la valeur de l’attribut Close−on−exec. Si le bit de poids faible est 0, le fichier restera ouvert même au travers d’un exec, autrement il sera fermé.

F_SETFD

positionne l’attribut Close−on−Exec avec la valeur précisée par arg (seul le bit de poids le plus faible est utilisé).

F_GETFL

retourne l’ensemble des attributs positionnés lors de open(2) pour le descripteur de fichier.

F_SETFL

fixe de nouveaux attributs pour le descripteur de fichier fd. Les nouveaux attributs sont contenus dans arg. Seuls O_APPEND, O_NONBLOCK et O_ASYNC peuvent être modifiés ainsi, les autres attributs ne sont pas affectés.

à noter, les attributs sont partagés entre les différentes copies (faites avec dup(2) etc...) d’un même descripteur de fichier.

Les attributs et leurs sémantiques sont décrits dans la page de manuel de open(2).

F_GETLK, F_SETLK, et F_SETLKW

servent à gérer les verrouillages de fichiers. Le troisième argument lock est un pointeur sur une structure flock (qui peut être écrasée par l’appel)

F_GETLK

renvoie la structure flock qui nous empêche d’accéder au verrou, ou positionne le champ l_type du verrou à la valeur F_UNLCK si c’est possible.

F_SETLK

active le verrou (si l_type vaut F_RDLCK ou F_WRLCK) ou efface le verrou (si l_type vaut F_UNLCK). Si le verrou est tenu par quelqu’un d’autre, cet appel renvoie −1 et positionne errno aux valeurs EACCES ou EAGAIN.

F_SETLKW

Comme F_SETLK, mais attend la libération du verrou au lieu de retourner une erreur. Si un signal à intercepter est reçu pendant que fcntl attend, il est interrompu et renverra immédiatement (après retour du gestionnaire de signaux) la valeur −1. errno sera remplie avec la valeur EINTR.

F_GETOWN, F_SETOWN, F_GETSIG and F_SETSIG servent à gérer la disponibilité des signaux d’entrée/sortie :

F_GETOWN

obtient le PID ou l’ID du groupe de processus qui reçoit les signaux SIGIO et SIGURG pour les événements concernant le descripteur de fichier fd. Les numéros de groupes de processus sont renvoyés sous forme de valeurs négatives.

F_SETOWN

fixe le PID ou l’ID du groupe de processus qui recevront les signaux SIGIO et SIGURG pour les événements concernant le descripteur.

Les numéros de groupes de processus sont formulés en tant que valeurs négatives. (F_SETSIG peut servir à indiquer un autre signal que SIGIO).

Si vous fixez l’attribut O_ASYNC sur un descripteur de fichier (soit en utilisant ce drapeau lors de l’appel à open(2), soit en utilisant la commande F_SETFL de fcntl), un signal SIGIO est envoyé dès que l’entrée ou la sortie sont possibles sur ce descripteur. Le processus, ou le groupe de processus, susceptibles de recevoir le signal peut être indiqué avec la commande F_SETOWN de la fonction fcntl. Si le descripteur est une socket, ceci permet également la réception de signaux SIGURG lorsque des données hors-bande arrivent sur la socket. (SIGURG est émis dans toutes les situations où l’appel select(2) aurait indiqué que la socket est dans une "situation exceptionnelle"). Si le descripteur de fichier correspond à un terminal, le signal SIGIO est envoyé au groupe de processus en avant-plan sur ce terminal.

F_GETSIG

Demande l’émission d’un signal lorsque l’entrée ou la sortie deviennent possibles. Une valeur nulle signifie l’émission de SIGIO. Toute autre valeur (y compris SIGIO) précise le signal à émettre, et des informations supplémentaires seront disponibles pour le gestionnaire de signaux s’il est installé à l’aide de SA_SIGINFO.

F_SETSIG

Indique le signal à émettre lorsque l’entrée ou la sortie deviennent possibles. Une valeur nulle signifie l’émission de SIGIO. Toute autre valeur (y compris SIGIO) précise le signal à émettre, et des informations supplémentaires seront disponibles pour le gestionnaire de signaux s’il est installé à l’aide de SA_SIGINFO.

En utilisant F_SETDIG avec une valeur non-nulle, et en configurant SA_SIGINFO pour le gestionnaire (voir sigaction(2)), des informations supplémentaires sur les événements d’E/S sont fournies au gestionnaire à travers une structure siginfo_t. Si le champ si_code indique que la source est SI_SIGIO, le champ si_fd fournit le descripteur du fichier concerné par l’événement. Sinon il n’y a pas d’indication du descripteur en attente, et il faut utiliser le mécanisme habituel (select(2), poll(2), read(2) avec O_NONBLOCK configuré etc.) pour déterminer quels descripteurs sont disponibles pour les E/S.

En sélectionnant un signal temps réel POSIX.1b (valeur >= SIGRTMIN), de multiples événements d’E/S peuvent être mémorisés avec le même numéro. (La taille de la file d’événements dépend de la mémoire libre). Des informations supplémentaires sont disponibles, comme ci-dessus, si SA_SIGINFO est configuré pour le gestionnaire.

En utilisant ces mécanismes, un programme peut implémenter des E/S totalement asynchrones, la plupart du temps sans avoir besoin d’invoquer select(2) ou poll(2).

L’utilisation de O_ASYNC, F_GETOWN, est spécifique BSD et Linux.

F_GETSIG et F_SETSIG sont spécifiques à Linux. POSIX disposent d’E/S asynchrones et de la structure aio_sigevent pour effectuer la même chose. Ceci est également disponible sous Linux dans la bibliothèque GNU C (Glibc).

La valeur renvoyée par fcntl varie suivant le type d’opération :

F_DUPFD

renvoie le nouveau descripteur.

F_GETFD

renvoie l’état de l’attribut.

F_GETFL

renvoie l’état des attributs.

F_GETOWN

renvoie le propriétaire du fichier.

F_GETSIG

Valeur du signal envoyé lorsque la lecture ou l’écriture deviennent possibles, ou zéro pour le comportement SIGIO traditionnel.

En cas d’échec −1 est renvoyé, auquel cas errno contient le code d’erreur.

EACCESS

L’opération est rendue impossible à cause d’un verrou maintenu par un autre processus.

EAGAIN

L’opération est rendue impossible à cause d’une projection en mémoire effectuée par un autre processus.

EBADF

fs n’est pas un descripteur de fichier ouvert, ou la commande était F_SETLK ou F_SETLKW et le mode d’ouverture du descripteur de fichier ne correspond pas à celui du type de verrou demandé.

EDEADLK

Le verrouillage en écriture conduirait à un blocage.

EFAULT

lock se trouve en dehors de l’espace d’adressage.

EINTR

Pour F_SETLKW, la commande a été interrompue par un signal. Pour F_GETLK et F_SETLK, la commande a été interrompue par un signal avant la vérification ou l’acquisition du verrou. Se produit surtout lors d’un verrouillage distant (par exemple à travers NFS), mais peut également arriver localement.

EINVAL

Pour F_DUPFD, arg est soit négatif, soit trop grand. Pour F_SETSIG, arg n’est pas un numéro de signal correct.

EMFILE

Pour F_DUPFD, le processus a déjà ouvert le nombre maximal de descripteurs de fichiers.

ENOLCK

La table des verrous est pleine.

EPERM

Essai d’effacement de l’attribut O_APPEND sur un fichier, mais il est considéré comme en-ajout-seulement.

Les erreurs renvoyées par dup2 ne sont pas les mêmes que celles renvoyées par fcntl avec la commande F_DUPFD.

SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Seules les opérations F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK et F_SETLKW sont spécifiées dans POSIX.1. F_GETOWN et F_SETOWN sont des BSDismes non supportés par SVr4. F_GETSIG et F_SETSIG sont spécifiques à Linux. Les attributs autorisés pour F_GETFL/F_SETFL sont ceux supportés par open(2) et peuvent être différents suivant les systèmes. O_APPEND, O_NONBLOCK, O_RDONLY, et O_RDWR sont spécifiés par POSIX.1. SVr4 propose plusieurs autres options et attributs non documentés ici.

SVr4 indique des erreurs EIO, ENOLINK et EOVERFLOW supplémentaires.

dup2(2), open(2), socket(2), flock(2)

Christophe Blaess, 1997.