From d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1 Mon Sep 17 00:00:00 2001 From: Rical Jasan Date: Thu, 15 Jun 2017 21:12:39 -0700 Subject: manual: Replace summary.awk with summary.pl. The Summary is now generated from @standards, and syntax-checking is performed. If invalid @standards syntax is detected, summary.pl will fail, reporting all errors. Failure and error reporting is disabled for now, however, since much of the manual is still incomplete wrt. header and standards annotations. Note that the sorting order of the Summary has changed; summary.pl respects the locale, like summary.awk did, but the use of LC_ALL=C is introduced in the Makefile. Other notable deviations are improved detection of the annotated elements' names, which are used for sorting, and improved detection of the @node used to reference into the manual. The most noticeable difference in the rendered Summary is that entries may now contain multiple lines, one for each header and standard combination. summary.pl accepts a `--help' option, which details the expected syntax of @standards. If errors are reported, the user is directed to this feature for further information. * manual/Makefile: Generate summary.texi with summary.pl. Force use of the C locale. Update Perl dependency comment. * manual/header.texi: Update reference to summary.awk. * manual/macros.texi: Refer authors to `summary.pl --help'. * manual/summary.awk: Remove file. * manual/summary.pl: New file. Generate summary.texi, and check for @standards-related syntax errors. * manual/argp.texi: Convert header and standards @comments to @standards. * manual/arith.texi: Likewise. * manual/charset.texi: Likewise. * manual/conf.texi: Likewise. * manual/creature.texi: Likewise. * manual/crypt.texi: Likewise. * manual/ctype.texi: Likewise. * manual/debug.texi: Likewise. * manual/errno.texi: Likewise. * manual/filesys.texi: Likewise. * manual/getopt.texi: Likewise. * manual/job.texi: Likewise. * manual/lang.texi: Likewise. * manual/llio.texi: Likewise. * manual/locale.texi: Likewise. * manual/math.texi: Likewise. * manual/memory.texi: Likewise. * manual/message.texi: Likewise. * manual/pattern.texi: Likewise. * manual/pipe.texi: Likewise. * manual/process.texi: Likewise. * manual/resource.texi: Likewise. * manual/search.texi: Likewise. * manual/setjmp.texi: Likewise. * manual/signal.texi: Likewise. * manual/socket.texi: Likewise. * manual/startup.texi: Likewise. * manual/stdio.texi: Likewise. * manual/string.texi: Likewise. * manual/sysinfo.texi: Likewise. * manual/syslog.texi: Likewise. * manual/terminal.texi: Likewise. * manual/threads.texi: Likewise. * manual/time.texi: Likewise. * manual/users.texi: Likewise. --- ChangeLog | 46 ++++ manual/Makefile | 9 +- manual/argp.texi | 126 ++++------ manual/arith.texi | 697 ++++++++++++--------------------------------------- manual/charset.texi | 96 +++---- manual/conf.texi | 651 ++++++++++++++++------------------------------- manual/creature.texi | 44 ++-- manual/crypt.texi | 65 ++--- manual/ctype.texi | 116 +++------ manual/debug.texi | 9 +- manual/errno.texi | 504 +++++++++++++------------------------ manual/filesys.texi | 389 ++++++++++------------------ manual/getopt.texi | 24 +- manual/header.texi | 2 +- manual/job.texi | 33 +-- manual/lang.texi | 190 ++++---------- manual/llio.texi | 345 +++++++++---------------- manual/locale.texi | 39 +-- manual/macros.texi | 1 + manual/math.texi | 524 ++++++++------------------------------ manual/memory.texi | 156 +++++------- manual/message.texi | 30 +-- manual/pattern.texi | 219 ++++++---------- manual/pipe.texi | 16 +- manual/process.texi | 69 ++--- manual/resource.texi | 169 +++++-------- manual/search.texi | 45 ++-- manual/setjmp.texi | 33 +-- manual/signal.texi | 257 +++++++------------ manual/socket.texi | 348 +++++++++---------------- manual/startup.texi | 52 ++-- manual/stdio.texi | 495 ++++++++++++------------------------ manual/string.texi | 301 ++++++++-------------- manual/summary.awk | 133 ---------- manual/summary.pl | 403 +++++++++++++++++++++++++++++ manual/sysinfo.texi | 77 ++---- manual/syslog.texi | 15 +- manual/terminal.texi | 303 ++++++++-------------- manual/threads.texi | 18 +- manual/time.texi | 151 ++++------- manual/users.texi | 281 ++++++++------------- 41 files changed, 2611 insertions(+), 4870 deletions(-) delete mode 100644 manual/summary.awk create mode 100755 manual/summary.pl diff --git a/ChangeLog b/ChangeLog index 3360344686..e9bb612d5b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,49 @@ +2017-06-15 Rical Jasan + + * manual/Makefile: Generate summary.texi with summary.pl. Force + use of the C locale. Update Perl dependency comment. + * manual/header.texi: Update reference to summary.awk. + * manual/macros.texi: Refer authors to `summary.pl --help'. + * manual/summary.awk: Remove file. + * manual/summary.pl: New file. Generate summary.texi, and check + for @standards-related syntax errors. + * manual/argp.texi: Convert header and standards @comments to + @standards. + * manual/arith.texi: Likewise. + * manual/charset.texi: Likewise. + * manual/conf.texi: Likewise. + * manual/creature.texi: Likewise. + * manual/crypt.texi: Likewise. + * manual/ctype.texi: Likewise. + * manual/debug.texi: Likewise. + * manual/errno.texi: Likewise. + * manual/filesys.texi: Likewise. + * manual/getopt.texi: Likewise. + * manual/job.texi: Likewise. + * manual/lang.texi: Likewise. + * manual/llio.texi: Likewise. + * manual/locale.texi: Likewise. + * manual/math.texi: Likewise. + * manual/memory.texi: Likewise. + * manual/message.texi: Likewise. + * manual/pattern.texi: Likewise. + * manual/pipe.texi: Likewise. + * manual/process.texi: Likewise. + * manual/resource.texi: Likewise. + * manual/search.texi: Likewise. + * manual/setjmp.texi: Likewise. + * manual/signal.texi: Likewise. + * manual/socket.texi: Likewise. + * manual/startup.texi: Likewise. + * manual/stdio.texi: Likewise. + * manual/string.texi: Likewise. + * manual/sysinfo.texi: Likewise. + * manual/syslog.texi: Likewise. + * manual/terminal.texi: Likewise. + * manual/threads.texi: Likewise. + * manual/time.texi: Likewise. + * manual/users.texi: Likewise. + 2017-06-15 Rical Jasan * manual/macros.texi (@standards): New macro. Provide placeholder diff --git a/manual/Makefile b/manual/Makefile index 510f160d3b..4ed63a8ef3 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -83,11 +83,10 @@ $(objpfx)libc/index.html: $(addprefix $(objpfx),$(libc-texi-generated)) # Generate the summary from the Texinfo source files for each chapter. $(objpfx)summary.texi: $(objpfx)stamp-summary ; -$(objpfx)stamp-summary: summary.awk $(filter-out $(objpfx)summary.texi, \ +$(objpfx)stamp-summary: summary.pl $(filter-out $(objpfx)summary.texi, \ $(texis-path)) $(SHELL) ./check-safety.sh $(filter-out $(objpfx)%, $(texis-path)) - $(AWK) -f $^ | sort -t' ' -df -k 1,1 | tr '\014' '\012' \ - > $(objpfx)summary-tmp + LC_ALL=C $(PERL) $^ > $(objpfx)summary-tmp $(move-if-change) $(objpfx)summary-tmp $(objpfx)summary.texi touch $@ @@ -154,7 +153,7 @@ $(objpfx)%.pdf: %.texinfo # Distribution. -minimal-dist = summary.awk texis.awk tsort.awk libc-texinfo.sh libc.texinfo \ +minimal-dist = summary.pl texis.awk tsort.awk libc-texinfo.sh libc.texinfo \ libm-err.texi stamp-libm-err check-safety.sh \ $(filter-out summary.texi, $(nonexamples)) \ $(patsubst %.c.texi,examples/%.c, $(examples)) @@ -173,7 +172,7 @@ include ../Rules .PHONY: install subdir_install install-data install-data subdir_install: install -# libm-err.texi generation requires perl. +# Generated files requiring perl: libm-err.texi, summary.texi ifneq ($(PERL),no) ifneq ($(strip $(MAKEINFO)),:) install: $(inst_infodir)/libc.info diff --git a/manual/argp.texi b/manual/argp.texi index bca3ca5ed9..854c71b017 100644 --- a/manual/argp.texi +++ b/manual/argp.texi @@ -33,9 +33,8 @@ cases, calling @code{argp_parse} is the only argument-parsing code needed in @code{main}. @xref{Program Arguments}. -@comment argp.h -@comment GNU @deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input}) +@standards{GNU, argp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtslocale{} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} @c Optionally alloca()tes standard help options, initializes the parser, @c then parses individual args in a loop, and then finalizes. @@ -108,18 +107,16 @@ These variables make it easy for user programs to implement the @samp{--version} option and provide a bug-reporting address in the @samp{--help} output. These are implemented in argp by default. -@comment argp.h -@comment GNU @deftypevar {const char *} argp_program_version +@standards{GNU, argp.h} If defined or set by the user program to a non-zero value, then a @samp{--version} option is added when parsing with @code{argp_parse}, which will print the @samp{--version} string followed by a newline and exit. The exception to this is if the @code{ARGP_NO_EXIT} flag is used. @end deftypevar -@comment argp.h -@comment GNU @deftypevar {const char *} argp_program_bug_address +@standards{GNU, argp.h} If defined or set by the user program to a non-zero value, @code{argp_program_bug_address} should point to a string that will be printed at the end of the standard output for the @samp{--help} option, @@ -127,9 +124,8 @@ embedded in a sentence that says @samp{Report bugs to @var{address}.}. @end deftypevar @need 1500 -@comment argp.h -@comment GNU @defvar argp_program_version_hook +@standards{GNU, argp.h} If defined or set by the user program to a non-zero value, a @samp{--version} option is added when parsing with @code{arg_parse}, which prints the program version and exits with a status of zero. This @@ -152,9 +148,8 @@ useful if a program has version information not easily expressed in a simple string. @end defvar -@comment argp.h -@comment GNU @deftypevar error_t argp_err_exit_status +@standards{GNU, argp.h} This is the exit status used when argp exits due to a parsing error. If not defined or set by the user program, this defaults to: @code{EX_USAGE} from @file{}. @@ -166,9 +161,8 @@ not defined or set by the user program, this defaults to: The first argument to the @code{argp_parse} function is a pointer to a @code{struct argp}, which is known as an @dfn{argp parser}: -@comment argp.h -@comment GNU @deftp {Data Type} {struct argp} +@standards{GNU, argp.h} This structure specifies how to parse a given set of options and arguments, perhaps in conjunction with other argp parsers. It has the following fields: @@ -243,9 +237,8 @@ option provided it has multiple names. This should be terminated by an entry with zero in all fields. Note that when using an initialized C array for options, writing @code{@{ 0 @}} is enough to achieve this. -@comment argp.h -@comment GNU @deftp {Data Type} {struct argp_option} +@standards{GNU, argp.h} This structure specifies a single option that an argp parser understands, as well as how to parse and document that option. It has the following fields: @@ -317,28 +310,24 @@ that option is parsed or displayed in help messages: @vtable @code -@comment argp.h -@comment GNU @item OPTION_ARG_OPTIONAL +@standards{GNU, argp.h} The argument associated with this option is optional. -@comment argp.h -@comment GNU @item OPTION_HIDDEN +@standards{GNU, argp.h} This option isn't displayed in any help messages. -@comment argp.h -@comment GNU @item OPTION_ALIAS +@standards{GNU, argp.h} This option is an alias for the closest previous non-alias option. This means that it will be displayed in the same help entry, and will inherit fields other than @code{name} and @code{key} from the option being aliased. -@comment argp.h -@comment GNU @item OPTION_DOC +@standards{GNU, argp.h} This option isn't actually an option and should be ignored by the actual option parser. It is an arbitrary section of documentation that should be displayed in much the same manner as the options. This is known as a @@ -353,9 +342,8 @@ first non-whitespace character is @samp{-}. This entry is displayed after all options, after @code{OPTION_DOC} entries with a leading @samp{-}, in the same group. -@comment argp.h -@comment GNU @item OPTION_NO_USAGE +@standards{GNU, argp.h} This option shouldn't be included in `long' usage messages, but should still be included in other help messages. This is intended for options that are completely documented in an argp's @code{args_doc} @@ -417,9 +405,8 @@ appropriate for @var{key}, and return @code{0} for success, parser function, or a unix error code if a real error occurred. @xref{Error Codes}. -@comment argp.h -@comment GNU @deftypevr Macro int ARGP_ERR_UNKNOWN +@standards{GNU, argp.h} Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any @var{key} value they do not recognize, or for non-option arguments (@code{@var{key} == ARGP_KEY_ARG}) that they are not equipped to handle. @@ -460,9 +447,8 @@ values. In the following example @var{arg} and @var{state} refer to parser function arguments. @xref{Argp Parser Functions}. @vtable @code -@comment argp.h -@comment GNU @item ARGP_KEY_ARG +@standards{GNU, argp.h} This is not an option at all, but rather a command line argument, whose value is pointed to by @var{arg}. @@ -480,9 +466,8 @@ decrements the @code{next} field of its @var{state} argument, the option won't be considered processed; this is to allow you to actually modify the argument, perhaps into an option, and have it processed again. -@comment argp.h -@comment GNU @item ARGP_KEY_ARGS +@standards{GNU, argp.h} If a parser function returns @code{ARGP_ERR_UNKNOWN} for @code{ARGP_KEY_ARG}, it is immediately called again with the key @code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more @@ -511,45 +496,39 @@ case ARGP_KEY_ARGS: break; @end smallexample -@comment argp.h -@comment GNU @item ARGP_KEY_END +@standards{GNU, argp.h} This indicates that there are no more command line arguments. Parser functions are called in a different order, children first. This allows each parser to clean up its state for the parent. -@comment argp.h -@comment GNU @item ARGP_KEY_NO_ARGS +@standards{GNU, argp.h} Because it's common to do some special processing if there aren't any non-option args, parser functions are called with this key if they didn't successfully process any non-option arguments. This is called just before @code{ARGP_KEY_END}, where more general validity checks on previously parsed arguments take place. -@comment argp.h -@comment GNU @item ARGP_KEY_INIT +@standards{GNU, argp.h} This is passed in before any parsing is done. Afterwards, the values of each element of the @code{child_input} field of @var{state}, if any, are copied to each child's state to be the initial value of the @code{input} when @emph{their} parsers are called. -@comment argp.h -@comment GNU @item ARGP_KEY_SUCCESS +@standards{GNU, argp.h} Passed in when parsing has successfully been completed, even if arguments remain. -@comment argp.h -@comment GNU @item ARGP_KEY_ERROR +@standards{GNU, argp.h} Passed in if an error has occurred and parsing is terminated. In this case a call with a key of @code{ARGP_KEY_SUCCESS} is never made. -@comment argp.h -@comment GNU @item ARGP_KEY_FINI +@standards{GNU, argp.h} The final key ever seen by any parser, even after @code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}. Any resources allocated by @code{ARGP_KEY_INIT} may be freed here. At times, certain @@ -597,9 +576,8 @@ The third argument to argp parser functions (@pxref{Argp Parser Functions}) is a pointer to a @code{struct argp_state}, which contains information about the state of the option parsing. -@comment argp.h -@comment GNU @deftp {Data Type} {struct argp_state} +@standards{GNU, argp.h} This structure has the following fields, which may be modified as noted: @table @code @@ -686,9 +664,8 @@ parser function. @xref{Argp Parsing State}. @cindex usage messages, in argp -@comment argp.h -@comment GNU @deftypefun void argp_usage (const struct argp_state *@var{state}) +@standards{GNU, argp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}} @c Just calls argp_state_help with stderr and ARGP_HELP_STD_USAGE. Outputs the standard usage message for the argp parser referred to by @@ -697,9 +674,8 @@ with @code{exit (argp_err_exit_status)}. @xref{Argp Global Variables}. @end deftypefun @cindex syntax error messages, in argp -@comment argp.h -@comment GNU @deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{}) +@standards{GNU, argp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}} @c Lock stream, vasprintf the formatted message into a buffer, print the @c buffer prefixed by the short program name (in libc, @@ -714,9 +690,8 @@ by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{} @end deftypefun @cindex error messages, in argp -@comment argp.h -@comment GNU @deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{}) +@standards{GNU, argp.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} @c Lock stream, write out the short program name, vasprintf the optional @c formatted message to a buffer, print the buffer prefixed by colon and @@ -736,9 +711,8 @@ don't reflect a syntactic problem with the input, such as illegal values for options, bad phase of the moon, etc. @end deftypefun -@comment argp.h -@comment GNU @deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags}) +@standards{GNU, argp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}} @c Just calls _help with the short program name and optionally exit. @c The main problems in _help, besides the usual issues with stream I/O @@ -920,9 +894,8 @@ option with the same name, the parser conflicts are resolved in favor of the parent argp parser(s), or the earlier of the argp parsers in the list of children. -@comment argp.h -@comment GNU @deftp {Data Type} {struct argp_child} +@standards{GNU, argp.h} An entry in the list of subsidiary argp parsers pointed to by the @code{children} field in a @code{struct argp}. The fields are as follows: @@ -963,62 +936,54 @@ modify these defaults, the following flags may be or'd together in the @var{flags} argument to @code{argp_parse}: @vtable @code -@comment argp.h -@comment GNU @item ARGP_PARSE_ARGV0 +@standards{GNU, argp.h} Don't ignore the first element of the @var{argv} argument to @code{argp_parse}. Unless @code{ARGP_NO_ERRS} is set, the first element of the argument vector is skipped for option parsing purposes, as it corresponds to the program name in a command line. -@comment argp.h -@comment GNU @item ARGP_NO_ERRS +@standards{GNU, argp.h} Don't print error messages for unknown options to @code{stderr}; unless this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]} is used as the program name in the error messages. This flag implies @code{ARGP_NO_EXIT}. This is based on the assumption that silent exiting upon errors is bad behavior. -@comment argp.h -@comment GNU @item ARGP_NO_ARGS +@standards{GNU, argp.h} Don't parse any non-option args. Normally these are parsed by calling the parse functions with a key of @code{ARGP_KEY_ARG}, the actual argument being the value. This flag needn't normally be set, as the default behavior is to stop parsing as soon as an argument fails to be parsed. @xref{Argp Parser Functions}. -@comment argp.h -@comment GNU @item ARGP_IN_ORDER +@standards{GNU, argp.h} Parse options and arguments in the same order they occur on the command line. Normally they're rearranged so that all options come first. -@comment argp.h -@comment GNU @item ARGP_NO_HELP +@standards{GNU, argp.h} Don't provide the standard long option @samp{--help}, which ordinarily causes usage and option help information to be output to @code{stdout} and @code{exit (0)}. -@comment argp.h -@comment GNU @item ARGP_NO_EXIT +@standards{GNU, argp.h} Don't exit on errors, although they may still result in error messages. -@comment argp.h -@comment GNU @item ARGP_LONG_ONLY +@standards{GNU, argp.h} Use the GNU getopt `long-only' rules for parsing arguments. This allows long-options to be recognized with only a single @samp{-} (i.e., @samp{-help}). This results in a less useful interface, and its use is discouraged as it conflicts with the way most GNU programs work as well as the GNU coding standards. -@comment argp.h -@comment GNU @item ARGP_SILENT +@standards{GNU, argp.h} Turns off any message-printing/exiting options, specifically @code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}. @end vtable @@ -1063,34 +1028,28 @@ function as the first argument in addition to key values for user options. They specify which help text the @var{text} argument contains: @vtable @code -@comment argp.h -@comment GNU @item ARGP_KEY_HELP_PRE_DOC +@standards{GNU, argp.h} The help text preceding options. -@comment argp.h -@comment GNU @item ARGP_KEY_HELP_POST_DOC +@standards{GNU, argp.h} The help text following options. -@comment argp.h -@comment GNU @item ARGP_KEY_HELP_HEADER +@standards{GNU, argp.h} The option header string. -@comment argp.h -@comment GNU @item ARGP_KEY_HELP_EXTRA +@standards{GNU, argp.h} This is used after all other documentation; @var{text} is zero for this key. -@comment argp.h -@comment GNU @item ARGP_KEY_HELP_DUP_ARGS_NOTE +@standards{GNU, argp.h} The explanatory note printed when duplicate option arguments have been suppressed. -@comment argp.h -@comment GNU @item ARGP_KEY_HELP_ARGS_DOC +@standards{GNU, argp.h} The argument doc string; formally the @code{args_doc} field from the argp parser. @xref{Argp Parsers}. @end vtable @@ -1105,9 +1064,8 @@ cases can be handled using @code{argp_usage} and desirable to print a help message in some context other than parsing the program options, argp offers the @code{argp_help} interface. -@comment argp.h -@comment GNU @deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name}) +@standards{GNU, argp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}} @c Just calls _help. This outputs a help message for the argp parser @var{argp} to diff --git a/manual/arith.texi b/manual/arith.texi index 5c1dcdce06..4554f94495 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -145,9 +145,8 @@ These functions are specified to return a result @var{r} such that the value To use these facilities, you should include the header file @file{stdlib.h} in your program. -@comment stdlib.h -@comment ISO @deftp {Data Type} div_t +@standards{ISO, stdlib.h} This is a structure type used to hold the result returned by the @code{div} function. It has the following members: @@ -160,9 +159,8 @@ The remainder from the division. @end table @end deftp -@comment stdlib.h -@comment ISO @deftypefun div_t div (int @var{numerator}, int @var{denominator}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Functions in this section are pure, and thus safe. The function @code{div} computes the quotient and remainder from @@ -183,9 +181,8 @@ result = div (20, -6); Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}. @end deftypefun -@comment stdlib.h -@comment ISO @deftp {Data Type} ldiv_t +@standards{ISO, stdlib.h} This is a structure type used to hold the result returned by the @code{ldiv} function. It has the following members: @@ -201,18 +198,16 @@ The remainder from the division. type @code{long int} rather than @code{int}.) @end deftp -@comment stdlib.h -@comment ISO @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{ldiv} function is similar to @code{div}, except that the arguments are of type @code{long int} and the result is returned as a structure of type @code{ldiv_t}. @end deftypefun -@comment stdlib.h -@comment ISO @deftp {Data Type} lldiv_t +@standards{ISO, stdlib.h} This is a structure type used to hold the result returned by the @code{lldiv} function. It has the following members: @@ -228,9 +223,8 @@ The remainder from the division. type @code{long long int} rather than @code{int}.) @end deftp -@comment stdlib.h -@comment ISO @deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{lldiv} function is like the @code{div} function, but the arguments are of type @code{long long int} and the result is returned as @@ -239,9 +233,8 @@ a structure of type @code{lldiv_t}. The @code{lldiv} function was added in @w{ISO C99}. @end deftypefun -@comment inttypes.h -@comment ISO @deftp {Data Type} imaxdiv_t +@standards{ISO, inttypes.h} This is a structure type used to hold the result returned by the @code{imaxdiv} function. It has the following members: @@ -260,9 +253,8 @@ See @ref{Integers} for a description of the @code{intmax_t} type. @end deftp -@comment inttypes.h -@comment ISO @deftypefun imaxdiv_t imaxdiv (intmax_t @var{numerator}, intmax_t @var{denominator}) +@standards{ISO, inttypes.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{imaxdiv} function is like the @code{div} function, but the arguments are of type @code{intmax_t} and the result is returned as @@ -323,9 +315,8 @@ and @dfn{not a number} (NaN). @w{ISO C99} defines macros that let you determine what sort of floating-point number a variable holds. -@comment math.h -@comment ISO @deftypefn {Macro} int fpclassify (@emph{float-type} @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is a generic macro which works on all floating-point types and which returns a value of type @code{int}. The possible values are: @@ -360,9 +351,8 @@ property at a time. Generally these macros execute faster than @code{fpclassify}, since there is special hardware support for them. You should therefore use the specific macros whenever possible. -@comment math.h -@comment ISO @deftypefn {Macro} int iscanonical (@emph{float-type} @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} In some floating-point formats, some values have canonical (preferred) and noncanonical encodings (for IEEE interchange binary formats, all @@ -377,9 +367,8 @@ correspond to any valid value of the type. In ISO C terms these are zero for such encodings. @end deftypefn -@comment math.h -@comment ISO @deftypefn {Macro} int isfinite (@emph{float-type} @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if @var{x} is finite: not plus or minus infinity, and not NaN. It is equivalent to @@ -392,9 +381,8 @@ minus infinity, and not NaN. It is equivalent to floating-point type. @end deftypefn -@comment math.h -@comment ISO @deftypefn {Macro} int isnormal (@emph{float-type} @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if @var{x} is finite and normalized. It is equivalent to @@ -404,9 +392,8 @@ It is equivalent to @end smallexample @end deftypefn -@comment math.h -@comment ISO @deftypefn {Macro} int isnan (@emph{float-type} @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if @var{x} is NaN. It is equivalent to @@ -416,25 +403,22 @@ to @end smallexample @end deftypefn -@comment math.h -@comment ISO @deftypefn {Macro} int issignaling (@emph{float-type} @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if @var{x} is a signaling NaN (sNaN). It is from TS 18661-1:2014. @end deftypefn -@comment math.h -@comment ISO @deftypefn {Macro} int issubnormal (@emph{float-type} @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if @var{x} is subnormal. It is from TS 18661-1:2014. @end deftypefn -@comment math.h -@comment ISO @deftypefn {Macro} int iszero (@emph{float-type} @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if @var{x} is zero. It is from TS 18661-1:2014. @@ -446,29 +430,19 @@ recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument. -@comment math.h -@comment BSD @deftypefun int isinf (double @var{x}) -@comment math.h -@comment BSD @deftypefunx int isinff (float @var{x}) -@comment math.h -@comment BSD @deftypefunx int isinfl (long double @var{x}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns @code{-1} if @var{x} represents negative infinity, @code{1} if @var{x} represents positive infinity, and @code{0} otherwise. @end deftypefun -@comment math.h -@comment BSD @deftypefun int isnan (double @var{x}) -@comment math.h -@comment BSD @deftypefunx int isnanf (float @var{x}) -@comment math.h -@comment BSD @deftypefunx int isnanl (long double @var{x}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns a nonzero value if @var{x} is a ``not a number'' value, and zero otherwise. @@ -483,15 +457,10 @@ function for some reason, you can write @end smallexample @end deftypefun -@comment math.h -@comment BSD @deftypefun int finite (double @var{x}) -@comment math.h -@comment BSD @deftypefunx int finitef (float @var{x}) -@comment math.h -@comment BSD @deftypefunx int finitel (long double @var{x}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns a nonzero value if @var{x} is finite or a ``not a number'' value, and zero otherwise. @@ -683,9 +652,8 @@ exception when applied to NaNs. @file{math.h} defines macros that allow you to explicitly set a variable to infinity or NaN. -@comment math.h -@comment ISO @deftypevr Macro float INFINITY +@standards{ISO, math.h} An expression representing positive infinity. It is equal to the value produced by mathematical operations like @code{1.0 / 0.0}. @code{-INFINITY} represents negative infinity. @@ -697,9 +665,8 @@ to this macro. However, this is not recommended; you should use the This macro was introduced in the @w{ISO C99} standard. @end deftypevr -@comment math.h -@comment GNU @deftypevr Macro float NAN +@standards{GNU, math.h} An expression representing a value which is ``not a number''. This macro is a GNU extension, available only on machines that support the ``not a number'' value---that is to say, on all machines that support @@ -711,18 +678,16 @@ such as by defining @code{_GNU_SOURCE}, and then you must include @file{math.h}.) @end deftypevr -@comment math.h -@comment ISO @deftypevr Macro float SNANF @deftypevrx Macro double SNAN @deftypevrx Macro {long double} SNANL +@standardsx{SNANF, ISO, math.h} These macros, defined by TS 18661-1:2014, are constant expressions for signaling NaNs. @end deftypevr -@comment fenv.h -@comment ISO @deftypevr Macro int FE_SNANS_ALWAYS_SIGNAL +@standards{ISO, fenv.h} This macro, defined by TS 18661-1:2014, is defined to @code{1} in @file{fenv.h} to indicate that functions and operations with signaling NaN inputs and floating-point results always raise the invalid @@ -754,25 +719,20 @@ you can test for FPU support with @samp{#ifdef}. They are defined in @file{fenv.h}. @vtable @code -@comment fenv.h -@comment ISO @item FE_INEXACT +@standards{ISO, fenv.h} The inexact exception. -@comment fenv.h -@comment ISO @item FE_DIVBYZERO +@standards{ISO, fenv.h} The divide by zero exception. -@comment fenv.h -@comment ISO @item FE_UNDERFLOW +@standards{ISO, fenv.h} The underflow exception. -@comment fenv.h -@comment ISO @item FE_OVERFLOW +@standards{ISO, fenv.h} The overflow exception. -@comment fenv.h -@comment ISO @item FE_INVALID +@standards{ISO, fenv.h} The invalid exception. @end vtable @@ -782,9 +742,8 @@ which are supported by the FP implementation. These functions allow you to clear exception flags, test for exceptions, and save and restore the set of exceptions flagged. -@comment fenv.h -@comment ISO @deftypefun int feclearexcept (int @var{excepts}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{@assposix{}}@acsafe{@acsposix{}}} @c The other functions in this section that modify FP status register @c mostly do so with non-atomic load-modify-store sequences, but since @@ -800,9 +759,8 @@ The function returns zero in case the operation was successful, a non-zero value otherwise. @end deftypefun -@comment fenv.h -@comment ISO @deftypefun int feraiseexcept (int @var{excepts}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function raises the supported exceptions indicated by @var{excepts}. If more than one exception bit in @var{excepts} is set @@ -816,9 +774,8 @@ The function returns zero in case the operation was successful, a non-zero value otherwise. @end deftypefun -@comment fenv.h -@comment ISO @deftypefun int fesetexcept (int @var{excepts}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function sets the supported exception flags indicated by @var{excepts}, like @code{feraiseexcept}, but without causing enabled @@ -828,9 +785,8 @@ The function returns zero in case the operation was successful, a non-zero value otherwise. @end deftypefun -@comment fenv.h -@comment ISO @deftypefun int fetestexcept (int @var{excepts}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Test whether the exception flags indicated by the parameter @var{except} are currently set. If any of them are, a nonzero value is returned @@ -865,9 +821,8 @@ You cannot explicitly set bits in the status word. You can, however, save the entire status word and restore it later. This is done with the following functions: -@comment fenv.h -@comment ISO @deftypefun int fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function stores in the variable pointed to by @var{flagp} an implementation-defined value representing the current setting of the @@ -877,9 +832,8 @@ The function returns zero in case the operation was successful, a non-zero value otherwise. @end deftypefun -@comment fenv.h -@comment ISO @deftypefun int fesetexceptflag (const fexcept_t *@var{flagp}, int @var{excepts}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function restores the flags for the exceptions indicated by @var{excepts} to the values stored in the variable pointed to by @@ -893,9 +847,8 @@ Note that the value stored in @code{fexcept_t} bears no resemblance to the bit mask returned by @code{fetestexcept}. The type may not even be an integer. Do not attempt to modify an @code{fexcept_t} variable. -@comment fenv.h -@comment ISO @deftypefun int fetestexceptflag (const fexcept_t *@var{flagp}, int @var{excepts}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Test whether the exception flags indicated by the parameter @var{excepts} are set in the variable pointed to by @var{flagp}. If @@ -956,15 +909,10 @@ overflows instead return a particular very large number (usually the largest representable number). @file{math.h} defines macros you can use to test for overflow on both old and new hardware. -@comment math.h -@comment ISO @deftypevr Macro double HUGE_VAL -@comment math.h -@comment ISO @deftypevrx Macro float HUGE_VALF -@comment math.h -@comment ISO @deftypevrx Macro {long double} HUGE_VALL +@standards{ISO, math.h} An expression representing a particular very large number. On machines that use @w{IEEE 754} floating point format, @code{HUGE_VAL} is infinity. On other machines, it's typically the largest positive number that can @@ -1016,24 +964,20 @@ various rounding modes. Each one will be defined if and only if the FPU supports the corresponding rounding mode. @vtable @code -@comment fenv.h -@comment ISO @item FE_TONEAREST +@standards{ISO, fenv.h} Round to nearest. -@comment fenv.h -@comment ISO @item FE_UPWARD +@standards{ISO, fenv.h} Round toward @math{+@infinity{}}. -@comment fenv.h -@comment ISO @item FE_DOWNWARD +@standards{ISO, fenv.h} Round toward @math{-@infinity{}}. -@comment fenv.h -@comment ISO @item FE_TOWARDZERO +@standards{ISO, fenv.h} Round toward zero. @end vtable @@ -1055,9 +999,8 @@ Negative zero can also result from some operations on infinity, such as At any time, one of the above four rounding modes is selected. You can find out which one with this function: -@comment fenv.h -@comment ISO @deftypefun int fegetround (void) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns the currently selected rounding mode, represented by one of the values of the defined rounding mode macros. @@ -1066,9 +1009,8 @@ values of the defined rounding mode macros. @noindent To change the rounding mode, use this function: -@comment fenv.h -@comment ISO @deftypefun int fesetround (int @var{round}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Changes the currently selected rounding mode to @var{round}. If @var{round} does not correspond to one of the supported rounding modes @@ -1111,9 +1053,8 @@ of this type directly. To save the state of the FPU, use one of these functions: -@comment fenv.h -@comment ISO @deftypefun int fegetenv (fenv_t *@var{envp}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Store the floating-point environment in the variable pointed to by @var{envp}. @@ -1122,9 +1063,8 @@ The function returns zero in case the operation was successful, a non-zero value otherwise. @end deftypefun -@comment fenv.h -@comment ISO @deftypefun int feholdexcept (fenv_t *@var{envp}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Store the current floating-point environment in the object pointed to by @var{envp}. Then clear all exception flags, and set the FPU to trap no @@ -1161,9 +1101,8 @@ Some platforms might define other predefined environments. To set the floating-point environment, you can use either of these functions: -@comment fenv.h -@comment ISO @deftypefun int fesetenv (const fenv_t *@var{envp}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Set the floating-point environment to that described by @var{envp}. @@ -1171,9 +1110,8 @@ The function returns zero in case the operation was successful, a non-zero value otherwise. @end deftypefun -@comment fenv.h -@comment ISO @deftypefun int feupdateenv (const fenv_t *@var{envp}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Like @code{fesetenv}, this function sets the floating-point environment to that described by @var{envp}. However, if any exceptions were @@ -1197,9 +1135,8 @@ The special macro @code{FE_DFL_MODE} may be passed to @code{fesetmode}. It represents the floating-point control modes at program start. -@comment fenv.h -@comment ISO @deftypefun int fegetmode (femode_t *@var{modep}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Store the floating-point control modes in the variable pointed to by @var{modep}. @@ -1208,9 +1145,8 @@ The function returns zero in case the operation was successful, a non-zero value otherwise. @end deftypefun -@comment fenv.h -@comment ISO @deftypefun int fesetmode (const femode_t *@var{modep}) +@standards{ISO, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Set the floating-point control modes to those described by @var{modep}. @@ -1225,9 +1161,8 @@ occur, you can use the following two functions. @strong{Portability Note:} These functions are all GNU extensions. -@comment fenv.h -@comment GNU @deftypefun int feenableexcept (int @var{excepts}) +@standards{GNU, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function enables traps for each of the exceptions as indicated by the parameter @var{excepts}. The individual exceptions are described in @@ -1238,9 +1173,8 @@ The function returns the previous enabled exceptions in case the operation was successful, @code{-1} otherwise. @end deftypefun -@comment fenv.h -@comment GNU @deftypefun int fedisableexcept (int @var{excepts}) +@standards{GNU, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function disables traps for each of the exceptions as indicated by the parameter @var{excepts}. The individual exceptions are described in @@ -1251,9 +1185,8 @@ The function returns the previous enabled exceptions in case the operation was successful, @code{-1} otherwise. @end deftypefun -@comment fenv.h -@comment GNU @deftypefun int fegetexcept (void) +@standards{GNU, fenv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function returns a bitmask of all currently enabled exceptions. It returns @code{-1} in case of failure. @@ -1294,18 +1227,12 @@ Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h}; @code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h}. @code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}. -@comment stdlib.h -@comment ISO @deftypefun int abs (int @var{number}) -@comment stdlib.h -@comment ISO @deftypefunx {long int} labs (long int @var{number}) -@comment stdlib.h -@comment ISO @deftypefunx {long long int} llabs (long long int @var{number}) -@comment inttypes.h -@comment ISO @deftypefunx intmax_t imaxabs (intmax_t @var{number}) +@standards{ISO, stdlib.h} +@standardsx{imaxabs, ISO, inttypes.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the absolute value of @var{number}. @@ -1319,29 +1246,19 @@ See @ref{Integers} for a description of the @code{intmax_t} type. @end deftypefun -@comment math.h -@comment ISO @deftypefun double fabs (double @var{number}) -@comment math.h -@comment ISO @deftypefunx float fabsf (float @var{number}) -@comment math.h -@comment ISO @deftypefunx {long double} fabsl (long double @var{number}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns the absolute value of the floating-point number @var{number}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun double cabs (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx float cabsf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {long double} cabsl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the absolute value of the complex number @var{z} (@pxref{Complex Numbers}). The absolute value of a complex number is: @@ -1371,15 +1288,10 @@ those cases. @pindex math.h All these functions are declared in @file{math.h}. -@comment math.h -@comment ISO @deftypefun double frexp (double @var{value}, int *@var{exponent}) -@comment math.h -@comment ISO @deftypefunx float frexpf (float @var{value}, int *@var{exponent}) -@comment math.h -@comment ISO @deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are used to split the number @var{value} into a normalized fraction and an exponent. @@ -1397,15 +1309,10 @@ If @var{value} is zero, then the return value is zero and zero is stored in @code{*@var{exponent}}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double ldexp (double @var{value}, int @var{exponent}) -@comment math.h -@comment ISO @deftypefunx float ldexpf (float @var{value}, int @var{exponent}) -@comment math.h -@comment ISO @deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the result of multiplying the floating-point number @var{value} by 2 raised to the power @var{exponent}. (It can @@ -1419,56 +1326,36 @@ The following functions, which come from BSD, provide facilities equivalent to those of @code{ldexp} and @code{frexp}. See also the @w{ISO C} function @code{logb} which originally also appeared in BSD. -@comment math.h -@comment BSD @deftypefun double scalb (double @var{value}, double @var{exponent}) -@comment math.h -@comment BSD @deftypefunx float scalbf (float @var{value}, float @var{exponent}) -@comment math.h -@comment BSD @deftypefunx {long double} scalbl (long double @var{value}, long double @var{exponent}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{scalb} function is the BSD name for @code{ldexp}. @end deftypefun -@comment math.h -@comment BSD @deftypefun double scalbn (double @var{x}, int @var{n}) -@comment math.h -@comment BSD @deftypefunx float scalbnf (float @var{x}, int @var{n}) -@comment math.h -@comment BSD @deftypefunx {long double} scalbnl (long double @var{x}, int @var{n}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{scalbn} is identical to @code{scalb}, except that the exponent @var{n} is an @code{int} instead of a floating-point number. @end deftypefun -@comment math.h -@comment BSD @deftypefun double scalbln (double @var{x}, long int @var{n}) -@comment math.h -@comment BSD @deftypefunx float scalblnf (float @var{x}, long int @var{n}) -@comment math.h -@comment BSD @deftypefunx {long double} scalblnl (long double @var{x}, long int @var{n}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{scalbln} is identical to @code{scalb}, except that the exponent @var{n} is a @code{long int} instead of a floating-point number. @end deftypefun -@comment math.h -@comment BSD @deftypefun double significand (double @var{x}) -@comment math.h -@comment BSD @deftypefunx float significandf (float @var{x}) -@comment math.h -@comment BSD @deftypefunx {long double} significandl (long double @var{x}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{significand} returns the mantissa of @var{x} scaled to the range @math{[1, 2)}. @@ -1500,86 +1387,61 @@ The @code{fromfp} functions use the following macros, from TS to the rounding directions defined in IEEE 754-2008. @vtable @code -@comment math.h -@comment ISO @item FP_INT_UPWARD +@standards{ISO, math.h} Round toward @math{+@infinity{}}. -@comment math.h -@comment ISO @item FP_INT_DOWNWARD +@standards{ISO, math.h} Round toward @math{-@infinity{}}. -@comment math.h -@comment ISO @item FP_INT_TOWARDZERO +@standards{ISO, math.h} Round toward zero. -@comment math.h -@comment ISO @item FP_INT_TONEARESTFROMZERO +@standards{ISO, math.h} Round to nearest, ties round away from zero. -@comment math.h -@comment ISO @item FP_INT_TONEAREST +@standards{ISO, math.h} Round to nearest, ties round to even. @end vtable -@comment math.h -@comment ISO @deftypefun double ceil (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float ceilf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} ceill (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions round @var{x} upwards to the nearest integer, returning that value as a @code{double}. Thus, @code{ceil (1.5)} is @code{2.0}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double floor (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float floorf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} floorl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions round @var{x} downwards to the nearest integer, returning that value as a @code{double}. Thus, @code{floor (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double trunc (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float truncf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} truncl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{trunc} functions round @var{x} towards zero to the nearest integer (returned in floating-point format). Thus, @code{trunc (1.5)} is @code{1.0} and @code{trunc (-1.5)} is @code{-1.0}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double rint (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float rintf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} rintl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions round @var{x} to an integer value according to the current rounding mode. @xref{Floating Point Parameters}, for @@ -1592,141 +1454,83 @@ If @var{x} was not initially an integer, these functions raise the inexact exception. @end deftypefun -@comment math.h -@comment ISO @deftypefun double nearbyint (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float nearbyintf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} nearbyintl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the same value as the @code{rint} functions, but do not raise the inexact exception if @var{x} is not an integer. @end deftypefun -@comment math.h -@comment ISO @deftypefun double round (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float roundf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} roundl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are similar to @code{rint}, but they round halfway cases away from zero instead of to the nearest integer (or other current rounding mode). @end deftypefun -@comment math.h -@comment ISO @deftypefun double roundeven (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float roundevenf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} roundevenl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions, from TS 18661-1:2014, are similar to @code{round}, but they round halfway cases to even instead of away from zero. @end deftypefun -@comment math.h -@comment ISO @deftypefun {long int} lrint (double @var{x}) -@comment math.h -@comment ISO @deftypefunx {long int} lrintf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long int} lrintl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are just like @code{rint}, but they return a @code{long int} instead of a floating-point number. @end deftypefun -@comment math.h -@comment ISO @deftypefun {long long int} llrint (double @var{x}) -@comment math.h -@comment ISO @deftypefunx {long long int} llrintf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long long int} llrintl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are just like @code{rint}, but they return a @code{long long int} instead of a floating-point number. @end deftypefun -@comment math.h -@comment ISO @deftypefun {long int} lround (double @var{x}) -@comment math.h -@comment ISO @deftypefunx {long int} lroundf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long int} lroundl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are just like @code{round}, but they return a @code{long int} instead of a floating-point number. @end deftypefun -@comment math.h -@comment ISO @deftypefun {long long int} llround (double @var{x}) -@comment math.h -@comment ISO @deftypefunx {long long int} llroundf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long long int} llroundl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are just like @code{round}, but they return a @code{long long int} instead of a floating-point number. @end deftypefun -@comment math.h -@comment ISO @deftypefun intmax_t fromfp (double @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx intmax_t fromfpf (float @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx intmax_t fromfpl (long double @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx uintmax_t ufromfp (double @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx uintmax_t ufromfpf (float @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx uintmax_t ufromfpl (long double @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx intmax_t fromfpx (double @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx intmax_t fromfpxf (float @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx intmax_t fromfpxl (long double @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx uintmax_t ufromfpx (double @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx uintmax_t ufromfpxf (float @var{x}, int @var{round}, unsigned int @var{width}) -@comment math.h -@comment ISO @deftypefunx uintmax_t ufromfpxl (long double @var{x}, int @var{round}, unsigned int @var{width}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions, from TS 18661-1:2014, convert a floating-point number to an integer according to the rounding direction @var{round} (one of @@ -1742,15 +1546,10 @@ exception. @end deftypefun -@comment math.h -@comment ISO @deftypefun double modf (double @var{value}, double *@var{integer-part}) -@comment math.h -@comment ISO @deftypefunx float modff (float @var{value}, float *@var{integer-part}) -@comment math.h -@comment ISO @deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions break the argument @var{value} into an integer part and a fractional part (between @code{-1} and @code{1}, exclusive). Their sum @@ -1769,15 +1568,10 @@ The functions in this section compute the remainder on division of two floating-point numbers. Each is a little different; pick the one that suits your problem. -@comment math.h -@comment ISO @deftypefun double fmod (double @var{numerator}, double @var{denominator}) -@comment math.h -@comment ISO @deftypefunx float fmodf (float @var{numerator}, float @var{denominator}) -@comment math.h -@comment ISO @deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute the remainder from the division of @var{numerator} by @var{denominator}. Specifically, the return value is @@ -1792,15 +1586,10 @@ less than the magnitude of the @var{denominator}. If @var{denominator} is zero, @code{fmod} signals a domain error. @end deftypefun -@comment math.h -@comment BSD @deftypefun double drem (double @var{numerator}, double @var{denominator}) -@comment math.h -@comment BSD @deftypefunx float dremf (float @var{numerator}, float @var{denominator}) -@comment math.h -@comment BSD @deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are like @code{fmod} except that they round the internal quotient @var{n} to the nearest integer instead of towards zero @@ -1816,15 +1605,10 @@ absolute value of the @var{denominator}. The difference between If @var{denominator} is zero, @code{drem} signals a domain error. @end deftypefun -@comment math.h -@comment BSD @deftypefun double remainder (double @var{numerator}, double @var{denominator}) -@comment math.h -@comment BSD @deftypefunx float remainderf (float @var{numerator}, float @var{denominator}) -@comment math.h -@comment BSD @deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is another name for @code{drem}. @end deftypefun @@ -1838,15 +1622,10 @@ perform by hand on floating-point numbers. @w{ISO C99} defines functions to do these operations, which mostly involve changing single bits. -@comment math.h -@comment ISO @deftypefun double copysign (double @var{x}, double @var{y}) -@comment math.h -@comment ISO @deftypefunx float copysignf (float @var{x}, float @var{y}) -@comment math.h -@comment ISO @deftypefunx {long double} copysignl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return @var{x} but with the sign of @var{y}. They work even if @var{x} or @var{y} are NaN or zero. Both of these can carry a @@ -1860,9 +1639,8 @@ This function is defined in @w{IEC 559} (and the appendix with recommended functions in @w{IEEE 754}/@w{IEEE 854}). @end deftypefun -@comment math.h -@comment ISO @deftypefun int signbit (@emph{float-type} @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{signbit} is a generic macro which can work on all floating-point types. It returns a nonzero value if the value of @var{x} has its sign @@ -1873,15 +1651,10 @@ point allows zero to be signed. The comparison @code{-0.0 < 0.0} is false, but @code{signbit (-0.0)} will return a nonzero value. @end deftypefun -@comment math.h -@comment ISO @deftypefun double nextafter (double @var{x}, double @var{y}) -@comment math.h -@comment ISO @deftypefunx float nextafterf (float @var{x}, float @var{y}) -@comment math.h -@comment ISO @deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{nextafter} function returns the next representable neighbor of @var{x} in the direction towards @var{y}. The size of the step between @@ -1897,30 +1670,20 @@ This function is defined in @w{IEC 559} (and the appendix with recommended functions in @w{IEEE 754}/@w{IEEE 854}). @end deftypefun -@comment math.h -@comment ISO @deftypefun double nexttoward (double @var{x}, long double @var{y}) -@comment math.h -@comment ISO @deftypefunx float nexttowardf (float @var{x}, long double @var{y}) -@comment math.h -@comment ISO @deftypefunx {long double} nexttowardl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are identical to the corresponding versions of @code{nextafter} except that their second argument is a @code{long double}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double nextup (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float nextupf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} nextupl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{nextup} function returns the next representable neighbor of @var{x} in the direction of positive infinity. If @var{x} is the smallest negative @@ -1932,15 +1695,10 @@ If @var{x} is @math{+@infinity{}}, @math{+@infinity{}} is returned. @code{nextup} never raises an exception except for signaling NaNs. @end deftypefun -@comment math.h -@comment ISO @deftypefun double nextdown (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float nextdownf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} nextdownl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{nextdown} function returns the next representable neighbor of @var{x} in the direction of negative infinity. If @var{x} is the smallest positive @@ -1953,15 +1711,10 @@ If @var{x} is @math{-@infinity{}}, @math{-@infinity{}} is returned. @end deftypefun @cindex NaN -@comment math.h -@comment ISO @deftypefun double nan (const char *@var{tagp}) -@comment math.h -@comment ISO @deftypefunx float nanf (const char *@var{tagp}) -@comment math.h -@comment ISO @deftypefunx {long double} nanl (const char *@var{tagp}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c The unsafe-but-ruled-safe locale use comes from strtod. The @code{nan} function returns a representation of NaN, provided that @@ -1974,15 +1727,10 @@ The argument @var{tagp} is used in an unspecified manner. On @w{IEEE selects one. On other systems it may do nothing. @end deftypefun -@comment math.h -@comment ISO @deftypefun int canonicalize (double *@var{cx}, const double *@var{x}) -@comment math.h -@comment ISO @deftypefunx int canonicalizef (float *@var{cx}, const float *@var{x}) -@comment math.h -@comment ISO @deftypefunx int canonicalizel (long double *@var{cx}, const long double *@var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} In some floating-point formats, some values have canonical (preferred) and noncanonical encodings (for IEEE interchange binary formats, all @@ -2004,15 +1752,10 @@ corresponding quiet NaN, if that value is a signaling NaN) may be produced as output. @end deftypefun -@comment math.h -@comment ISO @deftypefun double getpayload (const double *@var{x}) -@comment math.h -@comment ISO @deftypefunx float getpayloadf (const float *@var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} getpayloadl (const long double *@var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} IEEE 754 defines the @dfn{payload} of a NaN to be an integer value encoded in the representation of the NaN. Payloads are typically @@ -2024,15 +1767,10 @@ integer, or positive zero, represented as a floating-point number); if floating-point exceptions even for signaling NaNs. @end deftypefun -@comment math.h -@comment ISO @deftypefun int setpayload (double *@var{x}, double @var{payload}) -@comment math.h -@comment ISO @deftypefunx int setpayloadf (float *@var{x}, float @var{payload}) -@comment math.h -@comment ISO @deftypefunx int setpayloadl (long double *@var{x}, long double @var{payload}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions, defined by TS 18661-1:2014, set the object pointed to by @var{x} to a quiet NaN with payload @var{payload} and a zero sign @@ -2042,15 +1780,10 @@ object pointed to by @var{x} is set to positive zero and a nonzero value is returned. They raise no floating-point exceptions. @end deftypefun -@comment math.h -@comment ISO @deftypefun int setpayloadsig (double *@var{x}, double @var{payload}) -@comment math.h -@comment ISO @deftypefunx int setpayloadsigf (float *@var{x}, float @var{payload}) -@comment math.h -@comment ISO @deftypefunx int setpayloadsigl (long double *@var{x}, long double @var{payload}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions, defined by TS 18661-1:2014, set the object poin