From ffc9f6ff367b492844cecb3642bc67758080529f Mon Sep 17 00:00:00 2001
From: naddy <naddy@openbsd.org>
Date: Tue, 4 May 2021 21:03:30 +0000
Subject: [PATCH] shell scripts should use getopts instead of getopt

Add a prominent deprecation notice to getopt.1.
Add examples of the getopts idiom to sh.1 and ksh.1.

Requested by and ok espie@, ok jmc@
---
 bin/ksh/ksh.1           | 23 +++++++++++++++++++++--
 bin/ksh/sh.1            | 23 +++++++++++++++++++++--
 usr.bin/getopt/getopt.1 | 11 +++++++++--
 3 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/bin/ksh/ksh.1 b/bin/ksh/ksh.1
index a707a8c5798..b87dcf926a8 100644
--- a/bin/ksh/ksh.1
+++ b/bin/ksh/ksh.1
@@ -1,8 +1,8 @@
-.\"	$OpenBSD: ksh.1,v 1.214 2021/03/11 07:04:12 jmc Exp $
+.\"	$OpenBSD: ksh.1,v 1.215 2021/05/04 21:03:30 naddy Exp $
 .\"
 .\"	Public Domain
 .\"
-.Dd $Mdocdate: March 11 2021 $
+.Dd $Mdocdate: May 4 2021 $
 .Dt KSH 1
 .Os
 .Sh NAME
@@ -3219,6 +3219,25 @@ resetting
 .Ev OPTIND ,
 may lead to unexpected results.
 .Pp
+The following code fragment shows how one might process the arguments
+for a command that can take the option
+.Fl a
+and the option
+.Fl o ,
+which requires an argument.
+.Bd -literal -offset indent
+while getopts ao: name
+do
+	case $name in
+	a)	flag=1 ;;
+	o)	oarg=$OPTARG ;;
+	?)	echo "Usage: ..."; exit 2 ;;
+	esac
+done
+shift $(($OPTIND - 1))
+echo "Non-option arguments: " "$@"
+.Ed
+.Pp
 .It Xo
 .Ic hash
 .Op Fl r
diff --git a/bin/ksh/sh.1 b/bin/ksh/sh.1
index 8328548aa8c..48543693596 100644
--- a/bin/ksh/sh.1
+++ b/bin/ksh/sh.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: sh.1,v 1.152 2019/05/22 15:23:23 schwarze Exp $
+.\"	$OpenBSD: sh.1,v 1.153 2021/05/04 21:03:31 naddy Exp $
 .\"
 .\" Copyright (c) 2015 Jason McIntyre <jmc@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: May 22 2019 $
+.Dd $Mdocdate: May 4 2021 $
 .Dt SH 1
 .Os
 .Sh NAME
@@ -508,6 +508,25 @@ is a colon,
 .Ev OPTARG
 is set to the unsupported option,
 otherwise an error message is displayed.
+.Pp
+The following code fragment shows how one might process the arguments
+for a command that can take the option
+.Fl a
+and the option
+.Fl o ,
+which requires an argument.
+.Bd -literal -offset indent
+while getopts ao: name
+do
+	case $name in
+	a)	flag=1 ;;
+	o)	oarg=$OPTARG ;;
+	?)	echo "Usage: ..."; exit 2 ;;
+	esac
+done
+shift $(($OPTIND - 1))
+echo "Non-option arguments: " "$@"
+.Ed
 .It Ic hash Op Fl r | Ar utility
 Add
 .Ar utility
diff --git a/usr.bin/getopt/getopt.1 b/usr.bin/getopt/getopt.1
index 74cd0b459fa..b4a2e4c34c3 100644
--- a/usr.bin/getopt/getopt.1
+++ b/usr.bin/getopt/getopt.1
@@ -1,9 +1,9 @@
-.\"	$OpenBSD: getopt.1,v 1.19 2018/03/16 16:58:26 schwarze Exp $
+.\"	$OpenBSD: getopt.1,v 1.20 2021/05/04 21:03:31 naddy Exp $
 .\"
 .\" This material, written by Henry Spencer, was released by him
 .\" into the public domain and is thus not subject to any copyright.
 .\"
-.Dd $Mdocdate: March 16 2018 $
+.Dd $Mdocdate: May 4 2021 $
 .Dt GETOPT 1
 .Os
 .Sh NAME
@@ -14,6 +14,13 @@
 .Ar optstring
 .Va $*
 .Sh DESCRIPTION
+The
+.Nm
+utility cannot handle option arguments containing whitespace;
+consider using the standard
+.Ic getopts
+shell built-in instead.
+.Pp
 .Nm
 is used to break up options in command lines for easy parsing by
 shell procedures, and to check for legal options.
-- 
2.20.1