1 '\" te
   2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All Rights Reserved.
   5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8 .TH SOCKET 3SOCKET "Jan 28, 2009"
   9 .SH NAME
  10 socket \- create an endpoint for communication
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
  15 #include <sys/types.h>
  16 #include <sys/socket.h>
  17 
  18 \fBint\fR \fBsocket\fR(\fBint\fR \fIdomain\fR, \fBint\fR \fItype\fR, \fBint\fR \fIprotocol\fR);
  19 .fi
  20 
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fBsocket()\fR function creates an endpoint for communication and returns a
  25 descriptor.
  26 .sp
  27 .LP
  28 The \fIdomain\fR argument specifies the protocol family within which
  29 communication takes place. The protocol family is generally the same as the
  30 address family for the addresses supplied in later operations on the socket.
  31 These families are defined in \fB<sys/socket.h>\fR.
  32 .sp
  33 .LP
  34 The currently supported protocol families are:
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fBPF_UNIX\fR\fR
  39 .ad
  40 .RS 12n
  41 \fBUNIX\fR system internal protocols
  42 .RE
  43 
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fBPF_INET\fR\fR
  48 .ad
  49 .RS 12n
  50 Internet Protocol Version 4 (IPv4)
  51 .RE
  52 
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBPF_INET6\fR\fR
  57 .ad
  58 .RS 12n
  59 Internet Protocol Version 6 (IPv6)
  60 .RE
  61 
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBPF_NCA\fR\fR
  66 .ad
  67 .RS 12n
  68 Network Cache and Accelerator (NCA) protocols
  69 .RE
  70 
  71 .sp
  72 .LP
  73 The socket has the indicated \fItype\fR, which specifies the communication
  74 semantics. Currently defined types are:
  75 .sp
  76 .in +2
  77 .nf
  78 SOCK_STREAM
  79 SOCK_DGRAM
  80 SOCK_RAW
  81 SOCK_SEQPACKET
  82 SOCK_RDM
  83 .fi
  84 .in -2
  85 
  86 .sp
  87 .LP
  88 The \fItype\fR may be augmented by a bitwise-inclusive-OR of flags from the
  89 following list, defined in <sys/socket.h>.
  90 
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBSOCK_CLOEXEC\fR\fR
  95 .ad
  96 .RS 12n
  97 Creates the socket with the \fBFD_CLOEXEC\fR flag set, causing the underlying
  98 file descriptor to be closed prior to any future calls to \fBexec\fR(2). This
  99 is similar in purpose to the \fBO_CLOEXEC\fR flag to \fBopen\fR(2).
 100 .RE
 101 
 102 .sp
 103 .LP
 104 There must be an entry in the \fBnetconfig\fR(4) file for at least each
 105 protocol family and type required. If  a non-zero protocol has been specified
 106 but no exact match for the protocol family, type, and protocol is found, then
 107 the first entry containing the specified family and type with a \fIprotocol\fR
 108 value of zero will be used.
 109 .sp
 110 .LP
 111 A \fBSOCK_STREAM\fR type provides sequenced, reliable, two-way connection-based
 112 byte streams. An out-of-band data transmission mechanism may be supported. A
 113 \fBSOCK_DGRAM\fR socket supports datagrams (connectionless, unreliable messages
 114 of a fixed (typically small) maximum length). A \fBSOCK_SEQPACKET\fR socket may
 115 provide a sequenced, reliable, two-way connection-based data transmission path
 116 for datagrams of fixed maximum length; a consumer may be required to read an
 117 entire packet with each read system call. This facility is protocol specific,
 118 and presently not implemented for any protocol family. \fBSOCK_RAW\fR sockets
 119 provide access to internal network interfaces. The types \fBSOCK_RAW\fR, which
 120 is available only to a user with the \fBnet_rawaccess\fR privilege, and
 121 \fBSOCK_RDM\fR, for which no implementation currently exists, are not described
 122 here.
 123 .sp
 124 .LP
 125 The \fIprotocol\fR parameter is a protocol-family-specific value which
 126 specifies a particular protocol to be used with the socket.  Normally this
 127 value is zero, as commonly only a single protocol exists to support a
 128 particular socket type within a given protocol family. However, multiple
 129 protocols may exist, in which case a particular protocol may be specified in
 130 this manner.
 131 .sp
 132 .LP
 133 Sockets of type \fBSOCK_STREAM\fR are full-duplex byte streams, similar to
 134 pipes. A stream socket must be in a \fIconnected\fR state before any data may
 135 be sent or received on it. A connection to another socket is created with a
 136 \fBconnect\fR(3SOCKET) call. Once connected, data may be transferred using
 137 \fBread\fR(2) and \fBwrite\fR(2) calls or some variant of the
 138 \fBsend\fR(3SOCKET) and \fBrecv\fR(3SOCKET) calls. When a session has been
 139 completed, a \fBclose\fR(2) may be performed. Out-of-band data may also be
 140 transmitted as described on the \fBsend\fR(3SOCKET) manual page and received as
 141 described on the \fBrecv\fR(3SOCKET) manual page.
 142 .sp
 143 .LP
 144 The communications protocols used to implement a \fBSOCK_STREAM\fR insure that
 145 data is not lost or duplicated.  If a piece of data for which the peer protocol
 146 has buffer space cannot be successfully transmitted within a reasonable length
 147 of time, then the connection is considered broken and calls will indicate an
 148 error with \(mi1 returns and with \fBETIMEDOUT\fR as the specific code in the
 149 global variable \fBerrno\fR. The protocols optionally keep sockets "warm" by
 150 forcing transmissions roughly every minute in the absence of other activity. An
 151 error is then indicated if no response can be elicited on an otherwise idle
 152 connection for a extended period (for instance 5 minutes). A \fBSIGPIPE\fR
 153 signal is raised if a thread sends on a broken stream; this causes naive
 154 processes, which do not handle the signal, to exit.
 155 .sp
 156 .LP
 157 \fBSOCK_SEQPACKET\fR sockets employ the same system calls as \fBSOCK_STREAM\fR
 158 sockets. The only difference is that  \fBread\fR(2) calls will return only the
 159 amount of data requested, and any remaining in the arriving packet will be
 160 discarded.
 161 .sp
 162 .LP
 163 \fBSOCK_DGRAM\fR and \fBSOCK_RAW\fR sockets allow datagrams to be sent to
 164 correspondents named in \fBsendto\fR(3SOCKET) calls. Datagrams are generally
 165 received with \fBrecvfrom\fR(3SOCKET), which returns the next datagram with its
 166 return address.
 167 .sp
 168 .LP
 169 An \fBfcntl\fR(2) call can be used to specify a process group to receive a
 170 \fBSIGURG\fR signal when the out-of-band data arrives. It can also enable
 171 non-blocking I/O.
 172 .sp
 173 .LP
 174 The operation of sockets is controlled by socket level \fIoptions\fR. These
 175 options are defined in the file <\fBsys/socket.h\fR>. \fBsetsockopt\fR(3SOCKET)
 176 and \fBgetsockopt\fR(3SOCKET) are used to set and get options, respectively.
 177 .SH RETURN VALUES
 178 .sp
 179 .LP
 180 Upon successful completion, a descriptor referencing the socket is returned.
 181 Otherwise, -1 is returned and \fBerrno\fR is set to indicate the error.
 182 .SH ERRORS
 183 .sp
 184 .LP
 185 The \fBsocket()\fR function will fail if:
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBEACCES\fR\fR
 190 .ad
 191 .RS 19n
 192 Permission to create a socket of the specified type or protocol is denied.
 193 .RE
 194 
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBEAGAIN\fR\fR
 199 .ad
 200 .RS 19n
 201 There were insufficient resources available to complete the operation.
 202 .RE
 203 
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBEAFNOSUPPORT\fR\fR
 208 .ad
 209 .RS 19n
 210 The specified address family is not supported by the protocol family.
 211 .RE
 212 
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBEMFILE\fR\fR
 217 .ad
 218 .RS 19n
 219 The per-process descriptor table is full.
 220 .RE
 221 
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBENOMEM\fR\fR
 226 .ad
 227 .RS 19n
 228 Insufficient user memory is available.
 229 .RE
 230 
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBENOSR\fR\fR
 235 .ad
 236 .RS 19n
 237 There were insufficient STREAMS resources available to complete the operation.
 238 .RE
 239 
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fBEPFNOSUPPORT\fR\fR
 244 .ad
 245 .RS 19n
 246 The specified protocol family is not supported.
 247 .RE
 248 
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBEPROTONOSUPPORT\fR\fR
 253 .ad
 254 .RS 19n
 255 The protocol type is not supported by the address family.
 256 .RE
 257 
 258 .sp
 259 .ne 2
 260 .na
 261 \fB\fBEPROTOTYPE\fR\fR
 262 .ad
 263 .RS 19n
 264 The socket type is not supported by the protocol.
 265 .RE
 266 
 267 .SH ATTRIBUTES
 268 .sp
 269 .LP
 270 See \fBattributes\fR(5) for descriptions of the following attributes:
 271 .sp
 272 
 273 .sp
 274 .TS
 275 box;
 276 c | c
 277 l | l .
 278 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 279 _
 280 MT-Level        Safe
 281 .TE
 282 
 283 .SH SEE ALSO
 284 .sp
 285 .LP
 286 \fBnca\fR(1), \fBclose\fR(2), \fBfcntl\fR(2), \fBioctl\fR(2), \fBread\fR(2),
 287 \fBwrite\fR(2), \fBaccept\fR(3SOCKET), \fBbind\fR(3SOCKET), \fBexec\fR(2),
 288 \fBconnect\fR(3SOCKET), \fBgetsockname\fR(3SOCKET), \fBgetsockopt\fR(3SOCKET),
 289 \fBin.h\fR(3HEAD),\fBlisten\fR(3SOCKET), \fBrecv\fR(3SOCKET), \fBopen\fR(2),
 290 \fBsetsockopt\fR(3SOCKET), \fBsend\fR(3SOCKET), \fBshutdown\fR(3SOCKET),
 291 \fBsocket.h\fR(3HEAD), \fBsocketpair\fR(3SOCKET), \fBattributes\fR(5)
 292 .SH NOTES
 293 .sp
 294 .LP
 295 Historically, \fBAF_\fR* was commonly used in places where \fBPF_\fR* was
 296 meant. New code should be careful to use \fBPF_\fR* as necessary.