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

pipe.3p (5059B)


  1. '\" et
  2. .TH PIPE "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. pipe
  12. \(em create an interprocess channel
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int pipe(int \fIfildes\fP[2]);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIpipe\fR()
  23. function shall create a pipe and place two file descriptors, one
  24. each into the arguments
  25. .IR fildes [0]
  26. and
  27. .IR fildes [1],
  28. that refer to the open file descriptions for the read and write ends of
  29. the pipe. The file descriptors shall be allocated as described in
  30. .IR "Section 2.14" ", " "File Descriptor Allocation".
  31. The O_NONBLOCK and FD_CLOEXEC flags shall be clear on both file
  32. descriptors. (The
  33. \fIfcntl\fR()
  34. function can be used to set both these flags.)
  35. .P
  36. Data can be written to the file descriptor
  37. .IR fildes [1]
  38. and read from the file descriptor
  39. .IR fildes [0].
  40. A read on the file descriptor
  41. .IR fildes [0]
  42. shall access data written to the file descriptor
  43. .IR fildes [1]
  44. on a first-in-first-out basis. It is unspecified whether
  45. .IR fildes [0]
  46. is also open for writing and whether
  47. .IR fildes [1]
  48. is also open for reading.
  49. .P
  50. A process has the pipe open for reading (correspondingly writing) if it
  51. has a file descriptor open that refers to the read end,
  52. .IR fildes [0]
  53. (write end,
  54. .IR fildes [1]).
  55. .P
  56. The pipe's user ID shall be set to the effective user ID of the
  57. calling process.
  58. .P
  59. The pipe's group ID shall be set to the effective group ID of the
  60. calling process.
  61. .P
  62. Upon successful completion,
  63. \fIpipe\fR()
  64. shall mark for update the last data access, last data modification,
  65. and last file status change timestamps of the pipe.
  66. .SH "RETURN VALUE"
  67. Upon successful completion, 0 shall be returned; otherwise, \-1 shall
  68. be returned and
  69. .IR errno
  70. set to indicate the error, no file descriptors shall be allocated and
  71. the contents of
  72. .IR fildes
  73. shall be left unmodified.
  74. .SH ERRORS
  75. The
  76. \fIpipe\fR()
  77. function shall fail if:
  78. .TP
  79. .BR EMFILE
  80. All, or all but one, of the file descriptors available to the process
  81. are currently open.
  82. .TP
  83. .BR ENFILE
  84. The number of simultaneously open files in the system would exceed a
  85. system-imposed limit.
  86. .LP
  87. .IR "The following sections are informative."
  88. .SH EXAMPLES
  89. .SS "Using a Pipe to Pass Data Between a Parent Process and a Child Process"
  90. .P
  91. The following example demonstrates the use of a pipe to transfer data
  92. between a parent process and a child process. Error handling is
  93. excluded, but otherwise this code demonstrates good practice when using
  94. pipes: after the
  95. \fIfork\fR()
  96. the two processes close the unused ends of the pipe before they
  97. commence transferring data.
  98. .sp
  99. .RS 4
  100. .nf
  101. #include <stdlib.h>
  102. #include <unistd.h>
  103. \&...
  104. .P
  105. int fildes[2];
  106. const int BSIZE = 100;
  107. char buf[BSIZE];
  108. ssize_t nbytes;
  109. int status;
  110. .P
  111. status = pipe(fildes);
  112. if (status == -1 ) {
  113. /* an error occurred */
  114. ...
  115. }
  116. .P
  117. switch (fork()) {
  118. case -1: /* Handle error */
  119. break;
  120. .P
  121. case 0: /* Child - reads from pipe */
  122. close(fildes[1]); /* Write end is unused */
  123. nbytes = read(fildes[0], buf, BSIZE); /* Get data from pipe */
  124. /* At this point, a further read would see end-of-file ... */
  125. close(fildes[0]); /* Finished with pipe */
  126. exit(EXIT_SUCCESS);
  127. .P
  128. default: /* Parent - writes to pipe */
  129. close(fildes[0]); /* Read end is unused */
  130. write(fildes[1], "Hello world\en", 12); /* Write data on pipe */
  131. close(fildes[1]); /* Child will see EOF */
  132. exit(EXIT_SUCCESS);
  133. }
  134. .fi
  135. .P
  136. .RE
  137. .SH "APPLICATION USAGE"
  138. None.
  139. .SH RATIONALE
  140. The wording carefully avoids using the verb ``to open'' in order to
  141. avoid any implication of use of
  142. \fIopen\fR();
  143. see also
  144. \fIwrite\fR().
  145. .SH "FUTURE DIRECTIONS"
  146. None.
  147. .SH "SEE ALSO"
  148. .IR "Section 2.14" ", " "File Descriptor Allocation",
  149. .IR "\fIfcntl\fR\^(\|)",
  150. .IR "\fIread\fR\^(\|)",
  151. .IR "\fIwrite\fR\^(\|)"
  152. .P
  153. The Base Definitions volume of POSIX.1\(hy2017,
  154. .IR "\fB<fcntl.h>\fP",
  155. .IR "\fB<unistd.h>\fP"
  156. .\"
  157. .SH COPYRIGHT
  158. Portions of this text are reprinted and reproduced in electronic form
  159. from IEEE Std 1003.1-2017, Standard for Information Technology
  160. -- Portable Operating System Interface (POSIX), The Open Group Base
  161. Specifications Issue 7, 2018 Edition,
  162. Copyright (C) 2018 by the Institute of
  163. Electrical and Electronics Engineers, Inc and The Open Group.
  164. In the event of any discrepancy between this version and the original IEEE and
  165. The Open Group Standard, the original IEEE and The Open Group Standard
  166. is the referee document. The original Standard can be obtained online at
  167. http://www.opengroup.org/unix/online.html .
  168. .PP
  169. Any typographical or formatting errors that appear
  170. in this page are most likely
  171. to have been introduced during the conversion of the source files to
  172. man page format. To report such errors, see
  173. https://www.kernel.org/doc/man-pages/reporting_bugs.html .