man page macro and text revisions (-mdoc version 3)

[unix-history] / usr / src / lib / libc / sys / socket.2

diff --git a/usr/src/lib/libc/sys/socket.2 b/usr/src/lib/libc/sys/socket.2
index 3c5de2e..b9afe46 100644 (file)
--- a/usr/src/lib/libc/sys/socket.2
+++ b/usr/src/lib/libc/sys/socket.2
@@ -1,226 +1,231 @@
-.\" 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.
 creates an endpoint for communication and returns a descriptor.

-.PP
+.Pp

 The
 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
 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
 The socket has the indicated

-.I type
+.Fa type ,

 which specifies the semantics of communication.  Currently
 defined types are:
 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
 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).
 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
 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.
 but not yet implemented, are not described here.

-.PP
+.Pp

 The
 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
 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
 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
 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
 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
 call.  Once connected, data may be transferred using

-.IR read (2)
+.Xr read 2

 and
 and

-.IR write (2)
+.Xr write 2

 calls or some variant of the 
 calls or some variant of the 

-.IR send (2)
+.Xr send 2

 and
 and

-.IR recv (2)
+.Xr recv 2

 calls.  When a session has been completed a
 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
 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
 and received as described in

-.IR recv (2).
-.PP
+.Xr recv 2 .
+.Pp

 The communications protocols used to implement a
 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
 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).
 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.
 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
 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 
 An 

-.IR fcntl (2)
+.Xr fcntl 2

 call can be used to specify a process group to receive
 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
 The operation of sockets is controlled by socket level

-.IR options .
+.Em options .

 These options are defined in the file
 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
 and

-.IR getsockopt (2)
+.Xr getsockopt 2

 are used to set and get options, respectively.
 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.
 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.
 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 .