setsockopt.3.man

This a separate release of the OpenSS7 X/Open XTI/TLI library, TLI modules (timod, tirdwr) and the I

'\" rtp
.\" -*- nroff -*- vim: ft=nroff noautoindent nocindent nosmartindent
.\"
.\" @(#) setsockopt.3.man,v 1.1.2.1 2004/05/16 02:35:35 brian Exp
.\"
.\" =========================================================================
.\"
.\" Copyright (C) 2001-2004  OpenSS7 Corporation <www.openss7.com>
.\"
.\" All Rights Reserved.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" -------------------------------------------------------------------------
.\"
.\" U.S. GOVERNMENT RESTRICTED RIGHTS.  If you are licensing this Software
.\" on behalf of the U.S. Government ("Government"), the following
.\" provisions apply to you.  If the Software is supplied by the Department
.\" of Defense ("DoD"), it is classified as "Commercial Computer Software"
.\" under paragraph 252.227-7014 of the DoD Supplement to the Federal
.\" Acquisition Regulations ("DFARS") (or any successor regulations) and the
.\" Government is acquiring only the license rights granted herein (the
.\" license rights customarily provided to non-Government users).  If the
.\" Software is supplied to any unit or agency of the Government other than
.\" DoD, it is classified as "Restricted Computer Software" and the
.\" Government's rights in the Software are defined in paragraph 52.227-19
.\" of the Federal Acquisition Regulations ("FAR") (or any success
.\" regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the
.\" NASA Supplement to the FAR (or any successor regulations).
.\"
.\" =========================================================================
.\" 
.\" Commercial licensing and support of this software is available from
.\" OpenSS7 Corporation at a fee.  See http://www.openss7.com/
.\" 
.\" =========================================================================
.\"
.\" Last Modified 2004/05/16 02:35:35 by brian
.\"
.\" =========================================================================
.so strxnet.macros
.R1
bracket-label "\fR[\fB" "\fR]" "\fR, \fB"
no-default-database
database strxnet.refs
accumulate
move-punctuation
abbreviate A
join-authors ", " ", " " and "
et-al " et al" 2 3
abbreviate-label-ranges ".."
sort-adjacent-labels
.R2
.\"
.\"
.\"
.\"
.TH SETSOCKOPT 3 "2004/05/16 02:35:35" "strxnet-0_9_2-4" "Linux Fast-STREAMS Sockets Library"
.SH NAME
.B setsockopt
\- set the socket options
.SH SYNOPSIS
.PP
.B #include <sys/socket.h>
.HP
.BI "int setsockopt(int " socket ", int " level ", int " option_name ", const void *" option_value ", socklen_t " option_len );
.SH DESCRIPTION
.PP
The
.BR setsockopt ()
function sets the option specified by the
.I option_name
argument, at the protocol level specified by the
.I level
argument, to the value pointed to by the
.I option_value
argument for
the socket associated with the file descriptor specified by the
.I socket
argument.
.PP
The
.I level
argument specifies the protocol level at which the option
resides.  To set options at the socket level, specify the
.I level
argument as
.BR SOL_SOCKET .
To set options at other levels, supply the
appropriate lecel identifier for the protocol controlling the
option.  For example, to indicate that an option will be interpreted
by the TCP (Transport Control Protocol), set
.I level
to
.B IPPROTO_TCP
as defined in the <netinet/in.h> header.
.PP
The
.I option_name
argument specifies a single option to set.  The
.I option_name
argument and any specified options are passed
uninterpreted to the appropriate protocol module for
interpretations.  The <sys/socket.h> header defines the socket level
options.  The options are as follows:
.TP
.B SO_DEBUG
Turns on recording of debugging information.  This option
enables or disables debugging in the underlying protocol
modules.  This option takes an int value.  This is a boolean
option.
.TP
.B SO_BROADCAST
Permits sending of broadcast messages, if this is supported by
the protocol.  This option takes an int value.  This is a boolean
option.
.TP
.B SO_REUSEADDR
Specifies that the rules used in validating addresses supplied
to
.BR bind (3)
should allow reuse of local addresses, if this is
supported by the protocol.  This option takes an int value.  This
is a boolean option.
.TP
.B SO_KEEPALIVE
Keeps connections active by enabling the periodic transmission
of messages, if this is supported by the protocol.  This option
takes an int value.
If the connected socket fails to respond to these messages, the
connection is broken and processes writing to that socket are
notified with a
.B SIGPIPE
signal.
This is a boolean option.
.TP
.B SO_LINGER
Lingers on a
.BR close (2)
if data is present.  This option
controls the action taken when unsent messages queue on a
socket and
.BR close (2)
is performed.  If
.B SO_LINGER
is set, the
system blocks the process during
.BR close (2)
until it can
transmit the data or until the time expires.  If
.B SO_LINGER
is
not specified, and
.BR close (2)
is issued, the system handles the
call in a way that allows the process to continue as quickly as
possible.  This option takes a linger structure, as defined in
the <sys/socket.h> header, to specify the state of the option
and linger interval.
.TP
.B SO_OOBINLINE
Leaves received out-of-band data (data marked urgent) in line.
This option takes an int value.  This is a boolean option.
.TP
.B SO_SNDBUF
Sets send buffer size.  This option takes an int value.
.TP
.B SO_RCVBUF
Sets receive buffer size.  This option takes an int value.
.TP
.B SO_DONTROUTE
Requests that outgoing messages bypass the standard routing
facilities.  The destination must be on a directly-connected
network, and messages are directed to the appropriate network
interface according to the destination address.  The effect, if
any, of this option depends on what protocol is in use.  This
option takes an int value.  This is a boolean option.
.TP
.B SO_RCVLOWAT
Sets the minimum number of bytes to process for socket input
operations.  The default value for
.B SO_RCVLOWAT
is 1.  If
.B SO_RCVLOWAT
is set to a larger value, blocking receive calls
normally wait until they have received the smaller of the low
water mark value or the requested amount.  (They may return less
than the low water mark if an error occurs, a signal is caught,
or the type of data next in the receive queue is different than
that returned, e.g.  out of band data).  This option takes an int
value.  Note that not all implementations allow this option to
be set.
.TP
.B SO_RCVTIMEO
Sets the timeout value that specifies the maximum amount of
time an input function waits until it completes.  It accepts a
timeval structure with the number of seconds and microseconds
specifying the limit on how long to wait for an input operation
to complete.  If a receive operation has blocked for this much
time without receiving additional data, it returns with a
partial count or errno set to
.RB [ EAGAIN "] or [" EWOULDBLOCK ]
if no
data were received.  The default for this option is zero, which
indicates that a receive operation will not time out.  This
option takes a timeval structure.  Note that not all
implementations allow this option to be set.
.TP
.B SO_SNDLOWAT
Sets the minimum number of bytes to process for socket output
operations.  Non-blocking output operations will process no data
if flow control does not allow the smaller of the send low
water mark value or the entire request to be processed.  This
option takes an int value.  Note that not all implementations
allow this option to be set.
.TP
.B SO_SNDTIMEO
Sets the timeout value specifying the amount of time that an
output function blocks because flow control prevents data from
being sent.  If a send operation has blocked for this time, it
returns with a partial count or with errno set to
.RB [ EAGAIN "] or [" EWOULDBLOCK ]
if no data were sent.  The default for this option
is zero, which indicates that a send operation will not time
out.  This option stores a timeval structure.  Note that not all
implementations allow this option to be set.
.PP
For boolean options, 0 indicates that the option is disabled and 1
indicates that the option is enabled.
.PP
Options at other protocol levels vary in format and name.
.SH NOTES
.PP
The
.BR setsockopt ()
function provides an application program with the
means to control socket behaviour.  An application program can use
.BR setsockopt ()
to allocate buffer space, control timeouts, or permit
socket data broadcasts.  The <sys/socket.h> header defines the
socket-level options available to
.BR setsockopt ().
.PP
Options may exist at multiple protocol levels.  The
.B SO_
options are
always present at the uppermost socket level.
.SH CAVEATS
.PP
This system call is implemented as a
.B SIOCSOCKSYS
IOCTL.  See
.BR socksys (4)
for more information.
.SH "RETURN VALUE"
.PP
Upon successful completion,
.BR setsockopt ()
returns 0.  Otherwise, -1
is returned and errno is set to indicate the error.
.SH ERRORS
.PP
The
.BR setsockopt ()
function will fail if:
.TP
.RB [ EBADF ]
The
.I socket
argument is not a valid file descriptor.
.TP
.RB [ EDOM ]
The send and receive timeout values are too big to fit into the
timeout fields in the socket structure.
.TP
.RB [ EFAULT ]
The
.I option_value
parameter can not be accessed or written.
.TP
.RB [ EINVAL ]
The specified option is invalid at the specified socket level
or the socket has been shut down.
.TP
.RB [ EISCONN ]
The socket is already connected, and a specified option can not
be set while the socket is connected.
.TP
.RB [ ENOPROTOOPT ]
The option is not supported by the protocol.
.TP
.RB [ ENOTSOCK ]
The
.I socket
argument does not refer to a socket.
.PP
The
.BR setsockopt ()
function may fail if:
.TP
.RB [ ENOMEM ]
There was insufficient memory available for the operation to
complete.
.TP
.RB [ ENOBUFS ]
Insufficient resources are available in the system to complete
the call.
.TP
.RB [ ENOSR ]
There were insufficient
.IR STREAMS (4)
resources available for the
operation to complete.
.SH "SEE ALSO"
.PP
.BR bind (3),
.BR endprotoent (2),
.BR getsockopt (3),
.BR socket (3),
.BR <sys/socket.h> .
.SH "CONFORMING TO"
.PP
The Open Group XNS Issue 5.2.
.[
xns
.]
.\"
.\"
.[
$LIST$
.]
.TI