GETSOCKOPT(2)

NOM
getsockopt, setsockopt - Lire / ecrire les options d'une socket.

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

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

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

DESCRIPTION
Getsockopt et setsockopt manipulent les options associees a une socket. Ces options peuvent exister aux divers niveaux du protocole, et sont toujours presents au niveau socket le plus eleve. Quand on manipule les options d'une socket, il faut preciser le niveau ou 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 numero de protocole approprie. Par exemple, pour une option interpretee par le niveau de protocole TCP, level prendra le numero de protocole TCP. Voir getprotoent(3). Les parametres optval et optlen sont utilises pour determiner les options pour setsockopt. Pour getsockopt ils identifient un buffer dans lequel la valeur de l'option desiree doit etre renvoyee. Pour getsockopt, optlen est un parametre resultat, contenant initialement la taille du buffer pointe par optval, et rempli en retour pour indiquer la taille effective des valeurs renvoyees. Si aucune option n'est fournie ou renvoyee, optval peut etre NULL. Optname et toute autre option sont passees sans interpretation au protocole approprie, pour qu'il l'interprete lui-meme. Le fichier d'en-tete sys/socket.h contient les definitions pour le niveau socket, decrites 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 parametre de type int pour optval. Pour setsockopt, un parametre non nul valide une option booleenne, et zero l'invalide. SO_LINGER utilise un parametre de type struct linger defini dans sys/socket.h, qui indique l'etat desire et le delai de persistence (voir plus bas) SO_SNDTIMEO et SO_RCVTIMEO utilisent un parametre de type struct timeval defini dans sys/time.h. Les options suivantes sont traitees au niveau socket. Sauf indication contraire, elles peuvent toutes etre examinees avec getsockopt et positionnees avec setsockopt.

SO_DEBUG
    autorise l'enregistrement d'information de debugging

SO_REUSEADDR
    autorise la reutilisation de l'adresse locale

SO_KEEPALIVE
    valide la transmission periodique automatique

SO_DONTROUTE
    inhibe le routage en emission

SO_LINGER
    persistence des messages restants en cas de rupture de liaison

SO_BROADCAST
    autorise la diffusion des messages

SO_OOBINLINE
    valide la reception de messages hors-bande

SO_SNDBUF
    fixe la taille du buffer d'emission

SO_RCVBUF
    fixe la taille du buffer de reception

SO_SNDLOWAT
    fixe le seuil minimum du buffer en emission

SO_RCVLOWAT
    fixe le seuil minimum du buffer en reception

SO_SNDTIMEO
    lit la valeur de timeout en emission (seulement en lecture)

SO_RCVTIMEO
    lit la valeur de timeout en reception (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 debugging dans les modules de protocoles sous-jacents. SO_REUSEADDR indique que les regles de validation d'adresse utilisees dans la fonction bind(2) doivent autoriser la reutilisation des adresses locales. SO_KEEPALIVE valide la transmission periodique d'un message sur une socket en mode connecte. Si le correspondant ne repond plus a ces messages, la connexion est consideree comme interrompue, et les processus utilisant la socket en sont informes par un signal SIGPIPE lorsqu'il tentent d'emettre. SO_DONTROUTE indique que les messages emis doivent contourner les options de routage. A la place les messages sont envoyes directement a l'interface reseau appropriee, en utilisant la partie reseau de l'adresse de destination. SO_LINGER configure les actions a entreprendre s'il reste des messages en attente d'emission alors qu'un close(2) est effectue sur la socket. Si la socket necessite une delivrance garantie des messages, SO_LINGER est valide, l'appel a close sera bloquant pour le processus jusqu'a ce que les donnees aient ete envoyees, ou jusqu'a ce qu'il renonce a l'emission (un delai de timeout, appele persistance est specifie dans l'appel setsockopt avec SO_LINGER). Si SO_LINGER est desactive et que l'on appelle close le systeme fermera la connexion de facon a permettre au processus de continuer le plus rapidement possible. La structure linger est definie 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 duree de persistence en 100iemes de secondes avant de terminer le close. Si l_onoff vaut zero, le processus retournera immediatement. L'option SO_BROADCAST demande l'autorisation de pouvoir diffuser des datagrammes "broadcast" sur la socket. Dans les premieres versions du systeme, la diffusion broadcast etait une option privilegiee. Avec les protocoles qui acceptent les donnees hors-bande, l'option SO_OOBINLINE demande que ces donnees hors-bande soient placees dans la file de reception des donnees normales. Elles seront accessibles avec recv ou read sans l'attribut MSG_OOB. Certains protocoles se comportent toujours comme si cette option etait validee. SO_SNDBUF et SO_RCVBUF sont respectivement des options permettant d'ajuster la taille des buffers alloues pour l'emission et la reception. La taille des buffers peut etre augmentees pour des connexions avec un trafic important. Il y a des limites imposees par le systeme pour ces valeurs. SO_SNDLOWAT est une option permettant de fixer le seuil inferieur pour le buffer d'emission. La plupart des processus transmettent toutes leurs donnees au protocole qui assure le controle de flux. Les operations d'emissions non-bloquantes vont traiter autant de donnees que possible sans blocage, mais ne traiteront pas les donnees si le controle de flux ne permet pas la transmission de la plus petite valeur entre le seuil inferieur du buffer et la taille effective des donnees a emettre. Un appel a select(2) pour tester la possibilite d'ecrire sur une socket retournera vrai seulement si le seuil inferieur du buffer peut etre transmis. La valeur par defaut de SO_SNDLOWAT est configuree a une taille optimale pour le reseau, souvent 1024. SO_RCVLOWAT est une option fixant le seuil inferieur du buffer de reception. En general, les appels en lecture bloqueront jusqu'a ce qu'une quantite non nulle de donnees soient disponible, et retourneront ensuite la plus petite valeur entre les donnees effectivement disponible et la quantite demandee. La valeur par defaut de SO_SNDLOWAT est 1. Si SO_SNDLOWAT est fixe a une valeur plus grande, la lecture bloquante attendra de disposer de la plus petite valeur entre le seuil fixe et la quantite de donnees demandees. Les fontions de lecture peuvent toutefois retourner moins de donnees que le seuil inferieur si une erreur est survenue, ou si un signal est arrive. SO_SNDTIMEO est une option permettant de lire le delai de timeout pour les emissions, qui ne peut etre utilisee qu'avec getsockopt. Elle utilise un parametre de type struct timeval comprenant le nombre maximal de secondes et de micro-secondes pour l'attente en emission. Si une fonction d'emission dure plus plus longtemps, elle retournera un nombre partiel de donnees emises, ou eventuellement une erreur EWOULDBLOCK si aucune donnee n'a ete envoyee. Dans les implementations actuelles, la temporisation est reinitialisee chaque fois que de nouvelles donnees sont transmises au protocole. Le delai s'applique donc a la transmission du volume de donnees compris entre les seuils inferieur et superieur du buffer. SO_RCVTIMEO est une option permettant de lire le delai de timeout pour les receptions, qui ne peut etre utilisee qu'avec getsockopt. Elle utilise un parametre de type struct timeval comprenant le nombre maximal de secondes et de micro-secondes pour l'attente en reception. Dans les implementations actuelles, la temporisation est reinitialisee chaque fois que de nouvelles donnees sont recues par le protocole, il s'agit donc d'un delai d'inactivite. Si une fonction de reception dure plus plus longtemps, elle retournera un nombre partiel de donnees recues, ou eventuellement une erreur EWOULDBLOCK si aucune donnee n'a ete recue. Enfin SO_TYPE et SO_ERROR sont des options utilisees uniquement avec getsockopt. SO_TYPE renvoie le type de socket (par exemple : SOCK_STREAM ), ce qui est utile pour des serveurs heritant des sockets au demarrage. SO_ERROR renvoie une eventuelle erreur en attente, et reinitialise le status des erreurs. Cette fonction peut etre utilisee pour verifier des erreurs asynchrones sur des datagrammes connectes par exemple.

VALEUR RENVOYEE
getsockopt et setsockopt renvoient 0 s'ils reussissent, ou -1 s(ils echouent, 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 egalement a optlen.

CONFORMITE
SVr4, 4.4BSD (Ces appels systemes sont apparus dans 4.2BSD). SVr4 presente des codes d'erreurs spplementaires ENOMEM et ENOSR, mais ne documente pas les options SO_SNDLOWAT, SO_RCVLOWAT, SO_SNDTIMEO, SO_RCVTIMEO.

BUGS
Plusieurs options sur les sockets devraient etre gerees a un niveau plus bas par le systeme.

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