.\" to EXAMPLE text.
.\" 2008-10-10, mtk: add description of pipe2()
.\"
-.TH PIPE 2 2012-02-14 "Linux" "Linux Programmer's Manual"
+.TH PIPE 2 2017-11-26 "Linux" "Linux Programmer's Manual"
.SH NAME
pipe, pipe2 \- create pipe
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.sp
+.PP
+/* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64; see NOTES */
+.B struct fd_pair {
+.B " long fd[2];"
+.B "};"
+.B struct fd_pair pipe();
+.PP
+/* On all other architectures */
.BI "int pipe(int " pipefd "[2]);"
-.sp
+
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.BR "#include <fcntl.h>" " /* Obtain O_* constant definitions */
.B #include <unistd.h>
-.sp
+.PP
.BI "int pipe2(int " pipefd "[2], int " flags );
.fi
.SH DESCRIPTION
until it is read from the read end of the pipe.
For further details, see
.BR pipe (7).
-
+.PP
If
.IR flags
is 0, then
The following values can be bitwise ORed in
.IR flags
to obtain different behavior:
-.TP 12
-.B O_NONBLOCK
-Set the
-.BR O_NONBLOCK
-file status flag on the two new open file descriptions.
-Using this flag saves extra calls to
-.BR fcntl (2)
-to achieve the same result.
.TP
.B O_CLOEXEC
Set the close-on-exec
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 * 3
+Writes of greater than
+.BR PIPE_BUF
+bytes (see
+.BR pipe (7))
+will be split into multiple packets.
+The constant
+.BR PIPE_BUF
+is defined in
+.IR <limits.h> .
+.IP *
+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
+.BR PIPE_BUF
+will be sufficient to read the largest possible packets
+(see the previous point).
+.IP *
+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
+.BR 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.
.SH RETURN VALUE
On success, zero is returned.
On error, \-1 is returned, and
.I errno
is set appropriately.
+.PP
+On Linux (and other systems),
+.BR pipe ()
+does not modify
+.I pipefd
+on failure.
+A requirement standardizing this behavior was added in POSIX.1-2016.
+.\" 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
.IR flags .
.TP
.B EMFILE
-Too many file descriptors are in use by the process.
+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 system limit on the total number of open files has been reached.
+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).
.SH VERSIONS
.BR pipe2 ()
was added to Linux in version 2.6.27;
glibc support is available starting with
version 2.9.
+.SH NOTES
+.\" 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 SystemV 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 CONFORMING TO
.BR pipe ():
-POSIX.1-2001.
-
+POSIX.1-2001, POSIX.1-2008.
+.PP
.BR pipe2 ()
is Linux-specific.
.SH EXAMPLE
descriptors that refer to the same pipe.
After the
.BR fork (2),
-each process closes the descriptors that it doesn't need for the pipe
+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.
-.nf
-
+.SS Program source
+.EX
+#include <sys/types.h>
#include <sys/wait.h>
#include <stdio.h>
#include <stdlib.h>
char buf;
if (argc != 2) {
- fprintf(stderr, "Usage: %s <string>\\n", argv[0]);
- exit(EXIT_FAILURE);
+ fprintf(stderr, "Usage: %s <string>\\n", argv[0]);
+ exit(EXIT_FAILURE);
}
if (pipe(pipefd) == \-1) {
exit(EXIT_SUCCESS);
}
}
-.fi
+.EE
.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)
projects / thirdparty / man-pages.git / blobdiff