[illumos-gate merge]release-20200827

commit dbe930bf51e0d7458b24d30e9f25756c5da54ddf
    13040 grep can leverage bmg in more cases
commit 81dd18d87c3c2e198d2178dfd1f30d62a81b69ea
    3546 add support for grep -o option
commit 8ccd021704a4fe1b4022c110d3dd497f8cd907d5
    13038 grep could support --label
commit 2e5ac464a5683c5bf11439ccad74c9f279051820
    13037 grep could support -L
commit f415aa8f1340638644c6cf63e9d11d3767f4cbba
    13036 grep tests could be easier to extend
commit cd94aa947d1e02a1c25259f2cf06c165d75aa4fa
    13061 Import sed tests from freebsd
commit c6fc7f7b786ce47c35645054cdce73e83f39e7f3
    13051 sed: lastline check does not work properly with empty files
commit e0721d5ae1542c80097f6fcd487736fdfe601233
    13003 console: multiple issues related to colors and font loading and switching
commit 6863ede29751efd2be66ec1b48c3c0ee705d7d61
    13066 Want crontab -u
commit 31c9b836861e74f837a36ca29220b58f3657585a
    13044 Clarify parts of getopt_long(3C)
commit 9fff840dca14d75459a8240b19c931e2fec186c5
    13032 printf(3C) should talk about NULL string pointers

	Conflicts:
	usr/src/test/util-tests/tests/grep_xpg4/grep_test.ksh
	usr/src/man/man1/crontab.1
	usr/src/cmd/cron/crontab.c

2 files changed, 160 insertions, 46 deletions

diff --git a/usr/src/man/man3c/getopt_long.3c b/usr/src/man/man3c/getopt_long.3c
index adf48e6750..6c59fe3fc7 100644
--- a/usr/src/man/man3c/getopt_long.3c
+++ b/usr/src/man/man3c/getopt_long.3c
@@ -29,12 +29,14 @@
 .\"
 .\" Copyright 2018 Jason King
 .\" Copyright 2018, Joyent, Inc.
+.\" Copyright 2020 Oxide Computer Company
 .\"
-.Dd July 17, 2018
+.Dd August 10, 2020
 .Dt GETOPT_LONG 3C
 .Os
 .Sh NAME
 .Nm getopt_long ,
+.Nm getopt_long_clip ,
 .Nm getopt_long_only
 .Nd get long options from command line argument list
 .Sh SYNOPSIS
@@ -72,20 +74,56 @@ The
 .Fn getopt_long
 function is similar to
 .Xr getopt 3C
-but it accepts options in two forms: words and characters.
-The
-.Fn getopt_long
-function provides a superset of the functionality of
+but it accepts options in two forms: short options and long options.
+Short options are the traditional option flags that use a hyphen followed
+by a single character.
+This is the only form of option that is portable and it is supported by
 .Xr getopt 3C .
+Note, some implementation of
+.Xr getopt 3C
+do support non-standard extensions for long options; however, these are
+not portable and not considered in this manual page.
+Common example of short options are:
+.Fl a ,
+.Fl l ,
+and
+.Fl r .
+Long options use two hyphen characters are generally full words.
+The long versions of the above might be:
+.Fl -all ,
+.Fl -list ,
+and
+.Fl -recursive .
+.Pp
 The
 .Fn getopt_long
-function
-can be used in two ways.
+function can be used to:
+.Bl -enum
+.It
+Support an option with both short and long forms.
+.It
+Support an option with only a short form.
+.It
+Support an option with only a long form.
+.El
 .Pp
-In the first way, every long option understood
-by the program has a corresponding short option, and the option
-structure is only used to translate from long options to short
-options.
+To have a short option selected, as with
+.Xr getopt 3C ,
+it must be listed in
+.Fa optstring .
+Long options are instead listed in the
+.Fa longopts
+array.
+For an option to have both a short and long form it must be present in
+both
+.Fa optstring
+and
+.Fa longopts .
+.Pp
+Long options can be handled in two different ways.
+In the first way, every long option understood by the program has a
+corresponding short option, and the option structure is only used to
+translate from long options to short options.
 When used in this fashion,
 .Fn getopt_long
 behaves identically to
@@ -125,7 +163,8 @@ and
 acts similar to
 .Fa optstring
 in
-.Xr getopt 3C .
+.Xr getopt 3C ,
+listing the set of supported short option flags.
 In addition,
 .Fa optstring
 can begin with
@@ -190,7 +229,7 @@ struct option {
 .Pp
 The
 .Fa name
-field should contain the option name without the leading double dash.
+field should contain the option name without the leading double hyphen.
 .Pp
 The
 .Fa has_arg
@@ -281,12 +320,12 @@ is treated the same as
 .It
 Long options cannot be abbreviated on the command line.
 .It
-Long options must use a double dash
+Long options must use a double hyphen
 .Pq Ql -- .
 .It
 Option processing stops at the first non-option.
 .It
-All long options must have an eqivalent short option (single character) and
+All long options must have an equivalent short option (single character) and
 vice-versa.
 .It
 A leading
@@ -465,6 +504,22 @@ The correct invocation would be:
 .Pp
 .Dl cmd Fl cd Fl e Ar ieio
 .Sh EXAMPLES
+.Sy Example 1
+Basic usage of
+.Fn getopt_long .
+.Pp
+In this example, the short options,
+.Fl b
+and
+.Fl f
+are treated the same way as their corresponding long options
+.Fl -buffy
+and
+.Fl -fluoride .
+The long option
+.Fl -daggerset
+is only matched as a long option.
+.Pp
 .Bd -literal -compact
 int bflag, ch, fd;
 int daggerset;
@@ -500,6 +555,88 @@ while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {
 argc -= optind;
 argv += optind;
 .Ed
+.Pp
+.Sy Example 2
+Mixing short-only and long-only options.
+.Pp
+This example has a program that uses both short and long options and
+always causes the option to be handled in a way that is similar to
+.Xr getopt 3C
+regardless of if it is short or long.
+Options that are only long options are assigned a character value that
+is outside of the common 8-bit range
+.Po
+starting at
+.Dv USHRT_MAX
++ 1.
+.Pc
+This allows them to still integrate into a normal
+.Xr getopt 3C
+style option processing loop.
+.Pp
+In the following code,
+.Fl s
+is only usable as a short option while
+.Fl -long-only
+is only usable as a long option, hence
+.Fl s
+is only specified in
+.Fa optstring
+and
+.Fl -long-only
+is only specified in the
+.Fa longopts
+.Vt option
+array.
+.Pp
+.Bd -literal -compact
+#include <getopt.h>
+#include <stdio.h>
+#include <limits.h>
+
+enum longopt_chars {
+        LONG_ONLY = USHRT_MAX +1
+};
+
+static struct option longopts[] = {
+        { "all", no_argument, NULL, 'a' },
+        { "list", no_argument, NULL, 'l' },
+        { "long-only", no_argument, NULL, LONG_ONLY },
+        { "output", required_argument, NULL, 'o' },
+        { NULL }
+};
+
+int
+main(int argc, char *argv[])
+{
+        int ch;
+
+        while ((ch = getopt_long(argc, argv, "alo:s", longopts,
+            NULL)) != -1) {
+                switch (ch) {
+                case 'a':
+                        printf("found -a\en");
+                        break;
+                case 'l':
+                        printf("found -l\en");
+                        break;
+                case 'o':
+                        printf("found -o: %s\en", optarg);
+                        break;
+                case 's':
+                        printf("found -s\en");
+                        break;
+                case LONG_ONLY:
+                        printf("found --long-only\en");
+                        break;
+                default:
+                        break;
+                }
+        }
+
+        return (0);
+}
+.Ed
 .Sh ERRORS
 The
 .Fn getopt_long_clip
diff --git a/usr/src/man/man3c/printf.3c b/usr/src/man/man3c/printf.3c
index c2a9412b37..add9c37bb9 100644
--- a/usr/src/man/man3c/printf.3c
+++ b/usr/src/man/man3c/printf.3c
@@ -45,11 +45,10 @@
 .\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
 .\"
-.TH PRINTF 3C "Jan 7, 2009"
+.TH PRINTF 3C "Aug 19, 2020"
 .SH NAME
 printf, fprintf, sprintf, snprintf, asprintf \- print formatted output
 .SH SYNOPSIS
-.LP
 .nf
 #include <stdio.h>
 
@@ -82,8 +81,6 @@ printf, fprintf, sprintf, snprintf, asprintf \- print formatted output
 .fi
 
 .SH DESCRIPTION
-.sp
-.LP
 The \fBprintf()\fR function places output on the standard output stream
 \fBstdout\fR.
 .sp
@@ -149,8 +146,6 @@ defined by the program's locale (category \fBLC_NUMERIC\fR). In the POSIX
 locale, or in a locale where the radix character is not defined, the radix
 character defaults to a period (\fB\&.\fR).
 .SS "Conversion Specifications"
-.sp
-.LP
 Each conversion specification is introduced by the \fB%\fR character or by the
 character sequence \fB%\fR\fIn\fR\fB$\fR, after which the following appear in
 sequence:
@@ -264,8 +259,6 @@ used, specifying the \fIN\fRth argument requires that all the leading
 arguments, from the first to the (\fIN-1\fR)th, are specified in the format
 string.
 .SS "Flag Characters"
-.sp
-.LP
 The flag characters and their meanings are:
 .sp
 .ne 2
@@ -349,8 +342,6 @@ conversions, the behavior is undefined.
 .RE
 
 .SS "Length Modifiers"
-.sp
-.LP
 The length modifiers and their meanings are:
 .sp
 .ne 2
@@ -461,8 +452,6 @@ double\fR argument.
 If a length modifier appears with any conversion specifier other than as
 specified above, the behavior is undefined.
 .SS "Conversion Specifiers"
-.sp
-.LP
 Each conversion specifier results in fetching zero or more arguments. The
 results are undefined if there are insufficient arguments for the format. If
 the format is exhausted while arguments remain, the excess arguments are
@@ -706,8 +695,11 @@ write only the number of bytes specified by precision; an application that is
 not standard-conforming will write only the portion of the string that will
 display in the number of columns of screen display specified by precision. If
 the precision is not specified, it is taken to be infinite, so all bytes up to
-the first null byte are printed. An argument with a null value will yield
-undefined results.
+the first null byte are printed. An argument with a null value will print
+.BR (null) .
+Note, while this behavior is common across many operating systems, POSIX does
+not guarantee this behavior and portable applications should avoid passing
+NULL.
 .sp
 If an \fBl\fR (ell) qualifier is present, the argument must be a pointer to an
 array of type \fBwchar_t\fR. Wide-characters from the array are converted to
@@ -745,7 +737,8 @@ the precision is specified, only that portion of the wide-character array that
 will display in the number of columns of screen display specified by precision
 will be written. If the precision is not specified, it is taken to be infinite,
 so all wide characters up to the first null character are printed. An argument
-with a null value will yield undefined results.
+with a null value will print
+.BR (null) .
 .RE
 
 .sp
@@ -800,8 +793,6 @@ update between the call to a successful execution of \fBprintf()\fR or
 \fBfflush\fR(3C) or \fBfclose\fR(3C) on the same stream or a call to
 \fBexit\fR(3C) or \fBabort\fR(3C).
 .SH RETURN VALUES
-.sp
-.LP
 The \fBprintf()\fR, \fBfprintf()\fR, \fBsprintf()\fR, and \fBasprintf()\fR
 functions return the number of bytes transmitted (excluding the terminating
 null byte in the case of \fBsprintf()\fR and \fBasprintf()\fR).
@@ -817,8 +808,6 @@ terminating null byte) is returned.
 .LP
 Each function returns a negative value if an output error was encountered.
 .SH ERRORS
-.sp
-.LP
 For the conditions under which \fBprintf()\fR and \fBfprintf()\fR will fail and
 may fail, refer to \fBfputc\fR(3C) or \fBfputwc\fR(3C).
 .sp
@@ -881,14 +870,10 @@ Insufficient storage space is available.
 .RE
 
 .SH USAGE
-.sp
-.LP
 If the application calling the \fBprintf()\fR functions has any objects of type
 \fBwint_t\fR or \fBwchar_t\fR, it must also include the header \fB<wchar.h>\fR
 to have these objects defined.
 .SS "Escape Character Sequences"
-.sp
-.LP
 It is common to use the following escape sequences built into the C language
 when entering format strings for the \fBprintf()\fR functions, but these
 sequences are processed by the C compiler, not by the \fBprintf()\fR function.
@@ -983,7 +968,6 @@ number, omit the zero so that the prefix is an 'x' (uppercase 'X' is not
 allowed in this context). Support for hexadecimal sequences is an ANSI
 extension. See \fBstandards\fR(5).
 .SH EXAMPLES
-.LP
 \fBExample 1 \fRTo print the language-independent date and time format, the
 following statement could be used:
 .sp
@@ -1058,7 +1042,6 @@ printf("pi = %.5f", 4 * atan(1.0));
 .in -2
 
 .SS "Default"
-.LP
 \fBExample 4 \fRThe following example applies only to applications that are not
 standard-conforming. To print a list of names in columns which are 20
 characters wide:
@@ -1070,8 +1053,6 @@ characters wide:
 .in -2
 
 .SH ATTRIBUTES
-.sp
-.LP
 See \fBattributes\fR(5) for descriptions of the following attributes:
 .sp
 
@@ -1103,16 +1084,12 @@ See \fBstandards\fR(5) for the standards conformance of \fBprintf()\fR,
 function is modeled on the one that appears in the FreeBSD, NetBSD, and GNU C
 libraries.
 .SH SEE ALSO
-.sp
-.LP
 \fBexit\fR(2), \fBlseek\fR(2), \fBwrite\fR(2), \fBabort\fR(3C), \fBecvt\fR(3C),
 \fBexit\fR(3C), \fBfclose\fR(3C), \fBfflush\fR(3C), \fBfputwc\fR(3C),
 \fBfree\fR(3C), \fBmalloc\fR(3C), \fBputc\fR(3C), \fBscanf\fR(3C),
 \fBsetlocale\fR(3C), \fBstdio\fR(3C), \fBvprintf\fR(3C), \fBwcstombs\fR(3C),
 \fBwctomb\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)
 .SH NOTES
-.sp
-.LP
 If the \fBj\fR length modifier is used, 32-bit applications that were compiled
 using \fBc89\fR on releases prior to Solaris 10 will experience undefined
 behavior.