Module Name: src
Committed By: lukem
Date: Fri Jan 7 05:30:30 UTC 2022
Modified Files:
src/bin/sh: sh.1
Log Message:
sh(1): improve getopts docs for optstring leading :
getopts has different behaviour if the leading character
of optstring is `:', so describe in more detail:
- no errors are printed (already there)
- unknown options set var to `?' and OPTARG to the unknown option
- missing arguments set var to `:' and OPTARG to the option name
Slight rewording of other paragraphs for more clarity.
To generate a diff of this commit:
cvs rdiff -u -r1.242 -r1.243 src/bin/sh/sh.1
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/bin/sh/sh.1
diff -u src/bin/sh/sh.1:1.242 src/bin/sh/sh.1:1.243
--- src/bin/sh/sh.1:1.242 Fri Jan 7 05:10:30 2022
+++ src/bin/sh/sh.1 Fri Jan 7 05:30:30 2022
@@ -1,4 +1,4 @@
-.\" $NetBSD: sh.1,v 1.242 2022/01/07 05:10:30 lukem Exp $
+.\" $NetBSD: sh.1,v 1.243 2022/01/07 05:30:30 lukem Exp $
.\" Copyright (c) 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
@@ -2932,7 +2932,7 @@ Bell Labs\[en]derived
.Xr getopt 1 .
.Pp
The first argument should be a series of letters, each of which may be
-optionally followed by a colon to indicate that the option requires an
+optionally followed by a colon (:) to indicate that the option requires an
argument.
The variable specified is set to the parsed option.
.Pp
@@ -2969,21 +2969,38 @@ will be unset.
.Ar optstring
is a string of recognized option letters (see
.Xr getopt 3 ) .
-If a letter is followed by a colon, the option is expected to have an
-argument which may or may not be separated from it by whitespace.
+If a letter is followed by a colon (:), the option is expected to have an
+argument which may or may not be separated from the option by whitespace.
If an option character is not found where expected,
.Ic getopts
will set the variable
.Ar var
-to a
+to
.Sq Li \&? ;
.Ic getopts
will then unset
.Ev OPTARG
-and write output to standard error.
-By specifying a colon as the first character of
-.Ar optstring
-all errors will be ignored.
+and write an error to standard error.
+.Pp
+By specifying a colon (:) as the first character of
+.Ar optstring ,
+the error handling behavior changes:
+no errors will be written to standard error;
+unknown option characters will set
+.Ar var
+to
+.Sq Li \&?
+and set
+.Ev OPTARG
+to the unknown option character (instead of unset
+.Ev OPTARG Ns );
+and missing option arguments will set
+.Ar var
+to
+.Sq Li \&:
+and set
+.Ev OPTARG
+to the option character with the missing argument.
.Pp
A nonzero value is returned when the last option is reached.
If there are no remaining arguments,
