.\" 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)
.\" Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de)
.\" Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl)
.\" Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl)
.\" Translated Tue Dec 16 1997 by Gerardo Aburruzaga <gerardo.aburruzaga@uca.es> 
.\"
.TH GETSOCKOPT 2 "16 Diciembre 1997" "Pgina man de BSD" "Manual del Programador Linux"
.\" .TH GETSOCKOPT 2 "22 April 1996" "BSD Man Page" "Linux Programmer's Manual"
.SH NOMBRE
getsockopt, setsockopt \- obtiene y pone opciones en zcalos (\fIsockets\fR)
.SH SINOPSIS
.B #include <sys/types.h>
.br
.B #include <sys/socket.h>
.sp 2
.BI "int getsockopt(int " s ", int " nivel ", int " nomopc ,
.BI "void *" valopc ", int *" lonopc );
.sp
.BI "int setsockopt(int " s ", int " nivel ", int " nomopc ,
.BI "const void *" valopc ", int " lonopc );
.SH DESCRIPTION
.B Getsockopt
y
.B setsockopt
manipulan las
.I opciones
asociadas a un zcalo. stas pueden existir en mltiples niveles de
protocolo; siempre estn presentes en el nivel ms alto de 
.B zcalo.

Al manipular opciones de zcalo, deben especificarse el nivel en el
que reside la opcin, y su nombre.

Para manipular opciones en el nivel de zcalo,
.I nivel
se especifica como
.BR SOL_SOCKET .
Para manipular opciones a cualquier otro nivel, se suministra el
nmero de protocolo del apropiado que controle la opcin. Por ejemplo,
para indicar que una opcin ha de ser interpretada por el protocolo
.B TCP ,
.I nivel
debe ponerse como el nmero de protocolo de
.BR TCP ;
vea
.BR getprotoent (3).

Los parmetros
.I valopc
y
.I lonopc
se emplean para acceder a valores de opciones de
.BR setsockopt .
Para
.B getsockopt
identifican a un bfer en el que se pondr el valor para la opcin
pedida (u opciones). Para
.BR getsockopt ,
.I lonopc
es un parmetro por referencia, que contiene inicialmente el tamao
del bfer  apuntado por 
.IR optval ,
y que se modifica al acabar la funcin para contener el tamao real
del valor devuelto. Si no se va a suministrar o devolver un valor de
opcin, 
.I valopc
puede ser NULL.

.I Nomopc
y cualesquiera opciones especificadas se pasan sin interpretar al
mdulo de protocolo apropiado para su interpretacin. El fichero de cabecera
.I <sys/socket.h>
contiene definiciones para opciones de nivel de zcalo, descritas ms
abajo. Las opciones a otros niveles de protocolo varan en formato y
nombre; consulte las pginas apropiadas de la seccin 4 del Manual.

La mayora de las opciones de nivel-zcalo utilizan un parmetro
.I int
para
.IR valopc .
Para
.BR setsockopt ,
el parmetro debe ser distinto de cero para permitir una opcin
booleana, o cero si la opcin va a ser deshabilitada.
.B SO_LINGER
emplea un parmetro
.I struct linger ,
definido en
.IR <linux/socket.h> ,
que especifica el estado deseado de la opcin y el intervalo de
retardo (vea ms adelante).
.B SO_SNDTIMEO
y
.B SO_RCVTIMEO
emplean un parmetro
.I struct timeval ,
definido en
.IR <sys/time.h> .

Se reconocen las opciones siguientes en el nivel de zcalo.
Salvo que se diga otra cosa, cada una puede ser examinada con
.B getsockopt
y puede ser puesta con
.BR setsockopt .
.TP 0.8i
SO_DEBUG
permite la grabacin de informacin de depuracin
.TP
SO_REUSEADDR
permite reutilizacin de direccin local
.TP
SO_KEEPALIVE
permite mantener vivas las conexiones
.TP
SO_DONTROUTE
permite salto por encima de encaminamiento para mensajes salientes
.TP
SO_LINGER
retardo al cerrar si hay datos presentes
.TP
SO_BROADCAST
da permiso para transmitir mensajes de difusin
.TP
SO_OOBINLINE
permite recepcin de datos fuera-de-banda en banda
.TP
SO_SNDBUF
pone el tamao del bfer de salida
.TP
SO_RCVBUF
pone el tamao del bfer de entrada
.TP
SO_SNDLOWAT
pone la cuenta mnima para la salida
.TP
SO_RCVLOWAT
pone la cuenta mnima para la entrada
.TP
SO_SNDTIMEO
obtiene el valor del tiempo de espera para la salida (slo obtiene)
.TP
SO_RCVTIMEO
obtiene el valor del tiempo de espera para la entrada (slo obtiene)
.TP
SO_TYPE
obtiene el tipo del zcalo (slo obtiene)
.TP
SO_ERROR
obtiene y limpia el estado de error del zcalo (slo obtiene)
.PP
.B SO_DEBUG
permite depuracin en los mdulos de protocolo subyacentes.
.B SO_REUSEADDR
indica que las reglas empleadas en la validacin de direcciones
suministradas en una llamada a
.BR bind (2)
deben permitir reutilizacin de direcciones locales.
.B SO_KEEPALIVE
permite la transmisin peridica de mensajes en un zcalo conectado.

Si el vecino conectado fallara en responder a estos mensajes, la
conexin se considerar rota, y cuando los procesos que utilicen el
zcalo intentaran enviar datos se les notificara de aquel hecho
mediante uan seal
.B SIGPIPE .
.B SO_DONTROUTE
indica que los mensajes salientes deben saltar sobre las facilidades
normales de encaminamiento. En vez de eso, los mensajes se redirigen a
la interfaz de red apropiada segn la porcin de red de la direccin
de destino.
.B SO_LINGER
controla la accin tomada cuando mensajes no enviados se ponen en cola
en el zcalo y se ejecuta un
.BR close (2) .

Si el zcalo promete la entrega confiable de datos y
.B SO_LINGER
est activado, el sistema bloquear el proceso en el intento
.B close
hasta que sea capaz de transmitir los datos o hasta que  decida que es
incapaz de entregar la informacin (un perodo de espera, nombrado
como el intervalo de retardo, se especifica en la llamada a
.B setsockopt
cuando
.B SO_LINGER
ha sido requerido).
Si
.B SO_LINGER
est inhabilitado y se ha llamado a
.B close ,
el sistema procesar el cierre de tal manera que permita al proceso
continuar tan rpidamente como sea posible.
La estructura
.I linger
se define en
.I <linux/socket.h>
de la siguiente forma:
.sp
.RS
.nf
.ta 8n 16n 32n
struct linger {
        int  l_onoff;   /* Retardo activo */
        int  l_linger;  /* por cunto tiempo */
};
.ta
.fi
.RE

.B l_onoff
indica si retardar o no. Si est puesto a 1 entonces
.B l_linger
contiene el tiempo en centsimas de segundos que el proceso debe
retardarse para completar el
.BR close .
Si
.B l_onoff
est a cero, el proceso regresa inmediatamente.

La opcin
.B SO_BROADCAST
pide permiso para enviar datagramas de difusin en el zcalo.  La
difusin era una operacin privilegiada en anteriores versiones del
sistema. Con protocolos que soportan datos fuera-de-banda, la opcin
.B SO_OOBINLINE
pide que los datos fuera-de-banda se pongan en la cola normal de datos
de entrada tal como se reciban; entonces ser accesible con llamadas
.B recv
o
.B read
sin la seal
.B MSG_OOB .
Algunos protocolos siempre se comportan como si esta opcin estuviera activa.
.B SO_SNDBUF
y
.B SO_RCVBUF
son opciones para ajustar los tamaos normales de bfer asignados para
los bferes de entrada y salida, respectivamente. El tamao de bfer
puede ser incrementado para conexiones de mucho volumen, o
decrementado para limitar el posible \fIbacklog\fP de datos entrantes. El
sistema impone un lmite absoluto en estos valores.

.B SO_SNDLOWAT
es una opcin para establecer la mnima cuenta para operaciones de
salida. La mayora de las operaciones de salida procesan todos los
datos suministrados por la llamada, entregando datos al protocolo para
su transmisin y bloqueando segn convenga para el control de flujo.
Las operaciones de salida no bloqueantes procesarn tantos datos como
puedan sujetas al control de flujo sin bloqueo, pero no procesarn
ningn dato si el control de flujo no permite que sea procesado el
valor ms pequeo de la marca baja de agua de la peticin entera.
Una operacin
.BR select (2)
que compruebe la capacidad de escribir en un zcalo devulver
verdadero slo si la cantidad de la marca baja de agua pudiera
procesarse. El valor predeterminado de
.B SO_SNDLOWAT
est establecido como un tamao conveniente para la eficacia de la
red, a menudo 1024.

.B SO_RCVLOWAT
es una opcin para poner la cuenta mnima para operaciones de
entrada. En general, las llamadas de recepcin se bloquearn hasta que
se reciba alguna cantidad (no cero) de datos, entonces regresarn con
la menor de las cantidades disponible o pedida. El valor
predeterminado de
.B SO_RCVLOWAT
es 1.
Si 
.B SO_RCVLOWAT
est puesto a un valor mayor, las llamadas de recepcin bloqueantes
normalmente esperan hasta que han recibido el valor ms pequeo de la
marca de agua baja o la cantidad pedida. Las llamadas de recepcin
pueden an devolver algo menor que la marca de agua baja si ocurre un
error, si se captura una seal, o si el tipo de los datos siguientes
de la cola de recepcin es diferente del que se ha devuelto.

.B SO_SNDTIMEO
es una opcin para obtener el valor del tiempo de espera para
operaciones de salida.
(Puede usarse con
.I getsockopt
solamente). Devuelve un parmetro
.I struct timeval
con el nmero de segundos y microsegundos empleados para limitar
esperas para que se completen las operaciones de salida.
.B SO_RCVTIMEO
es una opcin para obtener el valor del tiempo de espera para
operaciones de entrada.
(Puede emplearse con
.I getsockopt
solamente). Devuelve un parmetro
.I struct timeval
con el nmero de segundos y microsegundos empleados para limitar
esperas para que se completen las operaciones de entrada.
En la implementacin actual, este
temporizador se pone a cero cada  vez que se reciben datos
adicionales por el protocolo, y por tanto el lmite es en efecto un
temporizador de inactividad. Si una operacin de recepcin ha sido
bloqueada durante este tiempo sin recibir datos adicionales, regresa
con una cuenta corta o con el error
.B EWOULDBLOCK
si no se recibieron datos.
Finalmente, tambin
.B SO_TYPE
y
.B SO_ERROR
son opciones empleadas slo con
.IR getsockopt .
.B SO_TYPE
devuelve el tipo del zcalo, como
.BR SOCK_STREAM ;
es til para servidores que heredan zcalos en el arranque.
.B SO_ERROR
devuelve cualquier error pendiente en el zcalo y limpia el indicador
de estado de error. Puede emplearse para comprobar la ocurrencia de
errores asncronos en zcalos de datagramas conectados o de otros tipos
de errores asncronos.
.SH "VALOR DE RETORNO"
Se devuelve cero en caso de xito. En caso de error se devuelve \-1, y
.I errno
toma un valor apropiado.
.SH ERRORES
.TP 0.8i
.B EBADF
El argumento
.I s
no es un descriptor vlido.
.TP
.B ENOTSOCK
El argumento
.I s
es un fichero, no un zcalo.
.TP
.B ENOPROTOOPT
La opcin es desconocida al nivel indicado.
.TP
.B EFAULT
La direccin apuntada por
.I valopc
no est en un sitio vlido del espacio de direcciones del proceso. Para
.BR getsockopt ,
este error puede tambin ser devuelto si
.I lonopc
no est en un sitio vlido del espacio de direcciones del proceso.
.SH CONFORME CON
SVr4, 4.4BSD (estas primitivas aparecieron por primera vez en 4.2BSD).
SVr4 documenta los cdigos de error adicionales ENOMEM y ENOSR, pero no
documenta las opciones 
.BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO " ni " SO_RCVTIMEO
.SH BUGS
Algunas de las opciones de zcalo deberan ser manejadas a niveles ms
bajos del sistema.
.SH "VEA"
.BR ioctl "(2), " socket "(2), " getprotoent "(3), " protocols (5)