logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

sys_socket.h.0p (14809B)


  1. '\" et
  2. .TH sys_socket.h "0P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. sys/socket.h
  12. \(em main sockets header
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/socket.h>
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR <sys/socket.h>
  21. header shall define the
  22. .BR socklen_t
  23. type, which is an integer type of width of at least 32 bits;
  24. see APPLICATION USAGE.
  25. .P
  26. The
  27. .IR <sys/socket.h>
  28. header shall define the
  29. .BR sa_family_t
  30. unsigned integer type.
  31. .P
  32. The
  33. .IR <sys/socket.h>
  34. header shall define the
  35. .BR sockaddr
  36. structure, which shall include at least the following members:
  37. .sp
  38. .RS 4
  39. .nf
  40. sa_family_t sa_family \fRAddress family.\fR
  41. char sa_data[] \fRSocket address (variable-length data).\fR
  42. .fi
  43. .P
  44. .RE
  45. .P
  46. The
  47. .BR sockaddr
  48. structure is used to define a socket address which is used
  49. in the
  50. \fIbind\fR(),
  51. \fIconnect\fR(),
  52. \fIgetpeername\fR(),
  53. \fIgetsockname\fR(),
  54. \fIrecvfrom\fR(),
  55. and
  56. \fIsendto\fR()
  57. functions.
  58. .P
  59. The
  60. .IR <sys/socket.h>
  61. header shall define the
  62. .BR sockaddr_storage
  63. structure, which shall be:
  64. .IP " *" 4
  65. Large enough to accommodate all supported protocol-specific address
  66. structures
  67. .IP " *" 4
  68. Aligned at an appropriate boundary so that pointers to it can be cast
  69. as pointers to protocol-specific address structures and used to access
  70. the fields of those structures without alignment problems
  71. .P
  72. The
  73. .BR sockaddr_storage
  74. structure shall include at least the following members:
  75. .sp
  76. .RS 4
  77. .nf
  78. sa_family_t ss_family
  79. .fi
  80. .P
  81. .RE
  82. .P
  83. When a pointer to a
  84. .BR sockaddr_storage
  85. structure is cast as a pointer to a
  86. .BR sockaddr
  87. structure, the
  88. .IR ss_family
  89. field of the
  90. .BR sockaddr_storage
  91. structure shall map onto the
  92. .IR sa_family
  93. field of the
  94. .BR sockaddr
  95. structure. When a pointer to a
  96. .BR sockaddr_storage
  97. structure is cast as a pointer to a protocol-specific address structure,
  98. the
  99. .IR ss_family
  100. field shall map onto
  101. a field of that structure that is of type
  102. .BR sa_family_t
  103. and that identifies the protocol's address family.
  104. .P
  105. The
  106. .IR <sys/socket.h>
  107. header shall define the
  108. .BR msghdr
  109. structure, which shall include at least the following members:
  110. .sp
  111. .RS 4
  112. .nf
  113. void *msg_name \fROptional address.\fR
  114. socklen_t msg_namelen \fRSize of address.\fR
  115. struct iovec *msg_iov \fRScatter/gather array.\fR
  116. int msg_iovlen \fRMembers in \fImsg_iov\fR.\fR
  117. void *msg_control \fRAncillary data; see below.\fR
  118. socklen_t msg_controllen \fRAncillary data buffer \fIlen\fR.\fR
  119. int msg_flags \fRFlags on received message.\fR
  120. .fi
  121. .P
  122. .RE
  123. .P
  124. The
  125. .BR msghdr
  126. structure is used to minimize the number of directly supplied
  127. parameters to the
  128. \fIrecvmsg\fR()
  129. and
  130. \fIsendmsg\fR()
  131. functions. This structure is used as a
  132. .IR value \(hy\c
  133. .IR result
  134. parameter in the
  135. \fIrecvmsg\fR()
  136. function and
  137. .IR value
  138. only for the
  139. \fIsendmsg\fR()
  140. function.
  141. .P
  142. The
  143. .IR <sys/socket.h>
  144. header shall define the
  145. .BR iovec
  146. structure as described in
  147. .IR <sys/uio.h> .
  148. .P
  149. The
  150. .IR <sys/socket.h>
  151. header shall define the
  152. .BR cmsghdr
  153. structure, which shall include at least the following members:
  154. .sp
  155. .RS 4
  156. .nf
  157. socklen_t cmsg_len \fRData byte count, including the \fBcmsghdr\fR.\fR
  158. int cmsg_level \fROriginating protocol.\fR
  159. int cmsg_type \fRProtocol-specific type.\fR
  160. .fi
  161. .P
  162. .RE
  163. .P
  164. The
  165. .BR cmsghdr
  166. structure is used for storage of ancillary data object information.
  167. .P
  168. Ancillary data consists of a sequence of pairs, each consisting of a
  169. .BR cmsghdr
  170. structure followed by a data array. The data array contains the
  171. ancillary data message, and the
  172. .BR cmsghdr
  173. structure contains descriptive information that allows an application
  174. to correctly parse the data.
  175. .P
  176. The values for
  177. .IR cmsg_level
  178. shall be legal values for the
  179. .IR level
  180. argument to the
  181. \fIgetsockopt\fR()
  182. and
  183. \fIsetsockopt\fR()
  184. functions. The system documentation shall specify the
  185. .IR cmsg_type
  186. definitions for the supported protocols.
  187. .P
  188. Ancillary data is also possible at the socket level. The
  189. .IR <sys/socket.h>
  190. header shall define the following symbolic constant for use as the
  191. .IR cmsg_type
  192. value when
  193. .IR cmsg_level
  194. is SOL_SOCKET:
  195. .IP SCM_RIGHTS 14
  196. Indicates that the data array contains the access rights to be sent or
  197. received.
  198. .P
  199. The
  200. .IR <sys/socket.h>
  201. header shall define the following macros to gain access to the data
  202. arrays in the ancillary data associated with a message header:
  203. .IP "CMSG_DATA(\fIcmsg\fP)" 6
  204. .br
  205. If the argument is a pointer to a
  206. .BR cmsghdr
  207. structure, this macro shall return an unsigned character pointer
  208. to the data array associated with the
  209. .BR cmsghdr
  210. structure.
  211. .IP "CMSG_NXTHDR(\fImhdr,cmsg\fP)" 6
  212. .br
  213. If the first argument is a pointer to a
  214. .BR msghdr
  215. structure and the second argument is a pointer to a
  216. .BR cmsghdr
  217. structure in the ancillary data pointed to by the
  218. .IR msg_control
  219. field of that
  220. .BR msghdr
  221. structure, this macro shall return a pointer to the next
  222. .BR cmsghdr
  223. structure, or a null pointer if this structure is the last
  224. .BR cmsghdr
  225. in the ancillary data.
  226. .IP "CMSG_FIRSTHDR(\fImhdr\fP)" 6
  227. .br
  228. If the argument is a pointer to a
  229. .BR msghdr
  230. structure, this macro shall return a pointer to the first
  231. .BR cmsghdr
  232. structure in the ancillary data associated with this
  233. .BR msghdr
  234. structure, or a null pointer if there is no ancillary data associated
  235. with the
  236. .BR msghdr
  237. structure.
  238. .P
  239. The
  240. .IR <sys/socket.h>
  241. header shall define the
  242. .BR linger
  243. structure, which shall include at least the following members:
  244. .sp
  245. .RS 4
  246. .nf
  247. int l_onoff \fRIndicates whether linger option is enabled.\fR
  248. int l_linger \fRLinger time, in seconds.\fR
  249. .fi
  250. .P
  251. .RE
  252. .P
  253. The
  254. .IR <sys/socket.h>
  255. header shall define the following symbolic constants with distinct values:
  256. .IP SOCK_DGRAM 14
  257. Datagram socket.
  258. .IP SOCK_RAW 14
  259. Raw Protocol Interface.
  260. .IP SOCK_SEQPACKET 14
  261. Sequenced-packet socket.
  262. .IP SOCK_STREAM 14
  263. Byte-stream socket.
  264. .P
  265. The
  266. .IR <sys/socket.h>
  267. header shall define the following symbolic constant for use as the
  268. .IR level
  269. argument of
  270. \fIsetsockopt\fR()
  271. and
  272. \fIgetsockopt\fR().
  273. .IP SOL_SOCKET 14
  274. Options to be accessed at socket level, not protocol level.
  275. .P
  276. The
  277. .IR <sys/socket.h>
  278. header shall define the following symbolic constants with distinct values
  279. for use as the
  280. .IR option_name
  281. argument in
  282. \fIgetsockopt\fR()
  283. or
  284. \fIsetsockopt\fR()
  285. calls (see the System Interfaces volume of POSIX.1\(hy2017,
  286. .IR "Section 2.10.16" ", " "Use of Options"):
  287. .IP SO_ACCEPTCONN 14
  288. Socket is accepting connections.
  289. .IP SO_BROADCAST 14
  290. Transmission of broadcast messages is supported.
  291. .IP SO_DEBUG 14
  292. Debugging information is being recorded.
  293. .IP SO_DONTROUTE 14
  294. Bypass normal routing.
  295. .IP SO_ERROR 14
  296. Socket error status.
  297. .IP SO_KEEPALIVE 14
  298. Connections are kept alive with periodic messages.
  299. .IP SO_LINGER 14
  300. Socket lingers on close.
  301. .IP SO_OOBINLINE 14
  302. Out-of-band data is transmitted in line.
  303. .IP SO_RCVBUF 14
  304. Receive buffer size.
  305. .IP SO_RCVLOWAT 14
  306. Receive ``low water mark''.
  307. .IP SO_RCVTIMEO 14
  308. Receive timeout.
  309. .IP SO_REUSEADDR 14
  310. Reuse of local addresses is supported.
  311. .IP SO_SNDBUF 14
  312. Send buffer size.
  313. .IP SO_SNDLOWAT 14
  314. Send ``low water mark''.
  315. .IP SO_SNDTIMEO 14
  316. Send timeout.
  317. .IP SO_TYPE 14
  318. Socket type.
  319. .P
  320. The
  321. .IR <sys/socket.h>
  322. header shall define the following symbolic constant for use as the maximum
  323. .IR backlog
  324. queue length which may be specified by the
  325. .IR backlog
  326. field of the
  327. \fIlisten\fR()
  328. function:
  329. .IP SOMAXCONN 14
  330. The maximum
  331. .IR backlog
  332. queue length.
  333. .P
  334. The
  335. .IR <sys/socket.h>
  336. header shall define the following symbolic constants with distinct values
  337. for use as the valid values for the
  338. .IR msg_flags
  339. field in the
  340. .BR msghdr
  341. structure, or the
  342. .IR flags
  343. parameter in
  344. \fIrecv\fR(),
  345. \fIrecvfrom\fR(),
  346. \fIrecvmsg\fR(),
  347. \fIsend\fR(),
  348. \fIsendmsg\fR(),
  349. or
  350. \fIsendto\fR()
  351. calls:
  352. .IP MSG_CTRUNC 14
  353. Control data truncated.
  354. .IP MSG_DONTROUTE 14
  355. Send without using routing tables.
  356. .IP MSG_EOR 14
  357. Terminates a record (if supported by the protocol).
  358. .IP MSG_OOB 14
  359. Out-of-band data.
  360. .IP MSG_NOSIGNAL 14
  361. No SIGPIPE generated when an attempt to send is made on a
  362. stream-oriented socket that is no longer connected.
  363. .IP MSG_PEEK 14
  364. Leave received data in queue.
  365. .IP MSG_TRUNC 14
  366. Normal data truncated.
  367. .IP MSG_WAITALL 14
  368. Attempt to fill the read buffer.
  369. .P
  370. The
  371. .IR <sys/socket.h>
  372. header shall define the following symbolic constants with distinct values:
  373. .IP AF_INET 14
  374. Internet domain sockets for use with IPv4 addresses.
  375. .IP AF_INET6 14
  376. Internet domain sockets for use with IPv6 addresses.
  377. .IP AF_UNIX 14
  378. UNIX domain sockets.
  379. .IP AF_UNSPEC 14
  380. Unspecified.
  381. .P
  382. The value of AF_UNSPEC shall be 0.
  383. .P
  384. The
  385. .IR <sys/socket.h>
  386. header shall define the following symbolic constants with distinct values:
  387. .IP SHUT_RD 14
  388. Disables further receive operations.
  389. .IP SHUT_RDWR 14
  390. Disables further send and receive operations.
  391. .IP SHUT_WR 14
  392. Disables further send operations.
  393. .P
  394. The
  395. .IR <sys/socket.h>
  396. header shall define the
  397. .BR size_t
  398. and
  399. .BR ssize_t
  400. types as described in
  401. .IR <sys/types.h> .
  402. .P
  403. The following shall be declared as functions and may also be defined as
  404. macros. Function prototypes shall be provided.
  405. .sp
  406. .RS 4
  407. .nf
  408. int accept(int, struct sockaddr *restrict, socklen_t *restrict);
  409. int bind(int, const struct sockaddr *, socklen_t);
  410. int connect(int, const struct sockaddr *, socklen_t);
  411. int getpeername(int, struct sockaddr *restrict, socklen_t *restrict);
  412. int getsockname(int, struct sockaddr *restrict, socklen_t *restrict);
  413. int getsockopt(int, int, int, void *restrict, socklen_t *restrict);
  414. int listen(int, int);
  415. ssize_t recv(int, void *, size_t, int);
  416. ssize_t recvfrom(int, void *restrict, size_t, int,
  417. struct sockaddr *restrict, socklen_t *restrict);
  418. ssize_t recvmsg(int, struct msghdr *, int);
  419. ssize_t send(int, const void *, size_t, int);
  420. ssize_t sendmsg(int, const struct msghdr *, int);
  421. ssize_t sendto(int, const void *, size_t, int, const struct sockaddr *,
  422. socklen_t);
  423. int setsockopt(int, int, int, const void *, socklen_t);
  424. int shutdown(int, int);
  425. int sockatmark(int);
  426. int socket(int, int, int);
  427. int socketpair(int, int, int, int [2]);
  428. .fi
  429. .P
  430. .RE
  431. .P
  432. Inclusion of
  433. .IR <sys/socket.h>
  434. may also make visible all symbols from
  435. .IR <sys/uio.h> .
  436. .LP
  437. .IR "The following sections are informative."
  438. .SH "APPLICATION USAGE"
  439. To forestall portability problems, it is recommended that applications
  440. not use values larger than 2\u\s-331\s+3\d \-1 for the
  441. .BR socklen_t
  442. type.
  443. .P
  444. The
  445. .BR sockaddr_storage
  446. structure solves the problem of declaring storage for automatic
  447. variables which is both large enough and aligned enough for storing the
  448. socket address data structure of any family. For example, code with a
  449. file descriptor and without the context of the address family can pass
  450. a pointer to a variable of this type, where a pointer to a socket
  451. address structure is expected in calls such as
  452. \fIgetpeername\fR(),
  453. and determine the address family by accessing the received content
  454. after the call.
  455. .P
  456. The example below illustrates a data structure which aligns on a 64-bit
  457. boundary. An implementation-defined field
  458. .IR _ss_align
  459. following
  460. .IR _ss_pad1
  461. is used to force a 64-bit alignment which covers proper alignment good
  462. enough for needs of at least
  463. .BR sockaddr_in6
  464. (IPv6) and
  465. .BR sockaddr_in
  466. (IPv4) address data structures. The size of padding field
  467. .IR _ss_pad1
  468. depends on the chosen alignment boundary. The size of padding field
  469. .IR _ss_pad2
  470. depends on the value of overall size chosen for the total size of the
  471. structure. This size and alignment are represented in the above example
  472. by implementation-defined (not required) constants _SS_MAXSIZE
  473. (chosen value 128) and _SS_ALIGNMENT (with chosen value 8). Constants
  474. _SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 112) are
  475. also for illustration and not required. The implementation-defined
  476. definitions and structure field names above start with an
  477. <underscore>
  478. to denote implementation private name space. Portable code is not expected
  479. to access or reference those fields or constants.
  480. .sp
  481. .RS 4
  482. .nf
  483. /*
  484. * Desired design of maximum size and alignment.
  485. */
  486. #define _SS_MAXSIZE 128
  487. /* Implementation-defined maximum size. */
  488. #define _SS_ALIGNSIZE (sizeof(int64_t))
  489. /* Implementation-defined desired alignment. */
  490. .P
  491. /*
  492. * Definitions used for sockaddr_storage structure paddings design.
  493. */
  494. #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof(sa_family_t))
  495. #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(sa_family_t)+ \e
  496. _SS_PAD1SIZE + _SS_ALIGNSIZE))
  497. struct sockaddr_storage {
  498. sa_family_t ss_family; /* Address family. */
  499. /*
  500. * Following fields are implementation-defined.
  501. */
  502. char _ss_pad1[_SS_PAD1SIZE];
  503. /* 6-byte pad; this is to make implementation-defined
  504. pad up to alignment field that follows explicit in
  505. the data structure. */
  506. int64_t _ss_align; /* Field to force desired structure
  507. storage alignment. */
  508. char _ss_pad2[_SS_PAD2SIZE];
  509. /* 112-byte pad to achieve desired size,
  510. _SS_MAXSIZE value minus size of ss_family
  511. __ss_pad1, __ss_align fields is 112. */
  512. };
  513. .fi
  514. .P
  515. .RE
  516. .SH "RATIONALE"
  517. None.
  518. .SH "FUTURE DIRECTIONS"
  519. None.
  520. .SH "SEE ALSO"
  521. .IR "\fB<sys_types.h>\fP",
  522. .IR "\fB<sys_uio.h>\fP"
  523. .P
  524. The System Interfaces volume of POSIX.1\(hy2017,
  525. .IR "\fIaccept\fR\^(\|)",
  526. .IR "\fIbind\fR\^(\|)",
  527. .IR "\fIconnect\fR\^(\|)",
  528. .IR "\fIgetpeername\fR\^(\|)",
  529. .IR "\fIgetsockname\fR\^(\|)",
  530. .IR "\fIgetsockopt\fR\^(\|)",
  531. .IR "\fIlisten\fR\^(\|)",
  532. .IR "\fIrecv\fR\^(\|)",
  533. .IR "\fIrecvfrom\fR\^(\|)",
  534. .IR "\fIrecvmsg\fR\^(\|)",
  535. .IR "\fIsend\fR\^(\|)",
  536. .IR "\fIsendmsg\fR\^(\|)",
  537. .IR "\fIsendto\fR\^(\|)",
  538. .IR "\fIsetsockopt\fR\^(\|)",
  539. .IR "\fIshutdown\fR\^(\|)",
  540. .IR "\fIsockatmark\fR\^(\|)",
  541. .IR "\fIsocket\fR\^(\|)",
  542. .IR "\fIsocketpair\fR\^(\|)"
  543. .\"
  544. .SH COPYRIGHT
  545. Portions of this text are reprinted and reproduced in electronic form
  546. from IEEE Std 1003.1-2017, Standard for Information Technology
  547. -- Portable Operating System Interface (POSIX), The Open Group Base
  548. Specifications Issue 7, 2018 Edition,
  549. Copyright (C) 2018 by the Institute of
  550. Electrical and Electronics Engineers, Inc and The Open Group.
  551. In the event of any discrepancy between this version and the original IEEE and
  552. The Open Group Standard, the original IEEE and The Open Group Standard
  553. is the referee document. The original Standard can be obtained online at
  554. http://www.opengroup.org/unix/online.html .
  555. .PP
  556. Any typographical or formatting errors that appear
  557. in this page are most likely
  558. to have been introduced during the conversion of the source files to
  559. man page format. To report such errors, see
  560. https://www.kernel.org/doc/man-pages/reporting_bugs.html .