.\" 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
.TH GETSOCKOPT 2 "8 Avril 1997" BSD "Manuel du programmeur Linux"
.SH NOM
getsockopt, setsockopt \- Lire / ecrire 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 ", int *" optlen );
.sp
.BI "int setsockopt(int " s ", int " level ", int " optname ,
.BI "const void *" optval ", int " optlen );
.SH DESCRIPTION
.B Getsockopt
et
.B setsockopt
manipulent les
.I options
associees a une socket. Ces options peuvent exister
aux divers niveaux du protocole, et sont toujours presents
au niveau
.B 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,
.I level
prend la valeur
.BR 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
.BR TCP ,
.I level
prendra le numero de protocole
.BR TCP.
Voir
.BR getprotoent (3).

Les parametres
.I optval
et
.I optlen
sont utilises pour determiner les options pour
.BR setsockopt.
Pour
.B getsockopt
ils identifient un buffer dans lequel la valeur de
l'option desiree doit etre renvoyee.
Pour
.BR getsockopt,
.I optlen
est un parametre resultat, contenant initialement la taille
du buffer pointe par
.IR optval,
et rempli en retour pour indiquer la taille effective des
valeurs renvoyees. Si aucune option n'est fournie ou
renvoyee, 
.I optval
peut etre NULL.

.I Optname
et toute autre option sont passees sans interpretation au protocole
approprie, pour qu'il l'interprete lui-meme.
Le fichier d'en-tete
.I 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
.I int
pour
.IR optval .

Pour
.BR setsockopt ,
un parametre non nul valide une option booleenne, et zero l'invalide.

.B SO_LINGER
utilise un parametre de type
.I struct linger
defini dans
.IR sys/socket.h,
qui indique l'etat desire et le delai de persistence (voir plus bas)

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

Les options suivantes sont traitees au niveau socket.
Sauf indication contraire, elles peuvent toutes etre
examinees avec
.B getsockopt
et positionnees avec
.BR setsockopt.
.TP 0.8i
SO_DEBUG
autorise l'enregistrement d'information de debugging
.TP
SO_REUSEADDR
autorise la reutilisation de l'adresse locale
.TP
SO_KEEPALIVE
valide la transmission periodique automatique
.TP
SO_DONTROUTE
inhibe le routage en emission
.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 reception de messages hors-bande
.TP
SO_SNDBUF
fixe la taille du buffer d'emission
.TP
SO_RCVBUF
fixe la taille du buffer de reception
.TP
SO_SNDLOWAT
fixe le seuil minimum du buffer en emission
.TP
SO_RCVLOWAT
fixe le seuil minimum du buffer en reception
.TP
SO_SNDTIMEO
lit la valeur de timeout en emission (seulement en lecture)
.TP
SO_RCVTIMEO
lit la valeur de timeout en reception (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 debugging dans les modules de protocoles sous-jacents.

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

.B 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
.B SIGPIPE
lorsqu'il tentent d'emettre.

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

.B SO_LINGER
configure les actions a entreprendre s'il reste des messages
en attente d'emission alors qu'un
.BR close (2)
est effectue sur la socket.
Si la socket necessite une delivrance garantie des messages,
.B SO_LINGER
est valide,
l'appel a
.B 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
.B setsockopt
avec
.BR SO_LINGER ).

Si
.B SO_LINGER
est desactive 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 definie 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 duree de persistence en 100iemes de secondes avant
de terminer le
.BR close .
Si
.B l_onoff
vaut zero, le processus retournera immediatement.


L'option
.B 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
.B SO_OOBINLINE
demande que ces donnees hors\-bande soient placees dans la file
de reception des donnees 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 validee.

.B SO_SNDBUF
et
.B 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.

.B 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 
.BR 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 
.B SO_SNDLOWAT
est configuree a une taille optimale pour le reseau, souvent 1024.

.B 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
.B SO_SNDLOWAT
est 1.
Si
.B 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.

.B SO_SNDTIMEO
est une option permettant de lire le delai de timeout pour les
emissions, qui ne peut etre utilisee qu'avec \fIgetsockopt\fP.
Elle utilise un parametre de type
.I 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
.B 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.

.B SO_RCVTIMEO
est une option permettant de lire le delai de timeout pour les
receptions, qui ne peut etre utilisee qu'avec \fIgetsockopt\fP.
Elle utilise un parametre de type
.I 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
.B EWOULDBLOCK
si aucune donnee n'a ete recue.

Enfin
.B SO_TYPE
et
.B SO_ERROR
sont des options utilisees uniquement avec
.IR getsockopt.
.B SO_TYPE
renvoie le type de socket (par exemple :
.BR SOCK_STREAM 
), ce qui est utile pour des serveurs heritant des sockets au demarrage.
.B 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.

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

.SH 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
.BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO .

.SH BUGS
Plusieurs options sur les sockets devraient etre gerees a un
niveau plus bas par le systeme.
.SH "VOIR AUSSI"
.BR ioctl "(2), " socket "(2), " getprotoent "(3), " protocols (5)