getsockopt, setsockopt − Lire / écrire les options d’une socket.

#include <sys/types.h>
#include <sys/socket.h>

int getsockopt(int s, int level, int optname, void *optval, socklen_t *optlen);

int setsockopt(int s, int level, int optname, const void *optval, socklen_t optlen);

Getsockopt et setsockopt manipulent les options associées à une socket. Ces options peuvent exister aux divers niveaux du protocole, et sont toujours présentes au niveau socket le plus élevé.

Quand on manipule une option d’une socket, il faut préciser le niveau où elle s’applique, et le nom de l’option. Au niveau socket, level prend la valeur SOL_SOCKET. Pour tous les autres niveaux, il faut fournir le numéro de protocole approprié. Par exemple, pour une option interprétée par le niveau de protocole TCP, level prendra le numéro de protocole TCP. Voir getprotoent(3).

Les paramètres optval et optlen sont utilisés pour déterminer les options pour setsockopt. Pour getsockopt ils identifient un buffer dans lequel la valeur de l’option désirée doit être renvoyée. Pour getsockopt, optlen est un paramètre résultat, contenant initialement la taille du buffer pointé par optval, et rempli en retour pour indiquer la taille effective des valeurs renvoyées. Si aucune option n’est fournie ou renvoyée, optval peut être NULL.

Optname et toute autre option sont passées sans interprétation au protocole approprié, pour qu’il l’interprète lui-même. Le fichier d’en-tête sys/socket.h contient les définitions pour le niveau socket, décrites ci-dessous. Les options pour les autres niveaux de protocole, peuvent varier tant en format qu’en nom, consulter les pages de manuel de la section 4 pour plus d’informations.

La plupart des options au niveau socket utilisent un paramètre de type int pour optval.

Pour setsockopt, un paramètre non nul valide une option booléenne, et zéro l’invalide.

SO_LINGER utilise un paramètre de type struct linger défini dans sys/socket.h, qui indique l’état désiré et le délai de persistance (voir plus bas)

SO_SNDTIMEO et SO_RCVTIMEO utilisent un paramètre de type struct timeval défini dans sys/time.h.

Les options suivantes sont traitées au niveau socket. Sauf indication contraire, elles peuvent toutes être examinées avec getsockopt et positionnées avec setsockopt.

SO_DEBUG

autorise l’enregistrement d’information de débugging

SO_REUSEADDR

autorise la réutilisation de l’adresse locale

SO_KEEPALIVE

valide la transmission périodique automatique

SO_DONTROUTE

inhibe le routage en émission

SO_LINGER

persistance des messages restants en cas de rupture de liaison

SO_BROADCAST

autorise la diffusion des messages

SO_OOBINLINE

valide la réception de messages hors-bande

SO_SNDBUF

fixe la taille du buffer d’émission

SO_RCVBUF

fixe la taille du buffer de réception

SO_SNDLOWAT

fixe le seuil minimum du buffer en émission

SO_RCVLOWAT

fixe le seuil minimum du buffer en réception

SO_SNDTIMEO

lit la valeur de timeout en émission (seulement en lecture)

SO_RCVTIMEO

lit la valeur de timeout en réception (seulement en lecture)

SO_TYPE

lit le type de socket (seulement en lecture)

SO_ERROR

lit les erreurs en attente (seulement en lecture)

SO_DEBUG autorise le débugging dans les modules de protocoles sous-jacents.

SO_REUSEADDR indique que les règles de validation d’adresse utilisées dans la fonction bind(2) doivent autoriser la réutilisation des adresses locales.

SO_KEEPALIVE valide la transmission périodique d’un message sur une socket en mode connecté. Si le correspondant ne répond plus à ces messages, la connexion est considérée comme interrompue, et les processus utilisant la socket en sont informés par un signal SIGPIPE lorsqu’il tentent d’émettre.

SO_DONTROUTE indique que les messages émis doivent contourner les options de routage. A la place les messages sont envoyés directement à l’interface réseau appropriée, en utilisant la partie réseau de l’adresse de destination.

SO_LINGER configure les actions à entreprendre s’il reste des messages en attente d’émission alors qu’un close(2) est effectué sur la socket. Si la socket nécessite une délivrance garantie des messages, SO_LINGER est validé, l’appel à close sera bloquant pour le processus jusqu’à ce que les données aient été envoyées, ou jusqu’à ce qu’il renonce à l’émission (un délai de timeout, appelé persistance est spécifié dans l’appel setsockopt avec SO_LINGER).

Si SO_LINGER est désactive et que l’on appelle close le système fermera la connexion de façon à permettre au processus de continuer le plus rapidement possible.

La structure linger est définie ainsi dans <linux/socket.h>

struct linger {
        int  l_onoff;   /* Linger active */
        int  l_linger;  /* How long to linger for */
};

l_onoff indique s’il y a ou non persistance. Si ce champ vaut 1 alors l_linger contient la durée de persistance en 100ièmes de secondes avant de terminer le close. Si l_onoff vaut zéro, le processus retournera immédiatement.

L’option SO_BROADCAST demande l’autorisation de pouvoir diffuser des datagrammes "broadcast" sur la socket. Dans les premières versions du système, la diffusion broadcast était une option privilégiée.

Avec les protocoles qui acceptent les données hors−bande, l’option SO_OOBINLINE demande que ces données hors−bande soient placées dans la file de réception des données normales. Elles seront accessibles avec recv ou read sans l’attribut MSG_OOB. Certains protocoles se comportent toujours comme si cette option était validée.

SO_SNDBUF et SO_RCVBUF sont respectivement des options permettant d’ajuster la taille des buffers alloués pour l’émission et la réception. La taille des buffers peut être augmentées pour des connexions avec un trafic important. Il y a des limites imposées par le système pour ces valeurs.

SO_SNDLOWAT est une option permettant de fixer le seuil inférieur pour le buffer d’émission. La plupart des processus transmettent toutes leurs données au protocole qui assure le contrôle de flux.

Les opérations d’émissions non−bloquantes vont traiter autant de données que possible sans blocage, mais ne traiteront pas les données si le contrôle de flux ne permet pas la transmission de la plus petite valeur entre le seuil inférieur du buffer et la taille effective des données à émettre.

Un appel à select(2) pour tester la possibilité d’écrire sur une socket retournera vrai seulement si le seuil inférieur du buffer peut être transmis.

La valeur par défaut de SO_SNDLOWAT est configurée à une taille optimale pour le réseau, souvent 1024.

SO_RCVLOWAT est une option fixant le seuil inférieur du buffer de réception. En général, les appels en lecture bloqueront jusqu’à ce qu’une quantité non nulle de données soient disponible, et retourneront ensuite la plus petite valeur entre les données effectivement disponible et la quantité demandée.

La valeur par défaut de SO_SNDLOWAT est 1. Si SO_SNDLOWAT est fixé à une valeur plus grande, la lecture bloquante attendra de disposer de la plus petite valeur entre le seuil fixe et la quantité de données demandée.

Les fonctions de lecture peuvent toutefois retourner moins de données que le seuil inférieur si une erreur est survenue, ou si un signal est arrivé.

SO_SNDTIMEO est une option permettant de lire le délai de timeout pour les émissions, qui ne peut être utilisée qu’avec getsockopt. Elle utilise un paramètre de type struct timeval comprenant le nombre maximal de secondes et de micro-secondes pour l’attente en émission. Si une fonction d’émission dure plus longtemps, elle retournera un nombre partiel de données émises, ou éventuellement une erreur EWOULDBLOCK si aucune donnée n’a été envoyée. Dans les implémentations actuelles, la temporisation est réinitialisée chaque fois que de nouvelles données sont transmises au protocole. Le délai s’applique donc à la transmission du volume de données compris entre les seuils inférieur et supérieur du buffer.

SO_RCVTIMEO est une option permettant de lire le délai de timeout pour les réceptions, qui ne peut être utilisée qu’avec getsockopt. Elle utilise un paramètre de type struct timeval comprenant le nombre maximal de secondes et de micro-secondes pour l’attente en réception. Dans les implémentations actuelles, la temporisation est réinitialisée chaque fois que de nouvelles données sont reçues par le protocole, il s’agit donc d’un délai d’inactivité. Si une fonction de réception dure plus longtemps, elle retournera un nombre partiel de données reçues, ou éventuellement une erreur EWOULDBLOCK si aucune donnée n’a été reçue.

Enfin SO_TYPE et SO_ERROR sont des options utilisées uniquement avec getsockopt. SO_TYPE renvoie le type de socket (par exemple : SOCK_STREAM ), ce qui est utile pour des serveurs héritant des sockets au démarrage. SO_ERROR renvoie une éventuelle erreur en attente, et réinitialise le statut des erreurs. Cette fonction peut être utilisée pour vérifier des erreurs asynchrones sur des datagrammes connectés par exemple.

getsockopt et setsockopt renvoient 0 s’ils réussissent, ou −1 s’ils échouent, auquel cas errno contient le code d’erreur.

EBADF

L’argument s n’est pas un descripteur valide.

ENOTSOCK

L’argument s est un fichier, pas une socket.

ENOPROTOOPT

L’option est inconnue pour ce protocole.

EFAULT

optval pointe en dehors de l’espace d’adressage accessible. Avec getsockopt, ceci peut s’appliquer également à optlen.

SVr4, 4.4BSD (Ces appels systèmes sont apparus dans 4.2BSD). SVr4 présente des codes d’erreurs supplémentaires ENOMEM et ENOSR, mais ne documente pas les options SO_SNDLOWAT, SO_RCVLOWAT, SO_SNDTIMEO, SO_RCVTIMEO.

Plusieurs options sur les sockets devraient être gérées à un niveau plus bas par le système.

Le cinquième argument de getsockopt et setsockopt est en fait un int (et c’est ce qu’utilisent BSD 4.*, libc4 et libc5). Une certaine confusion POSIX résulte du "socklen_t" actuel. Les propositions de standard n’ont pas encore été adoptées, mais glibc2 les suit déjà et utilise socklen_t. Pour plus de détails voir accept(2).

ioctl(2), socket(2), getprotoent(3), protocols(5)

Christophe Blaess, 1997.