xnu-3789.1.32.tar.gz

[apple/xnu.git] / bsd / man / man2 / socket.2

diff --git a/bsd/man/man2/socket.2 b/bsd/man/man2/socket.2
index 364ab4a3c05aeb2bd95777b5536b3fbac59605fe..4815d2e941c00e6d039821a13059025aec20e505 100644 (file)
--- a/bsd/man/man2/socket.2
+++ b/bsd/man/man2/socket.2
@@ -33,19 +33,22 @@
 .\"
 .\"     @(#)socket.2   8.1 (Berkeley) 6/4/93
 .\"
 .\"
 .\"     @(#)socket.2   8.1 (Berkeley) 6/4/93
 .\"

-.Dd June 4, 1993
+.Dd March 18, 2015

 .Dt SOCKET 2
 .Dt SOCKET 2

-.Os BSD 4.2
+.Os 

 .Sh NAME
 .Nm socket
 .Nd create an endpoint for communication
 .Sh SYNOPSIS
 .Sh NAME
 .Nm socket
 .Nd create an endpoint for communication
 .Sh SYNOPSIS

-.Fd #include <sys/types.h>

 .Fd #include <sys/socket.h>
 .Ft int
 .Fd #include <sys/socket.h>
 .Ft int

-.Fn socket "int domain" "int type" "int protocol"
+.Fo socket
+.Fa "int domain"
+.Fa "int type"
+.Fa "int protocol"
+.Fc

 .Sh DESCRIPTION
 .Sh DESCRIPTION

-.Fn Socket
+.Fn socket

 creates an endpoint for communication and returns a descriptor.
 .Pp
 The
 creates an endpoint for communication and returns a descriptor.
 .Pp
 The


@@ -58,11 +61,14 @@ These families are defined in the include file
 The currently understood formats are
 .Pp
 .Bd -literal -offset indent -compact
 The currently understood formats are
 .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).
+PF_LOCAL       Host-internal protocols, formerly called PF_UNIX,
+PF_UNIX                Host-internal protocols, deprecated, use PF_LOCAL,
+PF_INET                Internet version 4 protocols,
+PF_ROUTE       Internal Routing protocol,
+PF_KEY         Internal key-management function,
+PF_INET6       Internet version 6 protocols,
+PF_SYSTEM      System domain,
+PF_NDRV                Raw access to network device

 .Ed
 .Pp
 The socket has the indicated
 .Ed
 .Pp
 The socket has the indicated


@@ -74,8 +80,8 @@ defined types are:
 SOCK_STREAM
 SOCK_DGRAM
 SOCK_RAW
 SOCK_STREAM
 SOCK_DGRAM
 SOCK_RAW

-SOCK_SEQPACKET
-SOCK_RDM
+.\"SOCK_SEQPACKET
+.\"SOCK_RDM

 .Ed
 .Pp
 A
 .Ed
 .Pp
 A


@@ -88,23 +94,24 @@ A
 socket supports
 datagrams (connectionless, unreliable messages of
 a fixed (typically small) maximum length).
 socket supports
 datagrams (connectionless, unreliable messages of
 a fixed (typically small) maximum length).

-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 .
+.\"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.
 .Dv SOCK_RAW
 sockets provide access to internal network protocols and interfaces.

-The types
+The type

 .Dv SOCK_RAW ,
 .Dv SOCK_RAW ,

-which is available only to the super-user, and
-.Dv SOCK_RDM ,
-which is planned,
-but not yet implemented, are not described here.
+which is available only to the super-user. 
+.\" , and
+.\" .Dv SOCK_RDM ,
+.\" which is planned,
+.\" but not yet implemented, are not described here.

 .Pp
 The
 .Fa protocol
 .Pp
 The
 .Fa protocol


@@ -125,6 +132,8 @@ to pipes.  A stream socket must be in a
 state before any data may be sent or received
 on it.  A connection to another socket is created with a
 .Xr connect 2
 state before any data may be sent or received
 on it.  A connection to another socket is created with a
 .Xr connect 2

+or
+.Xr connectx 2

 call.  Once connected, data may be transferred using
 .Xr read 2
 and
 call.  Once connected, data may be transferred using
 .Xr read 2
 and


@@ -166,16 +175,16 @@ A
 signal is raised if a process sends
 on a broken stream; this causes naive processes,
 which do not handle the signal, to exit.
 signal is raised if a process sends
 on a broken stream; this causes naive processes,
 which do not handle the signal, to exit.

-.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_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
 .Pp
 .Dv SOCK_DGRAM
 and


@@ -212,27 +221,56 @@ value is a descriptor referencing the socket.
 .Sh ERRORS
 The
 .Fn socket
 .Sh ERRORS
 The
 .Fn socket

-call fails if:
+system call fails if:

 .Bl -tag -width Er
 .Bl -tag -width Er

-.It Bq Er EPROTONOSUPPORT
-The protocol type or the specified protocol is not supported
-within this domain.
+.\" ===========
+.It Bq Er EACCES
+Permission to create a socket of the specified type and/or protocol
+is denied.
+.\" ===========
+.It Bq Er EAFNOSUPPORT
+The specified address family is not supported.
+.\" ===========

 .It Bq Er EMFILE
 The per-process descriptor table is full.
 .It Bq Er EMFILE
 The per-process descriptor table is full.

+.\" ===========

 .It Bq Er ENFILE
 The system file table is full.
 .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.
 .It Bq Er ENOBUFS
 Insufficient buffer space is available.
 The socket cannot be created until sufficient resources are freed.

+.\" ===========
+.It Bq Er ENOMEM
+Insufficient memory was available to fulfill the request.
+.\" ===========
+.It Bq Er EPROTONOSUPPORT
+The protocol type or the specified protocol is not supported
+within this domain.
+.\" ===========
+.It Bq Er EPROTOTYPE
+The socket type is not supported by the protocol.

 .El
 .El

+.Pp
+If a new protocol family is defined,
+the socreate process is free to return any desired error code.
+The
+.Fn socket
+system call will pass this error code along
+(even if it is undefined).
+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/socket.h>
+.Pp
+The include file
+.In sys/types.h
+is necessary.

 .Sh SEE ALSO
 .Xr accept 2 ,
 .Xr bind 2 ,
 .Xr connect 2 ,
 .Sh SEE ALSO
 .Xr accept 2 ,
 .Xr bind 2 ,
 .Xr connect 2 ,

-.Xr getprotoent 3 ,
+.Xr connectx 2 ,
+.Xr disconnectx 2 ,

 .Xr getsockname 2 ,
 .Xr getsockopt 2 ,
 .Xr ioctl 2 ,
 .Xr getsockname 2 ,
 .Xr getsockopt 2 ,
 .Xr ioctl 2 ,


@@ -243,7 +281,12 @@ The socket cannot be created until sufficient resources are freed.
 .Xr send 2 ,
 .Xr shutdown 2 ,
 .Xr socketpair 2 ,
 .Xr send 2 ,
 .Xr shutdown 2 ,
 .Xr socketpair 2 ,

-.Xr write 2
+.Xr write 2 ,
+.Xr getprotoent 3 ,
+.Xr inet 4 ,
+.Xr inet6 4 ,
+.Xr unix 4 ,
+.Xr compat 5

 .Rs
 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 .%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
 .Rs
 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 .%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"