mirror of https://github.com/mkerrisk/man-pages
146 lines
4.2 KiB
Groff
146 lines
4.2 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" 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>.)
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.TH PIPE 2 2008-01-09 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
pipe \- create pipe
|
|
.SH SYNOPSIS
|
|
.B #include <unistd.h>
|
|
.sp
|
|
.BI "int pipe(int " pipefd "[2]);"
|
|
.SH DESCRIPTION
|
|
.BR pipe ()
|
|
creates a pipe, a unidirectional data channel that
|
|
can be used for interprocess communication.
|
|
The array
|
|
.IR pipefd
|
|
is used to return two file descriptors referring to the ends of the pipe.
|
|
.IR pipefd[0]
|
|
refers to the read end of the pipe.
|
|
.IR 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).
|
|
.SH "RETURN VALUE"
|
|
On success, zero is returned.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EFAULT
|
|
.I pipefd
|
|
is not valid.
|
|
.TP
|
|
.B EMFILE
|
|
Too many file descriptors are in use by the process.
|
|
.TP
|
|
.B ENFILE
|
|
The system limit on the total number of open files has been reached.
|
|
.SH "CONFORMING TO"
|
|
POSIX.1-2001.
|
|
.SH EXAMPLE
|
|
.\" 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 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
|
|
|
|
#include <sys/wait.h>
|
|
#include <assert.h>
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <unistd.h>
|
|
#include <string.h>
|
|
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
int pipefd[2];
|
|
pid_t cpid;
|
|
char buf;
|
|
|
|
assert(argc == 2);
|
|
|
|
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, "\\n", 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);
|
|
}
|
|
}
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
.BR fork (2),
|
|
.BR read (2),
|
|
.BR socketpair (2),
|
|
.BR write (2),
|
|
.BR popen (3),
|
|
.BR pipe (7)
|