Rewrote DESCRIPTION; minor additions to EXAMPLE text.

diff --git a/man2/pipe.2 b/man2/pipe.2
index 19f87d0bb7316ca4ec7b5d5f236f444327a485df..c5e8f9228da952a23120b9bcbeb5090c0fa6045a 100644 (file)
--- a/man2/pipe.2
+++ b/man2/pipe.2
@@ -1,6 +1,8 @@
 .\" Hey Emacs! This file is -*- nroff -*- source.
 .\"
-.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
+.\" 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
@@ -26,8 +28,11 @@
 .\" 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 2004-06-17 "Linux" "Linux Programmer's Manual"
+.TH PIPE 2 2008-01-09 "Linux" "Linux Programmer's Manual"
 .SH NAME
 pipe \- create pipe
 .SH SYNOPSIS
@@ -36,13 +41,19 @@ pipe \- create pipe
 .BI "int pipe(int " pipefd "[2]);"
 .SH DESCRIPTION
 .BR pipe ()
-creates a pair of file descriptors, pointing to a pipe inode, and places
-them in the array pointed to by
-.IR pipefd .
-.I pipefd[0]
-is for reading,
-.I pipefd[1]
-is for writing.
+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
@@ -65,7 +76,9 @@ POSIX.1-2001.
 .\" fork.2 refers to this example program.
 The following program creates a pipe, and then
 .BR fork (2)s
-to create a child process.
+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