-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved. The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1983, 1991 The Regents of the University of California.
+.\" All rights reserved.
.\"
-.\" @(#)socket.2 6.1 (Berkeley) %G%
+.\" %sccs.include.redist.man%
.\"
-.TH SOCKET 2 ""
-.UC 5
-.SH NAME
-socket \- create an endpoint for communication
-.SH SYNOPSIS
-.nf
-.ft B
-#include <sys/types.h>
-#include <sys/socket.h>
-.PP
-.ft B
-s = socket(af, type, protocol)
-int s, af, type, protocol;
-.fi
-.SH DESCRIPTION
-.I Socket
+.\" @(#)socket.2 6.8 (Berkeley) %G%
+.\"
+.Dd
+.Dt SOCKET 2
+.Os BSD 4.2
+.Sh NAME
+.Nm socket
+.Nd create an endpoint for communication
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/socket.h>
+.Ft int
+.Fn socket "int domain" "int type" "int protocol"
+.Sh DESCRIPTION
+.Fn Socket
creates an endpoint for communication and returns a descriptor.
-.PP
+.Pp
The
-.I af
-parameter specifies an address format with which addresses specified
-in later operations using the socket should be interpreted. These
-formats are defined in the include file
-.IR <sys/socket.h> .
+.Fa domain
+parameter specifies a communications domain within which
+communication will take place; this selects the protocol family
+which should be used.
+These families are defined in the include file
+.Ao Pa sys/socket.h Ac .
The currently understood formats are
-.PP
-.RS
-.nf
-.ta 1.25i 1.75i
-AF_UNIX (UNIX path names),
-AF_INET (ARPA Internet addresses),
-AF_PUP (Xerox PUP-I Internet addresses), and
-AF_IMPLINK (IMP \*(lqhost at IMP\*(rq addresses).
-.fi
-.RE
-.PP
+.Pp
+.Bd -literal -offset indent -compact
+AF_UNIX (UNIX internal protocols),
+AF_INET (ARPA Internet protocols),
+AF_ISO (ISO protocols),
+AF_NS (Xerox Network Systems protocols), and
+AF_IMPLINK (IMP \*(lqhost at IMP\*(rq link layer).
+.Ed
+.Pp
The socket has the indicated
-.I type
+.Fa type ,
which specifies the semantics of communication. Currently
defined types are:
-.PP
-.RS
-.nf
+.Pp
+.Bd -literal -offset indent -compact
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_SEQPACKET
SOCK_RDM
-.fi
-.RE
-.PP
-A SOCK_STREAM type provides sequenced, reliable,
-two-way connection based byte streams with an out-of-band data
-transmission mechanism.
-A SOCK_DGRAM socket supports
+.Ed
+.Pp
+A
+.Dv SOCK_STREAM
+type provides sequenced, reliable,
+two-way connection based byte streams.
+An out-of-band data transmission mechanism may be supported.
+A
+.Dv SOCK_DGRAM
+socket supports
datagrams (connectionless, unreliable messages of
a fixed (typically small) maximum length).
-SOCK_RAW sockets provide access to internal network interfaces.
-The types SOCK_RAW,
+A
+.Dv SOCK_SEQPACKET
+socket may provide a sequenced, reliable,
+two-way connection-based data transmission path for datagrams
+of fixed maximum length; a consumer may be required to read
+an entire packet with each read system call.
+This facility is protocol specific, and presently implemented
+only for
+.Dv PF_NS .
+.Dv SOCK_RAW
+sockets provide access to internal network protocols and interfaces.
+The types
+.Dv SOCK_RAW ,
which is available only to the super-user, and
-SOCK_SEQPACKET and SOCK_RDM, which are planned,
+.Dv SOCK_RDM ,
+which is planned,
but not yet implemented, are not described here.
-.PP
+.Pp
The
-.I protocol
+.Fa protocol
specifies a particular protocol to be used with the socket.
Normally only a single protocol exists to support a particular
-socket type using a given address format. However, it is possible
-that many protocols may exist in which case a particular protocol
+socket type within a given protocol family. However, it is possible
+that many protocols may exist, in which case a particular protocol
must be specified in this manner. The protocol number to use is
particular to the \*(lqcommunication domain\*(rq in which communication
is to take place; see
-.IR services (3N)
-and
-.IR protocols (3N).
-.PP
-Sockets of type SOCK_STREAM
+.Xr protocols 5 .
+.Pp
+Sockets of type
+.Dv SOCK_STREAM
are full-duplex byte streams, similar
to pipes. A stream socket must be in a
-.I connected
+.Em connected
state before any data may be sent or received
on it. A connection to another socket is created with a
-.IR connect (2)
+.Xr connect 2
call. Once connected, data may be transferred using
-.IR read (2)
+.Xr read 2
and
-.IR write (2)
+.Xr write 2
calls or some variant of the
-.IR send (2)
+.Xr send 2
and
-.IR recv (2)
+.Xr recv 2
calls. When a session has been completed a
-.IR close (2)
+.Xr close 2
may be performed.
Out-of-band data may also be transmitted as described in
-.IR send (2)
+.Xr send 2
and received as described in
-.IR recv (2).
-.PP
+.Xr recv 2 .
+.Pp
The communications protocols used to implement a
-SOCK_STREAM insure that data
+.Dv SOCK_STREAM
+insure that data
is not lost or duplicated. If a piece of data for which the
peer protocol has buffer space cannot be successfully transmitted
within a reasonable length of time, then
the connection is considered broken and calls
will indicate an error with
-\-1 returns and with ETIMEDOUT as the specific code
-in the global variable errno.
-The protocols optionally keep sockets \*(lqwarm\*(rq by
-forcing transmissions
+-1 returns and with
+.Dv ETIMEDOUT
+as the specific code
+in the global variable
+.Va errno .
+The protocols optionally keep sockets
+.Dq warm
+by forcing transmissions
roughly every minute in the absence of other activity.
An error is then indicated if no response can be
elicited on an otherwise
idle connection for a extended period (e.g. 5 minutes).
-A SIGPIPE signal is raised if a process sends
+A
+.Dv SIGPIPE
+signal is raised if a process sends
on a broken stream; this causes naive processes,
which do not handle the signal, to exit.
-.PP
-SOCK_DGRAM and SOCK_RAW
+.Pp
+.Dv SOCK_SEQPACKET
+sockets employ the same system calls
+as
+.Dv SOCK_STREAM
+sockets. The only difference
+is that
+.Xr read 2
+calls will return only the amount of data requested,
+and any remaining in the arriving packet will be discarded.
+.Pp
+.Dv SOCK_DGRAM
+and
+.Dv SOCK_RAW
sockets allow sending of datagrams to correspondents
named in
-.IR send (2)
-calls. It is also possible to receive datagrams at
-such a socket with
-.IR recv (2).
-.PP
+.Xr send 2
+calls. Datagrams are generally received with
+.Xr recvfrom 2 ,
+which returns the next datagram with its return address.
+.Pp
An
-.IR fcntl (2)
+.Xr fcntl 2
call can be used to specify a process group to receive
-a SIGURG signal when the out-of-band data arrives.
-.PP
+a
+.Dv SIGURG
+signal when the out-of-band data arrives.
+It may also enable non-blocking I/O
+and asynchronous notification of I/O events
+via
+.Dv SIGIO .
+.Pp
The operation of sockets is controlled by socket level
-.IR options .
+.Em options .
These options are defined in the file
-.RI < sys/socket.h >
-and explained below.
-.I Setsockopt
+.Ao Pa sys/socket.h Ac .
+.Xr Setsockopt 2
and
-.IR getsockopt (2)
+.Xr getsockopt 2
are used to set and get options, respectively.
-Options other than SO_LINGER take an
-.I int
-parameter which should non-zero if the option is to be
-enabled, or zero if it is to be disabled; SO_LINGER
-uses a
-.I struct linger
-parameter, defined in
-.RI < sys/socket.h >,
-which specifies the desired state of the option and the
-linger interval (see below).
-.PP
-.RS
-.DT
-.nf
-SO_DEBUG turn on recording of debugging information
-SO_REUSEADDR allow local address reuse
-SO_KEEPALIVE keep connections alive
-SO_DONTROUTE do not route outgoing messages
-SO_LINGER linger on close if data present
-SO_BROADCAST permit transmission of broadcast messages
-.fi
-.RE
-.PP
-SO_DEBUG enables debugging in the underlying protocol modules.
-SO_REUSEADDR indicates the rules used in validating addresses supplied
-in a
-.IR bind (2)
-call should allow reuse of local addresses. SO_KEEPALIVE enables 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 via a
-SIGPIPE signal. SO_DONTROUTE indicates that outgoing messages should
-bypass the standard routing facilities. Instead, 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 messags
-are queued on socket and a
-.IR 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
-.I close
-attempt until it is able to transmit the data or until it decides it
-is unable to deliver the information (a timeout period, termed the
-linger interval, is specified in the
-.IR setsockopt
-call when SO_LINGER is requested).
-If SO_LINGER is disabled and a
-.I close
-is issued, the system will process the close in a manner which allows
-the process to continue as quickly as possible.
-.SH "RETURN VALUE
-A \-1 is returned if an error occurs, otherwise the return
+.Sh RETURN VALUES
+A -1 is returned if an error occurs, otherwise the return
value is a descriptor referencing the socket.
-.SH "ERRORS
-The \fIsocket\fP call fails if:
-.TP 20
-[EAFNOSUPPORT]
-The specified address family is not supported in this version
-of the system.
-.TP 20
-[ESOCKTNOSUPPORT]
-The specified socket type is not supported in this address family.
-.TP 20
-[EPROTONOSUPPORT]
-The specified protocol is not supported.
-.TP 20
-[EMFILE]
+.Sh ERRORS
+The
+.Fn socket
+call fails if:
+.Bl -tag -width EPROTONOPSUPPORTA
+.It Bq Er EPROTONOSUPPORT
+The protocol type or the specified protocol is not supported
+within this domain.
+.It Bq Er EMFILE
The per-process descriptor table is full.
-.TP 20
-[ENOBUFS]
-No buffer space is available. The socket cannot be created.
-.SH SEE ALSO
-accept(2), bind(2), connect(2), getsockname(2), getsockopt(2),
-ioctl(2), listen(2), recv(2),
-select(2), send(2), shutdown(2), socketpair(2)
-.br
-``A 4.2BSD Interprocess Communication Primer''.
-.SH BUGS
-The use of keepalives is a questionable feature for this layer.
+.It Bq Er ENFILE
+The system file table is full.
+.It Bq Er EACCESS
+Permission to create a socket of the specified type and/or protocol
+is denied.
+.It Bq Er ENOBUFS
+Insufficient buffer space is available.
+The socket cannot be created until sufficient resources are freed.
+.El
+.Sh SEE ALSO
+.Xr accept 2 ,
+.Xr bind 2 ,
+.Xr connect 2 ,
+.Xr getprotoent 3 ,
+.Xr getsockname 2 ,
+.Xr getsockopt 2 ,
+.Xr ioctl 2 ,
+.Xr listen 2 ,
+.Xr read 2 ,
+.Xr recv 2 ,
+.Xr select 2 ,
+.Xr send 2 ,
+.Xr shutdown 2 ,
+.Xr socketpair 2 ,
+.Xr write 2
+.Rs
+.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
+.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
+.Re
+.Rs
+.%T "BSD Interprocess Communication Tutorial"
+.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
+.Re
+.Sh HISTORY
+The
+.Nm
+function call appeared in
+.Bx 4.2 .