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

socketpair.3p (5539B)


  1. '\" et
  2. .TH SOCKETPAIR "3P" 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. socketpair
  12. \(em create a pair of connected sockets
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/socket.h>
  17. .P
  18. int socketpair(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP,
  19. int \fIsocket_vector\fP[2]);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fIsocketpair\fR()
  24. function shall create an unbound pair of connected sockets in a
  25. specified
  26. .IR domain ,
  27. of a specified
  28. .IR type ,
  29. under the protocol optionally specified by the
  30. .IR protocol
  31. argument. The two sockets shall be identical. The file descriptors
  32. used in referencing the created sockets shall be returned in
  33. .IR socket_vector [0]
  34. and
  35. .IR socket_vector [1].
  36. The file descriptors shall be allocated as described in
  37. .IR "Section 2.14" ", " "File Descriptor Allocation".
  38. .P
  39. The
  40. \fIsocketpair\fR()
  41. function takes the following arguments:
  42. .IP "\fIdomain\fR" 12
  43. Specifies the communications domain in which the sockets are to be
  44. created.
  45. .IP "\fItype\fR" 12
  46. Specifies the type of sockets to be created.
  47. .IP "\fIprotocol\fR" 12
  48. Specifies a particular protocol to be used with the sockets.
  49. Specifying a
  50. .IR protocol
  51. of 0 causes
  52. \fIsocketpair\fR()
  53. to use an unspecified default protocol appropriate for the requested
  54. socket type.
  55. .IP "\fIsocket_vector\fR" 12
  56. Specifies a 2-integer array to hold the file descriptors of the created
  57. socket pair.
  58. .P
  59. The
  60. .IR type
  61. argument specifies the socket type, which determines the semantics of
  62. communications over the socket. The following socket types are defined;
  63. implementations may specify additional socket types:
  64. .IP SOCK_STREAM 14
  65. Provides sequenced, reliable, bidirectional, connection-mode byte
  66. streams, and may provide a transmission mechanism for out-of-band
  67. data.
  68. .IP SOCK_DGRAM 14
  69. Provides datagrams, which are connectionless-mode, unreliable messages
  70. of fixed maximum length.
  71. .IP SOCK_SEQPACKET 14
  72. Provides sequenced, reliable, bidirectional, connection-mode
  73. transmission paths for records. A record can be sent using one or more
  74. output operations and received using one or more input operations, but
  75. a single operation never transfers part of more than one record. Record
  76. boundaries are visible to the receiver via the MSG_EOR flag.
  77. .P
  78. If the
  79. .IR protocol
  80. argument is non-zero, it shall specify a protocol that is supported by
  81. the address family. If the
  82. .IR protocol
  83. argument is zero, the default protocol for this address family and type
  84. shall be used. The protocols supported by the system are
  85. implementation-defined.
  86. .P
  87. The process may need to have appropriate privileges to use the
  88. \fIsocketpair\fR()
  89. function or to create some sockets.
  90. .SH "RETURN VALUE"
  91. Upon successful completion, this function shall return 0; otherwise,
  92. \-1 shall be returned and
  93. .IR errno
  94. set to indicate the error, no file descriptors shall be allocated,
  95. and the contents of
  96. .IR socket_vector
  97. shall be left unmodified.
  98. .SH ERRORS
  99. The
  100. \fIsocketpair\fR()
  101. function shall fail if:
  102. .TP
  103. .BR EAFNOSUPPORT
  104. .br
  105. The implementation does not support the specified address family.
  106. .TP
  107. .BR EMFILE
  108. All, or all but one, of the file descriptors available to the
  109. process are currently open.
  110. .TP
  111. .BR ENFILE
  112. No more file descriptors are available for the system.
  113. .TP
  114. .BR EOPNOTSUPP
  115. The specified protocol does not permit creation of socket pairs.
  116. .TP
  117. .BR EPROTONOSUPPORT
  118. .br
  119. The protocol is not supported by the address family, or the protocol is
  120. not supported by the implementation.
  121. .TP
  122. .BR EPROTOTYPE
  123. The socket type is not supported by the protocol.
  124. .P
  125. The
  126. \fIsocketpair\fR()
  127. function may fail if:
  128. .TP
  129. .BR EACCES
  130. The process does not have appropriate privileges.
  131. .TP
  132. .BR ENOBUFS
  133. Insufficient resources were available in the system to perform the
  134. operation.
  135. .TP
  136. .BR ENOMEM
  137. Insufficient memory was available to fulfill the request.
  138. .LP
  139. .IR "The following sections are informative."
  140. .SH "EXAMPLES"
  141. None.
  142. .SH "APPLICATION USAGE"
  143. The documentation for specific address families specifies which
  144. protocols each address family supports. The documentation for specific
  145. protocols specifies which socket types each protocol supports.
  146. .P
  147. The
  148. \fIsocketpair\fR()
  149. function is used primarily with UNIX domain sockets and need not be
  150. supported for other domains.
  151. .SH "RATIONALE"
  152. None.
  153. .SH "FUTURE DIRECTIONS"
  154. None.
  155. .SH "SEE ALSO"
  156. .IR "Section 2.14" ", " "File Descriptor Allocation",
  157. .IR "\fIsocket\fR\^(\|)"
  158. .P
  159. The Base Definitions volume of POSIX.1\(hy2017,
  160. .IR "\fB<sys_socket.h>\fP"
  161. .\"
  162. .SH COPYRIGHT
  163. Portions of this text are reprinted and reproduced in electronic form
  164. from IEEE Std 1003.1-2017, Standard for Information Technology
  165. -- Portable Operating System Interface (POSIX), The Open Group Base
  166. Specifications Issue 7, 2018 Edition,
  167. Copyright (C) 2018 by the Institute of
  168. Electrical and Electronics Engineers, Inc and The Open Group.
  169. In the event of any discrepancy between this version and the original IEEE and
  170. The Open Group Standard, the original IEEE and The Open Group Standard
  171. is the referee document. The original Standard can be obtained online at
  172. http://www.opengroup.org/unix/online.html .
  173. .PP
  174. Any typographical or formatting errors that appear
  175. in this page are most likely
  176. to have been introduced during the conversion of the source files to
  177. man page format. To report such errors, see
  178. https://www.kernel.org/doc/man-pages/reporting_bugs.html .