GETSOCKOPT(2) Manuel du programmeur Linux GETSOCKOPT(2)
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 *opt
val, 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éter
miner 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 indi
quer 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 proto
cole, peuvent varier tant en format qu'en nom, consulter
les pages de manuel de la section 4 pour plus d'informa
tions.
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
Linux 18 Mai 1999 1
GETSOCKOPT(2) Manuel du programmeur Linux GETSOCKOPT(2)
défini dans sys/socket.h, qui indique l'état désiré et le
délai de persistence (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ébug
ging
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
persistence des messages restants en cas de rup
ture 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)
Linux 18 Mai 1999 2
GETSOCKOPT(2) Manuel du programmeur Linux GETSOCKOPT(2)
SO_ERROR
lit les erreurs en attente (seulement en lecture)
SO_DEBUG autorise le débugging dans les modules de proto
coles 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 mes
sage 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 con
tourner 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é persis
tance est spécifié dans l'appel setsockopt avec
SO_LINGER).
Si SO_LINGER est désactive et que l'on appelle close le
systeme fermera la connexion de facon a permettre au pro
cessus 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 persistence. Si ce champ
vaut 1 alors l_linger contient la durée de persistence 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
etait une option privilégiée.
Linux 18 Mai 1999 3
GETSOCKOPT(2) Manuel du programmeur Linux GETSOCKOPT(2)
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 nor
males. Elles seront accessibles avec recv ou read sans
l'attribut MSG_OOB. Certains protocoles se comportent
toujours comme si cette option etait 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 impor
tant. 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 pro
cessus 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 donnees que possible sans blocage, mais ne
traiteront pas les données si le contrôle de flux ne per
met 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 possibilite 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 donnees
soient disponible, et retourneront ensuite la plus petite
valeur entre les donnees effectivement disponible et la
quantite 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 quantite de données demandée.
Les fontions de lecture peuvent toutefois retourner moins
de données que le seuil inférieur si une erreur est surv
enue, 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
Linux 18 Mai 1999 4
GETSOCKOPT(2) Manuel du programmeur Linux GETSOCKOPT(2)
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éini
tialisée chaque fois que de nouvelles données sont trans
mises au protocole. Le délai s'applique donc à la trans
mission 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éini
tialisé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'appli
quer également à optlen.
CONFORMITÉ
SVr4, 4.4BSD (Ces appels systèmes sont apparus dans
4.2BSD). SVr4 présente des codes d'erreurs
Linux 18 Mai 1999 5
GETSOCKOPT(2) Manuel du programmeur Linux GETSOCKOPT(2)
supplémentaires ENOMEM et ENOSR, mais ne documente pas les
options SO_SNDLOWAT, SO_RCVLOWAT, SO_SNDTIMEO, SO_RCV
TIMEO.
BUGS
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.
Linux 18 Mai 1999 6