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

  man pages->Linux man pages -> socket (7)              



NAME    [Toc]    [Back]

       socket - Linux socket interface

SYNOPSIS    [Toc]    [Back]

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

DESCRIPTION    [Toc]    [Back]

       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.


       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 standard I/O operations like write(2),  writev(2),  send-
       file(2), read(2), and readv(2) can be used to read and write data.

       getsockname(2)  returns	the  local  socket  address and getpeername(2)
       returns the remote socket address.  getsockopt(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_NON-
       BLOCK flag on a socket file descriptor using fcntl(2).  Then all operations
 that would block will (usually)  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

SOCKET OPTIONS    [Toc]    [Back]

       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    [Toc]    [Back]
	      Enable  sending  of  keep-alive  messages on connection-oriented
	      sockets. Expects a integer boolean flag.

       SO_OOBINLINE    [Toc]    [Back]
	      If this option is enabled, out-of-band data is  directly	placed
	      into the receive data stream. Otherwise out-of-band data is only
	      passed when the MSG_OOB flag is set during receiving.

	      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; setsockopt  will	always
	      return ENOPROTOOPT.

	      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    [Toc]    [Back]
	      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 compatibility
 options (random  header  changing,  skipping  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    [Toc]    [Back]
	      Enable  or  disable the receiving of the SCM_CREDENTIALS control
	      message. For more information see unix(7).

       SO_PEERCRED    [Toc]    [Back]
	      Return the credentials of the foreign process connected to  this
	      socket.  Only useful for PF_UNIX sockets; see unix(7).  Argument
	      is a ucred structure. Only valid as a getsockopt.

       SO_BINDTODEVICE    [Toc]    [Back]
	      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 interface are processed by the socket. Note that
	      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    [Toc]    [Back]
	      Enable  socket  debugging.  Only	allowed for processes with the
	      CAP_NET_ADMIN capability or an effective user id of 0.

       SO_REUSEADDR    [Toc]    [Back]
	      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

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

       SO_DONTROUTE    [Toc]    [Back]
	      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

       SO_BROADCAST    [Toc]    [Back]
	      Set or get the broadcast flag. When  enabled,  datagram  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    [Toc]    [Back]
	      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    [Toc]    [Back]
	      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    [Toc]    [Back]
	      Sets  or	gets  the  SO_LINGER  option. The argument is a linger

	      struct linger {
		  int	l_onoff;    /* linger active */
		  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  immediately  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    [Toc]    [Back]
	      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

       SO_ERROR    [Toc]    [Back]
	      Get and clear the pending socket error. Only valid as a getsock-
	      opt.  Expects an integer.

SIGNALS    [Toc]    [Back]

       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  possible to use poll(2) or
       select(2) in the signal handler to find	out  which  socket  the  event
       occurred on.  An alternative (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  accessing  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    [Toc]    [Back]

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

	      contains the default setting in  bytes  of  the  socket  receive

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

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

	      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.

	      Maximum number of packets in the global input queue.

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

IOCTLS    [Toc]    [Back]

       These ioctls can be accessed using ioctl(2):

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

       SIOCGSTAMP    [Toc]    [Back]
	      Return a struct timeval with the receive timestamp of  the  last
	      packet  passed  to  the  user. This is useful for accurate round
	      trip time measurements. See setitimer(2) for  a  description  of
	      struct timeval.

       SIOCSPGRP    [Toc]    [Back]
	      Set the process or process group to send SIGIO or SIGURG signals
	      to when an asynchronous I/O operation  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.

       FIOASYNC    [Toc]    [Back]
	      Change  the  O_ASYNC  flag  to enable or disable asynchronous 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    [Toc]    [Back]
	      Get the current process or process group that receives SIGIO  or
	      SIGURG signals, or 0 when none is set.

       Valid fcntls:

       FIOCGETOWN    [Toc]    [Back]
	      The same as the SIOCGPGRP ioctl.

       FIOCSETOWN    [Toc]    [Back]
	      The same as the SIOCSPGRP ioctl

NOTES    [Toc]    [Back]

       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    [Toc]    [Back]

       are not documented. The suggested interface to  use  them  is  via  the
       libpcap library.

VERSIONS    [Toc]    [Back]

       SO_BINDTODEVICE	was introduced in Linux 2.0.30.  SO_PASSCRED is new in
       Linux 2.2.  The sysctls are new in Linux 2.2.

AUTHORS    [Toc]    [Back]

       This man page was written by Andi Kleen.

SEE ALSO    [Toc]    [Back]

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

Linux Man Page			  1999-05-07			     SOCKET(7)
[ Back ]
 Similar pages
Name OS Title
rtnetlink Linux Linux IPv4 routing socket.
sane-v4l Linux SANE interface for Video for Linux API
IO::Socket IRIX Object interface to socket communications
mac_get_fd FreeBSD get the label of a file, socket, socket peer or process
mac_get FreeBSD get the label of a file, socket, socket peer or process
mac_get_file FreeBSD get the label of a file, socket, socket peer or process
mac_get_pid FreeBSD get the label of a file, socket, socket peer or process
mac_get_proc FreeBSD get the label of a file, socket, socket peer or process
linux FreeBSD Linux ABI support
arp Linux Linux ARP kernel module.
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service