.\"
.\" @(#)socket.2 8.1 (Berkeley) 6/4/93
.\"
-.Dd June 4, 1993
+.Dd March 18, 2015
.Dt SOCKET 2
-.Os BSD 4.2
+.Os
.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"
+.Fo socket
+.Fa "int domain"
+.Fa "int type"
+.Fa "int protocol"
+.Fc
.Sh DESCRIPTION
-.Fn Socket
+.Fn socket
creates an endpoint for communication and returns a descriptor.
.Pp
The
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
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
-SOCK_SEQPACKET
-SOCK_RDM
+.\"SOCK_SEQPACKET
+.\"SOCK_RDM
.Ed
.Pp
A
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.
-The types
+The type
.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
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
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
.Sh ERRORS
The
.Fn socket
-call fails if:
+system call fails if:
.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 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 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
+.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 ,
-.Xr getprotoent 3 ,
+.Xr connectx 2 ,
+.Xr disconnectx 2 ,
.Xr getsockname 2 ,
.Xr getsockopt 2 ,
.Xr ioctl 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"
projects / apple / xnu.git / blobdiff