SOCKET(4)           Linux Programmer's Manual           SOCKET(4)

NAME
       socket - Linux socket interface

SYNOPSIS
       #include <sys/socket.h>
       mysocket  = socket(int socket_family, int socket_type, int
       protocol);

DESCRIPTION
       This man page describes the BSD compatible Linux  network-
       ing  sockets  layer.   The  sockets  layer  is the uniform
       interface between the user process and the in kernel  net-
       work  protocol  stacks.  The  protocol modules are grouped
       into protocol families like PF_INET, PF_IPX, PF_PACKET and
       socket  types  like  SOCK_RAW or SOCK_DGRAM. See socket(2)
       for more information.

SOCKET LAYER FUNCTIONS
       These functions are used by the user process  to  send  or
       receive  packets  and  to  do other socket operations. For
       more information see their man pages.

       socket(2) creates a socket, connect(2) connects  a  socket
       to  a foreign socket address, the bind(2) function binds a
       socket to a local  socket  address,  listen(2)  tells  the
       socket   that   new  connections  will  be  accepted,  and
       accept(2) is used to get a new socket with the new connec-
       tion.  socketpair(2) returns two connected anonymous sock-
       ets.

       send(2),  sendto(2),  and  sendmsg(2)  send  data  over  a
       socket,  and recv(2), recvfrom(2), recvmsg(2) receive data
       from a socket.  poll(2) and select(2)  wait  for  arriving
       data  or a readiness to send data.  In addition, the stan-
       dard I/O operations like write(2), writev(2), read(2), and
       readv(2) can be used to read and write data.

       getsockname(2)  returns  the local socket address and get-
       peername(2) returns the foreign socket address.   getsock-
       opt(2)  and  setsockopt(2)  are  used to set or get socket
       layer or protocol options.  ioctl(2) can be used to set or
       read some other options.

       close(2)  is  used  to close a socket.  shutdown(2) closes
       parts of a full duplex socket connection.

       Seeking is not supported on sockets.

SOCKET OPTIONS
       These socket options can be set by using setsockopt(2) and
       read  with  getsockopt(2)  with  the  socket  level set to
       SOL_SOCKET for all sockets..

       SO_KEEPALIVE
              Enable sending of keep-alive  messages  on  connec-
              tion-oriented  sockets.  Expects  a integer boolean
              flag.

       SO_OOBINLINE
              If this option  is  enabled,  out-of-band  data  is
              directly  placed into the receive data stream. Oth-
              erwise out-of-band data is  only  passed  when  the
              MSG_OOB flag is set during receiving.

       SO_RCVLOWAT and SO_SNDLOWAT
              Specify  the  minimum number of bytes in the buffer
              until the socket layer will pass the  data  to  the
              protocol  (SO_SNDLOWAT)  or  the  user on receiving
              (SO_RCVLOWAT).  These two values are not changeable
              in Linux and their argument size is always fixed to
              1 byte.  Getsockopt is able to read them;  setsock-
              opt will always return ENOPROTOOPT.

       SO_RCVTIME0 and SO_SNDTIME0
              Specify  the  sending  or  receiving timeouts until
              reporting an error.  They are fixed to  a  protocol
              specific  setting  in  Linux  and cannot be read or
              written.  They  can  be   easily   emulated   using
              alarm(2).

       SO_BSDCOMPAT
              Enable  BSD  bug-to-bug compatibility. This is used
              only by the UDP protocol module and scheduled to be
              removed in future.  If enabled ICMP errors received
              for a UDP socket will not be  passed  to  the  user
              program.  Linux 2.0 enabled BSD bug-to-bug compati-
              bility options (random header changing, skipping of
              the  broadcast  flag) for the raw sockets with this
              option too, but that has been  removed  with  Linux
              2.2.  It is better to fix the user programs than to
              enable this flag.

       SO_PASSCRED
              Enable or disable the receiving of the  SCM_CREDEN-
              TIALS  control  message.  For  more information see
              unix(4).

       SO_PEERCRED
              Return the credentials of the foreign process  con-
              nected  to  this  socket.   Only useful for PF_UNIX
              sockets; see unix(4).  Argument is a  ucred  struc-
              ture. Only valid as a getsockopt.

       SO_BINDTODEVICE
              Bind  this  socket  to  a  particular  device  like
              "eth0", as specified in the passed interface  name.
              If the name is an empty string or the option length
              is zero, the  socket  is  not  bound.   The  passed
              option  is  a variable-length interface name string
              (with the maximum size of IFNAMSIZ).  If  a  socket
              is  bound  to  an  interface, only packets received
              from the bound interface are passed to the user.

       SO_DEBUG
              Enable socket debugging. Only allowed for processes
              with effective user id 0.

       SO_REUSEADDR
              Indicates   that   the  rules  used  in  validating
              addresses supplied in a bind(2) call  should  allow
              reuse  of local addresses. For PF_INET sockets this
              means that a socket may bind, except when there  is
              an  active  listening  socket bound to the address.
              When the listening socket is  bound  to  INADDR_ANY
              with  a  specific  port  then it is not possible to
              bind to this port for any local address.

       SO_TYPE
              Gets  the  socket  type   as   an   integer   (like
              SOCK_STREAM).  Can be only read with getsockopt.

       SO_DONTROUTE
              Bypass  the  routing table and send directly to the
              interface specified by the network part of the des-
              tination  address.  The same effect can be achieved
              by setting the MSG_DONTROUTE flag on a socket  send
              operation. Expects an integer boolean flag.

       SO_BROADCAST
              Set  or get the broadcast flag. When enabled, data-
              gram sockets receive packets sent  to  a  broadcast
              address  and  they are allowed to send packets to a
              broadcast address.  This option has  no  effect  on
              stream-oriented sockets.

       SO_SNDBUF
              Sets  or  gets  the  maximum  socket send buffer in
              bytes. Default value is  set  by  the  wmem_default
              sysctl.  The  maximum  allowed  value is set by the
              wmem_max sysctl.

       SO_RCVBUF
              Sets or gets the maximum socket receive  buffer  in
              bytes.  Default  value  is  set by the rmem_default
              sysctl. The maximum allowed value  is  set  by  the
              rmem_max sysctl.

       SO_LINGER
              Sets  or gets the SO_LINGER option. The argument is
              a linger structure.

              struct linger {
                  int             l_onoff;    /* linger active */
                  int             l_linger;   /* how long to linger for in seconds */
              };

              When enabled, a close(2) or  shutdown(2)  will  not
              return  until  all  queued  messages for the socket
              have been successfully sent or the  linger  timeout
              has been reached. Otherwise, the call returns imme-
              diately and the closing is done in the  background.
              When  the  socket  is closed as part of exit(2), it
              always lingers in the background.

       SO_PRIORITY
              Set the protocol-defined priority for  all  packets
              to  be  sent on this socket.  Linux uses this value
              to order the  networking  queues:  packets  with  a
              higher priority may be processed first depending on
              the selected device queueing discipline. For ip(4),
              this  also  sets the IP type-of-service (TOS) field
              for outgoing packets.

       SO_ERROR
              Get and clear the pending socket error. Only  valid
              as a getsockopt.  Expects an integer.

SIGNALS
       On  connection-oriented  sockets,  SIGPIPE  is sent when a
       disconnection request has been  received  or  the  process
       writes  to  a  socket  that has been locally shut down. In
       some cases, SIGPIPE is only  send  when  the  SO_KEEPALIVE
       option is enabled.

       When  requested  with  the  FIOCSETOWN or SIOCSPGRP ioctl,
       SIGIO is sent when an I/O event occurs.  Valid I/O  events
       include:

       -  New  data  arrived.   The socket send buffer has enough
          room to queue new data.

       -  A new connection request has completed (only  for  con-
          nection-oriented protocols).

       -  A disconnection request has been initiated.

       -  A  connection  is  broken (only for connection-oriented
          protocols).  SIGPIPE might be sent also in this case.

       -  An asynchronous error occured.  The other end has  shut
          down one direction.

       In some situations (multiple processes or the kernel send-
       ing data to a single socket) the condition that caused the
       SIGIO  might  already  have  disappeared when the SIGIO is
       processed by the user process. When this happens the  user
       process should just wait again because Linux guarantees to
       resend a new SIGIO later.

SYSCTLS
       The core socket networking sysctls can be  accessed  using
       the  /proc/sys/net/core/*  files  or  with  the  sysctl(2)
       interface.

       rmem_default
              contains the default setting in bytes of the socket
              receive buffer.

       rmem_max
              contains  the maximum receive socket buffer size in
              bytes a user can set  using  the  SO_RCVBUF  socket
              option.

       wmem_default
              contains the default setting in bytes of the socket
              send buffer.

       wmem_max
              contains the maximum send  socket  buffer  size  in
              bytes  a  user  can  set using the SO_SNDBUF socket
              option.

       message_cost
              and message_burst configure the token bucket filter
              used  to  load  limit  warning  messages  caused by
              external network events.

       netdev_max_backlog
              Maximum number of packets in a input queue.

BUGS
       The  CONFIG_FILTER  socket  options  SO_ATTACH_FILTER  and
       SO_DETACH_FILTER are not documented.

VERSIONS
       SO_BINDTODEVICE  was introduced in Linux 2.0.30.  SO_PASS-
       CRED is new in Linux 2.2.  The sysctls are  new  in  Linux
       2.2.

SEE ALSO
       socket(2), ip(4), setsockopt(2), getsockopt(2), packet(4),
       ddp(4)

Linux Man Page              3 Oct 1998                          1