GETSOCKOPT

Section: Manuel du programmeur Linux (2)
Updated: 18 Mai 1999
Index Retour au Menu Principal

 

NOM

getsockopt, setsockopt - Lire / écrire les options d'une socket.  

SYNOPSIS

#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);  

DESCRIPTION

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.

 

VALEUR RENVOYÉE

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

ERREURS

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.

 

CONFORMITÉ

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.

 

BOGUES

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

NOTE

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

VOIR AUSSI

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

 

TRADUCTION

Christophe Blaess, 1997.


 

Index

NOM
SYNOPSIS
DESCRIPTION
VALEUR RENVOYÉE
ERREURS
CONFORMITÉ
BOGUES
NOTE
VOIR AUSSI
TRADUCTION

Time: 21:39:43 GMT, December 19, 2004