sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy - opérations sur les sémaphores.

#include <semaphore.h>

int sem_init(sem_t *sem, int pshared, unsigned int valeur);

int sem_wait(sem_t * sem);

int sem_trywait(sem_t * sem);

int sem_post(sem_t * sem);

int sem_getvalue(sem_t * sem, int * sval);

int sem_destroy(sem_t * sem);

Cette page de manuel documente les sémaphores du standard POSIX 1003.1b, à ne pas confondre avec ceux des IPC Système V tels que décrits par ipc(5), semctl(2) et semop(2).

Les sémaphores sont des compteurs pour les ressources partagées par plusieurs threads. Les opérations de base sur les sémaphores sont :

incrémenter le compteur de manière atomique

attendre que le compteur soit non-nul et décrémenter le compteur de manière atomique.

sem_init initialise le sémaphore pointé par sem. Le compteur associé au sémaphore est initialisé à valeur. L'argument pshared indique si le sémaphore est local au processus courrant (pshared est zéro) ou partagé entre plusieurs processus (pshared n'est pas nulle). LinuxThreads ne gère actuellement pas les sémaphores partagés entre plusieurs processus, donc sem_init renvoie toujours l'erreur ENOSYS si pshared n'est pas nul.

sem_wait suspend le thread appelant jusqu'à ce que le sémaphore pointé par sem ait un compteur non nul. Alors, le compteur du sémaphore est atomiquement décrémenté.

sem_trywait est une variante non bloquante de sem_wait. Si le sémaphore pointé par sem a une valeur non nulle, le compteur est atomiquement décrémenté et sem_trywait retourne immédiatement 0. Si le compteur du sémaphore est zéro, sem_trywait retourne immédiatement en indiquant l'erreur EAGAIN.

sem_post incrémente atomiquement le compteur du sémaphore pointé par sem. Cetts fonction ne bloque jamais et peut être utilisée de manière fiable dans un gestionnaire de signaux.

sem_getvalue sauvegarde à l'emplacement pointé par sval la valeur courrante du compteur du sémaphore sem.

sem_destroy détruit un sémaphore, libérant toutes les ressources qu'il possédait. Aucun thread ne doit être bloqué sur ce sémaphore quand sem_destroy est appelée. Dans l'implémentation LinuxThreads, aucune ressource ne peut être associée à un sémaphore, donc sem_destroy ne fait actuellement rien si ce n'est vérifier qu'aucun thread n'est bloqué sur ce sémaphore.

sem_wait est un point d'annulation.

Sur les processeurs proposant une opération test_et_échange (Intel 486, Pentium+, Alpha, PowerPC, MIPS II, Motorola 68k), la fonction sem_post est atomique en ce qui concerne le traitement ds signaux asynchrones. Elle peut donc être appelée par un gestionnaire de signal. C'est la seule fonction de synchronisation de threads définie par POSIX qui soit réentrante vis-à-vis des signaux asynchrones.

Sur les Intel 386 et les Sparc, l'implémentation courante de sem_post par LinuxThreads n'est pas atomique car le langage machine ne fournit pas d'instructions atomiques. L'utilisation de sem_post dans un gestionnaire de signal n'est donc pas fiable, deux signaux simultanés pouvant amener à n'enregistrer qu'une seule action.

Les fonctions sem_wait et sem_getvalue renvoient toujours 0. Toutes les autres fonctions relatives aux sémaphores renvoient zéro en cas de succès et -1 en cas d'erreur. Dans ce dernier cas, la variable errno est positionné au code d'erreur correspondant.

La fonction sem_init remplit errno avec l'un des codes d'erreur suivants :

EINVAL

valeur dépasse la valeur maximale du compteur. SEM_VALUE_MAX

ENOSYS

pshared n'est pas zéro.

La fonction sem_trywait remplit errno avc l'un des codes d'erreur suivants :

EAGAIN

le compteur du sémaphore vaut actuellement 0.

La fonction sem_post remplit errno avec l'un des codes d'erreur suivants :

ERANGE

après l'incrémentation, la valeur du sémaphore aurait dépassé SEM_VALUE_MAX (Le compteur du sémaphore n'est pas modifié dans ce cas)

La fonction sem_destroy remplit errno avec l'un des codes d'erreur suivants :

EBUSY

certains threads sont actuellement bloqués en attente sur le sémaphore.

Xavier Leroy <Xavier.Leroy@inria.fr>

pthread_mutex_init(3), pthread_cond_init(3), pthread_cancel(3), ipc(5).

Thierry Vignaud <tvignaud@mandrakesoft.com>, 2000