*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> getsockopt (2)              



NAME    [Toc]    [Back]

     getsockopt, setsockopt - get and set options on sockets

SYNOPSIS    [Toc]    [Back]

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

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

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

DESCRIPTION    [Toc]    [Back]

     getsockopt() and setsockopt() manipulate the options associated with a
     socket.  Options may exist at multiple protocol levels; they
are always
     present at the uppermost ``socket'' level.

     When  manipulating socket options the level at which the option resides
     and the name of the option must be specified.  To manipulate
options at
     the  socket level, level is specified as SOL_SOCKET.  To manipulate options
 at any other level the protocol number of  the  appropriate protocol
     controlling  the  option is supplied.  For example, to indicate that an option
 is to be interpreted by the TCP protocol, level  should
be set to the
     protocol number of TCP; see getprotoent(3).

     The  parameters  optval and optlen are used to access option
values for
     setsockopt().  For getsockopt() they identify  a  buffer  in
which the value
     for  the  requested  option(s)  are  to  be  returned.   For
getsockopt(), optlen
     is a value-result parameter, initially containing  the  size
of the buffer
     pointed to by optval, and modified on return to indicate the
actual size
     of the value returned.  If no option value is to be supplied
or returned,
     optval may be NULL.

     optname  and  any specified options are passed uninterpreted
to the appropriate
 protocol module for interpretation.  The include file
     <sys/socket.h>  contains  definitions  for  socket level options, described
     below.  Options at other protocol levels vary in format  and
name; consult
     the appropriate entries in section 4 of the manual.

     Most  socket-level  options  utilize  an  int  parameter for
optval.  For
     setsockopt(), the parameter should be non-zero to  enable  a
boolean option,
  or  zero  if the option is to be disabled.  SO_LINGER
uses a struct
     linger parameter, defined in <sys/socket.h>, which specifies
the desired
     state  of  the  option  and the linger interval (see below).
     SO_RCVTIMEO use  a  struct  timeval  parameter,  defined  in

     The  following  options  are recognized at the socket level.
Except as noted,
 each may be examined  with  getsockopt()  and  set  with

           SO_DEBUG         enables recording of debugging information
           SO_REUSEADDR    enables local address reuse
           SO_REUSEPORT    enables  duplicate  address  and  port
           SO_KEEPALIVE    enables keep connections alive
           SO_DONTROUTE     enables  routing  bypass for outgoing
           SO_LINGER       linger on close if data present
           SO_BROADCAST    enables permission to transmit  broadcast messages
           SO_OOBINLINE     enables reception of out-of-band data
in band
           SO_SNDBUF       set buffer size for output
           SO_RCVBUF       set buffer size for input
           SO_SNDLOWAT     set minimum count for output
           SO_RCVLOWAT     set minimum count for input
           SO_SNDTIMEO     set timeout value for output
           SO_RCVTIMEO     set timeout value for input
           SO_TYPE         get the type of the socket (get only)
           SO_ERROR        get and clear error on the socket (get

     SO_DEBUG  enables  debugging in the underlying protocol modules.
     SO_REUSEADDR indicates that the rules used in validating addresses supplied
 in a bind(2) call should allow reuse of local addresses.
     SO_REUSEPORT allows completely duplicate bindings by  multiple processes
     if  they all set SO_REUSEPORT before binding the port.  This
option permits
 multiple instances of a program to each receive  UDP/IP
multicast or
     broadcast   datagrams   destined   for   the   bound   port.
     the periodic transmission of messages on a connected socket.
Should the
     connected  party fail to respond to these messages, the connection is considered
 broken and processes using the socket  are  notified
     signal when attempting to send data.  SO_DONTROUTE indicates
that outgoing
 messages should bypass the standard routing  facilities.
     messages  are  directed to the appropriate network interface
according to
     the network portion of the destination address.

     SO_LINGER controls the action taken when unsent messages are
queued on
     socket  and a close(2) is performed.  If the socket promises
reliable delivery
 of data and SO_LINGER is set, the system  will  block
the process on
     the  close(2)  attempt until it is able to transmit the data
or until it
     decides it is unable to deliver the information  (a  timeout
period measured
  in  seconds, termed the linger interval, is specified
in the
     setsockopt()  call  when  SO_LINGER   is   requested).    If
SO_LINGER is disabled
     and  a close(2) is issued, the system will process the close
in a manner
     that allows the process to continue as quickly as  possible.

     The  option  SO_BROADCAST requests permission to send broadcast datagrams
     on the socket.  Broadcast was a privileged operation in earlier versions
     of  the system.  With protocols that support out-of-band data, the
     SO_OOBINLINE option requests that out-of-band data be placed
in the normal
 data input queue as received; it will then be accessible
with recv(2)
     or read(2) calls without the MSG_OOB flag.   Some  protocols
always behave
     as  if  this option is set.  SO_SNDBUF and SO_RCVBUF are options to adjust
     the normal buffer  sizes  allocated  for  output  and  input
buffers, respectively.
   The  buffer  size may be increased for high-volume
connections, or
     may be decreased to limit the possible backlog  of  incoming
data.  The
     system places an absolute limit on these values.

     SO_SNDLOWAT is an option to set the minimum count for output
     Most output operations process all of the data  supplied  by
the call, delivering
  data to the protocol for transmission and blocking
as necessary
     for flow control.  Nonblocking output operations  will  process as much data
  as  permitted  subject to flow control without blocking,
but will process
 no data if flow control does not allow the  smaller  of
the low water
     mark  value  or  the  entire request to be processed.  A select(2) or poll(2)
     operation testing the ability to write to a socket will  return true only
     if  the  low  water mark amount could be processed.  The default value for
     SO_SNDLOWAT is set to a convenient size  for  network  efficiency, often
     1024.  SO_RCVLOWAT is an option to set the minimum count for
input operations.
  In general, receive calls will block until any (nonzero) amount
     of  data  is  received,  then return with the smaller of the
amount available
     or the amount requested.  The default value for  SO_RCVLOWAT
is 1.  If
     SO_RCVLOWAT is set to a larger value, blocking receive calls
     wait until they have received the smaller of the  low  water
mark value or
     the  requested  amount.  Receive calls may still 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.

     SO_SNDTIMEO  is  an option to set a timeout value for output
     It accepts a struct timeval parameter  with  the  number  of
seconds and microseconds
 used to limit waits for output operations to complete.  If a
     send operation has blocked for this much  time,  it  returns
with a partial
     count or with the error EWOULDBLOCK if no data was sent.  In
the current
     implementation, this timer is restarted each time additional
data are delivered
  to the protocol, implying that the limit applies to
output portions
 ranging in size from the low water mark  to  the  high
water mark for
     output.  SO_RCVTIMEO is an option to set a timeout value for
input operations.
  It accepts a struct timeval parameter with the  number of seconds
     and microseconds used to limit waits for input operations to
     In the current implementation, this timer is restarted  each
time additional
 data are received by the protocol, and thus the limit
is in effect
     an inactivity  timer.   If  a  receive  operation  has  been
blocked for this
     much time without receiving additional data, it returns with
a short
     count or with the error EWOULDBLOCK  if  no  data  were  received.

     Finally,  SO_TYPE  and  SO_ERROR  are options used only with
     SO_TYPE returns the type of the socket, such as SOCK_STREAM;
it is useful
     for  servers  that inherit sockets on startup.  SO_ERROR returns any pending
 error on the socket and clears the error status.  It may
be used to
     check  for asynchronous errors on connected datagram sockets
or for other
     asynchronous errors.

RETURN VALUES    [Toc]    [Back]

     A 0 is returned if the call succeeds, -1 if it fails.

ERRORS    [Toc]    [Back]

     The call succeeds unless:

     [EBADF]       The argument s is not a valid descriptor.

     [ENOTSOCK]    The argument s is a file, not a socket.

                   The option is unknown at the level  indicated.

     [EFAULT]       The  address pointed to by optval is not in a
valid part of
                   the process address space.  For  getsockopt(),
this error
                   may  also  be  returned  if optlen is not in a
valid part of
                   the process address space.

SEE ALSO    [Toc]    [Back]

     connect(2), ioctl(2), poll(2), select(2), socket(2), getprotoent(3),

STANDARDS    [Toc]    [Back]

     SO_PEERCRED is not supported, see getpeereid(2) instead.

HISTORY    [Toc]    [Back]

     The getsockopt() system call appeared in 4.2BSD.

BUGS    [Toc]    [Back]

     Several  of  the  socket  options should be handled at lower
levels of the

OpenBSD     3.6                        February     15,      1999
[ Back ]
 Similar pages
Name OS Title
connect Tru64 Connect two sockets
sockstat FreeBSD list open sockets
raw Linux Linux IPv4 raw sockets
ng_btsocket FreeBSD Bluetooth sockets layer
recvfrom Tru64 Receive messages from sockets
socketpair FreeBSD create a pair of connected sockets
socketpair Tru64 Create a pair of connected sockets
socketpair HP-UX create a pair of connected sockets
recv Tru64 Receive messages from connected sockets
fuser Linux identify processes using files or sockets
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service