NAME
pipe —
create descriptor pair for
interprocess communication
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <unistd.h>
int
pipe(
int
fildes[2]);
#include <unistd.h>
#include <fcntl.h>
int
pipe2(
int
fildes[2],
int
flags);
DESCRIPTION
The
pipe() function creates a
pipe, which is
an object allowing unidirectional data flow, and allocates a pair of file
descriptors. The first descriptor connects to the
read end
of the pipe, and the second connects to the
write end, so
that data written to
fildes[1] appears on (i.e., can be
read from)
fildes[0]. This allows the output of one
program to be sent to another program: the source's standard output is set up
to be the write end of the pipe, and the sink's standard input is set up to be
the read end of the pipe. The pipe itself persists until all its associated
descriptors are closed.
A pipe whose read or write end has been closed is considered
widowed. Writing on such a pipe causes the writing process
to receive a
SIGPIPE
signal. Widowing a pipe is the
only way to deliver end-of-file to a reader: after the reader consumes any
buffered data, reading a widowed pipe returns a zero count.
The
pipe2() function behaves exactly like
pipe() only it allows extra
flags to
be set on the returned file descriptor. The following flags are valid:
-
-
O_CLOEXEC
- Set the “close-on-exec” property.
-
-
O_NONBLOCK
- Sets non-blocking I/O.
-
-
O_NOSIGPIPE
- Return
EPIPE
instead of raising
SIGPIPE
.
RETURN VALUES
On successful creation of the pipe, zero is returned. Otherwise, a value of -1
is returned and the variable
errno set to indicate the
error.
ERRORS
The
pipe() and
pipe2() calls will fail if:
-
-
- [
EFAULT
]
- The fildes buffer is in an invalid
area of the process's address space. The reliable detection of this error
cannot be guaranteed; when not detected, a signal may be delivered to the
process, indicating an address violation.
-
-
- [
EMFILE
]
- Too many descriptors are active.
-
-
- [
ENFILE
]
- The system file table is full.
pipe2() will also fail if:
-
-
- [
EINVAL
]
- flags contains an invalid value.
SEE ALSO
sh(1),
fork(2),
read(2),
socketpair(2),
write(2)
STANDARDS
The
pipe() function conforms to
IEEE Std
1003.1-1990 (“POSIX.1”).
HISTORY
A
pipe() function call appeared in
Version 6 AT&T UNIX. The
pipe2() function is inspired from Linux and appeared in
NetBSD 6.0.