Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 305 insertions, 0 deletions

diff --git a/man/man2/pipe.2 b/man/man2/pipe.2
new file mode 100644
index 0000000..ee2189a
--- /dev/null
+++ b/man/man2/pipe.2
@@ -0,0 +1,305 @@
+.\" 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 2024-05-02 "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/types.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)