summaryrefslogtreecommitdiffstats
path: root/man2/pipe.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/pipe.2')
-rw-r--r--man2/pipe.2304
1 files changed, 0 insertions, 304 deletions
diff --git a/man2/pipe.2 b/man2/pipe.2
deleted file mode 100644
index 55e631d..0000000
--- a/man2/pipe.2
+++ /dev/null
@@ -1,304 +0,0 @@
-.\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)