


getsockopt(3)                                       getsockopt(3)


NNAAMMEE
       getsockopt, setsockopt - get and set options on sockets

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<ssyyss//ssoocckkeett..hh>>

       iinntt ggeettssoocckkoopptt((iinntt ss,, iinntt lleevveell,, iinntt ooppttnnaammee,,
              vvooiidd **ooppttvvaall,, ssiizzee__tt **ooppttlleenn));;

       iinntt sseettssoocckkoopptt((iinntt ss,, iinntt lleevveell,, iinntt ooppttnnaammee,,
              vvooiidd **ooppttvvaall,, ssiizzee__tt ooppttlleenn));;

DDEESSCCRRIIPPTTIIOONN
       _g_e_t_s_o_c_k_o_p_t  and  _s_e_t_s_o_c_k_o_p_t  manipulate options associated
       with a socket.  The socket is  identified  by  the  socket
       descriptor _s.  Options can exist at multiple protocol lev-
       els,  and  they  are  always  present  at  the   uppermost
       ``socket'' level (see _s_o_c_k_e_t(3)).

       When  manipulating  socket options, the level at which the
       option resides (_l_e_v_e_l) and the name of  the  option  (_o_p_t_-
       _n_a_m_e)  must  be  specified.   To manipulate options at the
       ``socket'' level, _l_e_v_e_l is specified as SOL_SOCKET.

       There are two kinds of options: boolean  and  non-boolean.
       Boolean options are either set or not set and also can use
       _o_p_t_v_a_l and _o_p_t_l_e_n (see below) to pass  information.   Non-
       boolean  options  always  use  _o_p_t_v_a_l  and  _o_p_t_l_e_n to pass
       information.

       To determine whether or not a boolean option is  set,  the
       return  value  of  _g_e_t_s_o_c_k_o_p_t  must  be  examined.  If the
       option is set, _g_e_t_s_o_c_k_o_p_t returns without error.   If  the
       boolean option is not set, _g_e_t_s_o_c_k_o_p_t returns -1 and _e_r_r_n_o
       is set to ENOPROTOOPT.

       For _s_e_t_s_o_c_k_o_p_t_, the parameters _o_p_t_v_a_l and _o_p_t_l_e_n are  used
       to pass option information from the calling process to the
       system.  _o_p_t_v_a_l is the address of  a  location  in  memory
       that  contains  the option information to be passed to the
       system.  _o_p_t_l_e_n is an object of type size_t that specifies
       the size in bytes of the option information.

       For  _g_e_t_s_o_c_k_o_p_t_, _o_p_t_v_a_l and _o_p_t_l_e_n are used to pass option
       information from the system to the calling process.   _o_p_t_-
       _v_a_l  is  the address of a location in memory that contains
       the option information to be passed to  the  calling  pro-
       cess,  or  (char *) NULL if the option is of type boolean.
       _o_p_t_l_e_n is an address of an object of type size_t  that  is
       initially  used  to specify the maximum number of bytes of
       option information to be passed.  If _o_p_t_v_a_l is  not  (char
       *)  NULL,  _o_p_t_l_e_n is set on return to the actual number of
       bytes of option information  passed.   If  the  _g_e_t_s_o_c_k_o_p_t
       call fails, no option information is passed.



                             MiNT-Net                           1





getsockopt(3)                                       getsockopt(3)


       _o_p_t_n_a_m_e and any specified options are passed uninterpreted
       to the appropriate  protocol  module  for  interpretation.
       The  include  file <ssyyss//ssoocckkeett..hh> contains definitions for
       ``socket'' level  options  (see  _s_o_c_k_e_t(3)).   Options  at
       other protocol levels vary in format and name.

       The  ``socket''  level options defined in the include file
       <ssyyss//ssoocckkeett..hh> are explained below:

              SO_DEBUG                 (boolean option) no  func-
                                       tionality;  included  only
                                       for compatibility.

              SO_DONTROUTE             (boolean           option;
                                       SOCK_STREAM  sockets only)
                                       causes  outgoing  messages
                                       to bypass standard routing
                                       facilities   and   to   be
                                       routed by the network por-
                                       tion   of   the   Internet
                                       address.

              SO_REUSEADDR             (boolean  option;  AF_INET
                                       sockets only) allows local
                                       address reuse.

              SO_KEEPALIVE             (boolean           option;
                                       SOCK_STREAM sockets  only;
                                       AF_INET    sockets   only)
                                       keeps otherwise idle  con-
                                       nected  sockets  active by
                                       forcing      transmissions
                                       every 45 seconds for up to
                                       6   minutes   without    a
                                       response.

              SO_LINGER                (boolean           option;
                                       SOCK_STREAM sockets  only;
                                       AF_INET    sockets   only)
                                       lingers on close  if  data
                                       is      present.       For
                                       SO_LINGER,  optval  points
                                       to    a   struct   linger,
                                       defined in _<_s_y_s_/_s_o_c_k_e_t_._h_>.
                                       The  linger structure con-
                                       tains an  integer  boolean
                                       flag  to  toggle  behavior
                                       on/off  and   an   integer
                                       linger value.

              SO_BROADCAST             (boolean           option;
                                       SOCK_DGRAM  sockets  only;
                                       AF_INET sockets only) tog-
                                       gles     permission     to



                             MiNT-Net                           2





getsockopt(3)                                       getsockopt(3)


                                       transmit   broadcast  mes-
                                       sages.

              SO_RCVBUF                (non-boolean  option)  For
                                       stream  sockets it changes
                                       the  buffer  size   of   a
                                       socket's   receive  socket
                                       buffer.    For    datagram
                                       sockets   it  changes  the
                                       maximum  size  message   a
                                       socket can receive.

              SO_SNDBUF                (non-boolean  option)  For
                                       stream sockets, it changes
                                       the   buffer   size  of  a
                                       socket's    send    socket
                                       buffer.     For   datagram
                                       sockets  it  changes   the
                                       maximum  size message that
                                       can be sent.

              SO_USELOOPBACK           (boolean option) no  func-
                                       tionality;  included  only
                                       for compatibility.

       None of the boolean options are supported  for  SOCK_DGRAM
       sockets.

       If  SO_DONTROUTE  is set, the system does not use the net-
       work routing tables when determining  which  interface  to
       use  to  send  an  outbound  message.  Instead, the system
       sends the message out through the  interface  that  has  a
       configured  address matching the address to which the mes-
       sage is intended to be sent.  If SO_DONTROUTE is not  set,
       the system uses the network routing tables.

       SO_REUSEADDR   indicates  the  rules  used  in  validating
       addresses supplied in a _b_i_n_d(3) call should allow reuse of
       local addresses.  This allows multiple SOCK_STREAM sockets
       to be bound to the same local  address,  as  long  as  all
       existing sockets at the desired address are in a connected
       state before the _b_i_n_d(3) is done on the new  socket.   The
       SO_REUSEADDR option has no effect on SOCK_DGRAM sockets.

       The SO_KEEPALIVE option defaults to off.

       SO_LINGER  controls the actions taken when unsent messages
       are queued on a SOCK_STREAM socket and a _c_l_o_s_e(3) is  per-
       formed.  If SO_LINGER is toggled on with a non-zero linger
       interval, the system blocks the process  on  the  _c_l_o_s_e(3)
       attempt  until it is able to transmit the data or until it
       decides it is  unable  to  deliver  the  information.   If
       SO_LINGER  is  toggled  on with a linger interval of zero,
       the connection is immediately terminated on  the  _c_l_o_s_e(3)



                             MiNT-Net                           3





getsockopt(3)                                       getsockopt(3)


       of  the  socket, and any unsent data queued on the connec-
       tion is lost.  If SO_LINGER is toggled off  (default  upon
       socket  creation)  and  a  _c_l_o_s_e(3)  is  issued,  the call
       returns immediately.  The system still  gracefully  brings
       down  the  connection  by transmitting any queued data, if
       possible.  SO_LINGER can be toggled  on/off  at  any  time
       during  the  life  of an established connection.  Toggling
       SO_LINGER does not affect the action of _s_h_u_t_d_o_w_n(3).

       The SO_BROADCAST option requests permission to send Inter-
       net broadcast datagrams on the socket.

       For  stream  sockets,  SO_RCVBUF and SO_SNDBUF can be used
       with _g_e_t_s_o_c_k_o_p_t to find the current sizes  (in  number  of
       bytes)  of  the socket's receive and send buffers, respec-
       tively.  If  supported  by  the  protocol,  SO_RCVBUF  and
       SO_SNDBUF  can  also  be  used  with _s_e_t_s_o_c_k_o_p_t to set the
       sizes (in number of bytes) of  the  socket's  receive  and
       send buffers, respectively.  The sizes are passed as inte-
       ger values using _o_p_t_v_a_l and _o_p_t_l_e_n.  You  can  increase  a
       socket's  buffer size at any time, but you can decrease it
       only prior to establishing a connection.  The default  and
       maximum buffer sizes are protocol-specific.

       For  datagram sockets, SO_RCVBUF and SO_SNDBUF can be used
       with _g_e_t_s_o_c_k_o_p_t to find the current maximum datagram  size
       (in  number  of  bytes) in the inbound and outbound direc-
       tion, respectively.  SO_RCVBUF and SO_SNDBUF can  also  be
       used  with  _s_e_t_s_o_c_k_o_p_t  to  set the maximum datagram size.
       The default  and  maximum  datagram  sizes  are  protocol-
       specific.

RREETTUURRNN VVAALLUUEE
       If the call is successful, 0 is returned.  If it fails, -1
       is returned and an error code is stored in eerrrrnnoo.

DDIIAAGGNNOOSSTTIICCSS
       The call to _g_e_t_s_o_c_k_o_p_t or _s_e_t_s_o_c_k_o_p_t fails if:

       [EBADF]             The argument _s is not a valid descrip-
                           tor.

       [EOPNOTSUPP]        The  option  is  not  supported by the
                           protocol in use by the socket.

       [ENOMEM]            No buffer space is available.

       [ENOPROTOOPT]       In _g_e_t_s_o_c_k_o_p_t, the requested option is
                           currently not set.

       [EINVAL]            The  option  is  unknown at the socket
                           level or  the  socket  has  been  shut
                           down,  the  _o_p_t_v_a_l  or, in the case of
                           _g_e_t_s_o_c_k_o_p_t, _o_p_t_l_e_n parameters are  not



                             MiNT-Net                           4





getsockopt(3)                                       getsockopt(3)


                           valid  or  the  information  cannot be
                           obtained or set.  The argument _s is  a
                           file, not a socket.

SSEEEE AALLSSOO
       socket(3).



















































                             MiNT-Net                           5


