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@

diff --git a/bin/ksh/ksh.1 b/bin/ksh/ksh.1
index a707a8c..b87dcf9 100644 (file)
--- 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 8328548..4854369 100644 (file)
--- 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 74cd0b4..b4a2e4c 100644 (file)
--- 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.