diff options
Diffstat (limited to 'usr/src/man/man3c')
| -rw-r--r-- | usr/src/man/man3c/getopt_long.3c | 167 | ||||
| -rw-r--r-- | usr/src/man/man3c/printf.3c | 39 |
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. |