| blob | 35955b2f88a4ec976980775d890ef4ba03e09c97 |
1 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved.
2 .\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
4 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
5 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
6 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
7 .\" This notice shall appear on any product containing this material.
8 .\" 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.
9 .\" 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.
10 .\" 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]
11 .Dd Jun 18, 2017
12 .Dt SOCKET.H 3HEAD
13 .Os
14 .Sh NAME
15 .Nm socket.h ,
16 .Nm socket
17 .Nd Internet Protocol family
18 .Sh SYNOPSIS
19 .In sys/socket.h
20 .Sh DESCRIPTION
21 The
22 .Nm
23 header defines the unsigned integral type
24 .Vt sa_family_t
25 through
26 .Sy typedef .
27 .Pp
28 The
29 .Nm
30 header defines the
31 .Vt sockaddr
32 structure that includes the following members:
33 .Bd -literal -offset indent
34 sa_family_t sa_family /* address family */
35 char sa_data[] /* socket address (variable-length
36 data) */
37 .Ed
38 The
39 .Nm
40 header defines the
41 .Vt msghdr
42 structure that includes the following members:
43 .Bd -literal -offset indent
44 void *msg_name /* optional address */
45 socklen_t msg_namelen /* size of address */
46 struct iovec *msg_iov /* scatter/gather array */
47 int msg_iovlen /* members in msg_iov */
48 void *msg_control /* ancillary data, see below */
49 socklen_t msg_controllen /* ancillary data buffer len */
50 int msg_flags /* flags on received message */
51 .Ed
52 .Pp
53 The
54 .Nm
55 header defines the
56 .Vt cmsghdr
57 structure that includes the following members:
58 .Bd -literal -offset indent
59 socklen_t cmsg_len /* data byte count, including hdr */
60 int cmsg_level /* originating protocol */
61 int cmsg_type /* protocol-specific type */
62 .Ed
63 .Pp
64 Ancillary data consists of a sequence of pairs, each consisting of a
65 .Vt cmsghdr
66 structure followed by a data array. The data array contains the ancillary data
67 message, and the
68 .Vt cmsghdr
69 structure contains descriptive information that allows an application to
70 correctly parse the data.
71 .Pp
72 The values for
73 .Va cmsg_level
74 will be legal values for the level argument to the
75 .Fn getsockopt
76 and
77 .Fn setsockopt
78 functions. The
79 .Dv SCM_RIGHTS
80 type is supported for level
81 .Dv SOL_SOCKET .
82 .Pp
83 Ancillary data is also possible at the socket level. The
84 .Nm
85 header defines the following macros for use as the
86 .Va cmsg_type
87 values when
88 .Va cmsg_level
89 is
90 .Dv SOL_SOCKET .
91 .Bl -tag -width Ds
92 .It Dv SCM_RIGHTS
93 Indicates that the data array contains the access rights to be sent or
94 received.
95 .It Dv SCM_UCRED
96 Indicates that the data array contains a
97 .Vt ucred_t
98 to be received. The
99 .Vt ucred_t
100 is the credential of the sending process at the time the message was sent. This
101 is a Sun-specific, Evolving interface. See
102 .Xr ucred_get 3C .
103 .El
104 .Pp
105 The IPv4 data formats generally use the same values for data passed back in
106 .Vt cmsghdr
107 as for
108 .Fn setsockopt
109 to enable the feature. The IPv4 data formats are listed below with the
110 associated payload for each.
111 .Bl -tag -width Ds
112 .It Dv IPPROTO_IP IP_RECVDSTADDR
113 .Vt ipaddr_t ,
114 IP address
115 .It Dv IPPROTO_IP IP_RECVOPTS
116 variable-length IP options, up to 40 bytes
117 .It Dv IPPROTO_IP IP_RECVIF
118 .Vt uint_t ,
119 .Va ifIndex
120 number
121 .It Dv IPPROTO_IP IP_RECVSLLA
122 .Vt struct sockaddr_dl ,
123 link layer address
124 .It Dv IPPROTO_IP IP_RECVTTL
125 .Vt uint8_t
126 .It Dv SOL_SOCKET SO_RECVUCRED
127 .Vt ucred_t
128 -
129 .Va cmsghdr.cmsg_type
130 is
131 .Dv SCM_UCRED ,
132 not
133 .Dv SO_RECVUCRED
134 .El
135 .Pp
136 The IPv6 data formats use different values for enabling the option and for
137 passing the value back to the application. The IPv6 data formats are listed
138 below with the associated payload for each.
139 .Bl -tag -width Ds
140 .It Dv IPPROTO_IPV6 IPV6_RECVPKTINFO
141 .Vt in_pktinfo ,
142 .Va cmsg_type
143 .Dv IPV6_PKTINFO
144 .It Dv IPPROTO_IPV6 IPV6_RECVTCLASS
145 .Vt uint_t ,
146 .Va cmsg_type
147 .Dv IPV6_TCLASS
148 .It Dv IPPROTO_IPV6 IPV6_RECVPATHMTU
149 .Vt ip6_mtuinfo ,
150 .Va cmsg_type
151 .Dv IPV6_PATHMTU
152 .It Dv IPPROTO_IPV6 IPV6_RECVHOPLIMIT
153 .Vt uint_t ,
154 .Va cmsg_type
155 .Dv IPV6_HOPLIMIT
156 .It Dv IPPROTO_IPV6 IPV6_RECVHOPOPTS
157 variable-length IPv6 options,
158 .Va cmsg_type
159 .Dv IPV6_HOPOPTS
160 .It Dv IPPROTO_IPV6 IPV6_RECVDSTOPTS
161 variable-length IPv6 options,
162 .Va cmsg_type
163 .Dv IPV6_DSTOPTS
164 .It Dv IPPROTO_IPV6 IPV6_RECVRTHDR
165 variable-length IPv6 options,
166 .Va cmsg_type
167 .Dv IPV6_RTHDR
168 .It Dv IPPROTO_IPV6 IPV6_RECVRTHDRDSTOPTS
169 variable-length IPv6 options,
170 .Va cmsg_type
171 .Dv IPV6_DSTOPTS
172 .El
173 .Pp
174 The
175 .Nm
176 header defines the following macros to gain access to the data arrays in the
177 ancillary data associated with a message header:
178 .Xr CMSG_DATA 3 ,
179 .Xr CMSG_FIRSTHDR 3,
180 .Xr CMSG_NXTHDR 3 ,
181 and
182 .Xr CMSG_SPACE 3 .
183 .Pp
184 The
185 .Nm
186 header defines the linger structure that includes the following members:
187 .Bd -literal -offset indent
188 int l_onoff /* indicates whether linger option is enabled */
189 int l_linger /* linger time, in seconds */
190 .Ed
191 .Pp
192 The
193 .Nm
194 header defines the following macros:
195 .Bl -tag -width Ds
196 .It Dv SOCK_DGRAM
197 Datagram socket
198 .It Dv SOCK_STREAM
199 Byte-stream socket
200 .It Dv SOCK_SEQPACKET
201 Sequenced-packet socket
202 .El
203 .Pp
204 The
205 .Nm
206 header defines the following macros for use as the
207 .Fa level
208 argument of
209 .Fn setsockopt
210 and
211 .Fn getsockopt .
212 .Bl -tag -width Ds
213 .It Dv SOL_SOCKET
214 Options to be accessed at the socket level, not the protocol level.
215 .It Dv SOL_ROUTE
216 Options to be accessed at the routing socket level, not the protocol level.
217 .El
218 .Pp
219 The
220 .Nm
221 header defines the following macros for use as the
222 .Fa option_name
223 argument of
224 .Fn getsockopt
225 or
226 .Fn setsockopt
227 calls:
228 .Bl -tag -width Ds
229 .It Dv SO_DEBUG
230 Debugging information is being recorded.
231 .It Dv SO_ACCEPTCONN
232 Socket is accepting connections.
233 .It Dv SO_BROADCAST
234 Transmission of broadcast messages is supported.
235 .It Dv SO_REUSEADDR
236 Reuse of local addresses is supported.
237 .It Dv SO_KEEPALIVE
238 Connections are kept alive with periodic messages.
239 .It Dv SO_LINGER
240 Socket lingers on close.
241 .It Dv SO_OOBINLINE
242 Out-of-band data is transmitted in line.
243 .It Dv SO_SNDBUF
244 Send buffer size.
245 .It Dv SO_RCVBUF
246 Receive buffer size.
247 .It Dv SO_ERROR
248 Socket error status.
249 .It Dv SO_TYPE
250 Socket type.
251 .It Dv SO_RECVUCRED
252 Request the reception of user credential ancillary data. This is a
253 Sun-specific, Evolving interface. See
254 .Xr ucred_get 3C .
255 .It Dv SO_ALLZONES
256 Bypass zone boundaries (privileged).
257 .El
258 .Pp
259 The
260 .Nm
261 header defines the following macros for use as the valid values for the
262 .Va msg_flags
263 field in the
264 .Vt msghdr
265 structure, or the flags parameter in
266 .Fn recvfrom ,
267 .Fn recvmsg ,
268 .Fn sendto ,
269 or
270 .Fn sendmsg
271 calls:
272 .Bl -tag -width Ds
273 .It Dv MSG_CTRUNC
274 Control data truncated.
275 .It Dv MSG_EOR
276 Terminates a record (if supported by the protocol).
277 .It Dv MSG_OOB
278 Out-of-band data.
279 .It Dv MSG_PEEK
280 Leave received data in queue.
281 .It Dv MSG_TRUNC
282 Normal data truncated.
283 .It Dv MSG_WAITALL
284 Wait for complete message.
285 .It Dv MSG_NOSIGNAL
286 Do not generate the SIGPIPE signal.
287 .El
288 .Pp
289 The
290 .Nm
291 header defines the following macros:
292 .Bl -tag -width Ds
293 .It Dv AF_UNIX
294 UNIX domain sockets
295 .It Dv AF_INET
296 Internet domain sockets
297 .El
298 .Pp
299 The
300 .Nm
301 header defines the following macros:
302 .Bl -tag -width Ds
303 .It Dv SHUT_RD
304 Disables further receive operations.
305 .It Dv SHUT_WR
306 Disables further send operations.
307 .It Dv SHUT_RDWR
308 Disables further send and receive operations.
309 .El
310 .Sh SEE ALSO
311 .Xr CMSG_DATA 3 ,
312 .Xr getpeerucred 3C ,
313 .Xr ucred_get 3C ,
314 .Xr accept 3SOCKET ,
315 .Xr bind 3SOCKET ,
316 .Xr connect 3SOCKET ,
317 .Xr getpeername 3SOCKET ,
318 .Xr getsockname 3SOCKET ,
319 .Xr getsockopt 3SOCKET ,
320 .Xr listen 3SOCKET ,
321 .Xr recv 3SOCKET ,
322 .Xr recvfrom 3SOCKET ,
323 .Xr recvmsg 3SOCKET ,
324 .Xr send 3SOCKET ,
325 .Xr sendmsg 3SOCKET ,
326 .Xr sendto 3SOCKET ,
327 .Xr setsockopt 3SOCKET ,
328 .Xr shutdown 3SOCKET ,
329 .Xr sockaddr 3SOCKET ,
330 .Xr socket 3SOCKET ,
331 .Xr socketpair 3SOCKET ,
332 .Xr accept 3XNET ,
333 .Xr bind 3XNET ,
334 .Xr connect 3XNET ,
335 .Xr getpeername 3XNET ,
336 .Xr getsockname 3XNET ,
337 .Xr getsockopt 3XNET ,
338 .Xr listen 3XNET ,
339 .Xr recv 3XNET ,
340 .Xr recvfrom 3XNET ,
341 .Xr recvmsg 3XNET ,
342 .Xr send 3XNET ,
343 .Xr sendmsg 3XNET ,
344 .Xr sendto 3XNET ,
345 .Xr setsockopt 3XNET ,
346 .Xr shutdown 3XNET ,
347 .Xr socketpair 3XNET ,
348 .Xr attributes 5 ,
349 .Xr standards 5