@file{unistd.h}.
@pindex unistd.h
-@comment unistd.h
-@comment POSIX.2
@deftypevar int opterr
+@standards{POSIX.2, unistd.h}
If the value of this variable is nonzero, then @code{getopt} prints an
error message to the standard error stream if it encounters an unknown
option character or an option with a missing required argument. This is
to indicate an error.
@end deftypevar
-@comment unistd.h
-@comment POSIX.2
@deftypevar int optopt
+@standards{POSIX.2, unistd.h}
When @code{getopt} encounters an unknown option character or an option
with a missing required argument, it stores that option character in
this variable. You can use this for providing your own diagnostic
messages.
@end deftypevar
-@comment unistd.h
-@comment POSIX.2
@deftypevar int optind
+@standards{POSIX.2, unistd.h}
This variable is set by @code{getopt} to the index of the next element
of the @var{argv} array to be processed. Once @code{getopt} has found
all of the option arguments, you can use this variable to determine
this variable is @code{1}.
@end deftypevar
-@comment unistd.h
-@comment POSIX.2
@deftypevar {char *} optarg
+@standards{POSIX.2, unistd.h}
This variable is set by @code{getopt} to point at the value of the
option argument, for those options that accept arguments.
@end deftypevar
-@comment unistd.h
-@comment POSIX.2
-@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
+@deftypefun int getopt (int @var{argc}, char *const *@var{argv}, const char *@var{options})
+@standards{POSIX.2, unistd.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Swapping elements of passed-in argv may be partial in case of
+@c cancellation. Gettext brings about a whole lot of AS and AC safety
+@c issues. The getopt API involves returning values in the
+@c non-thread-specific optarg variable, which adds another thread-safety
+@c issue. Given print_errors, it may output errors to stderr, which may
+@c self-deadlock, leak locks, or encounter (in a signal handler) or
+@c leave (in case of cancellation) stderr in an inconsistent state.
+@c Various implicit, indirect uses of malloc, in uses of memstream and
+@c asprintf for error-printing, bring about the usual malloc issues.
+@c
+@c _getopt_internal
+@c _getopt_internal_r
+@c gettext
+@c _getopt_initialize
+@c getenv
+@c open_memstream
+@c lockfile, unlockfile, __fxprintf -> stderr
+@c asprintf
The @code{getopt} function gets the next option argument from the
argument list specified by the @var{argv} and @var{argc} arguments.
Normally these values come directly from the arguments received by
returned as if they were associated with option character @samp{\1}.
@item
-POSIX demands the following behavior: The first non-option stops option
+POSIX demands the following behavior: the first non-option stops option
processing. This mode is selected by either setting the environment
variable @code{POSIXLY_CORRECT} or beginning the @var{options} argument
string with a plus sign (@samp{+}).
program accept long options if it uses any options, for this takes
little extra work and helps beginners remember how to use the program.
-@comment getopt.h
-@comment GNU
@deftp {Data Type} {struct option}
+@standards{GNU, getopt.h}
This structure describes a single long option name for the sake of
@code{getopt_long}. The argument @var{longopts} must be an array of
these structures, one for each long option. Terminate the array with an
@end table
@end deftp
-@comment getopt.h
-@comment GNU
@deftypefun int getopt_long (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
+@standards{GNU, getopt.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Same issues as getopt.
Decode options from the vector @var{argv} (whose length is @var{argc}).
The argument @var{shortopts} describes the short options to accept, just as
it does in @code{getopt}. The argument @var{longopts} describes the long
When @code{getopt_long} encounters a short option, it does the same
thing that @code{getopt} would do: it returns the character code for the
-option, and stores the options argument (if it has one) in @code{optarg}.
+option, and stores the option's argument (if it has one) in @code{optarg}.
When @code{getopt_long} encounters a long option, it takes actions based
on the @code{flag} and @code{val} fields of the definition of that
@var{argv} of the next remaining argument.
@end deftypefun
-Since long option names were used before the @code{getopt_long}
-options was invented there are program interfaces which require programs
+Since long option names were used before @code{getopt_long}
+was invented there are program interfaces which require programs
to recognize options like @w{@samp{-option value}} instead of
@w{@samp{--option value}}. To enable these programs to use the GNU
getopt functionality there is one more function available.
-@comment getopt.h
-@comment GNU
@deftypefun int getopt_long_only (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
+@standards{GNU, getopt.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Same issues as getopt.
The @code{getopt_long_only} function is equivalent to the
-@code{getopt_long} function but it allows to specify the user of the
+@code{getopt_long} function but it allows the user of the
application to pass long options with only @samp{-} instead of
@samp{--}. The @samp{--} prefix is still recognized but instead of
looking through the short options if a @samp{-} is seen it is first