usr/src/man/man3socket/socket.3socket

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