From 622dc5dae3a2120fdaff68b0642084f41ec44578 Mon Sep 17 00:00:00 2001
From: Matthew Dillon <dillon@apollo.backplane.com>
Date: Sat, 6 Aug 2016 11:05:10 -0700
Subject: [PATCH] libc - Include information on the 'e' flag in the popen()
 manual page.

* Include information on the 'e' flag in the popen() manual page.
---
 lib/libc/gen/popen.3 | 37 +++++++++++++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 4 deletions(-)

diff --git a/lib/libc/gen/popen.3 b/lib/libc/gen/popen.3
index 635514beb2..26e0392ec8 100644
--- a/lib/libc/gen/popen.3
+++ b/lib/libc/gen/popen.3
@@ -25,10 +25,6 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     @(#)popen.3	8.2 (Berkeley) 5/3/95
-.\" $FreeBSD: src/lib/libc/gen/popen.3,v 1.10.2.4 2003/03/15 15:11:05 trhodes Exp $
-.\" $DragonFly: src/lib/libc/gen/popen.3,v 1.4 2006/04/08 08:17:06 swildner Exp $
-.\"
 .Dd May 3, 1995
 .Dt POPEN 3
 .Os
@@ -81,6 +77,20 @@ for writing, or
 for reading and writing.
 .Pp
 The
+.Fa type
+argument may be augmented by appending an
+.Ql e
+to set the descriptor's close-on-exec flag.
+For example,
+.Ql re
+for reading,
+.Ql we
+for writing, or
+.Ql r+e
+for reading and writing.
+Use of this flag is important when operating in threaded environments.
+.Pp
+The
 .Fa command
 argument is a pointer to a null-terminated string
 containing a shell command line.
@@ -114,6 +124,25 @@ Note that output
 .Fn popen
 streams are fully buffered by default.
 .Pp
+.Fn popen
+automatically interlocks and closes descriptors associated with other
+active
+.Fn popen
+files in any sub-process it creates, preventing file descriptor leakage
+between
+.Fn popen
+calls in a thread-safe manner.
+However,
+.Fn popen
+has no control over fork or fork/exec sequences run by other threads which
+do not use the popen mechanism and in this situation it is likely that
+popen descriptors will leak into those sub-processes.
+It is recommended that the
+.Ql e
+flag be used to prevent descriptor leakages into miscellanious fork/exec
+sequences that might be executed by other threads in a multi-threaded
+program.
+.Pp
 The
 .Fn pclose
 function waits for the associated process to terminate
-- 
2.11.4.GIT