The branch main has been updated by pstef:
URL:
https://cgit.FreeBSD.org/src/commit/?id=2980318b2747711433c4408e89cb1b208aac9748
commit 2980318b2747711433c4408e89cb1b208aac9748
Author: Piotr Paweł Stefaniak <ps...@freebsd.org>
AuthorDate: 2025-02-22 15:57:05 +0000
Commit: Piotr Paweł Stefaniak <ps...@freebsd.org>
CommitDate: 2025-02-27 17:39:29 +0000
sh.1: extend the section about getopts
Provide more details about the influence of optargs' first character
on the shell's behavior in regard to invalid arguments. Also do some
minor word-smithing.
Original submission by rea@
Differential Revision: https://reviews.freebsd.org/D49106
---
bin/sh/sh.1 | 60 ++++++++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 46 insertions(+), 14 deletions(-)
diff --git a/bin/sh/sh.1 b/bin/sh/sh.1
index 3d3f200a8e17..768193905c49 100644
--- a/bin/sh/sh.1
+++ b/bin/sh/sh.1
@@ -31,7 +31,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd January 10, 2025
+.Dd February 27, 2025
.Dt SH 1
.Os
.Sh NAME
@@ -2356,29 +2356,61 @@ Move the specified
.Ar job
or the current job to the foreground.
.It Ic getopts Ar optstring var
-The POSIX
-.Ic getopts
-command.
-The
-.Ic getopts
-command deprecates the older
-.Xr getopt 1
-command.
-The first argument should be a series of letters, each possibly
+Parse command-line options and arguments.
+The first argument
+.Va optstring
+should be a series of letters, each possibly
followed by a colon which indicates that the option takes an argument.
-The specified variable is set to the parsed option.
+The specified variable
+.Va var
+is set to the parsed option.
The index of
the next argument is placed into the shell variable
.Va OPTIND .
If an option takes an argument, it is placed into the shell variable
.Va OPTARG .
-If an invalid option is encountered,
+.Pp
+If the found character
+is not specified by
+.Va optstring
+or if it is missing a required argument,
+the option is considered invalid and:
+.Bl -offset indent
+.It
+If the first character of
+.Va optstring
+is not a colon then
+.Va OPTARG
+is unset,
.Ar var
is set to
-.Ql \&? .
-It returns a false value (1) when it encounters the end of the options.
+.Ql \&?
+and a diagnostic message is written to stderr.
+.It
+If the first character of
+.Va optstring
+is a colon then
+.Va OPTARG
+is set to the the option character found,
+.Ar var
+is set to
+.Ql \&:
+when a required argument is missing or to
+.Ql \&?
+when the option was not specified by
+.Va optstring ,
+and no diagnostic message is written to stderr.
+.El
+.Pp
+.Ic getopts
+returns a false value (1) when it encounters the end of the options.
A new set of arguments may be parsed by assigning
.Li OPTIND=1 .
+The POSIX
+.Ic getopts
+command deprecates the older
+.Xr getopt 1
+command.
.It Ic hash Oo Fl rv Oc Op Ar command ...
The shell maintains a hash table which remembers the locations of commands.
With no arguments whatsoever, the
