| .\" 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) |