document bidirectional popens

SCCS-vsn: lib/libc/gen/popen.3 8.2

diff --git a/usr/src/lib/libc/gen/popen.3 b/usr/src/lib/libc/gen/popen.3
index c2f95f9..3612953 100644 (file)
--- a/usr/src/lib/libc/gen/popen.3
+++ b/usr/src/lib/libc/gen/popen.3
@@ -3,7 +3,7 @@
 .\"
 .\" %sccs.include.redist.roff%
 .\"
 .\"
 .\" %sccs.include.redist.roff%
 .\"

-.\"     @(#)popen.3    8.1 (Berkeley) %G%
+.\"     @(#)popen.3    8.2 (Berkeley) %G%

 .\"
 .Dd 
 .Dt POPEN 3
 .\"
 .Dd 
 .Dt POPEN 3


@@ -24,13 +24,32 @@ The
 .Fn popen
 function
 .Dq opens
 .Fn popen
 function
 .Dq opens

-a process by creating a pipe,
+a process by creating an IPC connection,

 forking,
 and invoking the shell.
 forking,
 and invoking the shell.

-Since a pipe is by definition unidirectional, the
+Historically,
+.Nm popen
+was implemented with a unidirectional pipe;
+hence many implementations of
+.Nm popen
+only allow the

 .Fa type
 .Fa type

-argument may specify only reading or writing, not both;
-the resulting stream is correspondingly read-only or write-only.
+argument to specify reading or writing, not both.
+Since
+.Nm popen
+is now implemented using sockets, the
+.Fa type
+may request a bidirectional data flow.
+The
+.Fa type
+argument is a pointer to a null-terminated string
+which must be
+.Ql r
+for reading,
+.Ql w
+for writing, or
+.Ql r+
+for reading and writing.

 .Pp
 The
 .Fa command
 .Pp
 The
 .Fa command


@@ -41,15 +60,6 @@ This command is passed to
 using the
 .Fl c
 flag; interpretation, if any, is performed by the shell.
 using the
 .Fl c
 flag; interpretation, if any, is performed by the shell.

-The
-.Fa mode
-argument is a pointer to a null-terminated string
-which must be either
-.Ql r
-for reading
-or
-.Ql w
-for writing.

 .Pp
 The return value from
 .Fn popen
 .Pp
 The return value from
 .Fn popen


@@ -87,9 +97,10 @@ The
 function returns
 .Dv NULL
 if the
 function returns
 .Dv NULL
 if the

-.Xr fork 2
+.Xr fork 2 ,
+.Xr pipe 2 ,

 or
 or

-.Xr pipe 2
+.Xr socketpair 2

 calls fail,
 or if it cannot allocate memory.
 .Pp
 calls fail,
 or if it cannot allocate memory.
 .Pp


@@ -116,6 +127,7 @@ function does not reliably set
 .Xr fork 2 ,
 .Xr sh 1 ,
 .Xr pipe 2 ,
 .Xr fork 2 ,
 .Xr sh 1 ,
 .Xr pipe 2 ,

+.Xr socketpair 2 ,

 .Xr wait4 2 ,
 .Xr fflush 3 ,
 .Xr fclose 3 ,
 .Xr wait4 2 ,
 .Xr fflush 3 ,
 .Xr fclose 3 ,