socket - Linux socket interface


SYNOPSIS

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


DESCRIPTION

       This manual page describes  the  Linux  networking  socket
       layer  user  interface. The BSD compatible sockets are the
       uniform interface between the user process and the network
       protocol  stacks  in the kernel.  The protocol modules are
       grouped  into  protocol  families  like  PF_INET,  PF_IPX,
       PF_PACKET and socket types like SOCK_STREAM or SOCK_DGRAM.
       See socket(2) for more information on families and  types.


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 respective manual pages.

       socket(2)  creates  a socket, connect(2) connects a socket
       to a remote socket address, the bind(2) function  binds  a
       socket  to  a  local  socket  address, listen(2) tells the
       socket  that  new  connections  shall  be  accepted,   and
       accept(2) is used to get a new socket with a new incomming
       connection.  socketpair(2) returns two connected anonymous
       sockets  (only  implemented  for a few local families like
       PF_UNIX)

       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), sendfile(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 remote 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,  or calling pread(2) or pwrite(2) with a non-zero
       position is not supported on sockets.

       It is possible to do non-blocking IO on sockets by setting
       the  O_NONBLOCK  flag  on  a  socket file descriptor using

       ally)  return  with  EAGAIN  (operation  should be retried
       later); connect(2) will  return  EINPROGRESS  error.   The
       user  can  then  wait  for  various  events via poll(2) or
       select(2).

       +--------------------------------------------------------------------+
       |                            I/O events                              |
       +-----------+-----------+--------------------------------------------+
       |Event      | Poll flag | Occurrence                                 |
       +-----------+-----------+--------------------------------------------+
       |Read       | POLLIN    | New data arrived.                          |
       +-----------+-----------+--------------------------------------------+
       |Read       | POLLIN    | A connection setup has been completed (for |
       |           |           | connection-oriented sockets)               |
       +-----------+-----------+--------------------------------------------+
       |Read       | POLLHUP   | A disconnection request has been initiated |
       |           |           | by the other end.                          |
       +-----------+-----------+--------------------------------------------+
       |Read       | POLLHUP   | A connection is broken (only  for  connec­ |
       |           |           | tion-oriented protocols).  When the socket |
       |           |           | is written SIGPIPE is also sent.           |
       +-----------+-----------+--------------------------------------------+
       |Write      | POLLOUT   | Socket has enough send  buffer  space  for |
       |           |           | writing new data.                          |
       +-----------+-----------+--------------------------------------------+
       |Read/Write | POLLIN|   | An outgoing connect(2) finished.           |
       |           | POLLOUT   |                                            |
       +-----------+-----------+--------------------------------------------+
       |Read/Write | POLLERR   | An asynchronous error occured.             |
       +-----------+-----------+--------------------------------------------+
       |Read/Write | POLLHUP   | The other end has shut down one direction. |
       +-----------+-----------+--------------------------------------------+
       |Exception  | POLLPRI   | Urgent data arrived.  SIGURG is sent then. |
       +-----------+-----------+--------------------------------------------+

       An alternative to poll/select is to let the kernel  inform
       the  application about events via a SIGIO signal. For that
       the FASYNC flag must be set on a  socket  file  descriptor
       via  fcntl(2) and a valid signal handler for SIGIO must be
       installed via sigaction(2).  See  the  SIGNALS  discussion
       below.


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.

              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_RCVTIMEO and SO_SNDTIMEO
              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.  Their functionality can be emulated using
              alarm(2) or setitimer(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 also enabled BSD bug-to-bug com­
              patibility  options  (random header changing, skip­
              ping of the broadcast flag) for  raw  sockets  with
              this  option,  but  that  has been removed in 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(7).

       SO_PEERCRED
              Return  the credentials of the foreign process con­
              nected to this socket.   Only  useful  for  PF_UNIX
              sockets;  see  unix(7).  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 device binding is removed. The
              passed option is a variable-length null  terminated
              interface  name  string  with  the  maximum size of
              IFNAMSIZ.  If a socket is bound  to  an  interface,
              only   packets   received   from   that  particular

              this only works for some socket types, particularly
              AF_INET sockets. It is  not  supported  for  packet
              sockets (use normal bind(8) there).

       SO_DEBUG
              Enable socket debugging. Only allowed for processes
              with the CAP_NET_ADMIN capability or  an  effective
              user id of 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
              Don't  send  via  a  gateway, only send to directly
              connected hosts.  The same effect can  be  achieved
              by  setting  the  MSG_DONTROUTE  flag  on  a socket
              send(2) 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.   The  default   value   is   set   by   the
              wmem_default  sysctl  and the maximum allowed value
              is set by the wmem_max sysctl.

       SO_RCVBUF
              Sets or gets the maximum socket receive  buffer  in
              bytes. The default value is set by the rmem_default
              sysctl and 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_linger;   /* how many seconds to linger for */
              };

              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(7),
              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

       When  writing  onto  a connection-oriented socket that has
       been shut down (by the local or the remote end) SIGPIPE is
       sent  to  the  writing process and EPIPE is returned.  The
       signal is not sent  when  the  write  call  specified  the
       MSG_NOSIGNAL flag.

       When  requested  with  the  FIOCSETOWN  fcntl or SIOCSPGRP
       ioctl, SIGIO is sent when an I/O event occurs. It is  pos­
       sible to use poll(2) or select(2) in the signal handler to
       find out which socket the event occurred on.  An  alterna­
       tive  (in Linux 2.2) is to set a realtime signal using the
       F_SETSIG fcntl; the handler of the real time  signal  will
       be  called  with the file descriptor in the si_fd field of
       its siginfo_t.  See fcntl(2) for more information.

       Under some circumstances (e.g. multiple processes  access­
       ing  a single socket), the condition that caused the SIGIO
       may have already disappeared when the  process  reacts  to
       the  signal.   If  this  happens,  the process should wait
       again because Linux will resend the signal 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


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

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

       wmem_max
              contains the maximum socket  send  buffer  size  in
              bytes  which  a user may set by 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  the  global  input
              queue.

       optmem_max
              Maximum  length  of ancillary data and user control
              data like the iovecs per socket.


IOCTLS

       These ioctls can be accessed using ioctl(2):

              error = ioctl(ip_socket, ioctl_type, &value_result);

       SIOCGSTAMP
              Return a struct timeval with the receive  timestamp
              of the last packet passed to the user. This is use­
              ful for accurate round trip time measurements.  See
              setitimer(2) for a description of struct timeval.

       SIOCSPGRP
              Set  the  process or process group to send SIGIO or
              SIGURG signals to when an asynchronous  I/O  opera­
              tion has finished or urgent data is available.  The
              argument is a pointer to a pid_t.  If the  argument
              is  positive, send the signals to that process.  If
              the argument is negative, send the signals  to  the
              process  group with the id of the absolute value of
              the argument.  The process may only  choose  itself
              or  its own process group to receive signals unless
              it has the CAP_KILL capability or an effective  UID
              of 0.

              Change  the O_ASYNC flag to enable or disable asyn­
              chronous IO mode of  the  socket.  Asynchronous  IO
              mode  means that the SIGIO signal or the signal set
              with F_SETSIG  is  raised  when  a  new  I/O  event
              occurs.

              Argument is a integer boolean flag.

       SIOCGPGRP
              Get  the  current  process  or  process  group that
              receives SIGIO or SIGURG signals, or 0 when none is
              set.

       Valid fcntls:

       FIOCGETOWN
              The same as the SIOCGPGRP ioctl.

       FIOCSETOWN
              The same as the SIOCSPGRP ioctl


NOTES

       Linux assumes that half of the send/receive buffer is used
       for internal kernel structures; thus the sysctls are twice
       what can be observed on the wire.


BUGS

       The  CONFIG_FILTER  socket  options  SO_ATTACH_FILTER  and
       SO_DETACH_FILTER are not documented. The suggested  inter­
       face to use them is via the libpcap library.


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.


AUTHORS

       This man page was written by Andi Kleen.


SEE ALSO

       socket(2), ip(7), setsockopt(2), getsockopt(2), packet(7),
       ddp(7)


Man(1) output converted with man2html