2 files changed, 28 insertions, 9 deletions
diff --git a/lib/libc/gen/popen.3 b/lib/libc/gen/popen.3
index ba1b8cfc47f..7cda6a14fc1 100644
--- a/lib/libc/gen/popen.3
+++ b/lib/libc/gen/popen.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: popen.3,v 1.19 2014/08/31 02:21:18 guenther Exp $
+.\"	$OpenBSD: popen.3,v 1.20 2016/02/05 18:09:20 espie Exp $
 .\"
 .\" Copyright (c) 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 31 2014 $
+.Dd $Mdocdate: February 5 2016 $
 .Dt POPEN 3
 .Os
 .Sh NAME
@@ -158,6 +158,23 @@ and a
 .Fn pclose
 function appeared in
 .At v7 .
+.Sh CAVEATS
+Never supply the
+.Fn popen
+function with a command containing any part of an unsanitized user-supplied
+string.
+Shell meta-characters present will be honored by the
+.Xr sh 1
+command interpreter.
+.Pp
+It is often simpler to bypass the shell entirely and use
+.Xr pipe 2 ,
+.Xr fork 2 ,
+.Xr dup2 2 ,
+.Xr execlp 3 ,
+and
+.Xr fdopen 3
+directly instead of having to sanitize a string for shell consumption.
 .Sh BUGS
 Since the standard input of a command opened for reading
 shares its seek offset with the process that called
@@ -176,8 +193,3 @@ failure to execute
 .Fa command ,
 or an immediate exit of the command.
 The only hint is an exit status of 127.
-.Pp
-The
-.Fn popen
-argument always calls
-.Xr sh 1 .
diff --git a/lib/libc/stdlib/system.3 b/lib/libc/stdlib/system.3
index 878bb0a9d24..bdd94c01156 100644
--- a/lib/libc/stdlib/system.3
+++ b/lib/libc/stdlib/system.3
@@ -29,9 +29,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     $OpenBSD: system.3,v 1.13 2013/07/18 10:14:50 schwarze Exp $
+.\"     $OpenBSD: system.3,v 1.14 2016/02/05 18:09:19 espie Exp $
 .\"
-.Dd $Mdocdate: July 18 2013 $
+.Dd $Mdocdate: February 5 2016 $
 .Dt SYSTEM 3
 .Os
 .Sh NAME
@@ -107,3 +107,10 @@ string.
 Shell meta-characters present will be honored by the
 .Xr sh 1
 command interpreter.
+.Pp
+It is often simpler to bypass the shell and run an external command using
+.Xr fork 2 ,
+.Xr execlp 3 ,
+and
+.Xr waitpid 2
+directly instead of having to sanitize a string for shell consumption.