.\" Copyright (c) 1983, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)getsockopt.2	6.9 (Berkeley) 5/1/91
.\"
.\" Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu)
.\"
.\" Traduction 11/10/1996 par Christophe Blaess (ccb@club-internet.fr)
.\" Mise a jour 8/04/97
.\" Mise a jour 18/05/99 - LDP-man-pages-1.23
.TH GETSOCKOPT 2 "18 Mai 1999" Linux "Manuel du programmeur Linux"
.SH NOM
getsockopt, setsockopt \- Lire / crire les options d'une socket.
.SH SYNOPSIS
.B #include <sys/types.h>
.br
.B #include <sys/socket.h>
.sp 2
.BI "int getsockopt(int " s ", int " level ", int " optname ,
.BI "void *" optval ", socklen_t *" optlen );
.sp
.BI "int setsockopt(int " s ", int " level ", int " optname ,
.BI "const void *" optval ", socklen_t " optlen );
.SH DESCRIPTION
.B Getsockopt
et
.B setsockopt
manipulent les
.I options
associes  une socket. Ces options peuvent exister
aux divers niveaux du protocole, et sont toujours prsentes
au niveau
.B socket
le plus lev.

Quand on manipule une option d'une socket, il faut prciser
le niveau o elle s'applique, et le nom de l'option.
Au niveau socket,
.I level
prend la valeur
.BR SOL_SOCKET.
Pour tous les autres niveaux, il faut fournir le numro de
protocole appropri.
Par exemple, pour une option interprte par le niveau de protocole
.BR TCP ,
.I level
prendra le numro de protocole
.BR TCP.
Voir
.BR getprotoent (3).

Les paramtres
.I optval
et
.I optlen
sont utiliss pour dterminer les options pour
.BR setsockopt.
Pour
.B getsockopt
ils identifient un buffer dans lequel la valeur de
l'option dsire doit tre renvoye.
Pour
.BR getsockopt,
.I optlen
est un paramtre rsultat, contenant initialement la taille
du buffer point par
.IR optval,
et rempli en retour pour indiquer la taille effective des
valeurs renvoyes. Si aucune option n'est fournie ou
renvoye, 
.I optval
peut tre NULL.

.I Optname
et toute autre option sont passes sans interprtation au protocole
appropri, pour qu'il l'interprte lui-mme.
Le fichier d'en-tte
.I sys/socket.h
contient les dfinitions pour le niveau socket, dcrites 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 paramtre de type
.I int
pour
.IR optval .

Pour
.BR setsockopt ,
un paramtre non nul valide une option boolenne, et zro l'invalide.

.B SO_LINGER
utilise un paramtre de type
.I struct linger
dfini dans
.IR sys/socket.h,
qui indique l'tat dsir et le dlai de persistence (voir plus bas)

.B SO_SNDTIMEO
et
.B SO_RCVTIMEO
utilisent un paramtre de type
.I struct timeval
dfini dans
.IR sys/time.h.

Les options suivantes sont traites au niveau socket.
Sauf indication contraire, elles peuvent toutes tre
examines avec
.B getsockopt
et positionnes avec
.BR setsockopt.
.TP 0.8i
SO_DEBUG
autorise l'enregistrement d'information de dbugging
.TP
SO_REUSEADDR
autorise la rutilisation de l'adresse locale
.TP
SO_KEEPALIVE
valide la transmission priodique automatique
.TP
SO_DONTROUTE
inhibe le routage en mission
.TP
SO_LINGER
persistence des messages restants en cas de rupture de liaison
.TP
SO_BROADCAST
autorise la diffusion des messages
.TP
SO_OOBINLINE
valide la rception de messages hors-bande
.TP
SO_SNDBUF
fixe la taille du buffer d'mission
.TP
SO_RCVBUF
fixe la taille du buffer de rception
.TP
SO_SNDLOWAT
fixe le seuil minimum du buffer en mission
.TP
SO_RCVLOWAT
fixe le seuil minimum du buffer en rception
.TP
SO_SNDTIMEO
lit la valeur de timeout en mission (seulement en lecture)
.TP
SO_RCVTIMEO
lit la valeur de timeout en rception (seulement en lecture)
.TP
SO_TYPE
lit le type de socket (seulement en lecture)
.TP
SO_ERROR
lit les erreurs en attente (seulement en lecture)
.PP
.B SO_DEBUG
autorise le dbugging dans les modules de protocoles sous-jacents.

.B SO_REUSEADDR
indique que les rgles de validation d'adresse utilises dans
la fonction
.BR bind (2)
doivent autoriser la rutilisation des adresses locales.

.B SO_KEEPALIVE
valide la transmission priodique d'un message sur une socket en
mode connect. Si le correspondant ne rpond plus  ces messages,
la connexion est considre comme interrompue, et les processus
utilisant la socket en sont informs par un signal
.B SIGPIPE
lorsqu'il tentent d'mettre.

.B SO_DONTROUTE
indique que les messages mis doivent contourner les options de
routage. A la place les messages sont envoys directement  l'interface
rseau approprie, en utilisant la partie rseau de l'adresse de
destination.

.B SO_LINGER
configure les actions  entreprendre s'il reste des messages
en attente d'mission alors qu'un
.BR close (2)
est effectu sur la socket.
Si la socket ncessite une dlivrance garantie des messages,
.B SO_LINGER
est valid,
l'appel 
.B close
sera bloquant pour le processus jusqu' ce que les donnes aient t
envoyes, ou jusqu' ce qu'il renonce  l'mission (un dlai de
timeout, appel persistance est spcifi dans l'appel
.B setsockopt
avec
.BR SO_LINGER ).

Si
.B SO_LINGER
est dsactive et que l'on appelle
.B close
le systeme fermera la connexion de facon a permettre au processus
de continuer le plus rapidement possible.

La structure
.I linger
est dfinie ainsi  dans
.I <linux/socket.h>
.sp
.RS
.nf
.ta 8n 16n 32n
struct linger {
        int  l_onoff;   /* Linger active */
        int  l_linger;  /* How long to linger for */
};
.ta
.fi
.RE

.B l_onoff
indique s'il y a ou non persistence. Si ce champ vaut 1 alors
.B l_linger
contient la dure de persistence en 100imes de secondes avant
de terminer le
.BR close .
Si
.B l_onoff
vaut zro, le processus retournera immdiatement.


L'option
.B SO_BROADCAST
demande l'autorisation de pouvoir diffuser des datagrammes "broadcast"
sur la socket. Dans les premires versions du systme, la diffusion 
broadcast etait une option privilgie.

Avec les protocoles qui acceptent les donnes hors\-bande, l'option
.B SO_OOBINLINE
demande que ces donnes hors\-bande soient places dans la file
de rception des donnes normales. Elles seront accessibles
avec
.B recv
ou
.B read
sans l'attribut
.B MSG_OOB.
Certains protocoles se comportent toujours comme si cette option
etait valide.

.B SO_SNDBUF
et
.B SO_RCVBUF
sont respectivement des options permettant d'ajuster la taille des buffers 
allous pour l'mission et la rception. La taille des buffers peut tre
augmentes pour des connexions avec un trafic important.
Il y a des limites imposes par le systme pour ces valeurs.

.B SO_SNDLOWAT
est une option permettant de fixer le seuil infrieur pour le buffer
d'mission. La plupart des processus transmettent toutes leurs donnes
au protocole qui assure le contrle de flux.

Les oprations d'missions non\-bloquantes vont traiter autant de donnees
que possible sans blocage, mais ne traiteront pas les donnes si
le contrle de flux ne permet pas la transmission de la plus petite valeur
entre le seuil infrieur du buffer et la taille effective des donnes
 mettre.

Un appel  
.BR select (2)
pour tester la possibilite d'crire sur une socket retournera vrai seulement
si le seuil infrieur du buffer peut tre transmis.

La valeur par dfaut de 
.B SO_SNDLOWAT
est configure  une taille optimale pour le rseau, souvent 1024.

.B SO_RCVLOWAT
est une option fixant le seuil infrieur du buffer de rception. En
gnral, 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 demande.

La valeur par dfaut de
.B SO_SNDLOWAT
est 1.
Si
.B 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 donnes demande.

Les fontions de lecture peuvent toutefois retourner moins de donnes que
le seuil infrieur si une erreur est survenue, ou si un signal est arriv.

.B SO_SNDTIMEO
est une option permettant de lire le dlai de timeout pour les
missions, qui ne peut tre utilise qu'avec \fIgetsockopt\fP.
Elle utilise un paramtre de type
.I 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 donnes mises,
ou ventuellement une erreur
.B EWOULDBLOCK
si aucune donne n'a t envoye.
Dans les implmentations actuelles, la temporisation est rinitialise
chaque fois que de nouvelles donnes sont transmises au protocole. Le dlai
s'applique donc  la transmission du volume de donnes compris entre les
seuils infrieur et suprieur du buffer.

.B SO_RCVTIMEO
est une option permettant de lire le dlai de timeout pour les
rceptions, qui ne peut tre utilise qu'avec \fIgetsockopt\fP.
Elle utilise un paramtre de type
.I struct timeval
comprenant le nombre maximal de secondes et de micro-secondes pour
l'attente en rception. 
Dans les implmentations actuelles, la temporisation est rinitialise
chaque fois que de nouvelles donnes sont reues par le protocole, il
s'agit donc d'un dlai d'inactivit.
Si une fonction de rception dure plus
longtemps, elle retournera un nombre partiel de donnes reues,
ou ventuellement une erreur
.B EWOULDBLOCK
si aucune donne n'a t reue.

Enfin
.B SO_TYPE
et
.B SO_ERROR
sont des options utilises uniquement avec
.IR getsockopt.
.B SO_TYPE
renvoie le type de socket (par exemple :
.BR SOCK_STREAM 
), ce qui est utile pour des serveurs hritant des sockets au dmarrage.
.B SO_ERROR
renvoie une ventuelle erreur en attente, et rinitialise le statut des
erreurs. Cette fonction peut tre utilise pour vrifier des erreurs
asynchrones sur des datagrammes connects par exemple.

.SH "VALEUR RENVOYE"
.BR getsockopt " et " setsockopt
renvoient 0 s'ils russissent, ou \-1 s'ils chouent, auquel cas
.I errno
contient le code d'erreur.
.SH ERREURS
.TP 0.8i
.B EBADF
L'argument
.I s
n'est pas un descripteur valide.
.TP
.B ENOTSOCK
L'argument
.I s
est un fichier, pas une socket.
.TP
.B ENOPROTOOPT
L'option est inconnue pour ce protocole.
.TP
.B EFAULT
.I optval
pointe en dehors de l'espace d'adressage accessible.
Avec
.BR getsockopt ,
ceci peut s'appliquer galement 
.IR optlen .

.SH CONFORMIT
SVr4, 4.4BSD (Ces appels systmes sont apparus dans 4.2BSD).
SVr4 prsente des codes d'erreurs supplmentaires ENOMEM et ENOSR, mais ne
documente pas les options
.BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO .

.SH BUGS
Plusieurs options sur les sockets devraient tre gres  un
niveau plus bas par le systme.
.SH NOTE
Le cinquime argument de
.BR getsockopt " et " setsockopt
est en fait un int (et c'est ce qu'utilisent BSD 4.*, libc4 et libc5).
Une certaine confusion POSIX rsulte du "socklen_t" actuel. Les propositions
de standard n'ont pas encore t adoptes, mais glibc2 les suit dj et
utilise socklen_t. Pour plus de dtails voir
.BR accept (2).
.SH "VOIR AUSSI"
.BR ioctl "(2), " socket "(2), " getprotoent "(3), " protocols (5)

.SH TRADUCTION
Christophe Blaess, 1997.