diff options
Diffstat (limited to 'lib/libc/sys/socket.2')
| -rw-r--r-- | lib/libc/sys/socket.2 | 351 |
1 files changed, 351 insertions, 0 deletions
diff --git a/lib/libc/sys/socket.2 b/lib/libc/sys/socket.2 new file mode 100644 index 0000000..c0b1bdc --- /dev/null +++ b/lib/libc/sys/socket.2 @@ -0,0 +1,351 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd March 19, 2013 +.Dt SOCKET 2 +.Os +.Sh NAME +.Nm socket +.Nd create an endpoint for communication +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn socket "int domain" "int type" "int protocol" +.Sh DESCRIPTION +The +.Fn socket +system call +creates an endpoint for communication and returns a descriptor. +.Pp +The +.Fa domain +argument 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 +.In sys/socket.h . +The currently understood formats are: +.Pp +.Bd -literal -offset indent -compact +PF_LOCAL Host-internal protocols (alias for PF_UNIX), +PF_UNIX Host-internal protocols, +PF_INET Internet version 4 protocols, +PF_INET6 Internet version 6 protocols, +PF_ROUTE Internal routing protocol, +PF_LINK Link layer interface, +PF_KEY Internal key-management function, +PF_NATM Asynchronous transfer mode protocols, +PF_NETGRAPH Netgraph sockets, +PF_IEEE80211 IEEE 802.11 wireless link-layer protocols (WiFi), +PF_BLUETOOTH Bluetooth protocols, +PF_INET_SDP OFED socket direct protocol (IPv4), +PF_INET6_SDP OFED socket direct protocol (IPv6) +.Ed +.Pp +Each protocol family is connected to an address family, which has the +same name except that the prefix is +.Dq Dv AF_ +in place of +.Dq Dv PF_ . +Other protocol families may be also defined, beginning with +.Dq Dv PF_ , +with corresponding address families. +.Pp +The socket has the indicated +.Fa type , +which specifies the semantics of communication. +Currently +defined types are: +.Pp +.Bd -literal -offset indent -compact +SOCK_STREAM Stream socket, +SOCK_DGRAM Datagram socket, +SOCK_RAW Raw-protocol interface, +SOCK_RDM Reliably-delivered packet, +SOCK_SEQPACKET Sequenced packet stream +.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). +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 unimplemented. +.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 +.Dv SOCK_RDM , +which is planned, +but not yet implemented, are not described here. +.Pp +Additionally, the following flags are allowed in the +.Fa type +argument: +.Pp +.Bd -literal -offset indent -compact +SOCK_CLOEXEC Set close-on-exec on the new descriptor, +SOCK_NONBLOCK Set non-blocking mode on the new socket +.Ed +.Pp +The +.Fa protocol +argument +specifies a particular protocol to be used with the socket. +Normally only a single protocol exists to support a particular +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 +.Dq "communication domain" +in which communication +is to take place; see +.Xr protocols 5 . +.Pp +The +.Fa protocol +argument may be set to zero (0) to request the default +implementation of a socket type for the protocol, if any. +.Pp +Sockets of type +.Dv SOCK_STREAM +are full-duplex byte streams, similar +to pipes. +A stream socket must be in a +.Em connected +state before any data may be sent or received +on it. +A connection to another socket is created with a +.Xr connect 2 +system call. +Once connected, data may be transferred using +.Xr read 2 +and +.Xr write 2 +calls or some variant of the +.Xr send 2 +and +.Xr recv 2 +functions. +(Some protocol families, such as the Internet family, +support the notion of an +.Dq implied connect , +which permits data to be sent piggybacked onto a connect operation by +using the +.Xr sendto 2 +system call.) +When a session has been completed a +.Xr close 2 +may be performed. +Out-of-band data may also be transmitted as described in +.Xr send 2 +and received as described in +.Xr recv 2 . +.Pp +The communications protocols used to implement a +.Dv SOCK_STREAM +ensure 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 +.Er 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 an extended period (e.g.\& 5 minutes). +By default, a +.Dv SIGPIPE +signal is raised if a process sends +on a broken stream, but this behavior may be inhibited via +.Xr setsockopt 2 . +.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 +.Xr send 2 +calls. +Datagrams are generally received with +.Xr recvfrom 2 , +which returns the next datagram with its return address. +.Pp +An +.Xr fcntl 2 +system call can be used to specify a process group to receive +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 +.Em options . +These options are defined in the file +.In sys/socket.h . +The +.Xr setsockopt 2 +and +.Xr getsockopt 2 +system calls are used to set and get options, respectively. +.Sh RETURN VALUES +A -1 is returned if an error occurs, otherwise the return +value is a descriptor referencing the socket. +.Sh ERRORS +The +.Fn socket +system call fails if: +.Bl -tag -width Er +.It Bq Er EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.It Bq Er EAFNOSUPPORT +The address family (domain) is not supported or the +specified domain is not supported by this protocol family. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOBUFS +Insufficient buffer space is available. +The socket cannot be created until sufficient resources are freed. +.It Bq Er EPERM +User has insufficient privileges to carry out the requested operation. +.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 +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr connect 2 , +.Xr getpeername 2 , +.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 , +.Xr getprotoent 3 , +.Xr netgraph 4 , +.Xr protocols 5 +.Rs +.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 7 +.Re +.Rs +.%T "BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 8 +.Re +.Sh STANDARDS +The +.Fn socket +function conforms to +.St -p1003.1-2008 . +The +.Tn POSIX +standard specifies only the +.Dv AF_INET , +.Dv AF_INET6 , +and +.Dv AF_UNIX +constants for address families, and requires the use of +.Dv AF_* +constants for the +.Fa domain +argument of +.Fn socket . +The +.Dv SOCK_CLOEXEC +flag is expected to conform to the next revision of the +.Tn POSIX +standard. +The +.Dv SOCK_RDM +.Fa type , +the +.Dv PF_* +constants, and other address families are +.Fx +extensions. +.Sh HISTORY +The +.Fn socket +system call appeared in +.Bx 4.2 . |
