diff options
Diffstat (limited to 'man/man2/pipe.2')
| -rw-r--r-- | man/man2/pipe.2 | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/man/man2/pipe.2 b/man/man2/pipe.2 new file mode 100644 index 000000000..a440ad401 --- /dev/null +++ b/man/man2/pipe.2 @@ -0,0 +1,304 @@ +.\" Copyright (C) 2005, 2008, Michael Kerrisk <mtk.manpages@gmail.com> +.\" (A few fragments remain from an earlier (1992) version by +.\" Drew Eckhardt <drew@cs.colorado.edu>.) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt <michael@moria.de> +.\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" Modified 2005, mtk: added an example program +.\" Modified 2008-01-09, mtk: rewrote DESCRIPTION; minor additions +.\" to EXAMPLE text. +.\" 2008-10-10, mtk: add description of pipe2() +.\" +.TH pipe 2 (date) "Linux man-pages (unreleased)" +.SH NAME +pipe, pipe2 \- create pipe +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int pipe(int " pipefd [2]); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" +.B #include <unistd.h> +.P +.BI "int pipe2(int " pipefd "[2], int " flags ); +.P +/* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the + following prototype; see VERSIONS */ +.P +.B #include <unistd.h> +.P +.B struct fd_pair { +.B " long fd[2];" +.B "};" +.B struct fd_pair pipe(void); +.fi +.SH DESCRIPTION +.BR pipe () +creates a pipe, a unidirectional data channel that +can be used for interprocess communication. +The array +.I pipefd +is used to return two file descriptors referring to the ends of the pipe. +.I pipefd[0] +refers to the read end of the pipe. +.I pipefd[1] +refers to the write end of the pipe. +Data written to the write end of the pipe is buffered by the kernel +until it is read from the read end of the pipe. +For further details, see +.BR pipe (7). +.P +If +.I flags +is 0, then +.BR pipe2 () +is the same as +.BR pipe (). +The following values can be bitwise ORed in +.I flags +to obtain different behavior: +.TP +.B O_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the two new file descriptors. +See the description of the same flag in +.BR open (2) +for reasons why this may be useful. +.TP +.BR O_DIRECT " (since Linux 3.4)" +.\" commit 9883035ae7edef3ec62ad215611cb8e17d6a1a5d +Create a pipe that performs I/O in "packet" mode. +Each +.BR write (2) +to the pipe is dealt with as a separate packet, and +.BR read (2)s +from the pipe will read one packet at a time. +Note the following points: +.RS +.IP \[bu] 3 +Writes of greater than +.B PIPE_BUF +bytes (see +.BR pipe (7)) +will be split into multiple packets. +The constant +.B PIPE_BUF +is defined in +.IR <limits.h> . +.IP \[bu] +If a +.BR read (2) +specifies a buffer size that is smaller than the next packet, +then the requested number of bytes are read, +and the excess bytes in the packet are discarded. +Specifying a buffer size of +.B PIPE_BUF +will be sufficient to read the largest possible packets +(see the previous point). +.IP \[bu] +Zero-length packets are not supported. +(A +.BR read (2) +that specifies a buffer size of zero is a no-op, and returns 0.) +.RE +.IP +Older kernels that do not support this flag will indicate this via an +.B EINVAL +error. +.IP +Since Linux 4.5, +.\" commit 0dbf5f20652108106cb822ad7662c786baaa03ff +.\" FIXME . But, it is not possible to specify O_DIRECT when opening a FIFO +it is possible to change the +.B O_DIRECT +setting of a pipe file descriptor using +.BR fcntl (2). +.TP +.B O_NONBLOCK +Set the +.B O_NONBLOCK +file status flag on the open file descriptions +referred to by the new file descriptors. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B O_NOTIFICATION_PIPE +Since Linux 5.8, +.\" commit c73be61cede5882f9605a852414db559c0ebedfd +general notification mechanism is built on the top of the pipe where +kernel splices notification messages into pipes opened by user space. +The owner of the pipe has to tell the kernel which sources of events to watch +and filters can also be applied to select +which subevents should be placed into the pipe. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, +.I errno +is set to indicate the error, and +.I pipefd +is left unchanged. +.P +On Linux (and other systems), +.BR pipe () +does not modify +.I pipefd +on failure. +A requirement standardizing this behavior was added in POSIX.1-2008 TC2. +.\" http://austingroupbugs.net/view.php?id=467 +The Linux-specific +.BR pipe2 () +system call +likewise does not modify +.I pipefd +on failure. +.SH ERRORS +.TP +.B EFAULT +.I pipefd +is not valid. +.TP +.B EINVAL +.RB ( pipe2 ()) +Invalid value in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENFILE +The user hard limit on memory that can be allocated for pipes +has been reached and the caller is not privileged; see +.BR pipe (7). +.TP +.B ENOPKG +.RB ( pipe2 ()) +.B O_NOTIFICATION_PIPE +was passed in +.I flags +and support for notifications +.RB ( CONFIG_WATCH_QUEUE ) +is not compiled into the kernel. +.SH VERSIONS +.\" See http://math-atlas.sourceforge.net/devel/assembly/64.psabi.1.33.ps.Z +.\" for example, section 3.2.1 "Registers and the Stack Frame". +The System V ABI on some architectures allows the use of more than one register +for returning multiple values; several architectures +(namely, Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64) +(ab)use this feature in order to implement the +.BR pipe () +system call in a functional manner: +the call doesn't take any arguments and returns +a pair of file descriptors as the return value on success. +The glibc +.BR pipe () +wrapper function transparently deals with this. +See +.BR syscall (2) +for information regarding registers used for storing second file descriptor. +.SH STANDARDS +.TP +.BR pipe () +POSIX.1-2008. +.TP +.BR pipe2 () +Linux. +.SH HISTORY +.TP +.BR pipe () +POSIX.1-2001. +.TP +.BR pipe2 () +Linux 2.6.27, +glibc 2.9. +.SH EXAMPLES +.\" fork.2 refers to this example program. +The following program creates a pipe, and then +.BR fork (2)s +to create a child process; +the child inherits a duplicate set of file +descriptors that refer to the same pipe. +After the +.BR fork (2), +each process closes the file descriptors that it doesn't need for the pipe +(see +.BR pipe (7)). +The parent then writes the string contained in the program's +command-line argument to the pipe, +and the child reads this string a byte at a time from the pipe +and echoes it on standard output. +.SS Program source +.\" SRC BEGIN (pipe.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/wait.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + int pipefd[2]; + char buf; + pid_t cpid; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s <string>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (pipe(pipefd) == \-1) { + perror("pipe"); + exit(EXIT_FAILURE); + } +\& + cpid = fork(); + if (cpid == \-1) { + perror("fork"); + exit(EXIT_FAILURE); + } +\& + if (cpid == 0) { /* Child reads from pipe */ + close(pipefd[1]); /* Close unused write end */ +\& + while (read(pipefd[0], &buf, 1) > 0) + write(STDOUT_FILENO, &buf, 1); +\& + write(STDOUT_FILENO, "\en", 1); + close(pipefd[0]); + _exit(EXIT_SUCCESS); +\& + } else { /* Parent writes argv[1] to pipe */ + close(pipefd[0]); /* Close unused read end */ + write(pipefd[1], argv[1], strlen(argv[1])); + close(pipefd[1]); /* Reader will see EOF */ + wait(NULL); /* Wait for child */ + exit(EXIT_SUCCESS); + } +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fork (2), +.BR read (2), +.BR socketpair (2), +.BR splice (2), +.BR tee (2), +.BR vmsplice (2), +.BR write (2), +.BR popen (3), +.BR pipe (7) |