diff options
| author | Rical Jasan <ricaljasan@pacific.net> | 2017-06-15 21:12:39 -0700 |
|---|---|---|
| committer | Rical Jasan <ricaljasan@pacific.net> | 2017-06-15 21:26:20 -0700 |
| commit | d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1 (patch) | |
| tree | 6f27987046ae0e8804f4d641c99ff1666652117a | |
| parent | 27691d5cec9b896ea0792151a27c6d7d7a4065ea (diff) | |
| download | glibc-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.tar.gz glibc-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.tar.xz glibc-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.zip | |
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.
41 files changed, 2611 insertions, 4870 deletions
diff --git a/ChangeLog b/ChangeLog index 3360344686..e9bb612d5b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,51 @@ 2017-06-15 Rical Jasan <ricaljasan@pacific.net> + * 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 <ricaljasan@pacific.net> + * manual/macros.texi (@standards): New macro. Provide placeholder for header and standards annotations. (@standardsx): New macro. Likewise, for lists of @*x elements. 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{<sysexits.h>}. @@ -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 pointed to by @var{x} to a signaling NaN with payload @var{payload} and a zero @@ -2085,45 +1818,40 @@ argument; it also adds functions that provide a total ordering on all floating-point values, including NaNs, without raising any exceptions even for signaling NaNs. -@comment math.h -@comment ISO @deftypefn Macro int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is greater than @var{y}. It is equivalent to @code{(@var{x}) > (@var{y})}, but no exception is raised if @var{x} or @var{y} are NaN. @end deftypefn -@comment math.h -@comment ISO @deftypefn Macro int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is greater than or equal to @var{y}. It is equivalent to @code{(@var{x}) >= (@var{y})}, but no exception is raised if @var{x} or @var{y} are NaN. @end deftypefn -@comment math.h -@comment ISO @deftypefn Macro int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is less than @var{y}. It is equivalent to @code{(@var{x}) < (@var{y})}, but no exception is raised if @var{x} or @var{y} are NaN. @end deftypefn -@comment math.h -@comment ISO @deftypefn Macro int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is less than or equal to @var{y}. It is equivalent to @code{(@var{x}) <= (@var{y})}, but no exception is raised if @var{x} or @var{y} are NaN. @end deftypefn -@comment math.h -@comment ISO @deftypefn Macro int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is less or greater than @var{y}. It is equivalent to @code{(@var{x}) < (@var{y}) || @@ -2134,17 +1862,15 @@ This macro is not equivalent to @code{@var{x} != @var{y}}, because that expression is true if @var{x} or @var{y} are NaN. @end deftypefn -@comment math.h -@comment ISO @deftypefn Macro int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether its arguments are unordered. In other words, it is true if @var{x} or @var{y} are NaN, and false otherwise. @end deftypefn -@comment math.h -@comment ISO @deftypefn Macro int iseqsig (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether its arguments are equal. It is equivalent to @code{(@var{x}) == (@var{y})}, but it raises the invalid @@ -2152,13 +1878,12 @@ exception and sets @code{errno} to @code{EDOM} if either argument is a NaN. @end deftypefn -@comment math.h -@comment ISO @deftypefun int totalorder (double @var{x}, double @var{y}) -@comment ISO @deftypefunx int totalorderf (float @var{x}, float @var{y}) -@comment ISO @deftypefunx int totalorderl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} +@standardsx{totalorderf, ISO, ???} +@standardsx{totalorderl, ISO, ???} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions determine whether the total order relationship, defined in IEEE 754-2008, is true for @var{x} and @var{y}, returning @@ -2174,13 +1899,12 @@ increasing payload; positive quiet NaNs, in order of increasing payload. @end deftypefun -@comment math.h -@comment ISO @deftypefun int totalordermag (double @var{x}, double @var{y}) -@comment ISO @deftypefunx int totalordermagf (float @var{x}, float @var{y}) -@comment ISO @deftypefunx int totalordermagl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} +@standardsx{totalordermagf, ISO, ???} +@standardsx{totalordermagl, ISO, ???} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions determine whether the total order relationship, defined in IEEE 754-2008, is true for the absolute values of @var{x} @@ -2208,15 +1932,10 @@ operations that are awkward to express with C operators. On some processors these functions can use special machine instructions to perform these operations faster than the equivalent C code. -@comment math.h -@comment ISO @deftypefun double fmin (double @var{x}, double @var{y}) -@comment math.h -@comment ISO @deftypefunx float fminf (float @var{x}, float @var{y}) -@comment math.h -@comment ISO @deftypefunx {long double} fminl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fmin} function returns the lesser of the two values @var{x} and @var{y}. It is similar to the expression @@ -2229,15 +1948,10 @@ If an argument is NaN, the other argument is returned. If both arguments are NaN, NaN is returned. @end deftypefun -@comment math.h -@comment ISO @deftypefun double fmax (double @var{x}, double @var{y}) -@comment math.h -@comment ISO @deftypefunx float fmaxf (float @var{x}, float @var{y}) -@comment math.h -@comment ISO @deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fmax} function returns the greater of the two values @var{x} and @var{y}. @@ -2246,15 +1960,10 @@ If an argument is NaN, the other argument is returned. If both arguments are NaN, NaN is returned. @end deftypefun -@comment math.h -@comment ISO @deftypefun double fminmag (double @var{x}, double @var{y}) -@comment math.h -@comment ISO @deftypefunx float fminmagf (float @var{x}, float @var{y}) -@comment math.h -@comment ISO @deftypefunx {long double} fminmagl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions, from TS 18661-1:2014, return whichever of the two values @var{x} and @var{y} has the smaller absolute value. If both @@ -2262,15 +1971,10 @@ have the same absolute value, or either is NaN, they behave the same as the @code{fmin} functions. @end deftypefun -@comment math.h -@comment ISO @deftypefun double fmaxmag (double @var{x}, double @var{y}) -@comment math.h -@comment ISO @deftypefunx float fmaxmagf (float @var{x}, float @var{y}) -@comment math.h -@comment ISO @deftypefunx {long double} fmaxmagl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions, from TS 18661-1:2014, return whichever of the two values @var{x} and @var{y} has the greater absolute value. If both @@ -2278,15 +1982,10 @@ have the same absolute value, or either is NaN, they behave the same as the @code{fmax} functions. @end deftypefun -@comment math.h -@comment ISO @deftypefun double fdim (double @var{x}, double @var{y}) -@comment math.h -@comment ISO @deftypefunx float fdimf (float @var{x}, float @var{y}) -@comment math.h -@comment ISO @deftypefunx {long double} fdiml (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fdim} function returns the positive difference between @var{x} and @var{y}. The positive difference is @math{@var{x} - @@ -2295,15 +1994,10 @@ The @code{fdim} function returns the positive difference between If @var{x}, @var{y}, or both are NaN, NaN is returned. @end deftypefun -@comment math.h -@comment ISO @deftypefun double fma (double @var{x}, double @var{y}, double @var{z}) -@comment math.h -@comment ISO @deftypefunx float fmaf (float @var{x}, float @var{y}, float @var{z}) -@comment math.h -@comment ISO @deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z}) +@standards{ISO, math.h} @cindex butterfly @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fma} function performs floating-point multiply-add. This is @@ -2426,56 +2120,36 @@ complex numbers, such as decomposition and conjugation. The prototypes for all these functions are in @file{complex.h}. All functions are available in three variants, one for each of the three complex types. -@comment complex.h -@comment ISO @deftypefun double creal (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx float crealf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {long double} creall (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the real part of the complex number @var{z}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun double cimag (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx float cimagf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {long double} cimagl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the imaginary part of the complex number @var{z}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} conj (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} conjf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} conjl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the conjugate value of the complex number @var{z}. The conjugate of a complex number has the same real part and a negated imaginary part. In other words, @samp{conj(a + bi) = a + -bi}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun double carg (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx float cargf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {long double} cargl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the argument of the complex number @var{z}. The argument of a complex number is the angle in the complex plane @@ -2486,15 +2160,10 @@ number. This angle is measured in the usual fashion and ranges from @code{carg} has a branch cut along the negative real axis. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} cproj (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} cprojf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} cprojl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the projection of the complex value @var{z} onto the Riemann sphere. Values with an infinite imaginary part are projected @@ -2538,9 +2207,8 @@ functions in this section. It is seemingly useless but the @w{ISO C} standard uses it (for the functions defined there) so we have to do it as well. -@comment stdlib.h -@comment ISO @deftypefun {long int} strtol (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c strtol uses the thread-local pointer to the locale in effect, and @c strtol_l loads the LC_NUMERIC locale data from it early on and once, @@ -2610,9 +2278,8 @@ case there was overflow. There is an example at the end of this section. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {long int} wcstol (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstol} function is equivalent to the @code{strtol} function in nearly all aspects but handles wide character strings. @@ -2620,9 +2287,8 @@ in nearly all aspects but handles wide character strings. The @code{wcstol} function was introduced in @w{Amendment 1} of @w{ISO C90}. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun {unsigned long int} strtoul (const char *retrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoul} (``string-to-unsigned-long'') function is like @code{strtol} except it converts to an @code{unsigned long int} value. @@ -2639,9 +2305,8 @@ and an input more negative than @code{LONG_MIN} returns range, or @code{ERANGE} on overflow. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {unsigned long int} wcstoul (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoul} function is equivalent to the @code{strtoul} function in nearly all aspects but handles wide character strings. @@ -2649,9 +2314,8 @@ in nearly all aspects but handles wide character strings. The @code{wcstoul} function was introduced in @w{Amendment 1} of @w{ISO C90}. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun {long long int} strtoll (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoll} function is like @code{strtol} except that it returns a @code{long long int} value, and accepts numbers with a correspondingly @@ -2666,9 +2330,8 @@ appropriate for the sign of the value. It also sets @code{errno} to The @code{strtoll} function was introduced in @w{ISO C99}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {long long int} wcstoll (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoll} function is equivalent to the @code{strtoll} function in nearly all aspects but handles wide character strings. @@ -2676,16 +2339,14 @@ in nearly all aspects but handles wide character strings. The @code{wcstoll} function was introduced in @w{Amendment 1} of @w{ISO C90}. @end deftypefun -@comment stdlib.h -@comment BSD @deftypefun {long long int} strtoq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun {long long int} wcstoq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoq} function is equivalent to the @code{strtoq} function in nearly all aspects but handles wide character strings. @@ -2693,9 +2354,8 @@ in nearly all aspects but handles wide character strings. The @code{wcstoq} function is a GNU extension. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun {unsigned long long int} strtoull (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoull} function is related to @code{strtoll} the same way @code{strtoul} is related to @code{strtol}. @@ -2703,9 +2363,8 @@ The @code{strtoull} function is related to @code{strtoll} the same way The @code{strtoull} function was introduced in @w{ISO C99}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {unsigned long long int} wcstoull (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoull} function is equivalent to the @code{strtoull} function in nearly all aspects but handles wide character strings. @@ -2713,16 +2372,14 @@ in nearly all aspects but handles wide character strings. The @code{wcstoull} function was introduced in @w{Amendment 1} of @w{ISO C90}. @end deftypefun -@comment stdlib.h -@comment BSD @deftypefun {unsigned long long int} strtouq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @code{strtouq} is the BSD name for @code{strtoull}. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun {unsigned long long int} wcstouq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstouq} function is equivalent to the @code{strtouq} function in nearly all aspects but handles wide character strings. @@ -2730,9 +2387,8 @@ in nearly all aspects but handles wide character strings. The @code{wcstouq} function is a GNU extension. @end deftypefun -@comment inttypes.h -@comment ISO @deftypefun intmax_t strtoimax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@standards{ISO, inttypes.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoimax} function is like @code{strtol} except that it returns a @code{intmax_t} value, and accepts numbers of a corresponding range. @@ -2747,9 +2403,8 @@ See @ref{Integers} for a description of the @code{intmax_t} type. The @code{strtoimax} function was introduced in @w{ISO C99}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun intmax_t wcstoimax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoimax} function is equivalent to the @code{strtoimax} function in nearly all aspects but handles wide character strings. @@ -2757,9 +2412,8 @@ in nearly all aspects but handles wide character strings. The @code{wcstoimax} function was introduced in @w{ISO C99}. @end deftypefun -@comment inttypes.h -@comment ISO @deftypefun uintmax_t strtoumax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@standards{ISO, inttypes.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoumax} function is related to @code{strtoimax} the same way that @code{strtoul} is related to @code{strtol}. @@ -2768,9 +2422,8 @@ See @ref{Integers} for a description of the @code{intmax_t} type. The @code{strtoumax} function was introduced in @w{ISO C99}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun uintmax_t wcstoumax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoumax} function is equivalent to the @code{strtoumax} function in nearly all aspects but handles wide character strings. @@ -2778,9 +2431,8 @@ in nearly all aspects but handles wide character strings. The @code{wcstoumax} function was introduced in @w{ISO C99}. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun {long int} atol (const char *@var{string}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is similar to the @code{strtol} function with a @var{base} argument of @code{10}, except that it need not detect overflow errors. @@ -2788,18 +2440,16 @@ The @code{atol} function is provided mostly for compatibility with existing code; using @code{strtol} is more robust. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun int atoi (const char *@var{string}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is like @code{atol}, except that it returns an @code{int}. The @code{atoi} function is also considered obsolete; use @code{strtol} instead. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun {long long int} atoll (const char *@var{string}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is similar to @code{atol}, except it returns a @code{long long int}. @@ -2862,9 +2512,8 @@ functions in this section. It is seemingly useless but the @w{ISO C} standard uses it (for the functions defined there) so we have to do it as well. -@comment stdlib.h -@comment ISO @deftypefun double strtod (const char *restrict @var{string}, char **restrict @var{tailptr}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c Besides the unsafe-but-ruled-safe locale uses, this uses a lot of @c mpn, but it's all safe. @@ -2973,12 +2622,9 @@ should check for errors in the same way as for @code{strtol}, by examining @var{errno} and @var{tailptr}. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun float strtof (const char *@var{string}, char **@var{tailptr}) -@comment stdlib.h -@comment ISO @deftypefunx {long double} strtold (const char *@var{string}, char **@var{tailptr}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @comment See safety comments for strtod. These functions are analogous to @code{strtod}, but return @code{float} @@ -2991,12 +2637,9 @@ double} is a separate type). These functions have been GNU extensions and are new to @w{ISO C99}. @end deftypefun -@comment stdlib.h -@comment ISO/IEC TS 18661-3 @deftypefun _FloatN strtofN (const char *@var{string}, char **@var{tailptr}) -@comment stdlib.h -@comment ISO/IEC TS 18661-3 @deftypefunx _FloatNx strtofNx (const char *@var{string}, char **@var{tailptr}) +@standards{ISO/IEC TS 18661-3, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @comment See safety comments for strtod. These functions are like @code{strtod}, except for the return type. @@ -3005,21 +2648,14 @@ They were introduced in @w{ISO/IEC TS 18661-3} and are available on machines that support the related types; @pxref{Mathematics}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun double wcstod (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}) -@comment wchar.h -@comment ISO @deftypefunx float wcstof (const wchar_t *@var{string}, wchar_t **@var{tailptr}) -@comment wchar.h -@comment ISO @deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr}) -@comment wchar.h -@comment GNU @deftypefunx _FloatN wcstofN (const wchar_t *@var{string}, wchar_t **@var{tailptr}) -@comment wchar.h -@comment GNU @deftypefunx _FloatNx wcstofNx (const wchar_t *@var{string}, wchar_t **@var{tailptr}) +@standards{ISO, wchar.h} +@standardsx{wcstofN, GNU, wchar.h} +@standardsx{wcstofNx, GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @comment See safety comments for strtod. The @code{wcstod}, @code{wcstof}, @code{wcstol}, @code{wcstof@var{N}}, @@ -3039,9 +2675,8 @@ conversion functions. They are only available on machines that support the related types; @pxref{Mathematics}. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun double atof (const char *@var{string}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is similar to the @code{strtod} function, except that it need not detect overflow and underflow errors. The @code{atof} function @@ -3060,15 +2695,10 @@ See also @ref{Parsing of Integers}. @pindex stdlib.h The @samp{strfrom} functions are declared in @file{stdlib.h}. -@comment stdlib.h -@comment ISO/IEC TS 18661-1 @deftypefun int strfromd (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, double @var{value}) -@comment stdlib.h -@comment ISO/IEC TS 18661-1 @deftypefunx int strfromf (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, float @var{value}) -@comment stdlib.h -@comment ISO/IEC TS 18661-1 @deftypefunx int strfroml (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, long double @var{value}) +@standards{ISO/IEC TS 18661-1, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @comment All these functions depend on both __printf_fp and __printf_fphex, @comment which are both AS-unsafe (ascuheap) and AC-unsafe (acsmem). @@ -3098,12 +2728,9 @@ has been completely written if and only if the returned value is less than These functions were introduced by ISO/IEC TS 18661-1. @end deftypefun -@comment stdlib.h -@comment ISO/IEC TS 18661-3 @deftypefun int strfromfN (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, _Float@var{N} @var{value}) -@comment stdlib.h -@comment ISO/IEC TS 18661-3 @deftypefunx int strfromfNx (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, _Float@var{N}x @var{value}) +@standards{ISO/IEC TS 18661-3, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @comment See safety comments for strfromd. These functions are like @code{strfromd}, except for the type of @@ -3126,9 +2753,9 @@ need, it is better to use @code{sprintf}, which is standard. All these functions are defined in @file{stdlib.h}. -@comment stdlib.h -@comment SVID, Unix98 @deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) +@standards{SVID, stdlib.h} +@standards{Unix98, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:ecvt}}@asunsafe{}@acsafe{}} The function @code{ecvt} converts the floating-point number @var{value} to a string with at most @var{ndigit} decimal digits. The @@ -3152,9 +2779,9 @@ For example: @code{ecvt (12.3, 5, &d, &n)} returns @code{"12300"} and sets @var{d} to @code{2} and @var{n} to @code{0}. @end deftypefun -@comment stdlib.h -@comment SVID, Unix98 @deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) +@standards{SVID, stdlib.h} +@standards{Unix98, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:fcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The function @code{fcvt} is like @code{ecvt}, but @var{ndigit} specifies the number of digits after the decimal point. If @var{ndigit} is less @@ -3171,9 +2798,9 @@ The returned string is statically allocated and overwritten by each call to @code{fcvt}. @end deftypefun -@comment stdlib.h -@comment SVID, Unix98 @deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf}) +@standards{SVID, stdlib.h} +@standards{Unix98, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c gcvt calls sprintf, that ultimately calls vfprintf, which malloc()s @c args_value if it's too large, but gcvt never exercises this path. @@ -3188,27 +2815,24 @@ If @var{ndigit} decimal digits would exceed the precision of a As extensions, @theglibc{} provides versions of these three functions that take @code{long double} arguments. -@comment stdlib.h -@comment GNU @deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:qecvt}}@asunsafe{}@acsafe{}} This function is equivalent to @code{ecvt} except that it takes a @code{long double} for the first parameter and that @var{ndigit} is restricted by the precision of a @code{long double}. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:qfcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function is equivalent to @code{fcvt} except that it takes a @code{long double} for the first parameter and that @var{ndigit} is restricted by the precision of a @code{long double}. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is equivalent to @code{gcvt} except that it takes a @code{long double} for the first parameter and that @var{ndigit} is @@ -3227,9 +2851,8 @@ string into a user-supplied buffer. These have the conventional @code{gcvt_r} is not necessary, because @code{gcvt} already uses a user-supplied buffer. -@comment stdlib.h -@comment GNU @deftypefun int ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{ecvt_r} function is the same as @code{ecvt}, except that it places its result into the user-specified buffer pointed to by @@ -3239,9 +2862,9 @@ case of an error and zero otherwise. This function is a GNU extension. @end deftypefun -@comment stdlib.h -@comment SVID, Unix98 @deftypefun int fcvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) +@standards{SVID, stdlib.h} +@standards{Unix98, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fcvt_r} function is the same as @code{fcvt}, except that it places its result into the user-specified buffer pointed to by @@ -3251,9 +2874,8 @@ case of an error and zero otherwise. This function is a GNU extension. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{qecvt_r} function is the same as @code{qecvt}, except that it places its result into the user-specified buffer pointed to by @@ -3263,9 +2885,8 @@ case of an error and zero otherwise. This function is a GNU extension. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int qfcvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{qfcvt_r} function is the same as @code{qfcvt}, except that it places its result into the user-specified buffer pointed to by diff --git a/manual/charset.texi b/manual/charset.texi index 147d9c579a..1867ace485 100644 --- a/manual/charset.texi +++ b/manual/charset.texi @@ -98,9 +98,8 @@ designed to keep one character of a wide character string. To maintain the similarity there is also a type corresponding to @code{int} for those functions that take a single wide character. -@comment stddef.h -@comment ISO @deftp {Data type} wchar_t +@standards{ISO, stddef.h} This data type is used as the base type for wide character strings. In other words, arrays of objects of this type are the equivalent of @code{char[]} for multibyte character strings. The type is defined in @@ -123,9 +122,8 @@ resorting to multi-wide-character encoding contradicts the purpose of the @code{wchar_t} type. @end deftp -@comment wchar.h -@comment ISO @deftp {Data type} wint_t +@standards{ISO, wchar.h} @code{wint_t} is a data type used for parameters and variables that contain a single wide character. As the name suggests this type is the equivalent of @code{int} when using the normal @code{char} strings. The @@ -143,18 +141,16 @@ As there are for the @code{char} data type macros are available for specifying the minimum and maximum value representable in an object of type @code{wchar_t}. -@comment wchar.h -@comment ISO @deftypevr Macro wint_t WCHAR_MIN +@standards{ISO, wchar.h} The macro @code{WCHAR_MIN} evaluates to the minimum value representable by an object of type @code{wint_t}. This macro was introduced in @w{Amendment 1} to @w{ISO C90}. @end deftypevr -@comment wchar.h -@comment ISO @deftypevr Macro wint_t WCHAR_MAX +@standards{ISO, wchar.h} The macro @code{WCHAR_MAX} evaluates to the maximum value representable by an object of type @code{wint_t}. @@ -163,9 +159,8 @@ This macro was introduced in @w{Amendment 1} to @w{ISO C90}. Another special wide character value is the equivalent to @code{EOF}. -@comment wchar.h -@comment ISO @deftypevr Macro wint_t WEOF +@standards{ISO, wchar.h} The macro @code{WEOF} evaluates to a constant expression of type @code{wint_t} whose value is different from any member of the extended character set. @@ -402,18 +397,16 @@ conversion functions (as shown in the examples below). The @w{ISO C} standard defines two macros that provide this information. -@comment limits.h -@comment ISO @deftypevr Macro int MB_LEN_MAX +@standards{ISO, limits.h} @code{MB_LEN_MAX} specifies the maximum number of bytes in the multibyte sequence for a single character in any of the supported locales. It is a compile-time constant and is defined in @file{limits.h}. @pindex limits.h @end deftypevr -@comment stdlib.h -@comment ISO @deftypevr Macro int MB_CUR_MAX +@standards{ISO, stdlib.h} @code{MB_CUR_MAX} expands into a positive integer expression that is the maximum number of bytes in a multibyte character in the current locale. The value is never greater than @code{MB_LEN_MAX}. Unlike @@ -463,9 +456,8 @@ Since the conversion functions allow converting a text in more than one step we must have a way to pass this information from one call of the functions to another. -@comment wchar.h -@comment ISO @deftp {Data type} mbstate_t +@standards{ISO, wchar.h} @cindex shift state A variable of type @code{mbstate_t} can contain all the information about the @dfn{shift state} needed from one call to a conversion @@ -501,9 +493,8 @@ state. This is necessary, for example, to decide whether to emit escape sequences to set the state to the initial state at certain sequence points. Communication protocols often require this. -@comment wchar.h -@comment ISO @deftypefun int mbsinit (const mbstate_t *@var{ps}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c ps is dereferenced once, unguarded. This would call for @mtsrace:ps, @c but since a single word-sized field is (atomically) accessed, any @@ -564,9 +555,8 @@ of the multibyte character set. In such a scenario, each ASCII character stands for itself, and all other characters have at least a first byte that is beyond the range @math{0} to @math{127}. -@comment wchar.h -@comment ISO @deftypefun wint_t btowc (int @var{c}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c Calls btowc_fct or __fct; reads from locale, and from the @c get_gconv_fcts result multiple times. get_gconv_fcts calls @@ -628,9 +618,8 @@ this, using @code{btowc} is required. @noindent There is also a function for the conversion in the other direction. -@comment wchar.h -@comment ISO @deftypefun int wctob (wint_t @var{c}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{wctob} function (``wide character to byte'') takes as the parameter a valid wide character. If the multibyte representation for @@ -648,9 +637,8 @@ multibyte representation to wide characters and vice versa. These functions pose no limit on the length of the multibyte representation and they also do not require it to be in the initial state. -@comment wchar.h -@comment ISO @deftypefun size_t mbrtowc (wchar_t *restrict @var{pwc}, const char *restrict @var{s}, size_t @var{n}, mbstate_t *restrict @var{ps}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtunsafe{@mtasurace{:mbrtowc/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @cindex stateful The @code{mbrtowc} function (``multibyte restartable to wide @@ -743,9 +731,8 @@ away. Unfortunately there is no function to compute the length of the wide character string directly from the multibyte string. There is, however, a function that does part of the work. -@comment wchar.h -@comment ISO @deftypefun size_t mbrlen (const char *restrict @var{s}, size_t @var{n}, mbstate_t *@var{ps}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtunsafe{@mtasurace{:mbrlen/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{mbrlen} function (``multibyte restartable length'') computes the number of at most @var{n} bytes starting at @var{s}, which form the @@ -827,9 +814,8 @@ this conversion might be quite expensive. So it is necessary to think about the consequences of using the easier but imprecise method before doing the work twice. -@comment wchar.h -@comment ISO @deftypefun size_t wcrtomb (char *restrict @var{s}, wchar_t @var{wc}, mbstate_t *restrict @var{ps}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtunsafe{@mtasurace{:wcrtomb/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c wcrtomb uses a static, non-thread-local unguarded state variable when @c PS is NULL. When a state is passed in, and it's not used @@ -1015,9 +1001,8 @@ defines conversions on entire strings. However, the defined set of functions is quite limited; therefore, @theglibc{} contains a few extensions that can help in some important situations. -@comment wchar.h -@comment ISO @deftypefun size_t mbsrtowcs (wchar_t *restrict @var{dst}, const char **restrict @var{src}, size_t @var{len}, mbstate_t *restrict @var{ps}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtunsafe{@mtasurace{:mbsrtowcs/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{mbsrtowcs} function (``multibyte string restartable to wide character string'') converts the NUL-terminated multibyte character @@ -1100,9 +1085,8 @@ consumed from the input string. This way the problem of @code{mbsrtowcs}'s example above could be solved by determining the line length and passing this length to the function. -@comment wchar.h -@comment ISO @deftypefun size_t wcsrtombs (char *restrict @var{dst}, const wchar_t **restrict @var{src}, size_t @var{len}, mbstate_t *restrict @var{ps}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtunsafe{@mtasurace{:wcsrtombs/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{wcsrtombs} function (``wide character string restartable to multibyte string'') converts the NUL-terminated wide character string at @@ -1146,9 +1130,8 @@ input characters. One has to place the NUL wide character at the correct place or control the consumed input indirectly via the available output array size (the @var{len} parameter). -@comment wchar.h -@comment GNU @deftypefun size_t mbsnrtowcs (wchar_t *restrict @var{dst}, const char **restrict @var{src}, size_t @var{nmc}, size_t @var{len}, mbstate_t *restrict @var{ps}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtunsafe{@mtasurace{:mbsnrtowcs/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{mbsnrtowcs} function is very similar to the @code{mbsrtowcs} function. All the parameters are the same except for @var{nmc}, which is @@ -1199,9 +1182,8 @@ Since we don't insert characters in the strings that were not in there right from the beginning and we use @var{state} only for the conversion of the given buffer, there is no problem with altering the state. -@comment wchar.h -@comment GNU @deftypefun size_t wcsnrtombs (char *restrict @var{dst}, const wchar_t **restrict @var{src}, size_t @var{nwc}, size_t @var{len}, mbstate_t *restrict @var{ps}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtunsafe{@mtasurace{:wcsnrtombs/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{wcsnrtombs} function implements the conversion from wide character strings to multibyte character strings. It is similar to @@ -1344,9 +1326,8 @@ conversion functions.} @node Non-reentrant Character Conversion @subsection Non-reentrant Conversion of Single Characters -@comment stdlib.h -@comment ISO @deftypefun int mbtowc (wchar_t *restrict @var{result}, const char *restrict @var{string}, size_t @var{size}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{mbtowc} (``multibyte to wide character'') function when called with non-null @var{string} converts the first multibyte character @@ -1379,9 +1360,8 @@ returns nonzero if the multibyte character code in use actually has a shift state. @xref{Shift State}. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun int wctomb (char *@var{string}, wchar_t @var{wchar}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{wctomb} (``wide character to multibyte'') function converts the wide character code @var{wchar} to its corresponding multibyte @@ -1419,9 +1399,8 @@ Similar to @code{mbrlen} there is also a non-reentrant function that computes the length of a multibyte character. It can be defined in terms of @code{mbtowc}. -@comment stdlib.h -@comment ISO @deftypefun int mblen (const char *@var{string}, size_t @var{size}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{mblen} function with a non-null @var{string} argument returns the number of bytes that make up the multibyte character beginning at @@ -1458,9 +1437,8 @@ convert entire strings instead of single characters. These functions suffer from the same problems as their reentrant counterparts from @w{Amendment 1} to @w{ISO C90}; see @ref{Converting Strings}. -@comment stdlib.h -@comment ISO @deftypefun size_t mbstowcs (wchar_t *@var{wstring}, const char *@var{string}, size_t @var{size}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c Odd... Although this was supposed to be non-reentrant, the internal @c state is not a static buffer, but an automatic variable. @@ -1501,9 +1479,8 @@ mbstowcs_alloc (const char *string) @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun size_t wcstombs (char *@var{string}, const wchar_t *@var{wstring}, size_t @var{size}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} The @code{wcstombs} (``wide character string to multibyte string'') function converts the null-terminated wide character array @var{wstring} @@ -1674,9 +1651,8 @@ data type. Just like other open--use--close interfaces the functions introduced here work using handles and the @file{iconv.h} header defines a special type for the handles used. -@comment iconv.h -@comment XPG2 @deftp {Data Type} iconv_t +@standards{XPG2, iconv.h} This data type is an abstract type defined in @file{iconv.h}. The user must not assume anything about the definition of this type; it must be completely opaque. @@ -1689,9 +1665,8 @@ the conversions for which the handles stand for have to. @noindent The first step is the function to create a handle. -@comment iconv.h -@comment XPG2 @deftypefun iconv_t iconv_open (const char *@var{tocode}, const char *@var{fromcode}) +@standards{XPG2, iconv.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c Calls malloc if tocode and/or fromcode are too big for alloca. Calls @c strip and upstr on both, then gconv_open. strip and upstr call @@ -1763,9 +1738,8 @@ the handle returned by @code{iconv_open}. Therefore, it is crucial to free all the resources once all conversions are carried out and the conversion is not needed anymore. -@comment iconv.h -@comment XPG2 @deftypefun int iconv_close (iconv_t @var{cd}) +@standards{XPG2, iconv.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c Calls gconv_close to destruct and release each of the conversion @c steps, release the gconv_t object, then call gconv_close_transform. @@ -1795,9 +1769,8 @@ therefore, the most general interface: it allows conversion from one buffer to another. Conversion from a file to a buffer, vice versa, or even file to file can be implemented on top of it. -@comment iconv.h -@comment XPG2 @deftypefun size_t iconv (iconv_t @var{cd}, char **@var{inbuf}, size_t *@var{inbytesleft}, char **@var{outbuf}, size_t *@var{outbytesleft}) +@standards{XPG2, iconv.h} @safety{@prelim{}@mtsafe{@mtsrace{:cd}}@assafe{}@acunsafe{@acucorrupt{}}} @c Without guarding access to the iconv_t object pointed to by cd, call @c the conversion function to convert inbuf or flush the internal @@ -2356,9 +2329,8 @@ conversion and the second describes the state etc. There are really two type definitions like this in @file{gconv.h}. @pindex gconv.h -@comment gconv.h -@comment GNU @deftp {Data type} {struct __gconv_step} +@standards{GNU, gconv.h} This data structure describes one conversion a module can perform. For each function in a loaded module with conversion functions there is exactly one object of this type. This object is shared by all users of @@ -2424,9 +2396,8 @@ conversion function. @end table @end deftp -@comment gconv.h -@comment GNU @deftp {Data type} {struct __gconv_step_data} +@standards{GNU, gconv.h} This is the data structure that contains the information specific to each use of the conversion functions. @@ -2557,9 +2528,8 @@ this use of the conversion functions. There are three data types defined for the three module interface functions and these define the interface. -@comment gconv.h -@comment GNU @deftypevr {Data type} int {(*__gconv_init_fct)} (struct __gconv_step *) +@standards{GNU, gconv.h} This specifies the interface of the initialization function of the module. It is called exactly once for each conversion the module implements. @@ -2714,9 +2684,8 @@ The function called before the module is unloaded is significantly easier. It often has nothing at all to do; in which case it can be left out completely. -@comment gconv.h -@comment GNU @deftypevr {Data type} void {(*__gconv_end_fct)} (struct gconv_step *) +@standards{GNU, gconv.h} The task of this function is to free all resources allocated in the initialization function. Therefore only the @code{__data} element of the object pointed to by the argument is of interest. Continuing the @@ -2737,9 +2706,8 @@ get quite complicated for complex character sets. But since this is not of interest here, we will only describe a possible skeleton for the conversion function. -@comment gconv.h -@comment GNU @deftypevr {Data type} int {(*__gconv_fct)} (struct __gconv_step *, struct __gconv_step_data *, const char **, const char *, size_t *, int) +@standards{GNU, gconv.h} The conversion function can be called for two basic reasons: to convert text or to reset the state. From the description of the @code{iconv} function it can be seen why the flushing mode is necessary. What mode diff --git a/manual/conf.texi b/manual/conf.texi index 6700e86539..875862c847 100644 --- a/manual/conf.texi +++ b/manual/conf.texi @@ -56,17 +56,15 @@ with @samp{_POSIX}, which gives the lowest value that the limit is allowed to have on @emph{any} POSIX system. @xref{Minimums}. @cindex limits, program argument size -@comment limits.h -@comment POSIX.1 @deftypevr Macro int ARG_MAX +@standards{POSIX.1, limits.h} If defined, the unvarying maximum combined length of the @var{argv} and @var{environ} arguments that can be passed to the @code{exec} functions. @end deftypevr @cindex limits, number of processes -@comment limits.h -@comment POSIX.1 @deftypevr Macro int CHILD_MAX +@standards{POSIX.1, limits.h} If defined, the unvarying maximum number of processes that can exist with the same real user ID at any one time. In BSD and GNU, this is controlled by the @code{RLIMIT_NPROC} resource limit; @pxref{Limits on @@ -74,25 +72,22 @@ Resources}. @end deftypevr @cindex limits, number of open files -@comment limits.h -@comment POSIX.1 @deftypevr Macro int OPEN_MAX +@standards{POSIX.1, limits.h} If defined, the unvarying maximum number of files that a single process can have open simultaneously. In BSD and GNU, this is controlled by the @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}. @end deftypevr -@comment limits.h -@comment POSIX.1 @deftypevr Macro int STREAM_MAX +@standards{POSIX.1, limits.h} If defined, the unvarying maximum number of streams that a single process can have open simultaneously. @xref{Opening Streams}. @end deftypevr @cindex limits, time zone name length -@comment limits.h -@comment POSIX.1 @deftypevr Macro int TZNAME_MAX +@standards{POSIX.1, limits.h} If defined, the unvarying maximum length of a time zone name. @xref{Time Zone Functions}. @end deftypevr @@ -100,9 +95,8 @@ If defined, the unvarying maximum length of a time zone name. These limit macros are always defined in @file{limits.h}. @cindex limits, number of supplementary group IDs -@comment limits.h -@comment POSIX.1 @deftypevr Macro int NGROUPS_MAX +@standards{POSIX.1, limits.h} The maximum number of supplementary group IDs that one process can have. The value of this macro is actually a lower bound for the maximum. That @@ -112,9 +106,8 @@ IDs, but a particular machine might let you have even more. You can use more (@pxref{Sysconf}). @end deftypevr -@comment limits.h -@comment POSIX.1 @deftypevr Macro ssize_t SSIZE_MAX +@standards{POSIX.1, limits.h} The largest value that can fit in an object of type @code{ssize_t}. Effectively, this is the limit on the number of bytes that can be read or written in a single operation. @@ -123,9 +116,8 @@ This macro is defined in all POSIX systems because this limit is never configurable. @end deftypevr -@comment limits.h -@comment POSIX.2 @deftypevr Macro int RE_DUP_MAX +@standards{POSIX.2, limits.h} The largest number of repetitions you are guaranteed is allowed in the construct @samp{\@{@var{min},@var{max}\@}} in a regular expression. @@ -159,17 +151,15 @@ For the following macros, if the macro is defined in @file{unistd.h}, then the option is supported. Otherwise, the option may or may not be supported; use @code{sysconf} to find out. @xref{Sysconf}. -@comment unistd.h -@comment POSIX.1 @deftypevr Macro int _POSIX_JOB_CONTROL +@standards{POSIX.1, unistd.h} If this symbol is defined, it indicates that the system supports job control. Otherwise, the implementation behaves as if all processes within a session belong to a single process group. @xref{Job Control}. @end deftypevr -@comment unistd.h -@comment POSIX.1 @deftypevr Macro int _POSIX_SAVED_IDS +@standards{POSIX.1, unistd.h} If this symbol is defined, it indicates that the system remembers the effective user and group IDs of a process before it executes an executable file with the set-user-ID or set-group-ID bits set, and that @@ -186,42 +176,37 @@ then its value indicates whether the option is supported. A value of defined, then the option may or may not be supported; use @code{sysconf} to find out. @xref{Sysconf}. -@comment unistd.h -@comment POSIX.2 @deftypevr Macro int _POSIX2_C_DEV +@standards{POSIX.2, unistd.h} If this symbol is defined, it indicates that the system has the POSIX.2 C compiler command, @code{c89}. @Theglibc{} always defines this as @code{1}, on the assumption that you would not have installed it if you didn't have a C compiler. @end deftypevr -@comment unistd.h -@comment POSIX.2 @deftypevr Macro int _POSIX2_FORT_DEV +@standards{POSIX.2, unistd.h} If this symbol is defined, it indicates that the system has the POSIX.2 Fortran compiler command, @code{fort77}. @Theglibc{} never defines this, because we don't know what the system has. @end deftypevr -@comment unistd.h -@comment POSIX.2 @deftypevr Macro int _POSIX2_FORT_RUN +@standards{POSIX.2, unistd.h} If this symbol is defined, it indicates that the system has the POSIX.2 @code{asa} command to interpret Fortran carriage control. @Theglibc{} never defines this, because we don't know what the system has. @end deftypevr -@comment unistd.h -@comment POSIX.2 @deftypevr Macro int _POSIX2_LOCALEDEF +@standards{POSIX.2, unistd.h} If this symbol is defined, it indicates that the system has the POSIX.2 @code{localedef} command. @Theglibc{} never defines this, because we don't know what the system has. @end deftypevr -@comment unistd.h -@comment POSIX.2 @deftypevr Macro int _POSIX2_SW_DEV +@standards{POSIX.2, unistd.h} If this symbol is defined, it indicates that the system has the POSIX.2 commands @code{ar}, @code{make}, and @code{strip}. @Theglibc{} always defines this as @code{1}, on the assumption that you had to have @@ -232,9 +217,8 @@ always defines this as @code{1}, on the assumption that you had to have @node Version Supported @section Which Version of POSIX is Supported -@comment unistd.h -@comment POSIX.1 @deftypevr Macro {long int} _POSIX_VERSION +@standards{POSIX.1, unistd.h} This constant represents the version of the POSIX.1 standard to which the implementation conforms. For an implementation conforming to the 1995 POSIX.1 standard, the value is the integer @code{199506L}. @@ -250,9 +234,8 @@ probably fail because there is no @file{unistd.h}. We do not know of target system supports POSIX or whether @file{unistd.h} exists. @end deftypevr -@comment unistd.h -@comment POSIX.2 @deftypevr Macro {long int} _POSIX2_C_VERSION +@standards{POSIX.2, unistd.h} This constant represents the version of the POSIX.2 standard which the library and system kernel support. We don't know what value this will be for the first version of the POSIX.2 standard, because the value is @@ -285,9 +268,8 @@ constants are declared in the header file @file{unistd.h}. @node Sysconf Definition @subsection Definition of @code{sysconf} -@comment unistd.h -@comment POSIX.1 @deftypefun {long int} sysconf (int @var{parameter}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c Some parts of the implementation open /proc and /sys files and dirs @c to collect system details, using fd and stream I/O depending on the @@ -319,662 +301,540 @@ to @code{sysconf}. The values are all integer constants (more specifically, enumeration type values). @vtable @code -@comment unistd.h -@comment POSIX.1 @item _SC_ARG_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{ARG_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_CHILD_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{CHILD_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_OPEN_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{OPEN_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_STREAM_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{STREAM_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_TZNAME_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{TZNAME_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_NGROUPS_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{NGROUPS_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_JOB_CONTROL +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_JOB_CONTROL}. -@comment unistd.h -@comment POSIX.1 @item _SC_SAVED_IDS +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_SAVED_IDS}. -@comment unistd.h -@comment POSIX.1 @item _SC_VERSION +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_VERSION}. -@comment unistd.h -@comment POSIX.1 @item _SC_CLK_TCK +@standards{POSIX.1, unistd.h} Inquire about the number of clock ticks per second; @pxref{CPU Time}. The corresponding parameter @code{CLK_TCK} is obsolete. -@comment unistd.h -@comment GNU @item _SC_CHARCLASS_NAME_MAX +@standards{GNU, unistd.h} Inquire about the parameter corresponding to maximal length allowed for a character class name in an extended locale specification. These extensions are not yet standardized and so this option is not standardized as well. -@comment unistdh.h -@comment POSIX.1 @item _SC_REALTIME_SIGNALS +@standards{POSIX.1, unistdh.h} Inquire about the parameter corresponding to @code{_POSIX_REALTIME_SIGNALS}. -@comment unistd.h -@comment POSIX.1 @item _SC_PRIORITY_SCHEDULING +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PRIORITY_SCHEDULING}. -@comment unistd.h -@comment POSIX.1 @item _SC_TIMERS +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_TIMERS}. -@comment unistd.h -@comment POSIX.1 @item _SC_ASYNCHRONOUS_IO +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_ASYNCHRONOUS_IO}. -@comment unistd.h -@comment POSIX.1 @item _SC_PRIORITIZED_IO +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PRIORITIZED_IO}. -@comment unistd.h -@comment POSIX.1 @item _SC_SYNCHRONIZED_IO +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_SYNCHRONIZED_IO}. -@comment unistd.h -@comment POSIX.1 @item _SC_FSYNC +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_FSYNC}. -@comment unistd.h -@comment POSIX.1 @item _SC_MAPPED_FILES +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_MAPPED_FILES}. -@comment unistd.h -@comment POSIX.1 @item _SC_MEMLOCK +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_MEMLOCK}. -@comment unistd.h -@comment POSIX.1 @item _SC_MEMLOCK_RANGE +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_MEMLOCK_RANGE}. -@comment unistd.h -@comment POSIX.1 @item _SC_MEMORY_PROTECTION +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_MEMORY_PROTECTION}. -@comment unistd.h -@comment POSIX.1 @item _SC_MESSAGE_PASSING +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_MESSAGE_PASSING}. -@comment unistd.h -@comment POSIX.1 @item _SC_SEMAPHORES +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_SEMAPHORES}. -@comment unistd.h -@comment POSIX.1 @item _SC_SHARED_MEMORY_OBJECTS +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to@* @code{_POSIX_SHARED_MEMORY_OBJECTS}. -@comment unistd.h -@comment POSIX.1 @item _SC_AIO_LISTIO_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_AIO_LISTIO_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_AIO_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_AIO_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_AIO_PRIO_DELTA_MAX +@standards{POSIX.1, unistd.h} Inquire about the value by which a process can decrease its asynchronous I/O priority level from its own scheduling priority. This corresponds to the run-time invariant value @code{AIO_PRIO_DELTA_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_DELAYTIMER_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_DELAYTIMER_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_MQ_OPEN_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_MQ_OPEN_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_MQ_PRIO_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_MQ_PRIO_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_RTSIG_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_RTSIG_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_SEM_NSEMS_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_SEM_NSEMS_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_SEM_VALUE_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_SEM_VALUE_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_SIGQUEUE_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_SIGQUEUE_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_TIMER_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_TIMER_MAX}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII_XTI +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII_XTI}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII_SOCKET +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII_SOCKET}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII_INTERNET +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII_OSI +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII_OSI}. -@comment unistd.h -@comment POSIX.1g @item _SC_SELECT +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_SELECT}. -@comment unistd.h -@comment POSIX.1g @item _SC_UIO_MAXIOV +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_UIO_MAXIOV}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII_INTERNET_STREAM +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET_STREAM}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII_INTERNET_DGRAM +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET_DGRAM}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII_OSI_COTS +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_COTS}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII_OSI_CLTS +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_CLTS}. -@comment unistd.h -@comment POSIX.1g @item _SC_PII_OSI_M +@standards{POSIX.1g, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_M}. -@comment unistd.h -@comment POSIX.1g @item _SC_T_IOV_MAX +@standards{POSIX.1g, unistd.h} Inquire about the value associated with the @code{T_IOV_MAX} variable. -@comment unistd.h -@comment POSIX.1 @item _SC_THREADS +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_THREADS}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_SAFE_FUNCTIONS +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to@* @code{_POSIX_THREAD_SAFE_FUNCTIONS}. -@comment unistd.h -@comment POSIX.1 @item _SC_GETGR_R_SIZE_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_GETGR_R_SIZE_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_GETPW_R_SIZE_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_GETPW_R_SIZE_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_LOGIN_NAME_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_LOGIN_NAME_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_TTY_NAME_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_TTY_NAME_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_DESTRUCTOR_ITERATIONS +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_THREAD_DESTRUCTOR_ITERATIONS}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_KEYS_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_THREAD_KEYS_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_STACK_MIN +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_THREAD_STACK_MIN}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_THREADS_MAX +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_THREAD_THREADS_MAX}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_ATTR_STACKADDR +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to@*a @code{_POSIX_THREAD_ATTR_STACKADDR}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_ATTR_STACKSIZE +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to@* @code{_POSIX_THREAD_ATTR_STACKSIZE}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_PRIORITY_SCHEDULING +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_THREAD_PRIORITY_SCHEDULING}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_PRIO_INHERIT +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_THREAD_PRIO_INHERIT}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_PRIO_PROTECT +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_THREAD_PRIO_PROTECT}. -@comment unistd.h -@comment POSIX.1 @item _SC_THREAD_PROCESS_SHARED +@standards{POSIX.1, unistd.h} Inquire about the parameter corresponding to @code{_POSIX_THREAD_PROCESS_SHARED}. -@comment unistd.h -@comment POSIX.2 @item _SC_2_C_DEV +@standards{POSIX.2, unistd.h} Inquire about whether the system has the POSIX.2 C compiler command, @code{c89}. -@comment unistd.h -@comment POSIX.2 @item _SC_2_FORT_DEV +@standards{POSIX.2, unistd.h} Inquire about whether the system has the POSIX.2 Fortran compiler command, @code{fort77}. -@comment unistd.h -@comment POSIX.2 @item _SC_2_FORT_RUN +@standards{POSIX.2, unistd.h} Inquire about whether the system has the POSIX.2 @code{asa} command to interpret Fortran carriage control. -@comment unistd.h -@comment POSIX.2 @item _SC_2_LOCALEDEF +@standards{POSIX.2, unistd.h} Inquire about whether the system has the POSIX.2 @code{localedef} command. -@comment unistd.h -@comment POSIX.2 @item _SC_2_SW_DEV +@standards{POSIX.2, unistd.h} Inquire about whether the system has the POSIX.2 commands @code{ar}, @code{make}, and @code{strip}. -@comment unistd.h -@comment POSIX.2 @item _SC_BC_BASE_MAX +@standards{POSIX.2, unistd.h} Inquire about the maximum value of @code{obase} in the @code{bc} utility. -@comment unistd.h -@comment POSIX.2 @item _SC_BC_DIM_MAX +@standards{POSIX.2, unistd.h} Inquire about the maximum size of an array in the @code{bc} utility. -@comment unistd.h -@comment POSIX.2 @item _SC_BC_SCALE_MAX +@standards{POSIX.2, unistd.h} Inquire about the maximum value of @code{scale} in the @code{bc} utility. -@comment unistd.h -@comment POSIX.2 @item _SC_BC_STRING_MAX +@standards{POSIX.2, unistd.h} Inquire about the maximum size of a string constant in the @code{bc} utility. -@comment unistd.h -@comment POSIX.2 @item _SC_COLL_WEIGHTS_MAX +@standards{POSIX.2, unistd.h} Inquire about the maximum number of weights that can necessarily be used in defining the collating sequence for a locale. -@comment unistd.h -@comment POSIX.2 @item _SC_EXPR_NEST_MAX +@standards{POSIX.2, unistd.h} Inquire about the maximum number of expressions nested within parentheses when using the @code{expr} utility. -@comment unistd.h -@comment POSIX.2 @item _SC_LINE_MAX +@standards{POSIX.2, unistd.h} Inquire about the maximum size of a text line that the POSIX.2 text utilities can handle. -@comment unistd.h -@comment POSIX.2 @item _SC_EQUIV_CLASS_MAX +@standards{POSIX.2, unistd.h} Inquire about the maximum number of weights that can be assigned to an entry of the @code{LC_COLLATE} category @samp{order} keyword in a locale definition. @Theglibc{} does not presently support locale definitions. -@comment unistd.h -@comment POSIX.2 @item _SC_VERSION +@standards{POSIX.2, unistd.h} Inquire about the version number of POSIX.1 that the library and kernel support. -@comment unistd.h -@comment POSIX.2 @item _SC_2_VERSION +@standards{POSIX.2, unistd.h} Inquire about the version number of POSIX.2 that the system utilities support. -@comment unistd.h -@comment GNU @item _SC_PAGESIZE +@standards{GNU, unistd.h} Inquire about the virtual memory page size of the machine. @code{getpagesize} returns the same value (@pxref{Query Memory Parameters}). -@comment unistd.h -@comment GNU @item _SC_NPROCESSORS_CONF +@standards{GNU, unistd.h} Inquire about the number of configured processors. -@comment unistd.h -@comment GNU @item _SC_NPROCESSORS_ONLN +@standards{GNU, unistd.h} Inquire about the number of processors online. -@comment unistd.h -@comment GNU @item _SC_PHYS_PAGES +@standards{GNU, unistd.h} Inquire about the number of physical pages in the system. -@comment unistd.h -@comment GNU @item _SC_AVPHYS_PAGES +@standards{GNU, unistd.h} Inquire about the number of available physical pages in the system. -@comment unistd.h -@comment GNU @item _SC_ATEXIT_MAX +@standards{GNU, unistd.h} Inquire about the number of functions which can be registered as termination functions for @code{atexit}; @pxref{Cleanups on Exit}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_VERSION +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_VERSION}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_XCU_VERSION +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_XCU_VERSION}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_UNIX +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_UNIX}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_REALTIME +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_REALTIME}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_REALTIME_THREADS +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_REALTIME_THREADS}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_LEGACY +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_LEGACY}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_CRYPT +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_CRYPT}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_ENH_I18N +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_ENH_I18N}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_SHM +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_SHM}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_XPG2 +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_XPG2}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_XPG3 +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_XPG3}. -@comment unistd.h -@comment X/Open @item _SC_XOPEN_XPG4 +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{_XOPEN_XPG4}. -@comment unistd.h -@comment X/Open @item _SC_CHAR_BIT +@standards{X/Open, unistd.h} Inquire about the number of bits in a variable of type @code{char}. -@comment unistd.h -@comment X/Open @item _SC_CHAR_MAX +@standards{X/Open, unistd.h} Inquire about the maximum value which can be stored in a variable of type @code{char}. -@comment unistd.h -@comment X/Open @item _SC_CHAR_MIN +@standards{X/Open, unistd.h} Inquire about the minimum value which can be stored in a variable of type @code{char}. -@comment unistd.h -@comment X/Open @item _SC_INT_MAX +@standards{X/Open, unistd.h} Inquire about the maximum value which can be stored in a variable of type @code{int}. -@comment unistd.h -@comment X/Open @item _SC_INT_MIN +@standards{X/Open, unistd.h} Inquire about the minimum value which can be stored in a variable of type @code{int}. -@comment unistd.h -@comment X/Open @item _SC_LONG_BIT +@standards{X/Open, unistd.h} Inquire about the number of bits in a variable of type @code{long int}. -@comment unistd.h -@comment X/Open @item _SC_WORD_BIT +@standards{X/Open, unistd.h} Inquire about the number of bits in a variable of a register word. -@comment unistd.h -@comment X/Open @item _SC_MB_LEN_MAX +@standards{X/Open, unistd.h} Inquire about the maximum length of a multi-byte representation of a wide character value. -@comment unistd.h -@comment X/Open @item _SC_NZERO +@standards{X/Open, unistd.h} Inquire about the value used to internally represent the zero priority level for the process execution. -@comment unistd.h -@comment X/Open @item SC_SSIZE_MAX +@standards{X/Open, unistd.h} Inquire about the maximum value which can be stored in a variable of type @code{ssize_t}. -@comment unistd.h -@comment X/Open @item _SC_SCHAR_MAX +@standards{X/Open, unistd.h} Inquire about the maximum value which can be stored in a variable of type @code{signed char}. -@comment unistd.h -@comment X/Open @item _SC_SCHAR_MIN +@standards{X/Open, unistd.h} Inquire about the minimum value which can be stored in a variable of type @code{signed char}. -@comment unistd.h -@comment X/Open @item _SC_SHRT_MAX +@standards{X/Open, unistd.h} Inquire about the maximum value which can be stored in a variable of type @code{short int}. -@comment unistd.h -@comment X/Open @item _SC_SHRT_MIN +@standards{X/Open, unistd.h} Inquire about the minimum value which can be stored in a variable of type @code{short int}. -@comment unistd.h -@comment X/Open @item _SC_UCHAR_MAX +@standards{X/Open, unistd.h} Inquire about the maximum value which can be stored in a variable of type @code{unsigned char}. -@comment unistd.h -@comment X/Open @item _SC_UINT_MAX +@standards{X/Open, unistd.h} Inquire about the maximum value which can be stored in a variable of type @code{unsigned int}. -@comment unistd.h -@comment X/Open @item _SC_ULONG_MAX +@standards{X/Open, unistd.h} Inquire about the maximum value which can be stored in a variable of type @code{unsigned long int}. -@comment unistd.h -@comment X/Open @item _SC_USHRT_MAX +@standards{X/Open, unistd.h} Inquire about the maximum value which can be stored in a variable of type @code{unsigned short int}. -@comment unistd.h -@comment X/Open @item _SC_NL_ARGMAX +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{NL_ARGMAX}. -@comment unistd.h -@comment X/Open @item _SC_NL_LANGMAX +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{NL_LANGMAX}. -@comment unistd.h -@comment X/Open @item _SC_NL_MSGMAX +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{NL_MSGMAX}. -@comment unistd.h -@comment X/Open @item _SC_NL_NMAX +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{NL_NMAX}. -@comment unistd.h -@comment X/Open @item _SC_NL_SETMAX +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{NL_SETMAX}. -@comment unistd.h -@comment X/Open @item _SC_NL_TEXTMAX +@standards{X/Open, unistd.h} Inquire about the parameter corresponding to @code{NL_TEXTMAX}. @end vtable @@ -1031,75 +891,65 @@ safely push to these limits without checking whether the particular system you are using can go that far. @vtable @code -@comment limits.h -@comment POSIX.1 @item _POSIX_AIO_LISTIO_MAX +@standards{POSIX.1, limits.h} The most restrictive limit permitted by POSIX for the maximum number of I/O operations that can be specified in a list I/O call. The value of this constant is @code{2}; thus you can add up to two new entries of the list of outstanding operations. -@comment limits.h -@comment POSIX.1 @item _POSIX_AIO_MAX +@standards{POSIX.1, limits.h} The most restrictive limit permitted by POSIX for the maximum number of outstanding asynchronous I/O operations. The value of this constant is @code{1}. So you cannot expect that you can issue more than one operation and immediately continue with the normal work, receiving the notifications asynchronously. -@comment limits.h -@comment POSIX.1 @item _POSIX_ARG_MAX +@standards{POSIX.1, limits.h} The value of this macro is the most restrictive limit permitted by POSIX for the maximum combined length of the @var{argv} and @var{environ} arguments that can be passed to the @code{exec} functions. Its value is @code{4096}. -@comment limits.h -@comment POSIX.1 @item _POSIX_CHILD_MAX +@standards{POSIX.1, limits.h} The value of this macro is the most restrictive limit permitted by POSIX for the maximum number of simultaneous processes per real user ID. Its value is @code{6}. -@comment limits.h -@comment POSIX.1 @item _POSIX_NGROUPS_MAX +@standards{POSIX.1, limits.h} The value of this macro is the most restrictive limit permitted by POSIX for the maximum number of supplementary group IDs per process. Its value is @code{0}. -@comment limits.h -@comment POSIX.1 @item _POSIX_OPEN_MAX +@standards{POSIX.1, limits.h} The value of this macro is the most restrictive limit permitted by POSIX for the maximum number of files that a single process can have open simultaneously. Its value is @code{16}. -@comment limits.h -@comment POSIX.1 @item _POSIX_SSIZE_MAX +@standards{POSIX.1, limits.h} The value of this macro is the most restrictive limit permitted by POSIX for the maximum value that can be stored in an object of type @code{ssize_t}. Its value is @code{32767}. -@comment limits.h -@comment POSIX.1 @item _POSIX_STREAM_MAX +@standards{POSIX.1, limits.h} The value of this macro is the most restrictive limit permitted by POSIX for the maximum number of streams that a single process can have open simultaneously. Its value is @code{8}. -@comment limits.h -@comment POSIX.1 @item _POSIX_TZNAME_MAX +@standards{POSIX.1, limits.h} The value of this macro is the most restrictive limit permitted by POSIX for the maximum length of a time zone name. Its value is @code{3}. -@comment limits.h -@comment POSIX.2 @item _POSIX2_RE_DUP_MAX +@standards{POSIX.2, limits.h} The value of this macro is the most restrictive limit permitted by POSIX for the numbers used in the @samp{\@{@var{min},@var{max}\@}} construct in a regular expression. Its value is @code{255}. @@ -1128,32 +978,28 @@ Each parameter also has another macro, with a name starting with have on @emph{any} POSIX system. @xref{File Minimums}. @cindex limits, link count of files -@comment limits.h (optional) -@comment POSIX.1 @deftypevr Macro int LINK_MAX +@standards{POSIX.1, limits.h (optional)} The uniform system limit (if any) for the number of names for a given file. @xref{Hard Links}. @end deftypevr @cindex limits, terminal input queue -@comment limits.h -@comment POSIX.1 @deftypevr Macro int MAX_CANON +@standards{POSIX.1, limits.h} The uniform system limit (if any) for the amount of text in a line of input when input editing is enabled. @xref{Canonical or Not}. @end deftypevr -@comment limits.h -@comment POSIX.1 @deftypevr Macro int MAX_INPUT +@standards{POSIX.1, limits.h} The uniform system limit (if any) for the total number of characters typed ahead as input. @xref{I/O Queues}. @end deftypevr @cindex limits, file name length -@comment limits.h -@comment POSIX.1 @deftypevr Macro int NAME_MAX +@standards{POSIX.1, limits.h} The uniform system limit (if any) for the length of a file name component, not including the terminating null character. @@ -1161,9 +1007,8 @@ including the terminating null character. @code{NAME_MAX}, but does not actually enforce this limit. @end deftypevr -@comment limits.h -@comment POSIX.1 @deftypevr Macro int PATH_MAX +@standards{POSIX.1, limits.h} The uniform system limit (if any) for the length of an entire file name (that is, the argument given to system calls such as @code{open}), including the terminating null character. @@ -1173,9 +1018,8 @@ even if @code{PATH_MAX} is defined. @end deftypevr @cindex limits, pipe buffer size -@comment limits.h -@comment POSIX.1 @deftypevr Macro int PIPE_BUF +@standards{POSIX.1, limits.h} The uniform system limit (if any) for the number of bytes that can be written atomically to a pipe. If multiple processes are writing to the same pipe simultaneously, output from different processes might be @@ -1184,16 +1028,14 @@ interleaved in chunks of this size. @xref{Pipes and FIFOs}. These are alternative macro names for some of the same information. -@comment dirent.h -@comment BSD @deftypevr Macro int MAXNAMLEN +@standards{BSD, dirent.h} This is the BSD name for @code{NAME_MAX}. It is defined in @file{dirent.h}. @end deftypevr -@comment stdio.h -@comment ISO @deftypevr Macro int FILENAME_MAX +@standards{ISO, stdio.h} The value of this macro is an integer constant expression that represents the maximum length of a file name string. It is defined in @file{stdio.h}. @@ -1230,26 +1072,23 @@ one can never make a general statement about whether all file systems support the @code{_POSIX_CHOWN_RESTRICTED} and @code{_POSIX_NO_TRUNC} features. So these names are never defined as macros in @theglibc{}. -@comment unistd.h -@comment POSIX.1 @deftypevr Macro int _POSIX_CHOWN_RESTRICTED +@standards{POSIX.1, unistd.h} If this option is in effect, the @code{chown} function is restricted so that the only changes permitted to nonprivileged processes is to change the group owner of a file to either be the effective group ID of the process, or one of its supplementary group IDs. @xref{File Owner}. @end deftypevr -@comment unistd.h -@comment POSIX.1 @deftypevr Macro int _POSIX_NO_TRUNC +@standards{POSIX.1, unistd.h} If this option is in effect, file name components longer than @code{NAME_MAX} generate an @code{ENAMETOOLONG} error. Otherwise, file name components that are too long are silently truncated. @end deftypevr -@comment unistd.h -@comment POSIX.1 @deftypevr Macro {unsigned char} _POSIX_VDISABLE +@standards{POSIX.1, unistd.h} This option is only meaningful for files that are terminal devices. If it is enabled, then handling for special control characters can be disabled individually. @xref{Special Characters}. @@ -1272,73 +1111,62 @@ have these strict limitations. The actual limit should be requested if necessary. @vtable @code -@comment limits.h -@comment POSIX.1 @item _POSIX_LINK_MAX +@standards{POSIX.1, limits.h} The most restrictive limit permitted by POSIX for the maximum value of a file's link count. The value of this constant is @code{8}; thus, you can always make up to eight names for a file without running into a system limit. -@comment limits.h -@comment POSIX.1 @item _POSIX_MAX_CANON +@standards{POSIX.1, limits.h} The most restrictive limit permitted by POSIX for the maximum number of bytes in a canonical input line from a terminal device. The value of this constant is @code{255}. -@comment limits.h -@comment POSIX.1 @item _POSIX_MAX_INPUT +@standards{POSIX.1, limits.h} The most restrictive limit permitted by POSIX for the maximum number of bytes in a terminal device input queue (or typeahead buffer). @xref{Input Modes}. The value of this constant is @code{255}. -@comment limits.h -@comment POSIX.1 @item _POSIX_NAME_MAX +@standards{POSIX.1, limits.h} The most restrictive limit permitted by POSIX for the maximum number of bytes in a file name component. The value of this constant is @code{14}. -@comment limits.h -@comment POSIX.1 @item _POSIX_PATH_MAX +@standards{POSIX.1, limits.h} The most restrictive limit permitted by POSIX for the maximum number of bytes in a file name. The value of this constant is @code{256}. -@comment limits.h -@comment POSIX.1 @item _POSIX_PIPE_BUF +@standards{POSIX.1, limits.h} The most restrictive limit permitted by POSIX for the maximum number of bytes that can be written atomically to a pipe. The value of this constant is @code{512}. -@comment limits.h -@comment POSIX.1 @item SYMLINK_MAX +@standards{POSIX.1, limits.h} Maximum number of bytes in a symbolic link. -@comment limits.h -@comment POSIX.1 @item POSIX_REC_INCR_XFER_SIZE +@standards{POSIX.1, limits.h} Recommended increment for file transfer sizes between the @code{POSIX_REC_MIN_XFER_SIZE} and @code{POSIX_REC_MAX_XFER_SIZE} values. -@comment limits.h -@comment POSIX.1 @item POSIX_REC_MAX_XFER_SIZE +@standards{POSIX.1, limits.h} Maximum recommended file transfer size. -@comment limits.h -@comment POSIX.1 @item POSIX_REC_MIN_XFER_SIZE +@standards{POSIX.1, limits.h} Minimum recommended file transfer size. -@comment limits.h -@comment POSIX.1 @item POSIX_REC_XFER_ALIGN +@standards{POSIX.1, limits.h} Recommended file transfer buffer alignment. @end vtable @@ -1352,9 +1180,8 @@ out the value that applies to any particular file. These functions and the associated constants for the @var{parameter} argument are declared in the header file @file{unistd.h}. -@comment unistd.h -@comment POSIX.1 @deftypefun {long int} pathconf (const char *@var{filename}, int @var{parameter}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c When __statfs_link_max finds an ext* filesystem, it may read @c /proc/mounts or similar as a mntent stream. @@ -1384,9 +1211,8 @@ support the @var{parameter} for the specific file. @end table @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun {long int} fpathconf (int @var{filedes}, int @var{parameter}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c Same caveats as pathconf. This is just like @code{pathconf} except that an open file descriptor @@ -1410,89 +1236,72 @@ argument to @code{pathconf} and @code{fpathconf}. The values are all integer constants. @vtable @code -@comment unistd.h -@comment POSIX.1 @item _PC_LINK_MAX +@standards{POSIX.1, unistd.h} Inquire about the value of @code{LINK_MAX}. -@comment unistd.h -@comment POSIX.1 @item _PC_MAX_CANON +@standards{POSIX.1, unistd.h} Inquire about the value of @code{MAX_CANON}. -@comment unistd.h -@comment POSIX.1 @item _PC_MAX_INPUT +@standards{POSIX.1, unistd.h} Inquire about the value of @code{MAX_INPUT}. -@comment unistd.h -@comment POSIX.1 @item _PC_NAME_MAX +@standards{POSIX.1, unistd.h} Inquire about the value of @code{NAME_MAX}. -@comment unistd.h -@comment POSIX.1 @item _PC_PATH_MAX +@standards{POSIX.1, unistd.h} Inquire about the value of @code{PATH_MAX}. -@comment unistd.h -@comment POSIX.1 @item _PC_PIPE_BUF +@standards{POSIX.1, unistd.h} Inquire about the value of @code{PIPE_BUF}. -@comment unistd.h -@comment POSIX.1 @item _PC_CHOWN_RESTRICTED +@standards{POSIX.1, unistd.h} Inquire about the value of @code{_POSIX_CHOWN_RESTRICTED}. -@comment unistd.h -@comment POSIX.1 @item _PC_NO_TRUNC +@standards{POSIX.1, unistd.h} Inquire about the value of @code{_POSIX_NO_TRUNC}. -@comment unistd.h -@comment POSIX.1 @item _PC_VDISABLE +@standards{POSIX.1, unistd.h} Inquire about the value of @code{_POSIX_VDISABLE}. -@comment unistd.h -@comment POSIX.1 @item _PC_SYNC_IO +@standards{POSIX.1, unistd.h} Inquire about the value of @code{_POSIX_SYNC_IO}. -@comment unistd.h -@comment POSIX.1 @item _PC_ASYNC_IO +@standards{POSIX.1, unistd.h} Inquire about the value of @code{_POSIX_ASYNC_IO}. -@comment unistd.h -@comment POSIX.1 @item _PC_PRIO_IO +@standards{POSIX.1, unistd.h} Inquire about the value of @code{_POSIX_PRIO_IO}. -@comment unistd.h -@comment LFS @item _PC_FILESIZEBITS +@standards{LFS, unistd.h} Inquire about the availability of large files on the filesystem. -@comment unistd.h -@comment POSIX.1 @item _PC_REC_INCR_XFER_SIZE +@standards{POSIX.1, unistd.h} Inquire about the value of @code{POSIX_REC_INCR_XFER_SIZE}. -@comment unistd.h -@comment POSIX.1 @item _PC_REC_MAX_XFER_SIZE +@standards{POSIX.1, unistd.h} Inquire about the value of @code{POSIX_REC_MAX_XFER_SIZE}. -@comment unistd.h -@comment POSIX.1 @item _PC_REC_MIN_XFER_SIZE +@standards{POSIX.1, unistd.h} Inquire about the value of @code{POSIX_REC_MIN_XFER_SIZE}. -@comment unistd.h -@comment POSIX.1 @item _PC_REC_XFER_ALIGN +@standards{POSIX.1, unistd.h} Inquire about the value of @code{POSIX_REC_XFER_ALIGN}. @end vtable @@ -1511,60 +1320,52 @@ returns values for them if you ask; but these values convey no meaningful information. They are simply the smallest values that POSIX.2 permits. -@comment limits.h -@comment POSIX.2 @deftypevr Macro int BC_BASE_MAX +@standards{POSIX.2, limits.h} The largest value of @code{obase} that the @code{bc} utility is guaranteed to support. @end deftypevr -@comment limits.h -@comment POSIX.2 @deftypevr Macro int BC_DIM_MAX +@standards{POSIX.2, limits.h} The largest number of elements in one array that the @code{bc} utility is guaranteed to support. @end deftypevr -@comment limits.h -@comment POSIX.2 @deftypevr Macro int BC_SCALE_MAX +@standards{POSIX.2, limits.h} The largest value of @code{scale} that the @code{bc} utility is guaranteed to support. @end deftypevr -@comment limits.h -@comment POSIX.2 @deftypevr Macro int BC_STRING_MAX +@standards{POSIX.2, limits.h} The largest number of characters in one string constant that the @code{bc} utility is guaranteed to support. @end deftypevr -@comment limits.h -@comment POSIX.2 @deftypevr Macro int COLL_WEIGHTS_MAX +@standards{POSIX.2, limits.h} The largest number of weights that can necessarily be used in defining the collating sequence for a locale. @end deftypevr -@comment limits.h -@comment POSIX.2 @deftypevr Macro int EXPR_NEST_MAX +@standards{POSIX.2, limits.h} The maximum number of expressions that can be nested within parentheses by the @code{expr} utility. @end deftypevr -@comment limits.h -@comment POSIX.2 @deftypevr Macro int LINE_MAX +@standards{POSIX.2, limits.h} The largest text line that the text-oriented POSIX.2 utilities can support. (If you are using the GNU versions of these utilities, then there is no actual limit except that imposed by the available virtual memory, but there is no way that the library can tell you this.) @end deftypevr -@comment limits.h -@comment POSIX.2 @deftypevr Macro int EQUIV_CLASS_MAX +@standards{POSIX.2, limits.h} The maximum number of weights that can be assigned to an entry of the @code{LC_COLLATE} category @samp{order} keyword in a locale definition. @Theglibc{} does not presently support locale definitions. @@ -1574,54 +1375,46 @@ The maximum number of weights that can be assigned to an entry of the @section Minimum Values for Utility Limits @vtable @code -@comment limits.h -@comment POSIX.2 @item _POSIX2_BC_BASE_MAX +@standards{POSIX.2, limits.h} The most restrictive limit permitted by POSIX.2 for the maximum value of @code{obase} in the @code{bc} utility. Its value is @code{99}. -@comment limits.h -@comment POSIX.2 @item _POSIX2_BC_DIM_MAX +@standards{POSIX.2, limits.h} The most restrictive limit permitted by POSIX.2 for the maximum size of an array in the @code{bc} utility. Its value is @code{2048}. -@comment limits.h -@comment POSIX.2 @item _POSIX2_BC_SCALE_MAX +@standards{POSIX.2, limits.h} The most restrictive limit permitted by POSIX.2 for the maximum value of @code{scale} in the @code{bc} utility. Its value is @code{99}. -@comment limits.h -@comment POSIX.2 @item _POSIX2_BC_STRING_MAX +@standards{POSIX.2, limits.h} The most restrictive limit permitted by POSIX.2 for the maximum size of a string constant in the @code{bc} utility. Its value is @code{1000}. -@comment limits.h -@comment POSIX.2 @item _POSIX2_COLL_WEIGHTS_MAX +@standards{POSIX.2, limits.h} The most restrictive limit permitted by POSIX.2 for the maximum number of weights that can necessarily be used in defining the collating sequence for a locale. Its value is @code{2}. -@comment limits.h -@comment POSIX.2 @item _POSIX2_EXPR_NEST_MAX +@standards{POSIX.2, limits.h} The most restrictive limit permitted by POSIX.2 for the maximum number of expressions nested within parenthesis when using the @code{expr} utility. Its value is @code{32}. -@comment limits.h -@comment POSIX.2 @item _POSIX2_LINE_MAX +@standards{POSIX.2, limits.h} The most restrictive limit permitted by POSIX.2 for the maximum size of a text line that the text utilities can handle. Its value is @code{2048}. -@comment limits.h -@comment POSIX.2 @item _POSIX2_EQUIV_CLASS_MAX +@standards{POSIX.2, limits.h} The most restrictive limit permitted by POSIX.2 for the maximum number of weights that can be assigned to an entry of the @code{LC_COLLATE} category @samp{order} keyword in a locale definition. Its value is @@ -1635,9 +1428,8 @@ definitions. POSIX.2 defines a way to get string-valued parameters from the operating system with the function @code{confstr}: -@comment unistd.h -@comment POSIX.2 @deftypefun size_t confstr (int @var{parameter}, char *@var{buf}, size_t @var{len}) +@standards{POSIX.2, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function reads the value of a string-valued system parameter, storing the string into @var{len} bytes of memory space starting at @@ -1666,65 +1458,56 @@ The value of the @var{parameter} is invalid. Currently there is just one parameter you can read with @code{confstr}: @vtable @code -@comment unistd.h -@comment POSIX.2 @item _CS_PATH +@standards{POSIX.2, unistd.h} This parameter's value is the recommended default path for searching for executable files. This is the path that a user has by default just after logging in. -@comment unistd.h -@comment Unix98 @item _CS_LFS_CFLAGS +@standards{Unix98, unistd.h} The returned string specifies which additional flags must be given to the C compiler if a source is compiled using the @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}. -@comment unistd.h -@comment Unix98 @item _CS_LFS_LDFLAGS +@standards{Unix98, unistd.h} The returned string specifies which additional flags must be given to the linker if a source is compiled using the @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}. -@comment unistd.h -@comment Unix98 @item _CS_LFS_LIBS +@standards{Unix98, unistd.h} The returned string specifies which additional libraries must be linked to the application if a source is compiled using the @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}. -@comment unistd.h -@comment Unix98 @item _CS_LFS_LINTFLAGS +@standards{Unix98, unistd.h} The returned string specifies which additional flags must be given to the lint tool if a source is compiled using the @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}. -@comment unistd.h -@comment Unix98 @item _CS_LFS64_CFLAGS +@standards{Unix98, unistd.h} The returned string specifies which additional flags must be given to the C compiler if a source is compiled using the @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}. -@comment unistd.h -@comment Unix98 @item _CS_LFS64_LDFLAGS +@standards{Unix98, unistd.h} The returned string specifies which additional flags must be given to the linker if a source is compiled using the @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}. -@comment unistd.h -@comment Unix98 @item _CS_LFS64_LIBS +@standards{Unix98, unistd.h} The returned string specifies which additional libraries must be linked to the application if a source is compiled using the @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}. -@comment unistd.h -@comment Unix98 @item _CS_LFS64_LINTFLAGS +@standards{Unix98, unistd.h} The returned string specifies which additional flags must be given to the lint tool if a source is compiled using the @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}. diff --git a/manual/creature.texi b/manual/creature.texi index 23218bbac3..eb30b0118d 100644 --- a/manual/creature.texi +++ b/manual/creature.texi @@ -33,9 +33,8 @@ standard. It is insufficient for this purpose, as it will not protect you from including header files outside the standard, or relying on semantics undefined within the standard. -@comment (none) -@comment POSIX.1 @defvr Macro _POSIX_SOURCE +@standards{POSIX.1, (none)} If you define this macro, then the functionality from the POSIX.1 standard (IEEE Standard 1003.1) is available, as well as all of the @w{ISO C} facilities. @@ -44,9 +43,8 @@ The state of @code{_POSIX_SOURCE} is irrelevant if you define the macro @code{_POSIX_C_SOURCE} to a positive integer. @end defvr -@comment (none) -@comment POSIX.2 @defvr Macro _POSIX_C_SOURCE +@standards{POSIX.2, (none)} Define this macro to a positive integer to control which POSIX functionality is made available. The greater the value of this macro, the more functionality is made available. @@ -72,12 +70,9 @@ or equal to @code{199506L}, then the functionality from the 1996 edition is made available. @end defvr -@comment (none) -@comment X/Open @defvr Macro _XOPEN_SOURCE -@comment (none) -@comment X/Open @defvrx Macro _XOPEN_SOURCE_EXTENDED +@standards{X/Open, (none)} If you define this macro, functionality described in the X/Open Portability Guide is included. This is a superset of the POSIX.1 and POSIX.2 functionality and in fact @code{_POSIX_SOURCE} and @@ -95,9 +90,8 @@ all functionality described so far plus some new definitions from the Single Unix Specification, @w{version 2}. @end defvr -@comment (NONE) -@comment X/Open @defvr Macro _LARGEFILE_SOURCE +@standards{X/Open, (NONE)} If this macro is defined some extra functions are available which rectify a few shortcomings in all previous standards. Specifically, the functions @code{fseeko} and @code{ftello} are available. Without @@ -108,9 +102,8 @@ these functions the difference between the @w{ISO C} interface This macro was introduced as part of the Large File Support extension (LFS). @end defvr -@comment (NONE) -@comment X/Open @defvr Macro _LARGEFILE64_SOURCE +@standards{X/Open, (NONE)} If you define this macro an additional set of functions is made available which enables @w{32 bit} systems to use files of sizes beyond the usual limit of 2GB. This interface is not available if the system @@ -128,9 +121,8 @@ This macro was introduced as part of the Large File Support extension offsets are not generally used (see @code{_FILE_OFFSET_BITS}). @end defvr -@comment (NONE) -@comment X/Open @defvr Macro _FILE_OFFSET_BITS +@standards{X/Open, (NONE)} This macro determines which file system interface shall be used, one replacing the other. Whereas @code{_LARGEFILE64_SOURCE} makes the @w{64 bit} interface available as an additional interface, @@ -156,62 +148,55 @@ This macro was introduced as part of the Large File Support extension (LFS). @end defvr -@comment (none) -@comment GNU @defvr Macro _ISOC99_SOURCE +@standards{GNU, (none)} Until the revised @w{ISO C} standard is widely adopted the new features are not automatically enabled. @Theglibc{} nevertheless has a complete implementation of the new standard and to enable the new features the macro @code{_ISOC99_SOURCE} should be defined. @end defvr -@comment (none) -@comment ISO @defvr Macro __STDC_WANT_LIB_EXT2__ +@standards{ISO, (none)} If you define this macro to the value @code{1}, features from ISO/IEC TR 24731-2:2010 (Dynamic Allocation Functions) are enabled. Only some of the features from this TR are supported by @theglibc{}. @end defvr -@comment (none) -@comment ISO @defvr Macro __STDC_WANT_IEC_60559_BFP_EXT__ +@standards{ISO, (none)} If you define this macro, features from ISO/IEC TS 18661-1:2014 (Floating-point extensions for C: Binary floating-point arithmetic) are enabled. Only some of the features from this TS are supported by @theglibc{}. @end defvr -@comment (none) -@comment ISO @defvr Macro __STDC_WANT_IEC_60559_FUNCS_EXT__ +@standards{ISO, (none)} If you define this macro, features from ISO/IEC TS 18661-4:2015 (Floating-point extensions for C: Supplementary functions) are enabled. Only some of the features from this TS are supported by @theglibc{}. @end defvr -@comment (none) -@comment ISO @defvr Macro __STDC_WANT_IEC_60559_TYPES_EXT__ +@standards{ISO, (none)} If you define this macro, features from ISO/IEC TS 18661-3:2015 (Floating-point extensions for C: Interchange and extended types) are enabled. Only some of the features from this TS are supported by @theglibc{}. @end defvr -@comment (none) -@comment GNU @defvr Macro _GNU_SOURCE +@standards{GNU, (none)} If you define this macro, everything is included: @w{ISO C89}, @w{ISO C99}, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU extensions. In the cases where POSIX.1 conflicts with BSD, the POSIX definitions take precedence. @end defvr -@comment (none) -@comment GNU @defvr Macro _DEFAULT_SOURCE +@standards{GNU, (none)} If you define this macro, most features are included apart from X/Open, LFS and GNU extensions: the effect is to enable features from the 2008 edition of POSIX, as well as certain BSD and SVID features @@ -224,10 +209,9 @@ enables those features even when the other options would otherwise cause them to be disabled. @end defvr -@comment (none) -@comment GNU @defvr Macro _REENTRANT @defvrx Macro _THREAD_SAFE +@standardsx{_REENTRANT, GNU, (none)} These macros are obsolete. They have the same effect as defining @code{_POSIX_C_SOURCE} with the value @code{199506L}. diff --git a/manual/crypt.texi b/manual/crypt.texi index 59e42652ab..99d2d8e092 100644 --- a/manual/crypt.texi +++ b/manual/crypt.texi @@ -97,9 +97,8 @@ When reading in a password, it is desirable to avoid displaying it on the screen, to help keep it secret. The following function handles this in a convenient way. -@comment unistd.h -@comment BSD @deftypefun {char *} getpass (const char *@var{prompt}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtunsafe{@mtasuterm{}}@asunsafe{@ascuheap{} @asulock{} @asucorrupt{}}@acunsafe{@acuterm{} @aculock{} @acucorrupt{}}} @c This function will attempt to create a stream for terminal I/O, but @c will fallback to stdio/stderr. It attempts to change the terminal @@ -139,9 +138,9 @@ The substitute takes the same parameters as @code{getline} @node crypt @section Encrypting Passwords -@comment crypt.h -@comment BSD, SVID @deftypefun {char *} crypt (const char *@var{key}, const char *@var{salt}) +@standards{BSD, crypt.h} +@standards{SVID, crypt.h} @safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}} @c Besides the obvious problem of returning a pointer into static @c storage, the DES initializer takes an internal lock with the usual @@ -207,9 +206,8 @@ for a password and prints ``Access granted.'' if the user types @include testpass.c.texi @end smallexample -@comment crypt.h -@comment GNU @deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data}) +@standards{GNU, crypt.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}} @c Compared with crypt, this function fixes the @mtasurace:crypt @c problem, but nothing else. @@ -256,9 +254,9 @@ have odd parity; that is, out of bits 1 through 8, and 9 through 16, and so on, there must be an odd number of `1' bits, and this completely specifies the unused bits. -@comment crypt.h -@comment BSD, SVID @deftypefun void setkey (const char *@var{key}) +@standards{BSD, crypt.h} +@standards{SVID, crypt.h} @safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} @c The static buffer stores the key, making it fundamentally @c thread-unsafe. The locking issues are only in the initialization @@ -272,9 +270,9 @@ the 64th bit is @code{key[63]}. The @var{key} should have the correct parity. @end deftypefun -@comment crypt.h -@comment BSD, SVID @deftypefun void encrypt (char *@var{block}, int @var{edflag}) +@standards{BSD, crypt.h} +@standards{SVID, crypt.h} @safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} @c Same issues as setkey. @@ -287,12 +285,9 @@ Like @code{setkey}, @var{block} is specified as an array of 64 bits each stored in a @code{char}, but there are no parity bits in @var{block}. @end deftypefun -@comment crypt.h -@comment GNU @deftypefun void setkey_r (const char *@var{key}, {struct crypt_data *} @var{data}) -@comment crypt.h -@comment GNU @deftypefunx void encrypt_r (char *@var{block}, int @var{edflag}, {struct crypt_data *} @var{data}) +@standards{GNU, crypt.h} @c setkey_r: @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} @@ -306,9 +301,8 @@ The @code{setkey_r} and @code{encrypt_r} functions are GNU extensions. @code{setkey}, @code{encrypt}, @code{setkey_r}, and @code{encrypt_r} are defined in @file{crypt.h}. -@comment rpc/des_crypt.h -@comment SUNRPC @deftypefun int ecb_crypt (char *@var{key}, char *@var{blocks}, unsigned int @var{len}, unsigned int @var{mode}) +@standards{SUNRPC, rpc/des_crypt.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{ecb_crypt} encrypts or decrypts one or more blocks @@ -329,28 +323,24 @@ The result of the encryption replaces the input in @var{blocks}. The @var{mode} parameter is the bitwise OR of two of the following: @vtable @code -@comment rpc/des_crypt.h -@comment SUNRPC @item DES_ENCRYPT +@standards{SUNRPC, rpc/des_crypt.h} This constant, used in the @var{mode} parameter, specifies that @var{blocks} is to be encrypted. -@comment rpc/des_crypt.h -@comment SUNRPC @item DES_DECRYPT +@standards{SUNRPC, rpc/des_crypt.h} This constant, used in the @var{mode} parameter, specifies that @var{blocks} is to be decrypted. -@comment rpc/des_crypt.h -@comment SUNRPC @item DES_HW +@standards{SUNRPC, rpc/des_crypt.h} This constant, used in the @var{mode} parameter, asks to use a hardware device. If no hardware device is available, encryption happens anyway, but in software. -@comment rpc/des_crypt.h -@comment SUNRPC @item DES_SW +@standards{SUNRPC, rpc/des_crypt.h} This constant, used in the @var{mode} parameter, specifies that no hardware device is to be used. @end vtable @@ -358,40 +348,34 @@ hardware device is to be used. The result of the function will be one of these values: @vtable @code -@comment rpc/des_crypt.h -@comment SUNRPC @item DESERR_NONE +@standards{SUNRPC, rpc/des_crypt.h} The encryption succeeded. -@comment rpc/des_crypt.h -@comment SUNRPC @item DESERR_NOHWDEVICE +@standards{SUNRPC, rpc/des_crypt.h} The encryption succeeded, but there was no hardware device available. -@comment rpc/des_crypt.h -@comment SUNRPC @item DESERR_HWERROR +@standards{SUNRPC, rpc/des_crypt.h} The encryption failed because of a hardware problem. -@comment rpc/des_crypt.h -@comment SUNRPC @item DESERR_BADPARAM +@standards{SUNRPC, rpc/des_crypt.h} The encryption failed because of a bad parameter, for instance @var{len} is not a multiple of 8 or @var{len} is larger than @code{DES_MAXDATA}. @end vtable @end deftypefun -@comment rpc/des_crypt.h -@comment SUNRPC @deftypefun int DES_FAILED (int @var{err}) +@standards{SUNRPC, rpc/des_crypt.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns 1 if @var{err} is a `success' result code from @code{ecb_crypt} or @code{cbc_crypt}, and 0 otherwise. @end deftypefun -@comment rpc/des_crypt.h -@comment SUNRPC @deftypefun int cbc_crypt (char *@var{key}, char *@var{blocks}, unsigned int @var{len}, unsigned int @var{mode}, char *@var{ivec}) +@standards{SUNRPC, rpc/des_crypt.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{cbc_crypt} encrypts or decrypts one or more blocks @@ -416,9 +400,8 @@ bytes. Otherwise, all the parameters are similar to those for @code{ecb_crypt}. @end deftypefun -@comment rpc/des_crypt.h -@comment SUNRPC @deftypefun void des_setparity (char *@var{key}) +@standards{SUNRPC, rpc/des_crypt.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{des_setparity} changes the 64-bit @var{key}, stored @@ -442,9 +425,8 @@ below internally to obtain randomness to seed the generator. The @code{getrandom} function is intended for low-level applications which need additional control over the blocking behavior. -@comment sys/random.h -@comment GNU @deftypefun int getentropy (void *@var{buffer}, size_t @var{length}) +@standards{GNU, sys/random.h} @safety{@mtsafe{}@assafe{}@acsafe{}} This function writes @var{length} bytes of random data to the array @@ -480,9 +462,8 @@ could not be overwritten with random data for an unspecified reason. @end deftypefun -@comment sys/random.h -@comment GNU @deftypefun ssize_t getrandom (void *@var{buffer}, size_t @var{length}, unsigned int @var{flags}) +@standards{GNU, sys/random.h} @safety{@mtsafe{}@assafe{}@acsafe{}} This function writes @var{length} bytes of random data to the array diff --git a/manual/ctype.texi b/manual/ctype.texi index 818c095d13..d0618c5c38 100644 --- a/manual/ctype.texi +++ b/manual/ctype.texi @@ -63,9 +63,8 @@ These functions are declared in the header file @file{ctype.h}. @pindex ctype.h @cindex lower-case character -@comment ctype.h -@comment ISO @deftypefun int islower (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c The is* macros call __ctype_b_loc to get the ctype array from the @c current locale, and then index it by c. __ctype_b_loc reads from @@ -81,18 +80,16 @@ from the Latin alphabet, any alphabet representable is valid. @end deftypefun @cindex upper-case character -@comment ctype.h -@comment ISO @deftypefun int isupper (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is an upper-case letter. The letter need not be from the Latin alphabet, any alphabet representable is valid. @end deftypefun @cindex alphabetic character -@comment ctype.h -@comment ISO @deftypefun int isalpha (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is an alphabetic character (a letter). If @code{islower} or @code{isupper} is true of a character, then @@ -106,17 +103,15 @@ additional characters. @cindex digit character @cindex decimal digit character -@comment ctype.h -@comment ISO @deftypefun int isdigit (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}). @end deftypefun @cindex alphanumeric character -@comment ctype.h -@comment ISO @deftypefun int isalnum (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is an alphanumeric character (a letter or number); in other words, if either @code{isalpha} or @code{isdigit} is @@ -124,9 +119,8 @@ true of a character, then @code{isalnum} is also true. @end deftypefun @cindex hexadecimal digit character -@comment ctype.h -@comment ISO @deftypefun int isxdigit (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a hexadecimal digit. Hexadecimal digits include the normal decimal digits @samp{0} through @@ -135,9 +129,8 @@ Hexadecimal digits include the normal decimal digits @samp{0} through @end deftypefun @cindex punctuation character -@comment ctype.h -@comment ISO @deftypefun int ispunct (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a punctuation character. This means any printing character that is not alphanumeric or a space @@ -145,9 +138,8 @@ character. @end deftypefun @cindex whitespace character -@comment ctype.h -@comment ISO @deftypefun int isspace (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a @dfn{whitespace} character. In the standard @code{"C"} locale, @code{isspace} returns true for only the standard @@ -175,18 +167,16 @@ vertical tab @end deftypefun @cindex blank character -@comment ctype.h -@comment ISO @deftypefun int isblank (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a blank character; that is, a space or a tab. This function was originally a GNU extension, but was added in @w{ISO C99}. @end deftypefun @cindex graphic character -@comment ctype.h -@comment ISO @deftypefun int isgraph (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a graphic character; that is, a character that has a glyph associated with it. The whitespace characters are not @@ -194,27 +184,25 @@ considered graphic. @end deftypefun @cindex printing character -@comment ctype.h -@comment ISO @deftypefun int isprint (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a printing character. Printing characters include all the graphic characters, plus the space (@samp{ }) character. @end deftypefun @cindex control character -@comment ctype.h -@comment ISO @deftypefun int iscntrl (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a control character (that is, a character that is not a printing character). @end deftypefun @cindex ASCII character -@comment ctype.h -@comment SVID, BSD @deftypefun int isascii (int @var{c}) +@standards{SVID, ctype.h} +@standards{BSD, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a 7-bit @code{unsigned char} value that fits into the US/UK ASCII character set. This function is a BSD extension @@ -246,9 +234,8 @@ may need to write @code{islower(c) ? toupper(c) : c} rather than just These functions are declared in the header file @file{ctype.h}. @pindex ctype.h -@comment ctype.h -@comment ISO @deftypefun int tolower (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c The to* macros/functions call different functions that use different @c arrays than those of__ctype_b_loc, but the access patterns and @@ -258,34 +245,31 @@ lower-case letter. If @var{c} is not an upper-case letter, @var{c} is returned unchanged. @end deftypefun -@comment ctype.h -@comment ISO @deftypefun int toupper (int @var{c}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If @var{c} is a lower-case letter, @code{toupper} returns the corresponding upper-case letter. Otherwise @var{c} is returned unchanged. @end deftypefun -@comment ctype.h -@comment SVID, BSD @deftypefun int toascii (int @var{c}) +@standards{SVID, ctype.h} +@standards{BSD, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function converts @var{c} to a 7-bit @code{unsigned char} value that fits into the US/UK ASCII character set, by clearing the high-order bits. This function is a BSD extension and is also an SVID extension. @end deftypefun -@comment ctype.h -@comment SVID @deftypefun int _tolower (int @var{c}) +@standards{SVID, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is identical to @code{tolower}, and is provided for compatibility with the SVID. @xref{SVID}.@refill @end deftypefun -@comment ctype.h -@comment SVID @deftypefun int _toupper (int @var{c}) +@standards{SVID, ctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is identical to @code{toupper}, and is provided for compatibility with the SVID. @@ -319,9 +303,8 @@ character is in this class, using the classification value. On top of this the normal character classification functions as used for @code{char} objects can be defined. -@comment wctype.h -@comment ISO @deftp {Data type} wctype_t +@standards{ISO, wctype.h} The @code{wctype_t} can hold a value which represents a character class. The only defined way to generate such a value is by using the @code{wctype} function. @@ -330,9 +313,8 @@ The only defined way to generate such a value is by using the This type is defined in @file{wctype.h}. @end deftp -@comment wctype.h -@comment ISO @deftypefun wctype_t wctype (const char *@var{property}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c Although the source code of wctype contains multiple references to @c the locale, that could each reference different locale_data objects @@ -370,9 +352,8 @@ This function is declared in @file{wctype.h}. To test the membership of a character to one of the non-standard classes the @w{ISO C} standard defines a completely new function. -@comment wctype.h -@comment ISO @deftypefun int iswctype (wint_t @var{wc}, wctype_t @var{desc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c The compressed lookup table returned by wctype is read-only. This function returns a nonzero value if @var{wc} is in the character @@ -391,9 +372,8 @@ strings, and then it is important that @code{wctype} can also handle the standard classes. @cindex alphanumeric character -@comment wctype.h -@comment ISO @deftypefun int iswalnum (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c The implicit wctype call in the isw* functions is actually an @c optimized version because the category has a known offset, but the @@ -421,9 +401,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex alphabetic character -@comment wctype.h -@comment ISO @deftypefun int iswalpha (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is an alphabetic character (a letter). If @code{iswlower} or @code{iswupper} is true of a character, then @@ -446,9 +425,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex control character -@comment wctype.h -@comment ISO @deftypefun int iswcntrl (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is a control character (that is, a character that is not a printing character). @@ -465,9 +443,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex digit character -@comment wctype.h -@comment ISO @deftypefun int iswdigit (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is a digit (e.g., @samp{0} through @samp{9}). Please note that this function does not only return a nonzero value for @@ -496,9 +473,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex graphic character -@comment wctype.h -@comment ISO @deftypefun int iswgraph (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is a graphic character; that is, a character that has a glyph associated with it. The whitespace characters are not @@ -516,9 +492,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex lower-case character -@comment ctype.h -@comment ISO @deftypefun int iswlower (wint_t @var{wc}) +@standards{ISO, ctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is a lower-case letter. The letter need not be from the Latin alphabet, any alphabet representable is valid. @@ -535,9 +510,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex printing character -@comment wctype.h -@comment ISO @deftypefun int iswprint (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is a printing character. Printing characters include all the graphic characters, plus the space (@samp{ }) character. @@ -554,9 +528,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex punctuation character -@comment wctype.h -@comment ISO @deftypefun int iswpunct (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is a punctuation character. This means any printing character that is not alphanumeric or a space @@ -574,9 +547,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex whitespace character -@comment wctype.h -@comment ISO @deftypefun int iswspace (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is a @dfn{whitespace} character. In the standard @code{"C"} locale, @code{iswspace} returns true for only the standard @@ -614,9 +586,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex upper-case character -@comment wctype.h -@comment ISO @deftypefun int iswupper (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is an upper-case letter. The letter need not be from the Latin alphabet, any alphabet representable is valid. @@ -633,9 +604,8 @@ It is declared in @file{wctype.h}. @end deftypefun @cindex hexadecimal digit character -@comment wctype.h -@comment ISO @deftypefun int iswxdigit (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is a hexadecimal digit. Hexadecimal digits include the normal decimal digits @samp{0} through @@ -658,9 +628,8 @@ It is declared in @file{wctype.h}. characters as well. @cindex blank character -@comment wctype.h -@comment ISO @deftypefun int iswblank (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} Returns true if @var{wc} is a blank character; that is, a space or a tab. This function was originally a GNU extension, but was added in @w{ISO C99}. @@ -740,9 +709,8 @@ standard. Instead of just allowing the two standard mappings, a locale can contain others. Again, the @code{localedef} program already supports generating such locale data files. -@comment wctype.h -@comment ISO @deftp {Data Type} wctrans_t +@standards{ISO, wctype.h} This data type is defined as a scalar type which can hold a value representing the locale-dependent character mapping. There is no way to construct such a value apart from using the return value of the @@ -753,9 +721,8 @@ construct such a value apart from using the return value of the This type is defined in @file{wctype.h}. @end deftp -@comment wctype.h -@comment ISO @deftypefun wctrans_t wctrans (const char *@var{property}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c Similar implementation, same caveats as wctype. The @code{wctrans} function has to be used to find out whether a named @@ -777,9 +744,8 @@ guaranteed to be available in every locale: These functions are declared in @file{wctype.h}. @end deftypefun -@comment wctype.h -@comment ISO @deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Same caveats as iswctype. @code{towctrans} maps the input character @var{wc} @@ -796,9 +762,8 @@ For the generally available mappings, the @w{ISO C} standard defines convenient shortcuts so that it is not necessary to call @code{wctrans} for them. -@comment wctype.h -@comment ISO @deftypefun wint_t towlower (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c Same caveats as iswalnum, just using a wctrans rather than a wctype @c table. @@ -818,9 +783,8 @@ towctrans (wc, wctrans ("tolower")) This function is declared in @file{wctype.h}. @end deftypefun -@comment wctype.h -@comment ISO @deftypefun wint_t towupper (wint_t @var{wc}) +@standards{ISO, wctype.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} If @var{wc} is a lower-case letter, @code{towupper} returns the corresponding upper-case letter. Otherwise @var{wc} is returned unchanged. diff --git a/manual/debug.texi b/manual/debug.texi index ac5121b061..f4157e525e 100644 --- a/manual/debug.texi +++ b/manual/debug.texi @@ -33,9 +33,8 @@ The header file @file{execinfo.h} declares three functions that obtain and manipulate backtraces of the current thread. @pindex execinfo.h -@comment execinfo.h -@comment GNU @deftypefun int backtrace (void **@var{buffer}, int @var{size}) +@standards{GNU, execinfo.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{} @ascuheap{} @ascudlopen{} @ascuplugin{} @asulock{}}@acunsafe{@acuinit{} @acsmem{} @aculock{} @acsfd{}}} @c The generic implementation just does pointer chasing within the local @c stack, without any guarantees that this will handle signal frames @@ -63,9 +62,8 @@ another; frame pointer elimination will stop @code{backtrace} from interpreting the stack contents correctly. @end deftypefun -@comment execinfo.h -@comment GNU @deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size}) +@standards{GNU, execinfo.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @aculock{}}} @c Collects info returned by _dl_addr in an auto array, allocates memory @c for the whole return buffer with malloc then sprintfs into it storing @@ -106,9 +104,8 @@ The return value is @code{NULL} if sufficient memory for the strings cannot be obtained. @end deftypefun -@comment execinfo.h -@comment GNU @deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd}) +@standards{GNU, execinfo.h} @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} @c Single loop of _dl_addr over addresses, collecting info into an iovec @c written out with a writev call per iteration. Addresses and offsets diff --git a/manual/errno.texi b/manual/errno.texi index f4c07f0683..3e0b862c4e 100644 --- a/manual/errno.texi +++ b/manual/errno.texi @@ -36,9 +36,8 @@ variable @code{errno}. This variable is declared in the header file @file{errno.h}. @pindex errno.h -@comment errno.h -@comment ISO @deftypevr {Variable} {volatile int} errno +@standards{ISO, errno.h} The variable @code{errno} contains the system error number. You can change the value of @code{errno}. @@ -118,33 +117,29 @@ All of them expand into integer constant values. Some of these error codes can't occur on @gnusystems{}, but they can occur using @theglibc{} on other systems. -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EPERM +@standards{POSIX.1, errno.h} @errno{EPERM, 1, Operation not permitted} Only the owner of the file (or other resource) or processes with special privileges can perform the operation. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOENT +@standards{POSIX.1, errno.h} @errno{ENOENT, 2, No such file or directory} This is a ``file doesn't exist'' error for ordinary files that are referenced in contexts where they are expected to already exist. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ESRCH +@standards{POSIX.1, errno.h} @errno{ESRCH, 3, No such process} No process matches the specified process ID. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EINTR +@standards{POSIX.1, errno.h} @errno{EINTR, 4, Interrupted system call} An asynchronous signal occurred and prevented completion of the call. When this happens, you should try the call @@ -155,16 +150,14 @@ rather than failing with @code{EINTR}; see @ref{Interrupted Primitives}. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EIO +@standards{POSIX.1, errno.h} @errno{EIO, 5, Input/output error} Usually used for physical read or write errors. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENXIO +@standards{POSIX.1, errno.h} @errno{ENXIO, 6, No such device or address} The system tried to use the device represented by a file you specified, and it couldn't find the device. @@ -173,9 +166,8 @@ the physical device is missing or not correctly attached to the computer. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int E2BIG +@standards{POSIX.1, errno.h} @errno{E2BIG, 7, Argument list too long} Used when the arguments passed to a new program being executed with one of the @code{exec} functions (@pxref{Executing a @@ -183,35 +175,31 @@ File}) occupy too much memory space. This condition never arises on @gnuhurdsystems{}. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOEXEC +@standards{POSIX.1, errno.h} @errno{ENOEXEC, 8, Exec format error} Invalid executable file format. This condition is detected by the @code{exec} functions; see @ref{Executing a File}. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EBADF +@standards{POSIX.1, errno.h} @errno{EBADF, 9, Bad file descriptor} For example, I/O on a descriptor that has been closed or reading from a descriptor open only for writing (or vice versa). @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ECHILD +@standards{POSIX.1, errno.h} @errno{ECHILD, 10, No child processes} This error happens on operations that are supposed to manipulate child processes, when there aren't any processes to manipulate. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EDEADLK +@standards{POSIX.1, errno.h} @errno{EDEADLK, 11, Resource deadlock avoided} Allocating a system resource would have resulted in a deadlock situation. The system does not guarantee that it will notice @@ -219,98 +207,86 @@ all such situations. This error means you got lucky and the system noticed; it might just hang. @xref{File Locks}, for an example. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOMEM +@standards{POSIX.1, errno.h} @errno{ENOMEM, 12, Cannot allocate memory} The system cannot allocate more virtual memory because its capacity is full. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EACCES +@standards{POSIX.1, errno.h} @errno{EACCES, 13, Permission denied} The file permissions do not allow the attempted operation. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EFAULT +@standards{POSIX.1, errno.h} @errno{EFAULT, 14, Bad address} An invalid pointer was detected. On @gnuhurdsystems{}, this error never happens; you get a signal instead. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ENOTBLK +@standards{BSD, errno.h} @errno{ENOTBLK, 15, Block device required} A file that isn't a block special file was given in a situation that requires one. For example, trying to mount an ordinary file as a file system in Unix gives this error. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EBUSY +@standards{POSIX.1, errno.h} @errno{EBUSY, 16, Device or resource busy} A system resource that can't be shared is already in use. For example, if you try to delete a file that is the root of a currently mounted filesystem, you get this error. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EEXIST +@standards{POSIX.1, errno.h} @errno{EEXIST, 17, File exists} An existing file was specified in a context where it only makes sense to specify a new file. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EXDEV +@standards{POSIX.1, errno.h} @errno{EXDEV, 18, Invalid cross-device link} An attempt to make an improper link across file systems was detected. This happens not only when you use @code{link} (@pxref{Hard Links}) but also when you rename a file with @code{rename} (@pxref{Renaming Files}). @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENODEV +@standards{POSIX.1, errno.h} @errno{ENODEV, 19, No such device} The wrong type of device was given to a function that expects a particular sort of device. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOTDIR +@standards{POSIX.1, errno.h} @errno{ENOTDIR, 20, Not a directory} A file that isn't a directory was specified when a directory is required. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EISDIR +@standards{POSIX.1, errno.h} @errno{EISDIR, 21, Is a directory} You cannot open a directory for writing, or create or remove hard links to it. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EINVAL +@standards{POSIX.1, errno.h} @errno{EINVAL, 22, Invalid argument} This is used to indicate various kinds of problems with passing the wrong argument to a library function. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EMFILE +@standards{POSIX.1, errno.h} @errno{EMFILE, 24, Too many open files} The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. @@ -321,26 +297,23 @@ want to increase the @code{RLIMIT_NOFILE} limit or make it unlimited; @pxref{Limits on Resources}. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENFILE +@standards{POSIX.1, errno.h} @errno{ENFILE, 23, Too many open files in system} There are too many distinct file openings in the entire system. Note that any number of linked channels count as just one file opening; see @ref{Linked Channels}. This error never occurs on @gnuhurdsystems{}. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOTTY +@standards{POSIX.1, errno.h} @errno{ENOTTY, 25, Inappropriate ioctl for device} Inappropriate I/O control operation, such as trying to set terminal modes on an ordinary file. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ETXTBSY +@standards{BSD, errno.h} @errno{ETXTBSY, 26, Text file busy} An attempt to execute a file that is currently open for writing, or write to a file that is currently being executed. Often using a @@ -349,47 +322,41 @@ will cause this error. (The name stands for ``text file busy''.) This is not an error on @gnuhurdsystems{}; the text is copied as necessary. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EFBIG +@standards{POSIX.1, errno.h} @errno{EFBIG, 27, File too large} The size of a file would be larger than allowed by the system. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOSPC +@standards{POSIX.1, errno.h} @errno{ENOSPC, 28, No space left on device} Write operation on a file failed because the disk is full. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ESPIPE +@standards{POSIX.1, errno.h} @errno{ESPIPE, 29, Illegal seek} Invalid seek operation (such as on a pipe). @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EROFS +@standards{POSIX.1, errno.h} @errno{EROFS, 30, Read-only file system} An attempt was made to modify something on a read-only file system. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EMLINK +@standards{POSIX.1, errno.h} @errno{EMLINK, 31, Too many links} The link count of a single file would become too large. @code{rename} can cause this error if the file being renamed already has as many links as it can take (@pxref{Renaming Files}). @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EPIPE +@standards{POSIX.1, errno.h} @errno{EPIPE, 32, Broken pipe} There is no process reading from the other end of a pipe. Every library function that returns this error code also generates a @@ -398,25 +365,22 @@ or blocked. Thus, your program will never actually see @code{EPIPE} unless it has handled or blocked @code{SIGPIPE}. @end deftypevr -@comment errno.h -@comment ISO @deftypevr Macro int EDOM +@standards{ISO, errno.h} @errno{EDOM, 33, Numerical argument out of domain} Used by mathematical functions when an argument value does not fall into the domain over which the function is defined. @end deftypevr -@comment errno.h -@comment ISO @deftypevr Macro int ERANGE +@standards{ISO, errno.h} @errno{ERANGE, 34, Numerical result out of range} Used by mathematical functions when the result value is not representable because of overflow or underflow. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int EAGAIN +@standards{POSIX.1, errno.h} @errno{EAGAIN, 35, Resource temporarily unavailable} The call might work if you try again later. The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN}; @@ -449,9 +413,8 @@ and return to its command loop. @end itemize @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EWOULDBLOCK +@standards{BSD, errno.h} @errno{EWOULDBLOCK, EAGAIN, Operation would block} In @theglibc{}, this is another name for @code{EAGAIN} (above). The values are always the same, on every operating system. @@ -460,9 +423,8 @@ C libraries in many older Unix systems have @code{EWOULDBLOCK} as a separate error code. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EINPROGRESS +@standards{BSD, errno.h} @errno{EINPROGRESS, 36, Operation now in progress} An operation that cannot complete immediately was initiated on an object that has non-blocking mode selected. Some functions that must always @@ -474,63 +436,55 @@ use the @code{select} function to find out when the pending operation has completed; @pxref{Waiting for I/O}. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EALREADY +@standards{BSD, errno.h} @errno{EALREADY, 37, Operation already in progress} An operation is already in progress on an object that has non-blocking mode selected. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ENOTSOCK +@standards{BSD, errno.h} @errno{ENOTSOCK, 38, Socket operation on non-socket} A file that isn't a socket was specified when a socket is required. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EMSGSIZE +@standards{BSD, errno.h} @errno{EMSGSIZE, 40, Message too long} The size of a message sent on a socket was larger than the supported maximum size. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EPROTOTYPE +@standards{BSD, errno.h} @errno{EPROTOTYPE, 41, Protocol wrong type for socket} The socket type does not support the requested communications protocol. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ENOPROTOOPT +@standards{BSD, errno.h} @errno{ENOPROTOOPT, 42, Protocol not available} You specified a socket option that doesn't make sense for the particular protocol being used by the socket. @xref{Socket Options}. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EPROTONOSUPPORT +@standards{BSD, errno.h} @errno{EPROTONOSUPPORT, 43, Protocol not supported} The socket domain does not support the requested communications protocol (perhaps because the requested protocol is completely invalid). @xref{Creating a Socket}. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ESOCKTNOSUPPORT +@standards{BSD, errno.h} @errno{ESOCKTNOSUPPORT, 44, Socket type not supported} The socket type is not supported. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EOPNOTSUPP +@standards{BSD, errno.h} @errno{EOPNOTSUPP, 45, Operation not supported} The operation you requested is not supported. Some socket functions don't make sense for all types of sockets, and others may not be @@ -540,95 +494,83 @@ particular operation; it is a generic indication that the server knows nothing to do for that call. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EPFNOSUPPORT +@standards{BSD, errno.h} @errno{EPFNOSUPPORT, 46, Protocol family not supported} The socket communications protocol family you requested is not supported. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EAFNOSUPPORT +@standards{BSD, errno.h} @errno{EAFNOSUPPORT, 47, Address family not supported by protocol} The address family specified for a socket is not supported; it is inconsistent with the protocol being used on the socket. @xref{Sockets}. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EADDRINUSE +@standards{BSD, errno.h} @errno{EADDRINUSE, 48, Address already in use} The requested socket address is already in use. @xref{Socket Addresses}. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EADDRNOTAVAIL +@standards{BSD, errno.h} @errno{EADDRNOTAVAIL, 49, Cannot assign requested address} The requested socket address is not available; for example, you tried to give a socket a name that doesn't match the local host name. @xref{Socket Addresses}. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ENETDOWN +@standards{BSD, errno.h} @errno{ENETDOWN, 50, Network is down} A socket operation failed because the network was down. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ENETUNREACH +@standards{BSD, errno.h} @errno{ENETUNREACH, 51, Network is unreachable} A socket operation failed because the subnet containing the remote host was unreachable. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ENETRESET +@standards{BSD, errno.h} @errno{ENETRESET, 52, Network dropped connection on reset} A network connection was reset because the remote host crashed. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ECONNABORTED +@standards{BSD, errno.h} @errno{ECONNABORTED, 53, Software caused connection abort} A network connection was aborted locally. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ECONNRESET +@standards{BSD, errno.h} @errno{ECONNRESET, 54, Connection reset by peer} A network connection was closed for reasons outside the control of the local host, such as by the remote machine rebooting or an unrecoverable protocol violation. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ENOBUFS +@standards{BSD, errno.h} @errno{ENOBUFS, 55, No buffer space available} The kernel's buffers for I/O operations are all in use. In GNU, this error is always synonymous with @code{ENOMEM}; you may get one or the other from network operations. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EISCONN +@standards{BSD, errno.h} @errno{EISCONN, 56, Transport endpoint is already connected} You tried to connect a socket that is already connected. @xref{Connecting}. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ENOTCONN +@standards{BSD, errno.h} @errno{ENOTCONN, 57, Transport endpoint is not connected} The socket is not connected to anything. You get this error when you try to transmit data over a socket, without first specifying a @@ -636,110 +578,96 @@ destination for the data. For a connectionless socket (for datagram protocols, such as UDP), you get @code{EDESTADDRREQ} instead. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EDESTADDRREQ +@standards{BSD, errno.h} @errno{EDESTADDRREQ, 39, Destination address required} No default destination address was set for the socket. You get this error when you try to transmit data over a connectionless socket, without first specifying a destination for the data with @code{connect}. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ESHUTDOWN +@standards{BSD, errno.h} @errno{ESHUTDOWN, 58, Cannot send after transport endpoint shutdown} The socket has already been shut down. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ETOOMANYREFS +@standards{BSD, errno.h} @errno{ETOOMANYREFS, 59, Too many references: cannot splice} @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ETIMEDOUT +@standards{BSD, errno.h} @errno{ETIMEDOUT, 60, Connection timed out} A socket operation with a specified timeout received no response during the timeout period. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ECONNREFUSED +@standards{BSD, errno.h} @errno{ECONNREFUSED, 61, Connection refused} A remote host refused to allow the network connection (typically because it is not running the requested service). @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ELOOP +@standards{BSD, errno.h} @errno{ELOOP, 62, Too many levels of symbolic links} Too many levels of symbolic links were encountered in looking up a file name. This often indicates a cycle of symbolic links. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENAMETOOLONG +@standards{POSIX.1, errno.h} @errno{ENAMETOOLONG, 63, File name too long} Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for Files}) or host name too long (in @code{gethostname} or @code{sethostname}; @pxref{Host Identification}). @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EHOSTDOWN +@standards{BSD, errno.h} @errno{EHOSTDOWN, 64, Host is down} The remote host for a requested network connection is down. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EHOSTUNREACH +@standards{BSD, errno.h} @errno{EHOSTUNREACH, 65, No route to host} The remote host for a requested network connection is not reachable. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOTEMPTY +@standards{POSIX.1, errno.h} @errno{ENOTEMPTY, 66, Directory not empty} Directory not empty, where an empty directory was expected. Typically, this error occurs when you are trying to delete a directory. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EPROCLIM +@standards{BSD, errno.h} @errno{EPROCLIM, 67, Too many processes} This means that the per-user limit on new process would be exceeded by an attempted @code{fork}. @xref{Limits on Resources}, for details on the @code{RLIMIT_NPROC} limit. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EUSERS +@standards{BSD, errno.h} @errno{EUSERS, 68, Too many users} The file quota system is confused because there are too many users. @c This can probably happen in a GNU system when using NFS. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EDQUOT +@standards{BSD, errno.h} @errno{EDQUOT, 69, Disk quota exceeded} The user's disk quota was exceeded. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ESTALE +@standards{BSD, errno.h} @errno{ESTALE, 70, Stale file handle} This indicates an internal confusion in the file system which is due to file system rearrangements on the server host @@ -748,9 +676,8 @@ Repairing this condition usually requires unmounting, possibly repairing and remounting the file system. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EREMOTE +@standards{BSD, errno.h} @errno{EREMOTE, 71, Object is remote} An attempt was made to NFS-mount a remote file system with a file name that already specifies an NFS-mounted file. @@ -758,39 +685,33 @@ already specifies an NFS-mounted file. properly on @gnuhurdsystems{}, making this error code impossible.) @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EBADRPC +@standards{BSD, errno.h} @errno{EBADRPC, 72, RPC struct is bad} @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ERPCMISMATCH +@standards{BSD, errno.h} @errno{ERPCMISMATCH, 73, RPC version wrong} @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EPROGUNAVAIL +@standards{BSD, errno.h} @errno{EPROGUNAVAIL, 74, RPC program not available} @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EPROGMISMATCH +@standards{BSD, errno.h} @errno{EPROGMISMATCH, 75, RPC program version wrong} @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EPROCUNAVAIL +@standards{BSD, errno.h} @errno{EPROCUNAVAIL, 76, RPC bad procedure for program} @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOLCK +@standards{POSIX.1, errno.h} @errno{ENOLCK, 77, No locks available} This is used by the file locking facilities; see @ref{File Locks}. This error is never generated by @gnuhurdsystems{}, but @@ -798,9 +719,8 @@ it can result from an operation to an NFS server running another operating system. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EFTYPE +@standards{BSD, errno.h} @errno{EFTYPE, 79, Inappropriate file type or format} The file was the wrong type for the operation, or a data file had the wrong format. @@ -809,21 +729,18 @@ On some systems @code{chmod} returns this error if you try to set the sticky bit on a non-directory file; @pxref{Setting Permissions}. @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int EAUTH +@standards{BSD, errno.h} @errno{EAUTH, 80, Authentication error} @end deftypevr -@comment errno.h -@comment BSD @deftypevr Macro int ENEEDAUTH +@standards{BSD, errno.h} @errno{ENEEDAUTH, 81, Need authenticator} @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOSYS +@standards{POSIX.1, errno.h} @errno{ENOSYS, 78, Function not implemented} This indicates that the function called is not implemented at all, either in the C library itself or in the @@ -832,9 +749,8 @@ particular function will always fail with @code{ENOSYS} unless you install a new version of the C library or the operating system. @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ENOTSUP +@standards{POSIX.1, errno.h} @errno{ENOTSUP, 118, Not supported} A function returns this error when certain parameter values are valid, but the functionality they request is not available. @@ -850,17 +766,15 @@ If the entire function is not available at all in the implementation, it returns @code{ENOSYS} instead. @end deftypevr -@comment errno.h -@comment ISO @deftypevr Macro int EILSEQ +@standards{ISO, errno.h} @errno{EILSEQ, 106, Invalid or incomplete multibyte or wide character} While decoding a multibyte character the function came along an invalid or an incomplete sequence of bytes or the given wide character is invalid. @end deftypevr -@comment errno.h -@comment GNU @deftypevr Macro int EBACKGROUND +@standards{GNU, errno.h} @errno{EBACKGROUND, 100, Inappropriate operation for background process} On @gnuhurdsystems{}, servers supporting the @code{term} protocol return this error for certain operations when the caller is not in the @@ -870,114 +784,97 @@ it into a @code{SIGTTIN} or @code{SIGTTOU} signal. @xref{Job Control}, for information on process groups and these signals. @end deftypevr -@comment errno.h -@comment GNU @deftypevr Macro int EDIED +@standards{GNU, errno.h} @errno{EDIED, 101, Translator died} On @gnuhurdsystems{}, opening a file returns this error when the file is translated by a program and the translator program dies while starting up, before it has connected to the file. @end deftypevr -@comment errno.h -@comment GNU @deftypevr Macro int ED +@standards{GNU, errno.h} @errno{ED, 102, ?} The experienced user will know what is wrong. @c This error code is a joke. Its perror text is part of the joke. @c Don't change it. @end deftypevr -@comment errno.h -@comment GNU @deftypevr Macro int EGREGIOUS +@standards{GNU, errno.h} @errno{EGREGIOUS, 103, You really blew it this time} You did @strong{what}? @end deftypevr -@comment errno.h -@comment GNU @deftypevr Macro int EIEIO +@standards{GNU, errno.h} @errno{EIEIO, 104, Computer bought the farm} Go home and have a glass of warm, dairy-fresh milk. @end deftypevr -@comment errno.h -@comment GNU @deftypevr Macro int EGRATUITOUS +@standards{GNU, errno.h} @errno{EGRATUITOUS, 105, Gratuitous error} This error code has no purpose. @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int EBADMSG +@standards{XOPEN, errno.h} @errno{EBADMSG, 107, Bad message} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int EIDRM +@standards{XOPEN, errno.h} @errno{EIDRM, 108, Identifier removed} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int EMULTIHOP +@standards{XOPEN, errno.h} @errno{EMULTIHOP, 109, Multihop attempted} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int ENODATA +@standards{XOPEN, errno.h} @errno{ENODATA, 110, No data available} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int ENOLINK +@standards{XOPEN, errno.h} @errno{ENOLINK, 111, Link has been severed} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int ENOMSG +@standards{XOPEN, errno.h} @errno{ENOMSG, 112, No message of desired type} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int ENOSR +@standards{XOPEN, errno.h} @errno{ENOSR, 113, Out of streams resources} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int ENOSTR +@standards{XOPEN, errno.h} @errno{ENOSTR, 114, Device not a stream} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int EOVERFLOW +@standards{XOPEN, errno.h} @errno{EOVERFLOW, 115, Value too large for defined data type} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int EPROTO +@standards{XOPEN, errno.h} @errno{EPROTO, 116, Protocol error} @end deftypevr -@comment errno.h -@comment XOPEN @deftypevr Macro int ETIME +@standards{XOPEN, errno.h} @errno{ETIME, 117, Timer expired} @end deftypevr -@comment errno.h -@comment POSIX.1 @deftypevr Macro int ECANCELED +@standards{POSIX.1, errno.h} @errno{ECANCELED, 119, Operation canceled} An asynchronous operation was canceled before it completed. @xref{Asynchronous I/O}. When you call @code{aio_cancel}, @@ -989,285 +886,238 @@ error; @pxref{Cancel AIO Operations}. @emph{The following error codes are defined by the Linux/i386 kernel. They are not yet documented.} -@comment errno.h -@comment Linux??? @deftypevr Macro int ERESTART +@standards{Linux???, errno.h} @errno{ERESTART, ???/85, Interrupted system call should be restarted} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ECHRNG +@standards{Linux???, errno.h} @errno{ECHRNG, ???/44, Channel number out of range} @end deftypevr -@comment errno.h -@comment Obsolete @deftypevr Macro int EL2NSYNC +@standards{Obsolete, errno.h} @errno{EL2NSYNC, ???/45, Level 2 not synchronized} @end deftypevr -@comment errno.h -@comment Obsolete @deftypevr Macro int EL3HLT +@standards{Obsolete, errno.h} @errno{EL3HLT, ???/46, Level 3 halted} @end deftypevr -@comment errno.h -@comment Obsolete @deftypevr Macro int EL3RST +@standards{Obsolete, errno.h} @errno{EL3RST, ???/47, Level 3 reset} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ELNRNG +@standards{Linux???, errno.h} @errno{ELNRNG, ???/48, Link number out of range} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EUNATCH +@standards{Linux???, errno.h} @errno{EUNATCH, ???/49, Protocol driver not attached} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ENOCSI +@standards{Linux???, errno.h} @errno{ENOCSI, ???/50, No CSI structure available} @end deftypevr -@comment errno.h -@comment Obsolete @deftypevr Macro int EL2HLT +@standards{Obsolete, errno.h} @errno{EL2HLT, ???/51, Level 2 halted} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EBADE +@standards{Linux???, errno.h} @errno{EBADE, ???/52, Invalid exchange} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EBADR +@standards{Linux???, errno.h} @errno{EBADR, ???/53, Invalid request descriptor} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EXFULL +@standards{Linux???, errno.h} @errno{EXFULL, ???/54, Exchange full} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ENOANO +@standards{Linux???, errno.h} @errno{ENOANO, ???/55, No anode} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EBADRQC +@standards{Linux???, errno.h} @errno{EBADRQC, ???/56, Invalid request code} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EBADSLT +@standards{Linux???, errno.h} @errno{EBADSLT, ???/57, Invalid slot} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EDEADLOCK +@standards{Linux???, errno.h} @errno{EDEADLOCK, ???/58, File locking deadlock error} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EBFONT +@standards{Linux???, errno.h} @errno{EBFONT, ???/59, Bad font file format} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ENONET +@standards{Linux???, errno.h} @errno{ENONET, ???/64, Machine is not on the network} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ENOPKG +@standards{Linux???, errno.h} @errno{ENOPKG, ???/65, Package not installed} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EADV +@standards{Linux???, errno.h} @errno{EADV, ???/68, Advertise error} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ESRMNT +@standards{Linux???, errno.h} @errno{ESRMNT, ???/69, Srmount error} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ECOMM +@standards{Linux???, errno.h} @errno{ECOMM, ???/70, Communication error on send} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EDOTDOT +@standards{Linux???, errno.h} @errno{EDOTDOT, ???/73, RFS specific error} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ENOTUNIQ +@standards{Linux???, errno.h} @errno{ENOTUNIQ, ???/76, Name not unique on network} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EBADFD +@standards{Linux???, errno.h} @errno{EBADFD, ???/77, File descriptor in bad state} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EREMCHG +@standards{Linux???, errno.h} @errno{EREMCHG, ???/78, Remote address changed} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ELIBACC +@standards{Linux???, errno.h} @errno{ELIBACC, ???/79, Can not access a needed shared library} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ELIBBAD +@standards{Linux???, errno.h} @errno{ELIBBAD, ???/80, Accessing a corrupted shared library} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ELIBSCN +@standards{Linux???, errno.h} @errno{ELIBSCN, ???/81, .lib section in a.out corrupted} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ELIBMAX +@standards{Linux???, errno.h} @errno{ELIBMAX, ???/82, Attempting to link in too many shared libraries} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ELIBEXEC +@standards{Linux???, errno.h} @errno{ELIBEXEC, ???/83, Cannot exec a shared library directly} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ESTRPIPE +@standards{Linux???, errno.h} @errno{ESTRPIPE, ???/86, Streams pipe error} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EUCLEAN +@standards{Linux???, errno.h} @errno{EUCLEAN, ???/117, Structure needs cleaning} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ENOTNAM +@standards{Linux???, errno.h} @errno{ENOTNAM, ???/118, Not a XENIX named type file} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ENAVAIL +@standards{Linux???, errno.h} @errno{ENAVAIL, ???/119, No XENIX semaphores available} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EISNAM +@standards{Linux???, errno.h} @errno{EISNAM, ???/120, Is a named type file} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EREMOTEIO +@standards{Linux???, errno.h} @errno{EREMOTEIO, ???/121, Remote I/O error} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int ENOMEDIUM +@standards{Linux???, errno.h} @errno{ENOMEDIUM, ???/???, No medium found} @end deftypevr -@comment errno.h -@comment Linux??? @deftypevr Macro int EMEDIUMTYPE +@standards{Linux???, errno.h} @errno{EMEDIUMTYPE, ???/???, Wrong medium type} @end deftypevr -@comment errno.h -@comment Linux @deftypevr Macro int ENOKEY +@standards{Linux, errno.h} @errno{ENOKEY, ???/???, Required key not available} @end deftypevr -@comment errno.h -@comment Linux @deftypevr Macro int EKEYEXPIRED +@standards{Linux, errno.h} @errno{EKEYEXPIRED, ???/???, Key has expired} @end deftypevr -@comment errno.h -@comment Linux @deftypevr Macro int EKEYREVOKED +@standards{Linux, errno.h} @errno{EKEYREVOKED, ???/???, Key has been revoked} @end deftypevr -@comment errno.h -@comment Linux @deftypevr Macro int EKEYREJECTED +@standards{Linux, errno.h} @errno{EKEYREJECTED, ???/???, Key was rejected by service} @end deftypevr -@comment errno.h -@comment Linux @deftypevr Macro int EOWNERDEAD +@standards{Linux, errno.h} @errno{EOWNERDEAD, ???/???, Owner died} @end deftypevr -@comment errno.h -@comment Linux @deftypevr Macro int ENOTRECOVERABLE +@standards{Linux, errno.h} @errno{ENOTRECOVERABLE, ???/???, State not recoverable} @end deftypevr -@comment errno.h -@comment Linux @deftypevr Macro int ERFKILL +@standards{Linux, errno.h} @errno{ERFKILL, ???/???, Operation not possible due to RF-kill} @end deftypevr -@comment errno.h -@comment Linux @deftypevr Macro int EHWPOISON +@standards{Linux, errno.h} @errno{EHWPOISON, ???/???, Memory page has hardware error} @end deftypevr @@ -1282,9 +1132,8 @@ for a given error code; the variable @w{@code{program_invocation_short_name}} gives you convenient access to the name of the program that encountered the error. -@comment string.h -@comment ISO @deftypefun {char *} strerror (int @var{errnum}) +@standards{ISO, string.h} @safety{@prelim{}@mtunsafe{@mtasurace{:strerror}}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{}}} @c Calls strerror_r with a static buffer allocated with malloc on the @c first use. @@ -1302,9 +1151,8 @@ overwritten. (But it's guaranteed that no library function ever calls The function @code{strerror} is declared in @file{string.h}. @end deftypefun -@comment string.h -@comment GNU @deftypefun {char *} strerror_r (int @var{errnum}, char *@var{buf}, size_t @var{n}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuintl{}}@acunsafe{}} The @code{strerror_r} function works like @code{strerror} but instead of returning the error message in a statically allocated buffer shared by @@ -1324,9 +1172,8 @@ The function @code{strerror_r} is a GNU extension and it is declared in @file{string.h}. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun void perror (const char *@var{message}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c Besides strerror_r's and some of fprintf's issues, if stderr is not @c oriented yet, create a new stream with a dup of stderr's fd and write @@ -1362,9 +1209,8 @@ You can find that name in the variable @code{program_invocation_short_name}; the full file name is stored the variable @code{program_invocation_name}. -@comment errno.h -@comment GNU @deftypevar {char *} program_invocation_name +@standards{GNU, errno.h} This variable's value is the name that was used to invoke the program running in the current process. It is the same as @code{argv[0]}. Note that this is not necessarily a useful file name; often it contains no @@ -1373,9 +1219,8 @@ directory names. @xref{Program Arguments}. This variable is a GNU extension and is declared in @file{errno.h}. @end deftypevar -@comment errno.h -@comment GNU @deftypevar {char *} program_invocation_short_name +@standards{GNU, errno.h} This variable's value is the name that was used to invoke the program running in the current process, with directory names removed. (That is to say, it is the same as @code{program_invocation_name} minus @@ -1442,9 +1287,8 @@ encountered while reading the file. For these occasions there are two functions available which are widely used throughout the GNU project. These functions are declared in @file{error.h}. -@comment error.h -@comment GNU @deftypefun void error (int @var{status}, int @var{errnum}, const char *@var{format}, @dots{}) +@standards{GNU, error.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acsafe{}} @c Cancellation is disabled throughout the execution. It flushes stdout @c and then holds a lock on stderr while printing the program name and @@ -1484,9 +1328,8 @@ the @var{status} value for its parameter and therefore never return. If incremented by one to keep track of the number of errors reported. @end deftypefun -@comment error.h -@comment GNU @deftypefun void error_at_line (int @var{status}, int @var{errnum}, const char *@var{fname}, unsigned int @var{lineno}, const char *@var{format}, @dots{}) +@standards{GNU, error.h} @safety{@prelim{}@mtunsafe{@mtasurace{:error_at_line/error_one_per_line} @mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acunsafe{@acucorrupt{/error_one_per_line}}} @c The error_one_per_line variable is accessed (without any form of @c synchronization, but since it's an int used once, it should be safe @@ -1525,9 +1368,8 @@ As mentioned above, the @code{error} and @code{error_at_line} functions can be customized by defining a variable named @code{error_print_progname}. -@comment error.h -@comment GNU @deftypevar {void (*error_print_progname)} (void) +@standards{GNU, error.h} If the @code{error_print_progname} variable is defined to a non-zero value the function pointed to is called by @code{error} or @code{error_at_line}. It is expected to print the program name or do @@ -1539,17 +1381,15 @@ must be able to handle whatever orientation the stream has. The variable is global and shared by all threads. @end deftypevar -@comment error.h -@comment GNU @deftypevar {unsigned int} error_message_count +@standards{GNU, error.h} The @code{error_message_count} variable is incremented whenever one of the functions @code{error} or @code{error_at_line} returns. The variable is global and shared by all threads. @end deftypevar -@comment error.h -@comment GNU @deftypevar int error_one_per_line +@standards{GNU, error.h} The @code{error_one_per_line} variable influences only @code{error_at_line}. Normally the @code{error_at_line} function creates output for every invocation. If @code{error_one_per_line} is @@ -1598,9 +1438,8 @@ are used in BSD for the same purpose. These functions are declared in @file{err.h}. It is generally advised to not use these functions. They are included only for compatibility. -@comment err.h -@comment BSD @deftypefun void warn (const char *@var{format}, @dots{}) +@standards{BSD, err.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c Just calls vwarn with the va_list. The @code{warn} function is roughly equivalent to a call like @@ -1612,9 +1451,8 @@ except that the global variables @code{error} respects and modifies are not used. @end deftypefun -@comment err.h -@comment BSD @deftypefun void vwarn (const char *@var{format}, va_list @var{ap}) +@standards{BSD, err.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c While holding stderr's recursive lock, it prints the programname, the @c given message, and the error string with fw?printf's %m. When the @@ -1625,9 +1463,8 @@ parameters for the handling of the format string @var{format} are passed in as a value of type @code{va_list}. @end deftypefun -@comment err.h -@comment BSD @deftypefun void warnx (const char *@var{format}, @dots{}) +@standards{BSD, err.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c Same as warn, but without the strerror translation issues. The @code{warnx} function is roughly equivalent to a call like @@ -1640,9 +1477,8 @@ are not used. The difference to @code{warn} is that no error number string is printed. @end deftypefun -@comment err.h -@comment BSD @deftypefun void vwarnx (const char *@var{format}, va_list @var{ap}) +@standards{BSD, err.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c Same as vwarn, but without the strerror translation issues. The @code{vwarnx} function is just like @code{warnx} except that the @@ -1650,9 +1486,8 @@ parameters for the handling of the format string @var{format} are passed in as a value of type @code{va_list}. @end deftypefun -@comment err.h -@comment BSD @deftypefun void err (int @var{status}, const char *@var{format}, @dots{}) +@standards{BSD, err.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c Same as warn followed by exit. The @code{err} function is roughly equivalent to a call like @@ -1664,9 +1499,8 @@ except that the global variables @code{error} respects and modifies are not used and that the program is exited even if @var{status} is zero. @end deftypefun -@comment err.h -@comment BSD @deftypefun void verr (int @var{status}, const char *@var{format}, va_list @var{ap}) +@standards{BSD, err.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c Same as vwarn followed by exit. The @code{verr} function is just like @code{err} except that the @@ -1674,9 +1508,8 @@ parameters for the handling of the format string @var{format} are passed in as a value of type @code{va_list}. @end deftypefun -@comment err.h -@comment BSD @deftypefun void errx (int @var{status}, const char *@var{format}, @dots{}) +@standards{BSD, err.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c Same as warnx followed by exit. The @code{errx} function is roughly equivalent to a call like @@ -1690,9 +1523,8 @@ is zero. The difference to @code{err} is that no error number string is printed. @end deftypefun -@comment err.h -@comment BSD @deftypefun void verrx (int @var{status}, const char *@var{format}, va_list @var{ap}) +@standards{BSD, err.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c Same as vwarnx followed by exit. The @code{verrx} function is just like @code{errx} except that the diff --git a/manual/filesys.texi b/manual/filesys.texi index e3fe323f47..5f7eb0e231 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -55,9 +55,8 @@ Prototypes for these functions are declared in the header file @file{unistd.h}. @pindex unistd.h -@comment unistd.h -@comment POSIX.1 @deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c If buffer is NULL, this function calls malloc and realloc, and, in @c case of error, free. Linux offers a getcwd syscall that we use on @@ -132,9 +131,8 @@ gnu_getcwd () not a library function but is a customary name used in most GNU software. -@comment unistd.h -@comment BSD @deftypefn {Deprecated Function} {char *} getwd (char *@var{buffer}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{} @acsfd{}}} @c Besides the getcwd safety issues, it calls strerror_r on error, which @c brings in all of the i18n issues. @@ -149,9 +147,8 @@ necessarily enough space to contain the directory name. That is why this function is deprecated. @end deftypefn -@comment unistd.h -@comment GNU @deftypefun {char *} get_current_dir_name (void) +@standards{GNU, unistd.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c Besides getcwd, which this function calls as a fallback, it calls @c getenv, with the potential thread-safety issues that brings about. @@ -167,9 +164,8 @@ therefore yield a different result. This function is a GNU extension. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int chdir (const char *@var{filename}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is used to set the process's working directory to @var{filename}. @@ -181,9 +177,8 @@ syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the file @var{filename} is not a directory. @end deftypefun -@comment unistd.h -@comment XPG @deftypefun int fchdir (int @var{filedes}) +@standards{XPG, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is used to set the process's working directory to directory associated with the file descriptor @var{filedes}. @@ -256,9 +251,8 @@ This section describes what you find in a single directory entry, as you might obtain it from a directory stream. All the symbols are declared in the header file @file{dirent.h}. -@comment dirent.h -@comment POSIX.1 @deftp {Data Type} {struct dirent} +@standards{POSIX.1, dirent.h} This is a structure type used to return information about directory entries. It contains the following fields: @@ -318,16 +312,14 @@ corresponds to the file type bits in the @code{st_mode} member of value is DT_UNKNOWN. These two macros convert between @code{d_type} values and @code{st_mode} values: -@comment dirent.h -@comment BSD @deftypefun int IFTODT (mode_t @var{mode}) +@standards{BSD, dirent.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This returns the @code{d_type} value corresponding to @var{mode}. @end deftypefun -@comment dirent.h -@comment BSD @deftypefun mode_t DTTOIF (int @var{dtype}) +@standards{BSD, dirent.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This returns the @code{st_mode} value corresponding to @var{dtype}. @end deftypefun @@ -357,9 +349,8 @@ Attributes}. This section describes how to open a directory stream. All the symbols are declared in the header file @file{dirent.h}. -@comment dirent.h -@comment POSIX.1 @deftp {Data Type} DIR +@standards{POSIX.1, dirent.h} The @code{DIR} data type represents a directory stream. @end deftp @@ -368,9 +359,8 @@ You shouldn't ever allocate objects of the @code{struct dirent} or you. Instead, you refer to these objects using the pointers returned by the following functions. -@comment dirent.h -@comment POSIX.1 @deftypefun {DIR *} opendir (const char *@var{dirname}) +@standards{POSIX.1, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c Besides the safe syscall, we have to allocate the DIR object with @c __alloc_dir, that calls malloc. @@ -410,9 +400,8 @@ Or the way @code{opendir} implicitly creates a file descriptor for the directory is not the way a program might want it. In these cases an alternative interface can be used. -@comment dirent.h -@comment GNU @deftypefun {DIR *} fdopendir (int @var{fd}) +@standards{GNU, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c The DIR object is allocated with __alloc_dir, that calls malloc. The @code{fdopendir} function works just like @code{opendir} but @@ -456,9 +445,8 @@ was exposed and programs could access the fields. This does not happen in @theglibc{}. Instead a separate function is provided to allow access. -@comment dirent.h -@comment GNU @deftypefun int dirfd (DIR *@var{dirstream}) +@standards{GNU, dirent.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{dirfd} returns the file descriptor associated with the directory stream @var{dirstream}. This descriptor can be used until @@ -475,9 +463,8 @@ This section describes how to read directory entries from a directory stream, and how to close the stream when you are done with it. All the symbols are declared in the header file @file{dirent.h}. -@comment dirent.h -@comment POSIX.1 @deftypefun {struct dirent *} readdir (DIR *@var{dirstream}) +@standards{POSIX.1, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c This function holds dirstream's non-recursive lock, which brings @c about the usual issues with locks and async signals and cancellation, @@ -527,9 +514,8 @@ has problems with very long filenames (see below). We recommend you use @code{readdir}, but do not share @code{DIR} objects. @end deftypefun -@comment dirent.h -@comment GNU @deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result}) +@standards{GNU, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} This function is a version of @code{readdir} which performs internal locking. Like @code{readdir} it returns the next entry from the @@ -600,9 +586,8 @@ Code to call @code{readdir_r} could look like this: To support large filesystems on 32-bit machines there are LFS variants of the last two functions. -@comment dirent.h -@comment LFS @deftypefun {struct dirent64 *} readdir64 (DIR *@var{dirstream}) +@standards{LFS, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} The @code{readdir64} function is just like the @code{readdir} function except that it returns a pointer to a record of type @code{struct @@ -612,9 +597,8 @@ might have a different size to allow large filesystems. In all other aspects this function is equivalent to @code{readdir}. @end deftypefun -@comment dirent.h -@comment LFS @deftypefun int readdir64_r (DIR *@var{dirstream}, struct dirent64 *@var{entry}, struct dirent64 **@var{result}) +@standards{LFS, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} The deprecated @code{readdir64_r} function is equivalent to the @code{readdir_r} function except that it takes parameters of base type @@ -623,9 +607,8 @@ third position. The same precautions mentioned in the documentation of @code{readdir_r} also apply here. @end deftypefun -@comment dirent.h -@comment POSIX.1 @deftypefun int closedir (DIR *@var{dirstream}) +@standards{POSIX.1, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@acsmem{} @acsfd{} @aculock{/hurd}}} @c No synchronization in the posix implementation, only in the hurd @c one. This is regarded as safe because it is undefined behavior if @@ -666,9 +649,8 @@ This section describes how to reread parts of a directory that you have already read from an open directory stream. All the symbols are declared in the header file @file{dirent.h}. -@comment dirent.h -@comment POSIX.1 @deftypefun void rewinddir (DIR *@var{dirstream}) +@standards{POSIX.1, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} The @code{rewinddir} function is used to reinitialize the directory stream @var{dirstream}, so that if you call @code{readdir} it @@ -680,9 +662,8 @@ added or removed since you last called @code{opendir} or @code{rewinddir}.) @end deftypefun -@comment dirent.h -@comment BSD @deftypefun {long int} telldir (DIR *@var{dirstream}) +@standards{BSD, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}} @c The implementation is safe on most platforms, but on BSD it uses @c cookies, buckets and records, and the global array of pointers to @@ -692,9 +673,8 @@ stream @var{dirstream}. You can use this value with @code{seekdir} to restore the directory stream to that position. @end deftypefun -@comment dirent.h -@comment BSD @deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos}) +@standards{BSD, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}} @c The implementation is safe on most platforms, but on BSD it uses @c cookies, buckets and records, and the global array of pointers to @@ -715,9 +695,9 @@ A higher-level interface to the directory handling functions is the entries in a directory, possibly sort them and get a list of names as the result. -@comment dirent.h -@comment BSD, SVID @deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const struct dirent **, const struct dirent **)) +@standards{BSD, dirent.h} +@standards{SVID, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c The scandir function calls __opendirat, __readdir, and __closedir to @c go over the named dir; malloc and realloc to allocate the namelist @@ -758,9 +738,9 @@ must be a pointer to a sorting function. For the convenience of the programmer @theglibc{} contains implementations of functions which are very helpful for this purpose. -@comment dirent.h -@comment BSD, SVID @deftypefun int alphasort (const struct dirent **@var{a}, const struct dirent **@var{b}) +@standards{BSD, dirent.h} +@standards{SVID, dirent.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c Calls strcoll. The @code{alphasort} function behaves like the @code{strcoll} function @@ -772,9 +752,8 @@ The return value of @code{alphasort} is less than, equal to, or greater than zero depending on the order of the two entries @var{a} and @var{b}. @end deftypefun -@comment dirent.h -@comment GNU @deftypefun int versionsort (const struct dirent **@var{a}, const struct dirent **@var{b}) +@standards{GNU, dirent.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c Calls strverscmp, which will accesses the locale object multiple @c times. @@ -787,9 +766,8 @@ anymore since the @code{dirent} structure might not able to contain all the information. The LFS provides the new type @w{@code{struct dirent64}}. To use this we need a new function. -@comment dirent.h -@comment GNU @deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const struct dirent64 **, const struct dirent64 **)) +@standards{GNU, dirent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c See scandir. The @code{scandir64} function works like the @code{scandir} function @@ -807,9 +785,8 @@ As @var{cmp} is now a function of a different type, the functions @code{alphasort} and @code{versionsort} cannot be supplied for that argument. Instead we provide the two replacement functions below. -@comment dirent.h -@comment GNU @deftypefun int alphasort64 (const struct dirent64 **@var{a}, const struct dirent **@var{b}) +@standards{GNU, dirent.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c See alphasort. The @code{alphasort64} function behaves like the @code{strcoll} function @@ -821,9 +798,8 @@ Return value of @code{alphasort64} is less than, equal to, or greater than zero depending on the order of the two entries @var{a} and @var{b}. @end deftypefun -@comment dirent.h -@comment GNU @deftypefun int versionsort64 (const struct dirent64 **@var{a}, const struct dirent64 **@var{b}) +@standards{GNU, dirent.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c See versionsort. The @code{versionsort64} function is like @code{alphasort64}, excepted that it @@ -871,9 +847,8 @@ their 64-bit counterparts @code{ftw64} and @code{nftw64}. These functions take as one of their arguments a pointer to a callback function of the appropriate type. -@comment ftw.h -@comment GNU @deftp {Data Type} __ftw_func_t +@standards{GNU, ftw.h} @smallexample int (*) (const char *, const struct stat *, int) @@ -917,9 +892,8 @@ type is in fact @code{__ftw64_func_t} since this mode changes For the LFS interface and for use in the function @code{ftw64}, the header @file{ftw.h} defines another function type. -@comment ftw.h -@comment GNU @deftp {Data Type} __ftw64_func_t +@standards{GNU, ftw.h} @smallexample int (*) (const char *, const struct stat64 *, int) @@ -931,9 +905,8 @@ parameter to the function is a pointer to a variable of type @code{struct stat64} which is able to represent the larger values. @end deftp -@comment ftw.h -@comment GNU @deftp {Data Type} __nftw_func_t +@standards{GNU, ftw.h} @smallexample int (*) (const char *, const struct stat *, int, struct FTW *) @@ -963,9 +936,8 @@ type is in fact @code{__nftw64_func_t} since this mode changes For the LFS interface there is also a variant of this data type available which has to be used with the @code{nftw64} function. -@comment ftw.h -@comment GNU @deftp {Data Type} __nftw64_func_t +@standards{GNU, ftw.h} @smallexample int (*) (const char *, const struct stat64 *, int, struct FTW *) @@ -977,9 +949,8 @@ parameter to the function is this time a pointer to a variable of type @code{struct stat64} which is able to represent the larger values. @end deftp -@comment ftw.h -@comment XPG4.2 @deftp {Data Type} {struct FTW} +@standards{XPG4.2, ftw.h} The information contained in this structure helps in interpreting the name parameter and gives some information about the current state of the traversal of the directory hierarchy. @@ -1001,9 +972,8 @@ file was passed). @end deftp -@comment ftw.h -@comment SVID @deftypefun int ftw (const char *@var{filename}, __ftw_func_t @var{func}, int @var{descriptors}) +@standards{SVID, ftw.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c see nftw for safety details The @code{ftw} function calls the callback function given in the @@ -1053,9 +1023,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a interface transparently replaces the old interface. @end deftypefun -@comment ftw.h -@comment Unix98 @deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors}) +@standards{Unix98, ftw.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} This function is similar to @code{ftw} but it can work on filesystems with large files. File information is reported using a variable of type @@ -1067,9 +1036,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a transparently replaces the old implementation. @end deftypefun -@comment ftw.h -@comment XPG4.2 @deftypefun int nftw (const char *@var{filename}, __nftw_func_t @var{func}, int @var{descriptors}, int @var{flag}) +@standards{XPG4.2, ftw.h} @safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}} @c ftw_startup calls alloca, malloc, free, xstat/lxstat, tdestroy, and ftw_dir @c if FTW_CHDIR, call open, and fchdir, or chdir and getcwd @@ -1138,9 +1106,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a interface transparently replaces the old interface. @end deftypefun -@comment ftw.h -@comment Unix98 @deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag}) +@standards{Unix98, ftw.h} @safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}} This function is similar to @code{nftw} but it can work on filesystems with large files. File information is reported using a variable of type @@ -1182,9 +1149,8 @@ The prototype for the @code{link} function is declared in the header file @file{unistd.h}. @pindex unistd.h -@comment unistd.h -@comment POSIX.1 @deftypefun int link (const char *@var{oldname}, const char *@var{newname}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{link} function makes a new link to the existing file named by @var{oldname}, under the new name @var{newname}. @@ -1274,9 +1240,8 @@ Some systems have, for some functions operating on files, a limit on how many symbolic links are followed when resolving a path name. The limit if it exists is published in the @file{sys/param.h} header file. -@comment sys/param.h -@comment BSD @deftypevr Macro int MAXSYMLINKS +@standards{BSD, sys/param.h} The macro @code{MAXSYMLINKS} specifies how many symlinks some function will follow before returning @code{ELOOP}. Not all functions behave the @@ -1290,9 +1255,8 @@ Prototypes for most of the functions listed in this section are in @file{unistd.h}. @pindex unistd.h -@comment unistd.h -@comment BSD @deftypefun int symlink (const char *@var{oldname}, const char *@var{newname}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{symlink} function makes a symbolic link to @var{oldname} named @var{newname}. @@ -1328,9 +1292,8 @@ exceeded. @end table @end deftypefun -@comment unistd.h -@comment BSD @deftypefun ssize_t readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{readlink} function gets the value of the symbolic link @var{filename}. The file name that the link points to is copied into @@ -1388,9 +1351,8 @@ and no filename in the path is @code{.} or @code{..}. This is for instance desirable if files have to be compared in which case different names can refer to the same inode. -@comment stdlib.h -@comment GNU @deftypefun {char *} canonicalize_file_name (const char *@var{name}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c Calls realpath. @@ -1431,9 +1393,8 @@ The Unix standard includes a similar function which differs from @code{canonicalize_file_name} in that the user has to provide the buffer where the result is placed in. -@comment stdlib.h -@comment XPG @deftypefun {char *} realpath (const char *restrict @var{name}, char *restrict @var{resolved}) +@standards{XPG, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c Calls malloc, realloc, getcwd, lxstat64, readlink, alloca. @@ -1472,9 +1433,8 @@ Deletion actually deletes a file name. If this is the file's only name, then the file is deleted as well. If the file has other remaining names (@pxref{Hard Links}), it remains accessible under those names. -@comment unistd.h -@comment POSIX.1 @deftypefun int unlink (const char *@var{filename}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{unlink} function deletes the file name @var{filename}. If this is a file's sole name, the file itself is also deleted. (Actually, @@ -1515,9 +1475,8 @@ file system and can't be modified. @end table @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int rmdir (const char *@var{filename}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @cindex directories, deleting @cindex deleting a directory @@ -1543,9 +1502,8 @@ The prototype for this function is declared in the header file @pindex unistd.h @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int remove (const char *@var{filename}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Calls unlink and rmdir. This is the @w{ISO C} function to remove a file. It works like @@ -1560,9 +1518,8 @@ This is the @w{ISO C} function to remove a file. It works like The @code{rename} function is used to change a file's name. @cindex renaming a file -@comment stdio.h -@comment ISO @deftypefun int rename (const char *@var{oldname}, const char *@var{newname}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c In the absence of a rename syscall, there's an emulation with link @c and unlink, but it's racy, even more so if newname exists and is @@ -1659,9 +1616,8 @@ Directories are created with the @code{mkdir} function. (There is also a shell command @code{mkdir} which does the same thing.) @c !!! umask -@comment sys/stat.h -@comment POSIX.1 @deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode}) +@standards{POSIX.1, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{mkdir} function creates a new, empty directory with name @var{filename}. @@ -1751,9 +1707,8 @@ The header file @file{sys/stat.h} declares all the symbols defined in this section. @pindex sys/stat.h -@comment sys/stat.h -@comment POSIX.1 @deftp {Data Type} {struct stat} +@standards{POSIX.1, sys/stat.h} The @code{stat} structure type is used to return information about the attributes of a file. It contains at least the following members: @@ -1847,9 +1802,8 @@ The extensions for the Large File Support (LFS) require, even on 32-bit machines, types which can handle file sizes up to @twoexp{63}. Therefore a new definition of @code{struct stat} is necessary. -@comment sys/stat.h -@comment LFS @deftp {Data Type} {struct stat64} +@standards{LFS, sys/stat.h} The members of this type are the same and have the same names as those in @code{struct stat}. The only difference is that the members @code{st_ino}, @code{st_size}, and @code{st_blocks} have a different @@ -1930,18 +1884,16 @@ integer types that you know and love.) These typedef names are defined in the header file @file{sys/types.h} as well as in @file{sys/stat.h}. Here is a list of them. -@comment sys/types.h -@comment POSIX.1 @deftp {Data Type} mode_t +@standards{POSIX.1, sys/types.h} This is an integer data type used to represent file modes. In @theglibc{}, this is an unsigned type no narrower than @code{unsigned int}. @end deftp @cindex inode number -@comment sys/types.h -@comment POSIX.1 @deftp {Data Type} ino_t +@standards{POSIX.1, sys/types.h} This is an unsigned integer type used to represent file serial numbers. (In Unix jargon, these are sometimes called @dfn{inode numbers}.) In @theglibc{}, this type is no narrower than @code{unsigned int}. @@ -1950,9 +1902,8 @@ If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type is transparently replaced by @code{ino64_t}. @end deftp -@comment sys/types.h -@comment Unix98 @deftp {Data Type} ino64_t +@standards{Unix98, sys/types.h} This is an unsigned integer type used to represent file serial numbers for the use in LFS. In @theglibc{}, this type is no narrower than @code{unsigned int}. @@ -1961,22 +1912,19 @@ When compiling with @code{_FILE_OFFSET_BITS == 64} this type is available under the name @code{ino_t}. @end deftp -@comment sys/types.h -@comment POSIX.1 @deftp {Data Type} dev_t +@standards{POSIX.1, sys/types.h} This is an arithmetic data type used to represent file device numbers. In @theglibc{}, this is an integer type no narrower than @code{int}. @end deftp -@comment sys/types.h -@comment POSIX.1 @deftp {Data Type} nlink_t +@standards{POSIX.1, sys/types.h} This is an integer type used to represent file link counts. @end deftp -@comment sys/types.h -@comment Unix98 @deftp {Data Type} blkcnt_t +@standards{Unix98, sys/types.h} This is a signed integer type used to represent block counts. In @theglibc{}, this type is no narrower than @code{int}. @@ -1984,9 +1932,8 @@ If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type is transparently replaced by @code{blkcnt64_t}. @end deftp -@comment sys/types.h -@comment Unix98 @deftp {Data Type} blkcnt64_t +@standards{Unix98, sys/types.h} This is a signed integer type used to represent block counts for the use in LFS. In @theglibc{}, this type is no narrower than @code{int}. @@ -2002,9 +1949,8 @@ To examine the attributes of files, use the functions @code{stat}, a @code{struct stat} object. All three functions are declared in the header file @file{sys/stat.h}. -@comment sys/stat.h -@comment POSIX.1 @deftypefun int stat (const char *@var{filename}, struct stat *@var{buf}) +@standards{POSIX.1, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{stat} function returns information about the attributes of the file named by @w{@var{filename}} in the structure pointed to by @var{buf}. @@ -2029,9 +1975,8 @@ function is in fact @code{stat64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment sys/stat.h -@comment Unix98 @deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf}) +@standards{Unix98, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{stat} but it is also able to work on files larger than @twoexp{31} bytes on 32-bit systems. To be able to do @@ -2043,9 +1988,8 @@ function is available under the name @code{stat} and so transparently replaces the interface for small files on 32-bit machines. @end deftypefun -@comment sys/stat.h -@comment POSIX.1 @deftypefun int fstat (int @var{filedes}, struct stat *@var{buf}) +@standards{POSIX.1, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fstat} function is like @code{stat}, except that it takes an open file descriptor as an argument instead of a file name. @@ -2065,9 +2009,8 @@ function is in fact @code{fstat64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment sys/stat.h -@comment Unix98 @deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf}) +@standards{Unix98, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{fstat} but is able to work on large files on 32-bit platforms. For large files the file descriptor @@ -2084,9 +2027,8 @@ replaces the interface for small files on 32-bit machines. @c available. @c @safety{@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -@comment sys/stat.h -@comment BSD @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf}) +@standards{BSD, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct system call through lxstat, sometimes with an xstat conv call @c afterwards. @@ -2100,9 +2042,8 @@ function is in fact @code{lstat64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment sys/stat.h -@comment Unix98 @deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf}) +@standards{Unix98, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct system call through lxstat64, sometimes with an xstat conv @c call afterwards. @@ -2141,55 +2082,48 @@ The following predicate macros test the type of a file, given the value @var{m} which is the @code{st_mode} field returned by @code{stat} on that file: -@comment sys/stat.h -@comment POSIX @deftypefn Macro int S_ISDIR (mode_t @var{m}) +@standards{POSIX, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a directory. @end deftypefn -@comment sys/stat.h -@comment POSIX @deftypefn Macro int S_ISCHR (mode_t @var{m}) +@standards{POSIX, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a character special file (a device like a terminal). @end deftypefn -@comment sys/stat.h -@comment POSIX @deftypefn Macro int S_ISBLK (mode_t @var{m}) +@standards{POSIX, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a block special file (a device like a disk). @end deftypefn -@comment sys/stat.h -@comment POSIX @deftypefn Macro int S_ISREG (mode_t @var{m}) +@standards{POSIX, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a regular file. @end deftypefn -@comment sys/stat.h -@comment POSIX @deftypefn Macro int S_ISFIFO (mode_t @var{m}) +@standards{POSIX, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a FIFO special file, or a pipe. @xref{Pipes and FIFOs}. @end deftypefn -@comment sys/stat.h -@comment GNU @deftypefn Macro int S_ISLNK (mode_t @var{m}) +@standards{GNU, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a symbolic link. @xref{Symbolic Links}. @end deftypefn -@comment sys/stat.h -@comment GNU @deftypefn Macro int S_ISSOCK (mode_t @var{m}) +@standards{GNU, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a socket. @xref{Sockets}. @end deftypefn @@ -2210,48 +2144,40 @@ is equivalent to: ((@var{mode} & S_IFMT) == S_IFCHR) @end smallexample -@comment sys/stat.h -@comment BSD @deftypevr Macro int S_IFMT +@standards{BSD, sys/stat.h} This is a bit mask used to extract the file type code from a mode value. @end deftypevr These are the symbolic names for the different file type codes: @vtable @code -@comment sys/stat.h -@comment BSD @item S_IFDIR +@standards{BSD, sys/stat.h} This is the file type constant of a directory file. -@comment sys/stat.h -@comment BSD @item S_IFCHR +@standards{BSD, sys/stat.h} This is the file type constant of a character-oriented device file. -@comment sys/stat.h -@comment BSD @item S_IFBLK +@standards{BSD, sys/stat.h} This is the file type constant of a block-oriented device file. -@comment sys/stat.h -@comment BSD @item S_IFREG +@standards{BSD, sys/stat.h} This is the file type constant of a regular file. -@comment sys/stat.h -@comment BSD @item S_IFLNK +@standards{BSD, sys/stat.h} This is the file type constant of a symbolic link. -@comment sys/stat.h -@comment BSD @item S_IFSOCK +@standards{BSD, sys/stat.h} This is the file type constant of a socket. -@comment sys/stat.h -@comment BSD @item S_IFIFO +@standards{BSD, sys/stat.h} This is the file type constant of a FIFO or pipe. @end vtable @@ -2263,27 +2189,24 @@ macros. But unlike the other macros they do not take the value of the @code{st_mode} field as the parameter. Instead they expect a pointer to the whole @code{struct stat} structure. -@comment sys/stat.h -@comment POSIX @deftypefn Macro int S_TYPEISMQ (struct stat *@var{s}) +@standards{POSIX, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If the system implements POSIX message queues as distinct objects and the file is a message queue object, this macro returns a non-zero value. In all other cases the result is zero. @end deftypefn -@comment sys/stat.h -@comment POSIX @deftypefn Macro int S_TYPEISSEM (struct stat *@var{s}) +@standards{POSIX, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If the system implements POSIX semaphores as distinct objects and the file is a semaphore object, this macro returns a non-zero value. In all other cases the result is zero. @end deftypefn -@comment sys/stat.h -@comment POSIX @deftypefn Macro int S_TYPEISSHM (struct stat *@var{s}) +@standards{POSIX, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If the system implements POSIX shared memory objects as distinct objects and the file is a shared memory object, this macro returns a non-zero @@ -2326,9 +2249,8 @@ and @code{chgrp} shell commands. @pindex unistd.h The prototype for this function is declared in @file{unistd.h}. -@comment unistd.h -@comment POSIX.1 @deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{chown} function changes the owner of the file @var{filename} to @var{owner}, and its group owner to @var{group}. @@ -2361,9 +2283,8 @@ The file is on a read-only file system. @end table @end deftypefun -@comment unistd.h -@comment BSD @deftypefun int fchown (int @var{filedes}, uid_t @var{owner}, gid_t @var{group}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{chown}, except that it changes the owner of the open file with descriptor @var{filedes}. @@ -2407,97 +2328,79 @@ These symbolic constants are defined for the file mode bits that control access permission for the file: @vtable @code -@comment sys/stat.h -@comment POSIX.1 @item S_IRUSR -@comment sys/stat.h -@comment BSD @itemx S_IREAD +@standards{POSIX.1, sys/stat.h} +@standardsx{S_IREAD, BSD, sys/stat.h} Read permission bit for the owner of the file. On many systems this bit is 0400. @code{S_IREAD} is an obsolete synonym provided for BSD compatibility. -@comment sys/stat.h -@comment POSIX.1 @item S_IWUSR -@comment sys/stat.h -@comment BSD @itemx S_IWRITE +@standards{POSIX.1, sys/stat.h} +@standardsx{S_IWRITE, BSD, sys/stat.h} Write permission bit for the owner of the file. Usually 0200. @w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility. -@comment sys/stat.h -@comment POSIX.1 @item S_IXUSR -@comment sys/stat.h -@comment BSD @itemx S_IEXEC +@standards{POSIX.1, sys/stat.h} +@standardsx{S_IEXEC, BSD, sys/stat.h} Execute (for ordinary files) or search (for directories) permission bit for the owner of the file. Usually 0100. @code{S_IEXEC} is an obsolete synonym provided for BSD compatibility. -@comment sys/stat.h -@comment POSIX.1 @item S_IRWXU +@standards{POSIX.1, sys/stat.h} This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}. -@comment sys/stat.h -@comment POSIX.1 @item S_IRGRP +@standards{POSIX.1, sys/stat.h} Read permission bit for the group owner of the file. Usually 040. -@comment sys/stat.h -@comment POSIX.1 @item S_IWGRP +@standards{POSIX.1, sys/stat.h} Write permission bit for the group owner of the file. Usually 020. -@comment sys/stat.h -@comment POSIX.1 @item S_IXGRP +@standards{POSIX.1, sys/stat.h} Execute or search permission bit for the group owner of the file. Usually 010. -@comment sys/stat.h -@comment POSIX.1 @item S_IRWXG +@standards{POSIX.1, sys/stat.h} This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}. -@comment sys/stat.h -@comment POSIX.1 @item S_IROTH +@standards{POSIX.1, sys/stat.h} Read permission bit for other users. Usually 04. -@comment sys/stat.h -@comment POSIX.1 @item S_IWOTH +@standards{POSIX.1, sys/stat.h} Write permission bit for other users. Usually 02. -@comment sys/stat.h -@comment POSIX.1 @item S_IXOTH +@standards{POSIX.1, sys/stat.h} Execute or search permission bit for other users. Usually 01. -@comment sys/stat.h -@comment POSIX.1 @item S_IRWXO +@standards{POSIX.1, sys/stat.h} This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}. -@comment sys/stat.h -@comment POSIX @item S_ISUID +@standards{POSIX, sys/stat.h} This is the set-user-ID on execute bit, usually 04000. @xref{How Change Persona}. -@comment sys/stat.h -@comment POSIX @item S_ISGID +@standards{POSIX, sys/stat.h} This is the set-group-ID on execute bit, usually 02000. @xref{How Change Persona}. @cindex sticky bit -@comment sys/stat.h -@comment BSD @item S_ISVTX +@standards{BSD, sys/stat.h} This is the @dfn{sticky} bit, usually 01000. For a directory it gives permission to delete a file in that directory @@ -2624,9 +2527,8 @@ changing the umask is usually done only by shells. They use the The functions in this section are declared in @file{sys/stat.h}. @pindex sys/stat.h -@comment sys/stat.h -@comment POSIX.1 @deftypefun mode_t umask (mode_t @var{mask}) +@standards{POSIX.1, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{umask} function sets the file creation mask of the current process to @var{mask}, and returns the previous value of the file @@ -2650,18 +2552,16 @@ However, on @gnuhurdsystems{} it is better to use @code{getumask} if you just want to read the mask value, because it is reentrant. @end deftypefun -@comment sys/stat.h -@comment GNU @deftypefun mode_t getumask (void) +@standards{GNU, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Return the current value of the file creation mask for the current process. This function is a GNU extension and is only available on @gnuhurdsystems{}. @end deftypefun -@comment sys/stat.h -@comment POSIX.1 @deftypefun int chmod (const char *@var{filename}, mode_t @var{mode}) +@standards{POSIX.1, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{chmod} function sets the access permission bits for the file named by @var{filename} to @var{mode}. @@ -2700,9 +2600,8 @@ for full details on the sticky bit. @end table @end deftypefun -@comment sys/stat.h -@comment BSD @deftypefun int fchmod (int @var{filedes}, mode_t @var{mode}) +@standards{BSD, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{chmod}, except that it changes the permissions of the currently open file given by @var{filedes}. @@ -2771,9 +2670,8 @@ real ID. @pindex unistd.h The symbols in this section are declared in @file{unistd.h}. -@comment unistd.h -@comment POSIX.1 @deftypefun int access (const char *@var{filename}, int @var{how}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{access} function checks to see whether the file named by @var{filename} can be accessed in the way specified by the @var{how} @@ -2812,27 +2710,23 @@ as the @var{how} argument to the @code{access} function. The values are integer constants. @pindex unistd.h -@comment unistd.h -@comment POSIX.1 @deftypevr Macro int R_OK +@standards{POSIX.1, unistd.h} Flag meaning test for read permission. @end deftypevr -@comment unistd.h -@comment POSIX.1 @deftypevr Macro int W_OK +@standards{POSIX.1, unistd.h} Flag meaning test for write permission. @end deftypevr -@comment unistd.h -@comment POSIX.1 @deftypevr Macro int X_OK +@standards{POSIX.1, unistd.h} Flag meaning test for execute/search permission. @end deftypevr -@comment unistd.h -@comment POSIX.1 @deftypevr Macro int F_OK +@standards{POSIX.1, unistd.h} Flag meaning test for existence of the file. @end deftypevr @@ -2876,9 +2770,8 @@ the @code{utime} function---all except the attribute change time. You need to include the header file @file{utime.h} to use this facility. @pindex utime.h -@comment utime.h -@comment POSIX.1 @deftp {Data Type} {struct utimbuf} +@standards{POSIX.1, utime.h} The @code{utimbuf} structure is used with the @code{utime} function to specify new access and modification times for a file. It contains the following members: @@ -2892,9 +2785,8 @@ This is the modification time for the file. @end table @end deftp -@comment utime.h -@comment POSIX.1 @deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times}) +@standards{POSIX.1, utime.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c In the absence of a utime syscall, it non-atomically converts times @c to a struct timeval and calls utimes. @@ -2946,9 +2838,8 @@ the fractional part of the file times. The prototype for this function is in the header file @file{sys/time.h}. @pindex sys/time.h -@comment sys/time.h -@comment BSD @deftypefun int utimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]}) +@standards{BSD, sys/time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c In the absence of a utimes syscall, it non-atomically converts tvp @c to struct timespec array and issues a utimensat syscall, or to @@ -2964,9 +2855,8 @@ The return values and error conditions are the same as for the @code{utime} function. @end deftypefun -@comment sys/time.h -@comment BSD @deftypefun int lutimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]}) +@standards{BSD, sys/time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Since there's no lutimes syscall, it non-atomically converts tvp @c to struct timespec array and issues a utimensat syscall. @@ -2983,9 +2873,8 @@ The return values and error conditions are the same as for the @code{utime} function. @end deftypefun -@comment sys/time.h -@comment BSD @deftypefun int futimes (int @var{fd}, const struct timeval @var{tvp}@t{[2]}) +@standards{BSD, sys/time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Since there's no futimes syscall, it non-atomically converts tvp @c to struct timespec array and issues a utimensat syscall, falling back @@ -3041,9 +2930,8 @@ Using these functions on anything other than a regular file gives @emph{undefined} results. On many systems, such a call will appear to succeed, without actually accomplishing anything. -@comment unistd.h -@comment X/Open @deftypefun int truncate (const char *@var{filename}, off_t @var{length}) +@standards{X/Open, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c In the absence of a truncate syscall, we use open and ftruncate. @@ -3087,9 +2975,8 @@ The operation was interrupted by a signal. @end deftypefun -@comment unistd.h -@comment Unix98 @deftypefun int truncate64 (const char *@var{name}, off64_t @var{length}) +@standards{Unix98, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c In the absence of a syscall, try truncate if length fits. This function is similar to the @code{truncate} function. The @@ -3102,9 +2989,8 @@ When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a @code{truncate} and so transparently replaces the 32 bits interface. @end deftypefun -@comment unistd.h -@comment POSIX @deftypefun int ftruncate (int @var{fd}, off_t @var{length}) +@standards{POSIX, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{truncate}, but it works on a file descriptor @var{fd} @@ -3167,9 +3053,8 @@ The operation was interrupted by a signal. @end deftypefun -@comment unistd.h -@comment Unix98 @deftypefun int ftruncate64 (int @var{id}, off64_t @var{length}) +@standards{Unix98, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c In the absence of a syscall, try ftruncate if length fits. This function is similar to the @code{ftruncate} function. The @@ -3328,9 +3213,8 @@ this function for compatibility with BSD. The prototype for @code{mknod} is declared in @file{sys/stat.h}. @pindex sys/stat.h -@comment sys/stat.h -@comment BSD @deftypefun int mknod (const char *@var{filename}, mode_t @var{mode}, dev_t @var{dev}) +@standards{BSD, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Instead of issuing the syscall directly, we go through xmknod. @c Although the internal xmknod takes a dev_t*, that could lead to @@ -3383,9 +3267,8 @@ returns a pointer to a static buffer. These facilities are declared in the header file @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftypefun {FILE *} tmpfile (void) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} @c The unsafety issues are those of fdopen, plus @acsfd because of the @c open. @@ -3413,9 +3296,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a interface transparently replaces the old interface. @end deftypefun -@comment stdio.h -@comment Unix98 @deftypefun {FILE *} tmpfile64 (void) +@standards{Unix98, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} This function is similar to @code{tmpfile}, but the stream it returns a pointer to was opened using @code{tmpfile64}. Therefore this stream can @@ -3429,9 +3311,8 @@ bits machine this function is available under the name @code{tmpfile} and so transparently replaces the old interface. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun {char *} tmpnam (char *@var{result}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtunsafe{@mtasurace{:tmpnam/!result}}@asunsafe{}@acsafe{}} @c The passed-in buffer should not be modified concurrently with the @c call. @@ -3458,9 +3339,8 @@ opening the file you should use the @code{O_EXCL} flag. Using @code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun {char *} tmpnam_r (char *@var{result}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is nearly identical to the @code{tmpnam} function, except that if @var{result} is a null pointer it returns a null pointer. @@ -3472,17 +3352,15 @@ This guarantees reentrancy because the non-reentrant situation of @code{tmpnam}. @end deftypefun -@comment stdio.h -@comment ISO @deftypevr Macro int L_tmpnam +@standards{ISO, stdio.h} The value of this macro is an integer constant expression that represents the minimum size of a string large enough to hold a file name generated by the @code{tmpnam} function. @end deftypevr -@comment stdio.h -@comment ISO @deftypevr Macro int TMP_MAX +@standards{ISO, stdio.h} The macro @code{TMP_MAX} is a lower bound for how many temporary names you can create with @code{tmpnam}. You can rely on being able to call @code{tmpnam} at least this many times before it might fail saying you @@ -3495,9 +3373,8 @@ a fixed, small limit on the number of temporary files. The limit is never less than @code{25}. @end deftypevr -@comment stdio.h -@comment SVID @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix}) +@standards{SVID, stdio.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c There's no way (short of being setuid) to avoid getenv("TMPDIR"), @c even with a non-NULL dir. @@ -3544,9 +3421,8 @@ opening the file you should use the @code{O_EXCL} flag. Using @cindex TMPDIR environment variable @c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not?? -@comment stdio.h -@comment SVID @deftypevr {SVID Macro} {char *} P_tmpdir +@standards{SVID, stdio.h} This macro is the name of the default directory for temporary files. @end deftypevr @@ -3565,9 +3441,8 @@ would crash when @code{mktemp} or @code{mkstemp} tried to modify the string. These functions are declared in the header file @file{stdlib.h}. @pindex stdlib.h -@comment stdlib.h -@comment Unix @deftypefun {char *} mktemp (char *@var{template}) +@standards{Unix, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c __gen_tempname (caller tmpl, __GT_NOCREATE) ok The @code{mktemp} function generates a unique file name by modifying @@ -3585,9 +3460,8 @@ opening the file you should use the @code{O_EXCL} flag. Using @code{mkstemp} is a safe way to avoid this problem. @end deftypefun -@comment stdlib.h -@comment BSD @deftypefun int mkstemp (char *@var{template}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} @c __gen_tempname (caller tmpl, __GT_FILE) ok The @code{mkstemp} function generates a unique file name just as @@ -3609,9 +3483,8 @@ create a temporary file. This is because it works by calling @code{open} with the @code{O_EXCL} flag, which says you want to create a new file and get an error if the file already exists. -@comment stdlib.h -@comment BSD @deftypefun {char *} mkdtemp (char *@var{template}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c __gen_tempname (caller tmpl, __GT_DIR) ok The @code{mkdtemp} function creates a directory with a unique name. If diff --git a/manual/getopt.texi b/manual/getopt.texi index a71c3731aa..5485fc4694 100644 --- a/manual/getopt.texi +++ b/manual/getopt.texi @@ -20,9 +20,8 @@ use this facility, your program must include the header file @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 @@ -31,18 +30,16 @@ does not print any messages, but it still returns the character @code{?} 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 @@ -50,16 +47,14 @@ where the remaining non-option arguments begin. The initial value of 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 *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 @@ -207,9 +202,8 @@ declared in @file{getopt.h}, not @file{unistd.h}. You should make every 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 @@ -241,9 +235,8 @@ was seen. @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}). @@ -296,9 +289,8 @@ 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. diff --git a/manual/header.texi b/manual/header.texi index 2a551cd6e1..ce661df43b 100644 --- a/manual/header.texi +++ b/manual/header.texi @@ -14,7 +14,7 @@ it. @end iftex @table @code @comment summary.texi is generated from the other Texinfo files. -@comment See the Makefile and summary.awk for the details. +@comment See the Makefile and summary.pl for the details. @include summary.texi @end table @iftex diff --git a/manual/job.texi b/manual/job.texi index 72b55997d2..944967a73d 100644 --- a/manual/job.texi +++ b/manual/job.texi @@ -1036,9 +1036,8 @@ The function @code{ctermid} is declared in the header file @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment POSIX.1 @deftypefun {char *} ctermid (char *@var{string}) +@standards{POSIX.1, stdio.h} @safety{@prelim{}@mtsafe{@mtsposix{/!string}}@assafe{}@acsafe{}} @c This function is a stub by default; the actual implementation, for @c posix systems, returns a pointer to a string literal if passed a NULL @@ -1057,9 +1056,8 @@ any reason. Even if a file name is returned, access to the file it represents is not guaranteed. @end deftypefun -@comment stdio.h -@comment POSIX.1 @deftypevr Macro int L_ctermid +@standards{POSIX.1, stdio.h} The value of this macro is an integer constant expression that represents the size of a string large enough to hold the file name returned by @code{ctermid}. @@ -1078,9 +1076,8 @@ Your program should include the header files @file{sys/types.h} and @pindex unistd.h @pindex sys/types.h -@comment unistd.h -@comment POSIX.1 @deftypefun pid_t setsid (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is usually a direct syscall, but if a syscall is not available, @c we use a stub, or Hurd- and BSD-specific implementations. The former @@ -1107,9 +1104,8 @@ already another process group around that has the same process group ID. @end table @end deftypefun -@comment unistd.h -@comment SVID @deftypefun pid_t getsid (pid_t @var{pid}) +@standards{SVID, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Stub or direct syscall, except on hurd, where it is equally safe. @@ -1132,17 +1128,15 @@ from the calling process. @end table @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun pid_t getpgrp (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getpgrp} function returns the process group ID of the calling process. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int getpgid (pid_t @var{pid}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Stub or direct syscall, except on hurd, where it is equally safe. @@ -1164,9 +1158,8 @@ process. @end table @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int setpgid (pid_t @var{pid}, pid_t @var{pgid}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Stub or direct syscall, except on hurd, where it is equally safe. The @code{setpgid} function puts the process @var{pid} into the process @@ -1203,9 +1196,8 @@ process or a child of the calling process. @end table @end deftypefun -@comment unistd.h -@comment BSD @deftypefun int setpgrp (pid_t @var{pid}, pid_t @var{pgid}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall or setpgid wrapper. This is the BSD Unix name for @code{setpgid}. Both functions do exactly @@ -1227,9 +1219,8 @@ Although these functions take a file descriptor argument to specify the terminal device, the foreground job is associated with the terminal file itself and not a particular open file descriptor. -@comment unistd.h -@comment POSIX.1 @deftypefun pid_t tcgetpgrp (int @var{filedes}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Stub, or ioctl on BSD and GNU/Linux. This function returns the process group ID of the foreground process @@ -1257,9 +1248,8 @@ controlling terminal of the calling process. @end table @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int tcsetpgrp (int @var{filedes}, pid_t @var{pgid}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Stub, or ioctl on BSD and GNU/Linux. This function is used to set a terminal's foreground process group ID. @@ -1298,9 +1288,8 @@ process. @end table @end deftypefun -@comment termios.h -@comment Unix98 @deftypefun pid_t tcgetsid (int @var{fildes}) +@standards{Unix98, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Ioctl call, if available, or tcgetpgrp followed by getsid. This function is used to obtain the process group ID of the session diff --git a/manual/lang.texi b/manual/lang.texi index a151c9b690..cacbdfb7c5 100644 --- a/manual/lang.texi +++ b/manual/lang.texi @@ -48,9 +48,8 @@ checking is good no matter who is running the program. A wise user would rather have a program crash, visibly, than have it return nonsense without indicating anything might be wrong. -@comment assert.h -@comment ISO @deftypefn Macro void assert (int @var{expression}) +@standards{ISO, assert.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} @c assert_fail_base calls asprintf, and fflushes stderr. Verify the programmer's belief that @var{expression} is nonzero at @@ -90,9 +89,8 @@ return from an operating system function. Then it is useful to display not only where the program crashes, but also what error was returned. The @code{assert_perror} macro makes this easy. -@comment assert.h -@comment GNU @deftypefn Macro void assert_perror (int @var{errnum}) +@standards{GNU, assert.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} @c assert_fail_base calls asprintf, and fflushes stderr. Similar to @code{assert}, but verifies that @var{errnum} is zero. @@ -418,15 +416,13 @@ Here are descriptions of the macros used to retrieve variable arguments. These macros are defined in the header file @file{stdarg.h}. @pindex stdarg.h -@comment stdarg.h -@comment ISO @deftp {Data Type} va_list +@standards{ISO, stdarg.h} The type @code{va_list} is used for argument pointer variables. @end deftp -@comment stdarg.h -@comment ISO @deftypefn {Macro} void va_start (va_list @var{ap}, @var{last-required}) +@standards{ISO, stdarg.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is no longer provided by glibc, but rather by the compiler. This macro initializes the argument pointer variable @var{ap} to point @@ -434,9 +430,8 @@ to the first of the optional arguments of the current function; @var{last-required} must be the last required argument to the function. @end deftypefn -@comment stdarg.h -@comment ISO @deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type}) +@standards{ISO, stdarg.h} @safety{@prelim{}@mtsafe{@mtsrace{:ap}}@assafe{}@acunsafe{@acucorrupt{}}} @c This is no longer provided by glibc, but rather by the compiler. @c Unlike the other va_ macros, that either start/end the lifetime of @@ -453,9 +448,8 @@ specified in the call. @var{type} must be a self-promoting type (not of the actual argument. @end deftypefn -@comment stdarg.h -@comment ISO @deftypefn {Macro} void va_end (va_list @var{ap}) +@standards{ISO, stdarg.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is no longer provided by glibc, but rather by the compiler. This ends the use of @var{ap}. After a @code{va_end} call, further @@ -475,10 +469,9 @@ argument. But @code{va_list} is an opaque type and one cannot necessarily assign the value of one variable of type @code{va_list} to another variable of the same type. -@comment stdarg.h -@comment ISO @deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src}) @deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src}) +@standardsx{va_copy, ISO, stdarg.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is no longer provided by glibc, but rather by the compiler. The @code{va_copy} macro allows copying of objects of type @@ -536,9 +529,8 @@ You can assign it to any pointer variable since it has type @code{void *}. The preferred way to write a null pointer constant is with @code{NULL}. -@comment stddef.h -@comment ISO @deftypevr Macro {void *} NULL +@standards{ISO, stddef.h} This is a null pointer constant. @end deftypevr @@ -565,9 +557,8 @@ them in a portable fashion. They are defined in the header file @file{stddef.h}. @pindex stddef.h -@comment stddef.h -@comment ISO @deftp {Data Type} ptrdiff_t +@standards{ISO, stddef.h} This is the signed integer type of the result of subtracting two pointers. For example, with the declaration @code{char *p1, *p2;}, the expression @code{p2 - p1} is of type @code{ptrdiff_t}. This will @@ -576,9 +567,8 @@ int}}, @code{int} or @w{@code{long int}}), but might be a nonstandard type that exists only for this purpose. @end deftp -@comment stddef.h -@comment ISO @deftp {Data Type} size_t +@standards{ISO, stddef.h} This is an unsigned integer type used to represent the sizes of objects. The result of the @code{sizeof} operator is of this type, and functions such as @code{malloc} (@pxref{Unconstrained Allocation}) and @@ -639,9 +629,8 @@ bits in an integer data type. But you can compute it from the macro @code{CHAR_BIT}, defined in the header file @file{limits.h}. @table @code -@comment limits.h -@comment ISO @item CHAR_BIT +@standards{ISO, limits.h} This is the number of bits in a @code{char}---eight, on most systems. The value has type @code{int}. @@ -662,39 +651,18 @@ preprocessor directives, whereas @code{sizeof} cannot. The following macros are defined in @file{limits.h}. @vtable @code -@comment limits.h -@comment ISO @item CHAR_WIDTH -@comment limits.h -@comment ISO @itemx SCHAR_WIDTH -@comment limits.h -@comment ISO @itemx UCHAR_WIDTH -@comment limits.h -@comment ISO @itemx SHRT_WIDTH -@comment limits.h -@comment ISO @itemx USHRT_WIDTH -@comment limits.h -@comment ISO @itemx INT_WIDTH -@comment limits.h -@comment ISO @itemx UINT_WIDTH -@comment limits.h -@comment ISO @itemx LONG_WIDTH -@comment limits.h -@comment ISO @itemx ULONG_WIDTH -@comment limits.h -@comment ISO @itemx LLONG_WIDTH -@comment limits.h -@comment ISO @itemx ULLONG_WIDTH +@standards{ISO, limits.h} These are the widths of the types @code{char}, @code{signed char}, @code{unsigned char}, @code{short int}, @code{unsigned short int}, @@ -708,27 +676,14 @@ for types specified by width (@pxref{Integers}), the following are defined. @vtable @code -@comment stdint.h -@comment ISO @item INTPTR_WIDTH -@comment stdint.h -@comment ISO @itemx UINTPTR_WIDTH -@comment stdint.h -@comment ISO @itemx PTRDIFF_WIDTH -@comment stdint.h -@comment ISO @itemx SIG_ATOMIC_WIDTH -@comment stdint.h -@comment ISO @itemx SIZE_WIDTH -@comment stdint.h -@comment ISO @itemx WCHAR_WIDTH -@comment stdint.h -@comment ISO @itemx WINT_WIDTH +@standards{ISO, stdint.h} These are the widths of the types @code{intptr_t}, @code{uintptr_t}, @code{ptrdiff_t}, @code{sig_atomic_t}, @code{size_t}, @code{wchar_t} @@ -761,128 +716,100 @@ described by the macro---thus, @code{ULONG_MAX} has type @comment Extra blank lines make it look better. @vtable @code -@comment limits.h -@comment ISO @item SCHAR_MIN +@standards{ISO, limits.h} This is the minimum value that can be represented by a @w{@code{signed char}}. -@comment limits.h -@comment ISO @item SCHAR_MAX -@comment limits.h -@comment ISO @itemx UCHAR_MAX +@standards{ISO, limits.h} These are the maximum values that can be represented by a @w{@code{signed char}} and @w{@code{unsigned char}}, respectively. -@comment limits.h -@comment ISO @item CHAR_MIN +@standards{ISO, limits.h} This is the minimum value that can be represented by a @code{char}. It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero otherwise. -@comment limits.h -@comment ISO @item CHAR_MAX +@standards{ISO, limits.h} This is the maximum value that can be represented by a @code{char}. It's equal to @code{SCHAR_MAX} if @code{char} is signed, or @code{UCHAR_MAX} otherwise. -@comment limits.h -@comment ISO @item SHRT_MIN +@standards{ISO, limits.h} This is the minimum value that can be represented by a @w{@code{signed short int}}. On most machines that @theglibc{} runs on, @code{short} integers are 16-bit quantities. -@comment limits.h -@comment ISO @item SHRT_MAX -@comment limits.h -@comment ISO @itemx USHRT_MAX +@standards{ISO, limits.h} These are the maximum values that can be represented by a @w{@code{signed short int}} and @w{@code{unsigned short int}}, respectively. -@comment limits.h -@comment ISO @item INT_MIN +@standards{ISO, limits.h} This is the minimum value that can be represented by a @w{@code{signed int}}. On most machines that @theglibc{} runs on, an @code{int} is a 32-bit quantity. -@comment limits.h -@comment ISO @item INT_MAX -@comment limits.h -@comment ISO @itemx UINT_MAX +@standards{ISO, limits.h} These are the maximum values that can be represented by, respectively, the type @w{@code{signed int}} and the type @w{@code{unsigned int}}. -@comment limits.h -@comment ISO @item LONG_MIN +@standards{ISO, limits.h} This is the minimum value that can be represented by a @w{@code{signed long int}}. On most machines that @theglibc{} runs on, @code{long} integers are 32-bit quantities, the same size as @code{int}. -@comment limits.h -@comment ISO @item LONG_MAX -@comment limits.h -@comment ISO @itemx ULONG_MAX +@standards{ISO, limits.h} These are the maximum values that can be represented by a @w{@code{signed long int}} and @code{unsigned long int}, respectively. -@comment limits.h -@comment ISO @item LLONG_MIN +@standards{ISO, limits.h} This is the minimum value that can be represented by a @w{@code{signed long long int}}. On most machines that @theglibc{} runs on, @w{@code{long long}} integers are 64-bit quantities. -@comment limits.h -@comment ISO @item LLONG_MAX -@comment limits.h -@comment ISO @itemx ULLONG_MAX +@standards{ISO, limits.h} These are the maximum values that can be represented by a @code{signed long long int} and @code{unsigned long long int}, respectively. -@comment limits.h -@comment GNU @item LONG_LONG_MIN -@comment limits.h -@comment GNU @itemx LONG_LONG_MAX -@comment limits.h -@comment GNU @itemx ULONG_LONG_MAX +@standards{GNU, limits.h} These are obsolete names for @code{LLONG_MIN}, @code{LLONG_MAX}, and @code{ULLONG_MAX}. They are only available if @code{_GNU_SOURCE} is defined (@pxref{Feature Test Macros}). In GCC versions prior to 3.0, these were the only names available. -@comment limits.h -@comment GNU @item WCHAR_MAX +@standards{GNU, limits.h} This is the maximum value that can be represented by a @code{wchar_t}. @xref{Extended Char Intro}. @@ -1041,9 +968,8 @@ target machine is suitable. In practice, all the machines currently supported are suitable. @vtable @code -@comment float.h -@comment ISO @item FLT_ROUNDS +@standards{ISO, float.h} This value characterizes the rounding mode for floating point addition. The following values indicate standard rounding modes: @@ -1081,17 +1007,15 @@ the IEEE single-precision standard. -1.00000007 -1.0 -1.00000012 -1.0 -1.00000012 @end smallexample -@comment float.h -@comment ISO @item FLT_RADIX +@standards{ISO, float.h} This is the value of the base, or radix, of the exponent representation. This is guaranteed to be a constant expression, unlike the other macros described in this section. The value is 2 on all machines we know of except the IBM 360 and derivatives. -@comment float.h -@comment ISO @item FLT_MANT_DIG +@standards{ISO, float.h} This is the number of base-@code{FLT_RADIX} digits in the floating point mantissa for the @code{float} data type. The following expression yields @code{1.0} (even though mathematically it should not) due to the @@ -1106,18 +1030,16 @@ float radix = FLT_RADIX; @noindent where @code{radix} appears @code{FLT_MANT_DIG} times. -@comment float.h -@comment ISO @item DBL_MANT_DIG @itemx LDBL_MANT_DIG +@standardsx{DBL_MANT_DIG, ISO, float.h} This is the number of base-@code{FLT_RADIX} digits in the floating point mantissa for the data types @code{double} and @code{long double}, respectively. @comment Extra blank lines make it look better. -@comment float.h -@comment ISO @item FLT_DIG +@standards{ISO, float.h} This is the number of decimal digits of precision for the @code{float} data type. Technically, if @var{p} and @var{b} are the precision and @@ -1130,77 +1052,67 @@ change to the @var{q} decimal digits. The value of this macro is supposed to be at least @code{6}, to satisfy @w{ISO C}. -@comment float.h -@comment ISO @item DBL_DIG @itemx LDBL_DIG +@standardsx{DBL_DIG, ISO, float.h} These are similar to @code{FLT_DIG}, but for the data types @code{double} and @code{long double}, respectively. The values of these macros are supposed to be at least @code{10}. -@comment float.h -@comment ISO @item FLT_MIN_EXP +@standards{ISO, float.h} This is the smallest possible exponent value for type @code{float}. More precisely, it is the minimum negative integer such that the value @code{FLT_RADIX} raised to this power minus 1 can be represented as a normalized floating point number of type @code{float}. -@comment float.h -@comment ISO @item DBL_MIN_EXP @itemx LDBL_MIN_EXP +@standardsx{DBL_MIN_EXP, ISO, float.h} These are similar to @code{FLT_MIN_EXP}, but for the data types @code{double} and @code{long double}, respectively. -@comment float.h -@comment ISO @item FLT_MIN_10_EXP +@standards{ISO, float.h} This is the minimum negative integer such that @code{10} raised to this power minus 1 can be represented as a normalized floating point number of type @code{float}. This is supposed to be @code{-37} or even less. -@comment float.h -@comment ISO @item DBL_MIN_10_EXP @itemx LDBL_MIN_10_EXP +@standardsx{DBL_MIN_10_EXP, ISO, float.h} These are similar to @code{FLT_MIN_10_EXP}, but for the data types @code{double} and @code{long double}, respectively. -@comment float.h -@comment ISO @item FLT_MAX_EXP +@standards{ISO, float.h} This is the largest possible exponent value for type @code{float}. More precisely, this is the maximum positive integer such that value @code{FLT_RADIX} raised to this power minus 1 can be represented as a floating point number of type @code{float}. -@comment float.h -@comment ISO @item DBL_MAX_EXP @itemx LDBL_MAX_EXP +@standardsx{DBL_MAX_EXP, ISO, float.h} These are similar to @code{FLT_MAX_EXP}, but for the data types @code{double} and @code{long double}, respectively. -@comment float.h -@comment ISO @item FLT_MAX_10_EXP +@standards{ISO, float.h} This is the maximum positive integer such that @code{10} raised to this power minus 1 can be represented as a normalized floating point number of type @code{float}. This is supposed to be at least @code{37}. -@comment float.h -@comment ISO @item DBL_MAX_10_EXP @itemx LDBL_MAX_10_EXP +@standardsx{DBL_MAX_10_EXP, ISO, float.h} These are similar to @code{FLT_MAX_10_EXP}, but for the data types @code{double} and @code{long double}, respectively. -@comment float.h -@comment ISO @item FLT_MAX +@standards{ISO, float.h} The value of this macro is the maximum number representable in type @code{float}. It is supposed to be at least @code{1E+37}. The value @@ -1208,44 +1120,39 @@ has type @code{float}. The smallest representable number is @code{- FLT_MAX}. -@comment float.h -@comment ISO @item DBL_MAX @itemx LDBL_MAX +@standardsx{DBL_MAX, ISO, float.h} These are similar to @code{FLT_MAX}, but for the data types @code{double} and @code{long double}, respectively. The type of the macro's value is the same as the type it describes. -@comment float.h -@comment ISO @item FLT_MIN +@standards{ISO, float.h} The value of this macro is the minimum normalized positive floating point number that is representable in type @code{float}. It is supposed to be no more than @code{1E-37}. -@comment float.h -@comment ISO @item DBL_MIN @itemx LDBL_MIN +@standardsx{DBL_MIN, ISO, float.h} These are similar to @code{FLT_MIN}, but for the data types @code{double} and @code{long double}, respectively. The type of the macro's value is the same as the type it describes. -@comment float.h -@comment ISO @item FLT_EPSILON +@standards{ISO, float.h} This is the difference between 1 and the smallest floating point number of type @code{float} that is greater than 1. It's supposed to be no greater than @code{1E-5}. -@comment float.h -@comment ISO @item DBL_EPSILON @itemx LDBL_EPSILON +@standardsx{DBL_EPSILON, ISO, float.h} These are similar to @code{FLT_EPSILON}, but for the data types @code{double} and @code{long double}, respectively. The type of the @@ -1306,9 +1213,8 @@ DBL_EPSILON 2.2204460492503131E-016 You can use @code{offsetof} to measure the location within a structure type of a particular structure member. -@comment stddef.h -@comment ISO @deftypefn {Macro} size_t offsetof (@var{type}, @var{member}) +@standards{ISO, stddef.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is no longer provided by glibc, but rather by the compiler. This expands to an integer constant expression that is the offset of the diff --git a/manual/llio.texi b/manual/llio.texi index 8d18509d45..ba1f455dfd 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -79,9 +79,8 @@ declared in @file{unistd.h}. @pindex unistd.h @pindex fcntl.h -@comment fcntl.h -@comment POSIX.1 @deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}]) +@standards{POSIX.1, fcntl.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} The @code{open} function creates and returns a new file descriptor for the file named by @var{filename}. Initially, the file position @@ -166,9 +165,8 @@ The @code{open} function is the underlying primitive for the @code{fopen} and @code{freopen} functions, that create streams. @end deftypefun -@comment fcntl.h -@comment Unix98 @deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}]) +@standards{Unix98, fcntl.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function is similar to @code{open}. It returns a file descriptor which can be used to access the file named by @var{filename}. The only @@ -181,9 +179,8 @@ new, extended API using 64 bit file sizes and offsets transparently replaces the old API. @end deftypefun -@comment fcntl.h -@comment POSIX.1 @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode}) +@standards{POSIX.1, fcntl.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function is obsolete. The call: @@ -206,9 +203,8 @@ functions to use files up to @twoexp{63} in size and offset from since all of the low-level file handling functions are equally replaced. @end deftypefn -@comment fcntl.h -@comment Unix98 @deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode}) +@standards{Unix98, fcntl.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function is similar to @code{creat}. It returns a file descriptor which can be used to access the file named by @var{filename}. The only @@ -224,9 +220,8 @@ new, extended API using 64 bit file sizes and offsets transparently replaces the old API. @end deftypefn -@comment unistd.h -@comment POSIX.1 @deftypefun int close (int @var{filedes}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} The function @code{close} closes the file descriptor @var{filedes}. Closing a file has the following consequences: @@ -297,18 +292,16 @@ output operations on file descriptors: @code{read}, @code{write}, and @file{unistd.h}. @pindex unistd.h -@comment unistd.h -@comment POSIX.1 @deftp {Data Type} ssize_t +@standards{POSIX.1, unistd.h} This data type is used to represent the sizes of blocks that can be read or written in a single operation. It is similar to @code{size_t}, but must be a signed type. @end deftp @cindex reading from a file descriptor -@comment unistd.h -@comment POSIX.1 @deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{read} function reads up to @var{size} bytes from the file with descriptor @var{filedes}, storing the results in the @var{buffer}. @@ -402,9 +395,8 @@ The @code{read} function is the underlying primitive for all of the functions that read from streams, such as @code{fgetc}. @end deftypefun -@comment unistd.h -@comment Unix98 @deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset}) +@standards{Unix98, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is usually a safe syscall. The sysdeps/posix fallback emulation @c is not MT-Safe because it uses lseek, read and lseek back, but is it @@ -441,9 +433,8 @@ The function is an extension defined in the Unix Single Specification version 2. @end deftypefun -@comment unistd.h -@comment Unix98 @deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset}) +@standards{Unix98, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is usually a safe syscall. The sysdeps/posix fallback emulation @c is not MT-Safe because it uses lseek64, read and lseek64 back, but is @@ -462,9 +453,8 @@ When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a @end deftypefun @cindex writing to a file descriptor -@comment unistd.h -@comment POSIX.1 @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Some say write is thread-unsafe on Linux without O_APPEND. In the VFS layer @c the vfs_write() does no locking around the acquisition of a file offset and @@ -603,9 +593,8 @@ The @code{write} function is the underlying primitive for all of the functions that write to streams, such as @code{fputc}. @end deftypefun -@comment unistd.h -@comment Unix98 @deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset}) +@standards{Unix98, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is usually a safe syscall. The sysdeps/posix fallback emulation @c is not MT-Safe because it uses lseek, write and lseek back, but is it @@ -646,9 +635,8 @@ The function is an extension defined in the Unix Single Specification version 2. @end deftypefun -@comment unistd.h -@comment Unix98 @deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset}) +@standards{Unix98, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is usually a safe syscall. The sysdeps/posix fallback emulation @c is not MT-Safe because it uses lseek64, write and lseek64 back, but @@ -666,9 +654,8 @@ When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a @code{pwrite} and so transparently replaces the 32 bit interface. @end deftypefun -@comment sys/uio.h -@comment BSD @deftypefun ssize_t preadv (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}) +@standards{BSD, sys/uio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is a syscall for Linux 3.2 for all architectures but microblaze @c (which was added on 3.15). The sysdeps/posix fallback emulation @@ -691,9 +678,8 @@ indicating end-of-file, or @math{-1} indicating an error. The possible errors are the same as in @code{readv} and @code{pread}. @end deftypefun -@comment unistd.h -@comment BSD @deftypefun ssize_t preadv64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is a syscall for Linux 3.2 for all architectures but microblaze @c (which was added on 3.15). The sysdeps/posix fallback emulation @@ -713,9 +699,8 @@ When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a @code{preadv} and so transparently replaces the 32 bit interface. @end deftypefun -@comment sys/uio.h -@comment BSD @deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}) +@standards{BSD, sys/uio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is a syscall for Linux 3.2 for all architectures but microblaze @c (which was added on 3.15). The sysdeps/posix fallback emulation @@ -742,9 +727,8 @@ indicating end-of-file, or @math{-1} indicating an error. The possible errors are the same as in @code{writev} and @code{pwrite}. @end deftypefun -@comment unistd.h -@comment BSD @deftypefun ssize_t pwritev64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is a syscall for Linux 3.2 for all architectures but microblaze @c (which was added on 3.15). The sysdeps/posix fallback emulation @@ -764,9 +748,8 @@ When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a @code{pwritev} and so transparently replaces the 32 bit interface. @end deftypefun -@comment sys/uio.h -@comment GNU @deftypefun ssize_t preadv2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags}) +@standards{GNU, sys/uio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation @c is also MT-Safe since it calls preadv. @@ -810,9 +793,8 @@ An unsupported @var{flags} was used. @end deftypefun -@comment unistd.h -@comment GNU @deftypefun ssize_t preadv64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags}) +@standards{GNU, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation @c is also MT-Safe since it calls preadv. @@ -831,9 +813,8 @@ When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a @end deftypefun -@comment sys/uio.h -@comment GNU @deftypefun ssize_t pwritev2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags}) +@standards{GNU, sys/uio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation @c is also MT-Safe since it calls pwritev. @@ -853,9 +834,8 @@ indicating end-of-file, or @math{-1} indicating an error. The possible errors are the same as in @code{preadv2}. @end deftypefun -@comment unistd.h -@comment GNU @deftypefun ssize_t pwritev64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags}) +@standards{GNU, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation @c is also MT-Safe since it calls pwritev. @@ -889,9 +869,8 @@ To read the current file position value from a descriptor, use @cindex file positioning on a file descriptor @cindex positioning a file descriptor @cindex seeking on a file descriptor -@comment unistd.h -@comment POSIX.1 @deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{lseek} function is used to change the file position of the file with descriptor @var{filedes}. @@ -979,9 +958,8 @@ The @code{lseek} function is the underlying primitive for the descriptors. @end deftypefun -@comment unistd.h -@comment Unix98 @deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence}) +@standards{Unix98, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to the @code{lseek} function. The difference is that the @var{offset} parameter is of type @code{off64_t} instead of @@ -1043,9 +1021,8 @@ will read four characters starting with the 1024'th character of @file{foo}, and then four more characters starting with the 1028'th character. -@comment sys/types.h -@comment POSIX.1 @deftp {Data Type} off_t +@standards{POSIX.1, sys/types.h} This is a signed integer type used to represent file sizes. In @theglibc{}, this type is no narrower than @code{int}. @@ -1053,9 +1030,8 @@ If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type is transparently replaced by @code{off64_t}. @end deftp -@comment sys/types.h -@comment Unix98 @deftp {Data Type} off64_t +@standards{Unix98, sys/types.h} This type is used similar to @code{off_t}. The difference is that even on 32 bit machines, where the @code{off_t} type would have 32 bits, @code{off64_t} has 64 bits and so is able to address files up to @@ -1092,9 +1068,8 @@ an existing stream with the @code{fileno} function. These functions are declared in the header file @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment POSIX.1 @deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype}) +@standards{POSIX.1, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} The @code{fdopen} function returns a new stream for the file descriptor @var{filedes}. @@ -1121,9 +1096,8 @@ for file descriptors do not permit the access specified by For an example showing the use of the @code{fdopen} function, see @ref{Creating a Pipe}. -@comment stdio.h -@comment POSIX.1 @deftypefun int fileno (FILE *@var{stream}) +@standards{POSIX.1, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns the file descriptor associated with the stream @var{stream}. If an error is detected (for example, if the @var{stream} @@ -1131,9 +1105,8 @@ is not valid) or if @var{stream} does not do I/O to a file, @code{fileno} returns @math{-1}. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun int fileno_unlocked (FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fileno_unlocked} function is equivalent to the @code{fileno} function except that it does not implicitly lock the stream if the state @@ -1150,23 +1123,20 @@ file descriptors belonging to the standard streams @code{stdin}, @pindex unistd.h @vtable @code -@comment unistd.h -@comment POSIX.1 @item STDIN_FILENO +@standards{POSIX.1, unistd.h} This macro has value @code{0}, which is the file descriptor for standard input. @cindex standard input file descriptor -@comment unistd.h -@comment POSIX.1 @item STDOUT_FILENO +@standards{POSIX.1, unistd.h} This macro has value @code{1}, which is the file descriptor for standard output. @cindex standard output file descriptor -@comment unistd.h -@comment POSIX.1 @item STDERR_FILENO +@standards{POSIX.1, unistd.h} This macro has value @code{2}, which is the file descriptor for standard error output. @end vtable @@ -1321,9 +1291,8 @@ primitives, so they are not a portability threat. They are defined in These functions are controlled with arrays of @code{iovec} structures, which describe the location and size of each buffer. -@comment sys/uio.h -@comment BSD @deftp {Data Type} {struct iovec} +@standards{BSD, sys/uio.h} The @code{iovec} structure describes a buffer. It contains two fields: @@ -1338,9 +1307,8 @@ Contains the length of the buffer. @end table @end deftp -@comment sys/uio.h -@comment BSD @deftypefun ssize_t readv (int @var{filedes}, const struct iovec *@var{vector}, int @var{count}) +@standards{BSD, sys/uio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c The fallback sysdeps/posix implementation, used even on GNU/Linux @c with old kernels that lack a full readv/writev implementation, may @@ -1361,9 +1329,8 @@ errors are the same as in @code{read}. @end deftypefun -@comment sys/uio.h -@comment BSD @deftypefun ssize_t writev (int @var{filedes}, const struct iovec *@var{vector}, int @var{count}) +@standards{BSD, sys/uio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c The fallback sysdeps/posix implementation, used even on GNU/Linux @c with old kernels that lack a full readv/writev implementation, may @@ -1426,9 +1393,8 @@ size_t page_size = (size_t) sysconf (_SC_PAGESIZE); @noindent These functions are declared in @file{sys/mman.h}. -@comment sys/mman.h -@comment POSIX @deftypefun {void *} mmap (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset}) +@standards{POSIX, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{mmap} function creates a new mapping, connected to bytes @@ -1546,9 +1512,8 @@ The file is on a filesystem that doesn't support mapping. @end deftypefun -@comment sys/mman.h -@comment LFS @deftypefun {void *} mmap64 (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off64_t @var{offset}) +@standards{LFS, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c The page_shift auto detection when MMAP2_PAGE_SHIFT is -1 (it never @c is) would be thread-unsafe. @@ -1565,9 +1530,8 @@ new, extended API using 64 bit file sizes and offsets transparently replaces the old API. @end deftypefun -@comment sys/mman.h -@comment POSIX @deftypefun int munmap (void *@var{addr}, size_t @var{length}) +@standards{POSIX, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} + @@ -1592,9 +1556,8 @@ aligned. @end deftypefun -@comment sys/mman.h -@comment POSIX @deftypefun int msync (void *@var{address}, size_t @var{length}, int @var{flags}) +@standards{POSIX, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} When using shared mappings, the kernel can write the file at any time @@ -1640,9 +1603,8 @@ There is no existing mapping in at least part of the given region. @end deftypefun -@comment sys/mman.h -@comment GNU @deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag}) +@standards{GNU, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function can be used to change the size of an existing memory @@ -1689,9 +1651,8 @@ not support mapping at all. Thus, programs using @code{mmap} should have a fallback method to use should it fail. @xref{Mmap,,,standards,GNU Coding Standards}. -@comment sys/mman.h -@comment POSIX @deftypefun int madvise (void *@var{addr}, size_t @var{length}, int @var{advice}) +@standards{POSIX, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function can be used to provide the system with @var{advice} about @@ -1759,9 +1720,8 @@ There is no existing mapping in at least part of the given region. @end table @end deftypefun -@comment sys/mman.h -@comment POSIX @deftypefn Function int shm_open (const char *@var{name}, int @var{oflag}, mode_t @var{mode}) +@standards{POSIX, sys/mman.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c shm_open @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd @c libc_once(where_is_shmfs) @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd @@ -1848,16 +1808,14 @@ The file descriptor sets for the @code{select} function are specified as @code{fd_set} objects. Here is the description of the data type and some macros for manipulating these objects. -@comment sys/types.h -@comment BSD @deftp {Data Type} fd_set +@standards{BSD, sys/types.h} The @code{fd_set} data type represents file descriptor sets for the @code{select} function. It is actually a bit array. @end deftp -@comment sys/types.h -@comment BSD @deftypevr Macro int FD_SETSIZE +@standards{BSD, sys/types.h} The value of this macro is the maximum number of file descriptors that a @code{fd_set} object can hold information about. On systems with a fixed maximum number, @code{FD_SETSIZE} is at least that number. On @@ -1868,17 +1826,15 @@ descriptor with a value as high as @code{FD_SETSIZE}, you cannot put that descriptor into an @code{fd_set}. @end deftypevr -@comment sys/types.h -@comment BSD @deftypefn Macro void FD_ZERO (fd_set *@var{set}) +@standards{BSD, sys/types.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} This macro initializes the file descriptor set @var{set} to be the empty set. @end deftypefn -@comment sys/types.h -@comment BSD @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set}) +@standards{BSD, sys/types.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} @c Setting a bit isn't necessarily atomic, so there's a potential race @c here if set is not used exclusively. @@ -1888,9 +1844,8 @@ The @var{filedes} parameter must not have side effects since it is evaluated more than once. @end deftypefn -@comment sys/types.h -@comment BSD @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set}) +@standards{BSD, sys/types.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} @c Setting a bit isn't necessarily atomic, so there's a potential race @c here if set is not used exclusively. @@ -1900,9 +1855,8 @@ The @var{filedes} parameter must not have side effects since it is evaluated more than once. @end deftypefn -@comment sys/types.h -@comment BSD @deftypefn Macro int FD_ISSET (int @var{filedes}, const fd_set *@var{set}) +@standards{BSD, sys/types.h} @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} This macro returns a nonzero value (true) if @var{filedes} is a member of the file descriptor set @var{set}, and zero (false) otherwise. @@ -1913,9 +1867,8 @@ evaluated more than once. Next, here is the description of the @code{select} function itself. -@comment sys/types.h -@comment BSD @deftypefun int select (int @var{nfds}, fd_set *@var{read-fds}, fd_set *@var{write-fds}, fd_set *@var{except-fds}, struct timeval *@var{timeout}) +@standards{BSD, sys/types.h} @safety{@prelim{}@mtsafe{@mtsrace{:read-fds} @mtsrace{:write-fds} @mtsrace{:except-fds}}@assafe{}@acsafe{}} @c The select syscall is preferred, but pselect6 may be used instead, @c which requires converting timeout to a timespec and back. The @@ -2019,9 +1972,8 @@ In situations where synchronization points are necessary, you can use special functions which ensure that all operations finish before they return. -@comment unistd.h -@comment X/Open @deftypefun void sync (void) +@standards{X/Open, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} A call to this function will not return as long as there is data which has not been written to the device. All dirty buffers in the kernel will @@ -2035,9 +1987,8 @@ Programs more often want to ensure that data written to a given file is committed, rather than all data in the system. For this, @code{sync} is overkill. -@comment unistd.h -@comment POSIX @deftypefun int fsync (int @var{fildes}) +@standards{POSIX, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fsync} function can be used to make sure all data associated with the open file @var{fildes} is written to the device associated with the @@ -2073,9 +2024,8 @@ Meta-information, like the modification time etc., are not that important and leaving such information uncommitted does not prevent a successful recovery of the file in case of a problem. -@comment unistd.h -@comment POSIX @deftypefun int fdatasync (int @var{fildes}) +@standards{POSIX, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} When a call to the @code{fdatasync} function returns, it is ensured that all of the file data is written to the device. For all pending I/O @@ -2124,9 +2074,8 @@ asynchronous I/O operations are controlled using a data structure named @code{struct aiocb} (@dfn{AIO control block}). It is defined in @file{aio.h} as follows. -@comment aio.h -@comment POSIX.1b @deftp {Data Type} {struct aiocb} +@standards{POSIX.1b, aio.h} The POSIX.1b standard mandates that the @code{struct aiocb} structure contains at least the members described in the following table. There might be more elements which are used by the implementation, but @@ -2207,9 +2156,8 @@ defined which replaces the types of the appropriate members with larger types but otherwise is equivalent to @code{struct aiocb}. Particularly, all member names are the same. -@comment aio.h -@comment POSIX.1b @deftp {Data Type} {struct aiocb64} +@standards{POSIX.1b, aio.h} @table @code @item int aio_fildes This element specifies the file descriptor which is used for the @@ -2275,9 +2223,8 @@ aiocb64}, since the LFS transparently replaces the old interface. @node Asynchronous Reads/Writes @subsection Asynchronous Read and Write Operations -@comment aio.h -@comment POSIX.1b @deftypefun int aio_read (struct aiocb *@var{aiocbp}) +@standards{POSIX.1b, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} @c Calls aio_enqueue_request. @c aio_enqueue_request @asulock @ascuheap @aculock @acsmem @@ -2492,9 +2439,8 @@ function is in fact @code{aio_read64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment aio.h -@comment Unix98 @deftypefun int aio_read64 (struct aiocb64 *@var{aiocbp}) +@standards{Unix98, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to the @code{aio_read} function. The only difference is that on @w{32 bit} machines, the file descriptor should @@ -2511,9 +2457,8 @@ replaces the interface for small files on 32 bit machines. To write data asynchronously to a file, there exists an equivalent pair of functions with a very similar interface. -@comment aio.h -@comment POSIX.1b @deftypefun int aio_write (struct aiocb *@var{aiocbp}) +@standards{POSIX.1b, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function initiates an asynchronous write operation. The function call immediately returns after the operation was enqueued or if before @@ -2578,9 +2523,8 @@ function is in fact @code{aio_write64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment aio.h -@comment Unix98 @deftypefun int aio_write64 (struct aiocb64 *@var{aiocbp}) +@standards{Unix98, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to the @code{aio_write} function. The only difference is that on @w{32 bit} machines the file descriptor should @@ -2600,9 +2544,8 @@ operation at a time, and which can handle freely mixed read and write operations. It is therefore similar to a combination of @code{readv} and @code{writev}. -@comment aio.h -@comment POSIX.1b @deftypefun int lio_listio (int @var{mode}, struct aiocb *const @var{list}[], int @var{nent}, struct sigevent *@var{sig}) +@standards{POSIX.1b, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} @c Call lio_listio_internal, that takes the aio_requests_mutex lock and @c enqueues each request. Then, it waits for notification or prepares @@ -2689,9 +2632,8 @@ function is in fact @code{lio_listio64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment aio.h -@comment Unix98 @deftypefun int lio_listio64 (int @var{mode}, struct aiocb64 *const @var{list}[], int @var{nent}, struct sigevent *@var{sig}) +@standards{Unix98, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to the @code{lio_listio} function. The only difference is that on @w{32 bit} machines, the file descriptor should @@ -2718,9 +2660,8 @@ mode is @code{LIO_NOWAIT}), one sometimes needs to know whether a specific request already terminated and if so, what the result was. The following two functions allow you to get this kind of information. -@comment aio.h -@comment POSIX.1b @deftypefun int aio_error (const struct aiocb *@var{aiocbp}) +@standards{POSIX.1b, aio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function determines the error state of the request described by the @code{struct aiocb} variable pointed to by @var{aiocbp}. If the @@ -2740,9 +2681,8 @@ function is in fact @code{aio_error64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment aio.h -@comment Unix98 @deftypefun int aio_error64 (const struct aiocb64 *@var{aiocbp}) +@standards{Unix98, aio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{aio_error} with the only difference that the argument is a reference to a variable of type @code{struct @@ -2754,9 +2694,8 @@ transparently replaces the interface for small files on 32 bit machines. @end deftypefun -@comment aio.h -@comment POSIX.1b @deftypefun ssize_t aio_return (struct aiocb *@var{aiocbp}) +@standards{POSIX.1b, aio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function can be used to retrieve the return status of the operation carried out by the request described in the variable pointed to by @@ -2778,9 +2717,8 @@ function is in fact @code{aio_return64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment aio.h -@comment Unix98 @deftypefun ssize_t aio_return64 (struct aiocb64 *@var{aiocbp}) +@standards{Unix98, aio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{aio_return} with the only difference that the argument is a reference to a variable of type @code{struct @@ -2807,9 +2745,8 @@ The @code{aio_fsync} and @code{aio_fsync64} functions are only available if the symbol @code{_POSIX_SYNCHRONIZED_IO} is defined in @file{unistd.h}. @cindex synchronizing -@comment aio.h -@comment POSIX.1b @deftypefun int aio_fsync (int @var{op}, struct aiocb *@var{aiocbp}) +@standards{POSIX.1b, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} @c After fcntl to check that the FD is open, it calls @c aio_enqueue_request. @@ -2857,9 +2794,8 @@ function is in fact @code{aio_fsync64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment aio.h -@comment Unix98 @deftypefun int aio_fsync64 (int @var{op}, struct aiocb64 *@var{aiocbp}) +@standards{Unix98, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to @code{aio_fsync} with the only difference that the argument is a reference to a variable of type @code{struct @@ -2884,9 +2820,8 @@ interrupted by a notification since the new client will not be handled before the current client is served. For situations like this @code{aio_suspend} should be used. -@comment aio.h -@comment POSIX.1b @deftypefun int aio_suspend (const struct aiocb *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout}) +@standards{POSIX.1b, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c Take aio_requests_mutex, set up waitlist and requestlist, wait @c for completion or timeout, and release the mutex. @@ -2925,9 +2860,8 @@ function is in fact @code{aio_suspend64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment aio.h -@comment Unix98 @deftypefun int aio_suspend64 (const struct aiocb64 *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout}) +@standards{Unix98, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} This function is similar to @code{aio_suspend} with the only difference that the argument is a reference to a variable of type @code{struct @@ -2953,9 +2887,8 @@ is not capable of forcing the cancellation of the request. It is up to the implementation to decide whether it is possible to cancel the operation or not. Therefore using this function is merely a hint. -@comment aio.h -@comment POSIX.1b @deftypefun int aio_cancel (int @var{fildes}, struct aiocb *@var{aiocbp}) +@standards{POSIX.1b, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} @c After fcntl to check the fd is open, hold aio_requests_mutex, call @c aio_find_req_fd, aio_remove_request, then aio_notify and @@ -3010,9 +2943,8 @@ function is in fact @code{aio_cancel64} since the LFS interface transparently replaces the normal implementation. @end deftypefun -@comment aio.h -@comment Unix98 @deftypefun int aio_cancel64 (int @var{fildes}, struct aiocb64 *@var{aiocbp}) +@standards{Unix98, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to @code{aio_cancel} with the only difference that the argument is a reference to a variable of type @code{struct @@ -3038,9 +2970,8 @@ limitations, hard limitations are something best avoided in @theglibc{}. Therefore, @theglibc{} provides a means for tuning the AIO implementation according to the individual use. -@comment aio.h -@comment GNU @deftp {Data Type} {struct aioinit} +@standards{GNU, aio.h} This data type is used to pass the configuration or tunable parameters to the implementation. The program has to initialize the members of this struct and pass it to the implementation using the @code{aio_init} @@ -3066,9 +2997,8 @@ Unused. @end table @end deftp -@comment aio.h -@comment GNU @deftypefun void aio_init (const struct aioinit *@var{init}) +@standards{GNU, aio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c All changes to global objects are guarded by aio_requests_mutex. This function must be called before any other AIO function. Calling it @@ -3102,9 +3032,8 @@ various flags that are used with it are declared in the header file function; see @ref{Opening and Closing Files}. @pindex fcntl.h -@comment fcntl.h -@comment POSIX.1 @deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{}) +@standards{POSIX.1, fcntl.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fcntl} function performs the operation specified by @var{command} on the file descriptor @var{filedes}. Some commands @@ -3197,18 +3126,16 @@ The @code{fcntl} function and flags are declared in @file{fcntl.h}, while prototypes for @code{dup} and @code{dup2} are in the header file @file{unistd.h}. -@comment unistd.h -@comment POSIX.1 @deftypefun int dup (int @var{old}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies descriptor @var{old} to the first available descriptor number (the first number not currently open). It is equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int dup2 (int @var{old}, int @var{new}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies the descriptor @var{old} to descriptor number @var{new}. @@ -3231,9 +3158,8 @@ middle of calling @code{dup2} at which @var{new} is closed and not yet a duplicate of @var{old}. @end deftypefun -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_DUPFD +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to copy the file descriptor given as the first argument. @@ -3321,9 +3247,8 @@ The symbols in this section are defined in the header file @file{fcntl.h}. @pindex fcntl.h -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_GETFD +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to specify that it should return the file descriptor flags associated with the @var{filedes} argument. @@ -3342,9 +3267,8 @@ The @var{filedes} argument is invalid. @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_SETFD +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to specify that it should set the file descriptor flags associated with the @var{filedes} argument. This requires a third @code{int} argument to @@ -3364,9 +3288,8 @@ The following macro is defined for use as a file descriptor flag with the @code{fcntl} function. The value is an integer constant usable as a bit mask value. -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int FD_CLOEXEC +@standards{POSIX.1, fcntl.h} @cindex close-on-exec (file descriptor flag) This flag specifies that the file descriptor should be closed when an @code{exec} function is invoked; see @ref{Executing a File}. When @@ -3453,21 +3376,18 @@ writing, or both. (On @gnuhurdsystems{}, they can also allow none of these, and allow execution of the file as a program.) The access modes are chosen when the file is opened, and never change. -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_RDONLY +@standards{POSIX.1, fcntl.h} Open the file for read access. @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_WRONLY +@standards{POSIX.1, fcntl.h} Open the file for write access. @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_RDWR +@standards{POSIX.1, fcntl.h} Open the file for both reading and writing. @end deftypevr @@ -3483,21 +3403,18 @@ access modes. These names are preferred when writing GNU-specific code. But most programs will want to be portable to other POSIX.1 systems and should use the POSIX.1 names above instead. -@comment fcntl.h (optional) -@comment GNU @deftypevr Macro int O_READ +@standards{GNU, fcntl.h (optional)} Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU. @end deftypevr -@comment fcntl.h (optional) -@comment GNU @deftypevr Macro int O_WRITE +@standards{GNU, fcntl.h (optional)} Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU. @end deftypevr -@comment fcntl.h (optional) -@comment GNU @deftypevr Macro int O_EXEC +@standards{GNU, fcntl.h (optional)} Open the file for executing. Only defined on GNU. @end deftypevr @@ -3509,9 +3426,8 @@ the flags word. But in other POSIX.1 systems, reading and writing access modes are not stored as distinct bit flags. The portable way to extract the file access mode bits is with @code{O_ACCMODE}. -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_ACCMODE +@standards{POSIX.1, fcntl.h} This macro stands for a mask that can be bitwise-ANDed with the file status flag value to produce a value representing the file access mode. The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}. @@ -3546,25 +3462,22 @@ perform on the file once it is open. Here are the file name translation flags. -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_CREAT +@standards{POSIX.1, fcntl.h} If set, the file will be created if it doesn't already exist. @c !!! mode arg, umask @cindex create on open (file status flag) @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_EXCL +@standards{POSIX.1, fcntl.h} If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails if the specified file already exists. This is guaranteed to never clobber an existing file. @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_NONBLOCK +@standards{POSIX.1, fcntl.h} @cindex non-blocking open This prevents @code{open} from blocking for a ``long time'' to open the file. This is only meaningful for some kinds of files, usually devices @@ -3581,9 +3494,8 @@ I/O that blocks, you must call @code{open} with @code{O_NONBLOCK} set and then call @code{fcntl} to turn the bit off. @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_NOCTTY +@standards{POSIX.1, fcntl.h} If the named file is a terminal device, don't make it the controlling terminal for the process. @xref{Job Control}, for information about what it means to be the controlling terminal. @@ -3599,27 +3511,24 @@ to be portable, use @code{O_NOCTTY} when it is important to avoid this. The following three file name translation flags exist only on @gnuhurdsystems{}. -@comment fcntl.h (optional) -@comment GNU @deftypevr Macro int O_IGNORE_CTTY +@standards{GNU, fcntl.h (optional)} Do not recognize the named file as the controlling terminal, even if it refers to the process's existing controlling terminal device. Operations on the new file descriptor will never induce job control signals. @xref{Job Control}. @end deftypevr -@comment fcntl.h (optional) -@comment GNU @deftypevr Macro int O_NOLINK +@standards{GNU, fcntl.h (optional)} If the named file is a symbolic link, open the link itself instead of the file it refers to. (@code{fstat} on the new file descriptor will return the information returned by @code{lstat} on the link's name.) @cindex symbolic link, opening @end deftypevr -@comment fcntl.h (optional) -@comment GNU @deftypevr Macro int O_NOTRANS +@standards{GNU, fcntl.h (optional)} If the named file is specially translated, do not invoke the translator. Open the bare file the translator itself sees. @end deftypevr @@ -3630,9 +3539,8 @@ which are not really related to opening the file. The reason to do them as part of @code{open} instead of in separate calls is that @code{open} can do them @i{atomically}. -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_TRUNC +@standards{POSIX.1, fcntl.h} Truncate the file to zero length. This option is only useful for regular files, not special files such as directories or FIFOs. POSIX.1 requires that you open the file for writing to use @code{O_TRUNC}. In @@ -3649,9 +3557,8 @@ compatibility. The remaining operating modes are BSD extensions. They exist only on some systems. On other systems, these macros are not defined. -@comment fcntl.h (optional) -@comment BSD @deftypevr Macro int O_SHLOCK +@standards{BSD, fcntl.h (optional)} Acquire a shared lock on the file, as with @code{flock}. @xref{File Locks}. @@ -3660,9 +3567,8 @@ creating the file. You are guaranteed that no other process will get the lock on the new file first. @end deftypevr -@comment fcntl.h (optional) -@comment BSD @deftypevr Macro int O_EXLOCK +@standards{BSD, fcntl.h (optional)} Acquire an exclusive lock on the file, as with @code{flock}. @xref{File Locks}. This is atomic like @code{O_SHLOCK}. @end deftypevr @@ -3674,9 +3580,8 @@ The operating modes affect how input and output operations using a file descriptor work. These flags are set by @code{open} and can be fetched and changed with @code{fcntl}. -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_APPEND +@standards{POSIX.1, fcntl.h} The bit that enables append mode for the file. If set, then all @code{write} operations write the data at the end of the file, extending it, regardless of the current file position. This is the only reliable @@ -3688,9 +3593,8 @@ extend the file after you set the file position but before you write, resulting in your data appearing someplace before the real end of file. @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int O_NONBLOCK +@standards{POSIX.1, fcntl.h} The bit that enables nonblocking mode for the file. If this bit is set, @code{read} requests on the file can return immediately with a failure status if there is no input immediately available, instead of blocking. @@ -3701,9 +3605,8 @@ Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O operating mode and a file name translation flag; @pxref{Open-time Flags}. @end deftypevr -@comment fcntl.h -@comment BSD @deftypevr Macro int O_NDELAY +@standards{BSD, fcntl.h} This is an obsolete name for @code{O_NONBLOCK}, provided for compatibility with BSD. It is not defined by the POSIX.1 standard. @end deftypevr @@ -3711,18 +3614,16 @@ compatibility with BSD. It is not defined by the POSIX.1 standard. The remaining operating modes are BSD and GNU extensions. They exist only on some systems. On other systems, these macros are not defined. -@comment fcntl.h -@comment BSD @deftypevr Macro int O_ASYNC +@standards{BSD, fcntl.h} The bit that enables asynchronous input mode. If set, then @code{SIGIO} signals will be generated when input is available. @xref{Interrupt Input}. Asynchronous input mode is a BSD feature. @end deftypevr -@comment fcntl.h -@comment BSD @deftypevr Macro int O_FSYNC +@standards{BSD, fcntl.h} The bit that enables synchronous writing for the file. If set, each @code{write} call will make sure the data is reliably stored on disk before returning. @c !!! xref fsync @@ -3730,15 +3631,13 @@ returning. @c !!! xref fsync Synchronous writing is a BSD feature. @end deftypevr -@comment fcntl.h -@comment BSD @deftypevr Macro int O_SYNC +@standards{BSD, fcntl.h} This is another name for @code{O_FSYNC}. They have the same value. @end deftypevr -@comment fcntl.h -@comment GNU @deftypevr Macro int O_NOATIME +@standards{GNU, fcntl.h} If this bit is set, @code{read} will not update the access time of the file. @xref{File Times}. This is used by programs that do backups, so that backing a file up does not count as reading it. @@ -3752,9 +3651,8 @@ This is a GNU extension. The @code{fcntl} function can fetch or change file status flags. -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_GETFL +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to read the file status flags for the open file with descriptor @var{filedes}. @@ -3774,9 +3672,8 @@ The @var{filedes} argument is invalid. @end table @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_SETFL +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to set the file status flags for the open file corresponding to the @var{filedes} argument. This command requires a third @code{int} @@ -3870,9 +3767,8 @@ lock and where. This data type and the associated macros for the @code{fcntl} function are declared in the header file @file{fcntl.h}. @pindex fcntl.h -@comment fcntl.h -@comment POSIX.1 @deftp {Data Type} {struct flock} +@standards{POSIX.1, fcntl.h} This structure is used with the @code{fcntl} function to describe a file lock. It has these members: @@ -3906,9 +3802,8 @@ conflicting lock is an open file description lock @end table @end deftp -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_GETLK +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to specify that it should get information about a lock. This command requires a third argument of type @w{@code{struct flock *}} to be passed @@ -3950,9 +3845,8 @@ or the file associated with @var{filedes} doesn't support locks. @end table @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_SETLK +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to specify that it should set or clear a lock. This command requires a third argument of type @w{@code{struct flock *}} to be passed to @@ -4002,9 +3896,8 @@ to a file system on another machine. @end table @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_SETLKW +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to specify that it should set or clear a lock. It is just like the @code{F_SETLK} command, but causes the process to block (or wait) @@ -4036,19 +3929,16 @@ The following macros are defined for use as values for the @code{l_type} member of the @code{flock} structure. The values are integer constants. @vtable @code -@comment fcntl.h -@comment POSIX.1 @item F_RDLCK +@standards{POSIX.1, fcntl.h} This macro is used to specify a read (or shared) lock. -@comment fcntl.h -@comment POSIX.1 @item F_WRLCK +@standards{POSIX.1, fcntl.h} This macro is used to specify a write (or exclusive) lock. -@comment fcntl.h -@comment POSIX.1 @item F_UNLCK +@standards{POSIX.1, fcntl.h} This macro is used to specify that the region is unlocked. @end vtable @@ -4174,9 +4064,8 @@ associated with @var{filedes} doesn't support locks. @end table @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_OFD_SETLK +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to specify that it should set or clear a lock. This command requires a third argument of type @w{@code{struct flock *}} to be passed to @@ -4223,9 +4112,8 @@ to a file system on another machine. @end table @end deftypevr -@comment fcntl.h -@comment POSIX.1 @deftypevr Macro int F_OFD_SETLKW +@standards{POSIX.1, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to specify that it should set or clear a lock. It is just like the @code{F_OFD_SETLK} command, but causes the process to wait until the request @@ -4310,9 +4198,8 @@ signals are sent to the foreground process group of the terminal. The symbols in this section are defined in the header file @file{fcntl.h}. -@comment fcntl.h -@comment BSD @deftypevr Macro int F_GETOWN +@standards{BSD, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to specify that it should get information about the process or process group to which @code{SIGIO} signals are sent. (For a terminal, this is @@ -4330,9 +4217,8 @@ The @var{filedes} argument is invalid. @end table @end deftypevr -@comment fcntl.h -@comment BSD @deftypevr Macro int F_SETOWN +@standards{BSD, fcntl.h} This macro is used as the @var{command} argument to @code{fcntl}, to specify that it should set the process or process group to which @code{SIGIO} signals are sent. This command requires a third argument @@ -4401,9 +4287,8 @@ numbers and multiplexed through the @code{ioctl} function, defined in @code{sys/ioctl.h}. The code numbers themselves are defined in many different headers. -@comment sys/ioctl.h -@comment BSD @deftypefun int ioctl (int @var{filedes}, int @var{command}, @dots{}) +@standards{BSD, sys/ioctl.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{ioctl} function performs the generic I/O operation diff --git a/manual/locale.texi b/manual/locale.texi index ae71ccc906..f7a40c2cff 100644 --- a/manual/locale.texi +++ b/manual/locale.texi @@ -138,55 +138,47 @@ argument to @code{setlocale}) has to be a valid locale name. @xref{Locale Names}. @vtable @code -@comment locale.h -@comment ISO @item LC_COLLATE +@standards{ISO, locale.h} This category applies to collation of strings (functions @code{strcoll} and @code{strxfrm}); see @ref{Collation Functions}. -@comment locale.h -@comment ISO @item LC_CTYPE +@standards{ISO, locale.h} This category applies to classification and conversion of characters, and to multibyte and wide characters; see @ref{Character Handling}, and @ref{Character Set Handling}. -@comment locale.h -@comment ISO @item LC_MONETARY +@standards{ISO, locale.h} This category applies to formatting monetary values; see @ref{General Numeric}. -@comment locale.h -@comment ISO @item LC_NUMERIC +@standards{ISO, locale.h} This category applies to formatting numeric values that are not monetary; see @ref{General Numeric}. -@comment locale.h -@comment ISO @item LC_TIME +@standards{ISO, locale.h} This category applies to formatting date and time values; see @ref{Formatting Calendar Time}. -@comment locale.h -@comment XOPEN @item LC_MESSAGES +@standards{XOPEN, locale.h} This category applies to selecting the language used in the user interface for message translation (@pxref{The Uniforum approach}; @pxref{Message catalogs a la X/Open}) and contains regular expressions for affirmative and negative responses. -@comment locale.h -@comment ISO @item LC_ALL +@standards{ISO, locale.h} This is not a category; it is only a macro that you can use with @code{setlocale} to set a single locale for all purposes. Setting this environment variable overwrites all selections by the other @code{LC_*} variables or @code{LANG}. -@comment locale.h -@comment ISO @item LANG +@standards{ISO, locale.h} If this environment variable is defined, its value specifies the locale to use for all purposes except as overridden by the variables above. @end vtable @@ -228,9 +220,8 @@ general use or for a specific category. @pindex locale.h The symbols in this section are defined in the header file @file{locale.h}. -@comment locale.h -@comment ISO @deftypefun {char *} setlocale (int @var{category}, const char *@var{locale}) +@standards{ISO, locale.h} @safety{@prelim{}@mtunsafe{@mtasuconst{:@mtslocale{}} @mtsenv{}}@asunsafe{@asuinit{} @asulock{} @ascuheap{} @asucorrupt{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c Uses of the global locale object are unguarded in functions that @c ought to be MT-Safe, so we're ruling out the use of this function @@ -623,9 +614,8 @@ according to the selected locale using this information. @cindex monetary value formatting @cindex numeric value formatting -@comment locale.h -@comment ISO @deftypefun {struct lconv *} localeconv (void) +@standards{ISO, locale.h} @safety{@prelim{}@mtunsafe{@mtasurace{:localeconv} @mtslocale{}}@asunsafe{}@acsafe{}} @c This function reads from multiple components of the locale object, @c without synchronization, while writing to the static buffer it uses @@ -640,9 +630,8 @@ be overwritten by subsequent calls to @code{localeconv}, or by calls to value. @end deftypefun -@comment locale.h -@comment ISO @deftp {Data Type} {struct lconv} +@standards{ISO, locale.h} @code{localeconv}'s return value is of this data type. Its elements are described in the following subsections. @end deftp @@ -893,9 +882,8 @@ in the locale (as later specified in the POSIX.1 standard) requires more ways to access it. Therefore the @code{nl_langinfo} function was introduced. -@comment langinfo.h -@comment XOPEN @deftypefun {char *} nl_langinfo (nl_item @var{item}) +@standards{XOPEN, langinfo.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c It calls _nl_langinfo_l with the current locale, which returns a @c pointer into constant strings defined in locale data structures. @@ -1406,9 +1394,8 @@ English. @Theglibc{} contains @code{rpmatch} to give applications easy access to the corresponding locale definitions. -@comment stdlib.h -@comment GNU @deftypefun int rpmatch (const char *@var{response}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c Calls nl_langinfo with YESEXPR and NOEXPR, triggering @mtslocale but @c it's regcomp and regexec that bring in all of the safety issues. diff --git a/manual/macros.texi b/manual/macros.texi index 170e954a50..4a2e22f473 100644 --- a/manual/macros.texi +++ b/manual/macros.texi @@ -275,6 +275,7 @@ cwd\comments\ @end macro @c Dummy placeholder while converting annotations. +@c For details on expected use, see `summary.pl --help'. @macro standards {standard, header} @end macro @c To be used for @*x lists of elements. diff --git a/manual/math.texi b/manual/math.texi index 53c2bc1a1f..912e74009f 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -159,43 +159,28 @@ yourself: You can also compute the value of pi with the expression @code{acos (-1.0)}. -@comment math.h -@comment ISO @deftypefun double sin (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float sinf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} sinl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the sine of @var{x}, where @var{x} is given in radians. The return value is in the range @code{-1} to @code{1}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double cos (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float cosf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} cosl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the cosine of @var{x}, where @var{x} is given in radians. The return value is in the range @code{-1} to @code{1}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double tan (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float tanf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} tanl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the tangent of @var{x}, where @var{x} is given in radians. @@ -210,15 +195,10 @@ and cosine of the same angle are needed at the same time. It is more efficient to compute them simultaneously, so the library provides a function to do that. -@comment math.h -@comment GNU @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx}) -@comment math.h -@comment GNU @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx}) -@comment math.h -@comment GNU @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx}) +@standards{GNU, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the sine of @var{x} in @code{*@var{sinx}} and the cosine of @var{x} in @code{*@var{cosx}}, where @var{x} is given in @@ -239,15 +219,10 @@ by the standard. (As of this writing GCC supports complex numbers, but there are bugs in the implementation.) -@comment complex.h -@comment ISO @deftypefun {complex double} csin (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} csinf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} csinl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c There are calls to nan* that could trigger @mtslocale if they didn't get @c empty strings. @@ -262,15 +237,10 @@ $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$ @end tex @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} ccos (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} ccosf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} ccosl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the complex cosine of @var{z}. The mathematical definition of the complex cosine is @@ -283,15 +253,10 @@ $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$ @end tex @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} ctan (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} ctanf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} ctanl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the complex tangent of @var{z}. The mathematical definition of the complex tangent is @@ -318,15 +283,10 @@ These are the usual arcsine, arccosine and arctangent functions, which are the inverses of the sine, cosine and tangent functions respectively. -@comment math.h -@comment ISO @deftypefun double asin (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float asinf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} asinl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute the arcsine of @var{x}---that is, the value whose sine is @var{x}. The value is in units of radians. Mathematically, @@ -338,15 +298,10 @@ over the domain @code{-1} to @code{1}. If @var{x} is outside the domain, @code{asin} signals a domain error. @end deftypefun -@comment math.h -@comment ISO @deftypefun double acos (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float acosf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} acosl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute the arccosine of @var{x}---that is, the value whose cosine is @var{x}. The value is in units of radians. @@ -358,15 +313,10 @@ over the domain @code{-1} to @code{1}. If @var{x} is outside the domain, @code{acos} signals a domain error. @end deftypefun -@comment math.h -@comment ISO @deftypefun double atan (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float atanf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} atanl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute the arctangent of @var{x}---that is, the value whose tangent is @var{x}. The value is in units of radians. @@ -374,15 +324,10 @@ Mathematically, there are infinitely many such values; the one actually returned is the one between @code{-pi/2} and @code{pi/2} (inclusive). @end deftypefun -@comment math.h -@comment ISO @deftypefun double atan2 (double @var{y}, double @var{x}) -@comment math.h -@comment ISO @deftypefunx float atan2f (float @var{y}, float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function computes the arctangent of @var{y}/@var{x}, but the signs of both arguments are used to determine the quadrant of the result, and @@ -403,15 +348,10 @@ If both @var{x} and @var{y} are zero, @code{atan2} returns zero. @cindex inverse complex trigonometric functions @w{ISO C99} defines complex versions of the inverse trig functions. -@comment complex.h -@comment ISO @deftypefun {complex double} casin (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} casinf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} casinl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute the complex arcsine of @var{z}---that is, the value whose sine is @var{z}. The value returned is in radians. @@ -420,15 +360,10 @@ Unlike the real-valued functions, @code{casin} is defined for all values of @var{z}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} cacos (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} cacosf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} cacosl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute the complex arccosine of @var{z}---that is, the value whose cosine is @var{z}. The value returned is in radians. @@ -438,15 +373,10 @@ values of @var{z}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} catan (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} catanf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} catanl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute the complex arctangent of @var{z}---that is, the value whose tangent is @var{z}. The value is in units of radians. @@ -459,15 +389,10 @@ the value whose tangent is @var{z}. The value is in units of radians. @cindex power functions @cindex logarithm functions -@comment math.h -@comment ISO @deftypefun double exp (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float expf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} expl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute @code{e} (the base of natural logarithms) raised to the power @var{x}. @@ -476,38 +401,25 @@ If the magnitude of the result is too large to be representable, @code{exp} signals overflow. @end deftypefun -@comment math.h -@comment ISO @deftypefun double exp2 (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float exp2f (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} exp2l (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute @code{2} raised to the power @var{x}. Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double exp10 (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float exp10f (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} exp10l (long double @var{x}) -@comment math.h -@comment GNU @deftypefunx double pow10 (double @var{x}) -@comment math.h -@comment GNU @deftypefunx float pow10f (float @var{x}) -@comment math.h -@comment GNU @deftypefunx {long double} pow10l (long double @var{x}) +@standards{ISO, math.h} +@standardsx{pow10, GNU, math.h} +@standardsx{pow10f, GNU, math.h} +@standardsx{pow10l, GNU, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute @code{10} raised to the power @var{x}. Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}. @@ -518,15 +430,10 @@ preferred, since it is analogous to @code{exp} and @code{exp2}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double log (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float logf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} logl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute the natural logarithm of @var{x}. @code{exp (log (@var{x}))} equals @var{x}, exactly in mathematics and approximately in @@ -537,44 +444,29 @@ is zero, it returns negative infinity; if @var{x} is too close to zero, it may signal overflow. @end deftypefun -@comment math.h -@comment ISO @deftypefun double log10 (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float log10f (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} log10l (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the base-10 logarithm of @var{x}. @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double log2 (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float log2f (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} log2l (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the base-2 logarithm of @var{x}. @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double logb (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float logbf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} logbl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions extract the exponent of @var{x} and return it as a floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal @@ -586,24 +478,13 @@ negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero, @code{logb} returns @math{@infinity{}}. It does not signal. @end deftypefun -@comment math.h -@comment ISO @deftypefun int ilogb (double @var{x}) -@comment math.h -@comment ISO @deftypefunx int ilogbf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx int ilogbl (long double @var{x}) -@comment math.h -@comment ISO @deftypefunx {long int} llogb (double @var{x}) -@comment math.h -@comment ISO @deftypefunx {long int} llogbf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long int} llogbl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are equivalent to the corresponding @code{logb} functions except that they return signed integer values. The @@ -616,36 +497,32 @@ Since integers cannot represent infinity and NaN, @code{ilogb} instead returns an integer that can't be the exponent of a normal floating-point number. @file{math.h} defines constants so you can check for this. -@comment math.h -@comment ISO @deftypevr Macro int FP_ILOGB0 +@standards{ISO, math.h} @code{ilogb} returns this value if its argument is @code{0}. The numeric value is either @code{INT_MIN} or @code{-INT_MAX}. This macro is defined in @w{ISO C99}. @end deftypevr -@comment math.h -@comment ISO @deftypevr Macro {long int} FP_LLOGB0 +@standards{ISO, math.h} @code{llogb} returns this value if its argument is @code{0}. The numeric value is either @code{LONG_MIN} or @code{-LONG_MAX}. This macro is defined in TS 18661-1:2014. @end deftypevr -@comment math.h -@comment ISO @deftypevr Macro int FP_ILOGBNAN +@standards{ISO, math.h} @code{ilogb} returns this value if its argument is @code{NaN}. The numeric value is either @code{INT_MIN} or @code{INT_MAX}. This macro is defined in @w{ISO C99}. @end deftypevr -@comment math.h -@comment ISO @deftypevr Macro {long int} FP_LLOGBNAN +@standards{ISO, math.h} @code{llogb} returns this value if its argument is @code{NaN}. The numeric value is either @code{LONG_MIN} or @code{LONG_MAX}. @@ -675,15 +552,10 @@ if (i == FP_ILOGB0 || i == FP_ILOGBNAN) @} @end smallexample -@comment math.h -@comment ISO @deftypefun double pow (double @var{base}, double @var{power}) -@comment math.h -@comment ISO @deftypefunx float powf (float @var{base}, float @var{power}) -@comment math.h -@comment ISO @deftypefunx {long double} powl (long double @var{base}, long double @var{power}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These are general exponentiation functions, returning @var{base} raised to @var{power}. @@ -695,15 +567,10 @@ underflow or overflow the destination type. @end deftypefun @cindex square root function -@comment math.h -@comment ISO @deftypefun double sqrt (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float sqrtf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} sqrtl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the nonnegative square root of @var{x}. @@ -712,29 +579,19 @@ Mathematically, it should return a complex number. @end deftypefun @cindex cube root function -@comment math.h -@comment BSD @deftypefun double cbrt (double @var{x}) -@comment math.h -@comment BSD @deftypefunx float cbrtf (float @var{x}) -@comment math.h -@comment BSD @deftypefunx {long double} cbrtl (long double @var{x}) +@standards{BSD, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the cube root of @var{x}. They cannot fail; every representable real value has a representable real cube root. @end deftypefun -@comment math.h -@comment ISO @deftypefun double hypot (double @var{x}, double @var{y}) -@comment math.h -@comment ISO @deftypefunx float hypotf (float @var{x}, float @var{y}) -@comment math.h -@comment ISO @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return @code{sqrt (@var{x}*@var{x} + @var{y}*@var{y})}. This is the length of the hypotenuse of a right @@ -744,15 +601,10 @@ instead of the direct formula is wise, since the error is much smaller. See also the function @code{cabs} in @ref{Absolute Value}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double expm1 (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float expm1f (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} expm1l (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return a value equivalent to @code{exp (@var{x}) - 1}. They are computed in a way that is accurate even if @var{x} is @@ -760,15 +612,10 @@ near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing to subtraction of two numbers that are nearly equal. @end deftypefun -@comment math.h -@comment ISO @deftypefun double log1p (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float log1pf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} log1pl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return a value equivalent to @w{@code{log (1 + @var{x})}}. They are computed in a way that is accurate even if @var{x} is @@ -781,15 +628,10 @@ near zero. @w{ISO C99} defines complex variants of some of the exponentiation and logarithm functions. -@comment complex.h -@comment ISO @deftypefun {complex double} cexp (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} cexpf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} cexpl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return @code{e} (the base of natural logarithms) raised to the power of @var{z}. @@ -803,15 +645,10 @@ $$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$ @end tex @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} clog (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} clogf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} clogl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the natural logarithm of @var{z}. Mathematically, this corresponds to the value @@ -830,15 +667,10 @@ or is very close to 0. It is well-defined for all other values of @end deftypefun -@comment complex.h -@comment GNU @deftypefun {complex double} clog10 (complex double @var{z}) -@comment complex.h -@comment GNU @deftypefunx {complex float} clog10f (complex float @var{z}) -@comment complex.h -@comment GNU @deftypefunx {complex long double} clog10l (complex long double @var{z}) +@standards{GNU, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the base 10 logarithm of the complex value @var{z}. Mathematically, this corresponds to the value @@ -853,29 +685,19 @@ $$\log_{10}(z) = \log_{10}|z| + i \arg z / \log (10)$$ These functions are GNU extensions. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} csqrt (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} csqrtf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} csqrtl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the complex square root of the argument @var{z}. Unlike the real-valued functions, they are defined for all values of @var{z}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power}) -@comment complex.h -@comment ISO @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return @var{base} raised to the power of @var{power}. This is equivalent to @w{@code{cexp (y * clog (x))}} @@ -888,45 +710,30 @@ These functions return @var{base} raised to the power of The functions in this section are related to the exponential functions; see @ref{Exponents and Logarithms}. -@comment math.h -@comment ISO @deftypefun double sinh (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float sinhf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} sinhl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the hyperbolic sine of @var{x}, defined mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}. They may signal overflow if @var{x} is too large. @end deftypefun -@comment math.h -@comment ISO @deftypefun double cosh (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float coshf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} coshl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the hyperbolic cosine of @var{x}, defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}. They may signal overflow if @var{x} is too large. @end deftypefun -@comment math.h -@comment ISO @deftypefun double tanh (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float tanhf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} tanhl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the hyperbolic tangent of @var{x}, defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}. @@ -938,43 +745,28 @@ They may signal overflow if @var{x} is too large. There are counterparts for the hyperbolic functions which take complex arguments. -@comment complex.h -@comment ISO @deftypefun {complex double} csinh (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} csinhf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} csinhl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the complex hyperbolic sine of @var{z}, defined mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} ccosh (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} ccoshf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} ccoshl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the complex hyperbolic cosine of @var{z}, defined mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} ctanh (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} ctanhf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} ctanhl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the complex hyperbolic tangent of @var{z}, defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}. @@ -983,44 +775,29 @@ defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}. @cindex inverse hyperbolic functions -@comment math.h -@comment ISO @deftypefun double asinh (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float asinhf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} asinhl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the inverse hyperbolic sine of @var{x}---the value whose hyperbolic sine is @var{x}. @end deftypefun -@comment math.h -@comment ISO @deftypefun double acosh (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float acoshf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} acoshl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the inverse hyperbolic cosine of @var{x}---the value whose hyperbolic cosine is @var{x}. If @var{x} is less than @code{1}, @code{acosh} signals a domain error. @end deftypefun -@comment math.h -@comment ISO @deftypefun double atanh (double @var{x}) -@comment math.h -@comment ISO @deftypefunx float atanhf (float @var{x}) -@comment math.h -@comment ISO @deftypefunx {long double} atanhl (long double @var{x}) +@standards{ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the inverse hyperbolic tangent of @var{x}---the value whose hyperbolic tangent is @var{x}. If the absolute value of @@ -1030,44 +807,29 @@ if it is equal to 1, @code{atanh} returns infinity. @cindex inverse complex hyperbolic functions -@comment complex.h -@comment ISO @deftypefun {complex double} casinh (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} casinhf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} casinhl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the inverse complex hyperbolic sine of @var{z}---the value whose complex hyperbolic sine is @var{z}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} cacosh (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} cacoshf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} cacoshl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the inverse complex hyperbolic cosine of @var{z}---the value whose complex hyperbolic cosine is @var{z}. Unlike the real-valued functions, there are no restrictions on the value of @var{z}. @end deftypefun -@comment complex.h -@comment ISO @deftypefun {complex double} catanh (complex double @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex float} catanhf (complex float @var{z}) -@comment complex.h -@comment ISO @deftypefunx {complex long double} catanhl (complex long double @var{z}) +@standards{ISO, complex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the inverse complex hyperbolic tangent of @var{z}---the value whose complex hyperbolic tangent is @var{z}. Unlike @@ -1084,15 +846,10 @@ the real-valued functions, there are no restrictions on the value of These are some more exotic mathematical functions which are sometimes useful. Currently they only have real-valued versions. -@comment math.h -@comment SVID @deftypefun double erf (double @var{x}) -@comment math.h -@comment SVID @deftypefunx float erff (float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} erfl (long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{erf} returns the error function of @var{x}. The error function is defined as @@ -1106,29 +863,19 @@ erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt @end ifnottex @end deftypefun -@comment math.h -@comment SVID @deftypefun double erfc (double @var{x}) -@comment math.h -@comment SVID @deftypefunx float erfcf (float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} erfcl (long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a fashion that avoids round-off error when @var{x} is large. @end deftypefun -@comment math.h -@comment SVID @deftypefun double lgamma (double @var{x}) -@comment math.h -@comment SVID @deftypefunx float lgammaf (float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} lgammal (long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}} @code{lgamma} returns the natural logarithm of the absolute value of the gamma function of @var{x}. The gamma function is defined as @@ -1159,30 +906,20 @@ The gamma function has singularities at the non-positive integers. singularity. @end deftypefun -@comment math.h -@comment XPG @deftypefun double lgamma_r (double @var{x}, int *@var{signp}) -@comment math.h -@comment XPG @deftypefunx float lgammaf_r (float @var{x}, int *@var{signp}) -@comment math.h -@comment XPG @deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp}) +@standards{XPG, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{lgamma_r} is just like @code{lgamma}, but it stores the sign of the intermediate result in the variable pointed to by @var{signp} instead of in the @var{signgam} global. This means it is reentrant. @end deftypefun -@comment math.h -@comment SVID @deftypefun double gamma (double @var{x}) -@comment math.h -@comment SVID @deftypefunx float gammaf (float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} gammal (long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}} These functions exist for compatibility reasons. They are equivalent to @code{lgamma} etc. It is better to use @code{lgamma} since for one the @@ -1190,15 +927,15 @@ name reflects better the actual computation, and moreover @code{lgamma} is standardized in @w{ISO C99} while @code{gamma} is not. @end deftypefun -@comment math.h -@comment XPG, ISO @deftypefun double tgamma (double @var{x}) -@comment math.h -@comment XPG, ISO @deftypefunx float tgammaf (float @var{x}) -@comment math.h -@comment XPG, ISO @deftypefunx {long double} tgammal (long double @var{x}) +@standardsx{tgamma, XPG, math.h} +@standardsx{tgamma, ISO, math.h} +@standardsx{tgammaf, XPG, math.h} +@standardsx{tgammaf, ISO, math.h} +@standardsx{tgammal, XPG, math.h} +@standardsx{tgammal, ISO, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{tgamma} applies the gamma function to @var{x}. The gamma function is defined as @@ -1214,57 +951,37 @@ gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt This function was introduced in @w{ISO C99}. @end deftypefun -@comment math.h -@comment SVID @deftypefun double j0 (double @var{x}) -@comment math.h -@comment SVID @deftypefunx float j0f (float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} j0l (long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{j0} returns the Bessel function of the first kind of order 0 of @var{x}. It may signal underflow if @var{x} is too large. @end deftypefun -@comment math.h -@comment SVID @deftypefun double j1 (double @var{x}) -@comment math.h -@comment SVID @deftypefunx float j1f (float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} j1l (long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{j1} returns the Bessel function of the first kind of order 1 of @var{x}. It may signal underflow if @var{x} is too large. @end deftypefun -@comment math.h -@comment SVID @deftypefun double jn (int @var{n}, double @var{x}) -@comment math.h -@comment SVID @deftypefunx float jnf (int @var{n}, float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} jnl (int @var{n}, long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{jn} returns the Bessel function of the first kind of order @var{n} of @var{x}. It may signal underflow if @var{x} is too large. @end deftypefun -@comment math.h -@comment SVID @deftypefun double y0 (double @var{x}) -@comment math.h -@comment SVID @deftypefunx float y0f (float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} y0l (long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{y0} returns the Bessel function of the second kind of order 0 of @var{x}. It may signal underflow if @var{x} is too large. If @var{x} @@ -1272,15 +989,10 @@ is negative, @code{y0} signals a domain error; if it is zero, @code{y0} signals overflow and returns @math{-@infinity}. @end deftypefun -@comment math.h -@comment SVID @deftypefun double y1 (double @var{x}) -@comment math.h -@comment SVID @deftypefunx float y1f (float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} y1l (long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{y1} returns the Bessel function of the second kind of order 1 of @var{x}. It may signal underflow if @var{x} is too large. If @var{x} @@ -1288,15 +1000,10 @@ is negative, @code{y1} signals a domain error; if it is zero, @code{y1} signals overflow and returns @math{-@infinity}. @end deftypefun -@comment math.h -@comment SVID @deftypefun double yn (int @var{n}, double @var{x}) -@comment math.h -@comment SVID @deftypefunx float ynf (int @var{n}, float @var{x}) -@comment math.h -@comment SVID @deftypefunx {long double} ynl (int @var{n}, long double @var{x}) +@standards{SVID, math.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{yn} returns the Bessel function of the second kind of order @var{n} of @var{x}. It may signal underflow if @var{x} is too large. If @var{x} @@ -1492,27 +1199,24 @@ To use these facilities, you should include the header file @file{stdlib.h} in your program. @pindex stdlib.h -@comment stdlib.h -@comment ISO @deftypevr Macro int RAND_MAX +@standards{ISO, stdlib.h} The value of this macro is an integer constant representing the largest value the @code{rand} function can return. In @theglibc{}, it is @code{2147483647}, which is the largest signed integer representable in 32 bits. In other libraries, it may be as low as @code{32767}. @end deftypevr -@comment stdlib.h -@comment ISO @deftypefun int rand (void) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c Just calls random. The @code{rand} function returns the next pseudo-random number in the series. The value ranges from @code{0} to @code{RAND_MAX}. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun void srand (unsigned int @var{seed}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c Alias to srandom. This function establishes @var{seed} as the seed for a new series of @@ -1528,9 +1232,8 @@ POSIX.1 extended the C standard functions to support reproducible random numbers in multi-threaded programs. However, the extension is badly designed and unsuitable for serious work. -@comment stdlib.h -@comment POSIX.1 @deftypefun int rand_r (unsigned int *@var{seed}) +@standards{POSIX.1, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns a random number in the range 0 to @code{RAND_MAX} just as @code{rand} does. However, all its state is stored in the @@ -1555,9 +1258,8 @@ with @theglibc{}; we support them for BSD compatibility only. The prototypes for these functions are in @file{stdlib.h}. @pindex stdlib.h -@comment stdlib.h -@comment BSD @deftypefun {long int} random (void) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c Takes a lock and calls random_r with an automatic variable and the @c global state, while holding a lock. @@ -1571,9 +1273,8 @@ differently. Users must always be aware of the 32-bit limitation, though. @end deftypefun -@comment stdlib.h -@comment BSD @deftypefun void srandom (unsigned int @var{seed}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c Takes a lock and calls srandom_r with an automatic variable and a @c static buffer. There's no MT-safety issue because the static buffer @@ -1588,9 +1289,8 @@ To produce a different set of pseudo-random numbers each time your program runs, do @code{srandom (time (0))}. @end deftypefun -@comment stdlib.h -@comment BSD @deftypefun {char *} initstate (unsigned int @var{seed}, char *@var{state}, size_t @var{size}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} The @code{initstate} function is used to initialize the random number generator state. The argument @var{state} is an array of @var{size} @@ -1603,9 +1303,8 @@ You can use this value later as an argument to @code{setstate} to restore that state. @end deftypefun -@comment stdlib.h -@comment BSD @deftypefun {char *} setstate (char *@var{state}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} The @code{setstate} function restores the random number state information @var{state}. The argument must have been the result of @@ -1632,9 +1331,8 @@ following interfaces. The @file{stdlib.h} header contains a definition of the following type: -@comment stdlib.h -@comment GNU @deftp {Data Type} {struct random_data} +@standards{GNU, stdlib.h} Objects of type @code{struct random_data} contain the information necessary to represent the state of the PRNG. Although a complete @@ -1644,36 +1342,32 @@ definition of the type is present the type should be treated as opaque. The functions modifying the state follow exactly the already described functions. -@comment stdlib.h -@comment GNU @deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} The @code{random_r} function behaves exactly like the @code{random} function except that it uses and modifies the state in the object pointed to by the first parameter instead of the global state. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} The @code{srandom_r} function behaves exactly like the @code{srandom} function except that it uses and modifies the state in the object pointed to by the second parameter instead of the global state. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} The @code{initstate_r} function behaves exactly like the @code{initstate} function except that it uses and modifies the state in the object pointed to by the fourth parameter instead of the global state. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} The @code{setstate_r} function behaves exactly like the @code{setstate} function except that it uses and modifies the state in the object @@ -1718,9 +1412,8 @@ The prototypes for these functions are in @file{stdlib.h}. @pindex stdlib.h -@comment stdlib.h -@comment SVID @deftypefun double drand48 (void) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} @c Uses of the static state buffer are not guarded by a lock (thus @c @mtasurace:drand48), so they may be found or left at a @@ -1737,9 +1430,8 @@ generator. These are (of course) chosen to be the least significant bits and they are initialized to @code{0}. @end deftypefun -@comment stdlib.h -@comment SVID @deftypefun double erand48 (unsigned short int @var{xsubi}[3]) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} @c The static buffer is just initialized with default parameters, which @c are later read to advance the state held in xsubi. @@ -1752,9 +1444,8 @@ guarantee random numbers. The array should have been initialized before initial use to obtain reproducible results. @end deftypefun -@comment stdlib.h -@comment SVID @deftypefun {long int} lrand48 (void) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} The @code{lrand48} function returns an integer value in the range of @code{0} to @code{2^31} (exclusive). Even if the size of the @code{long @@ -1763,9 +1454,8 @@ The random bits are determined by the global state of the random number generator in the C library. @end deftypefun -@comment stdlib.h -@comment SVID @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3]) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} This function is similar to the @code{lrand48} function in that it returns a number in the range of @code{0} to @code{2^31} (exclusive) but @@ -1778,18 +1468,16 @@ number generator). The array should have been initialized before the first call to obtain reproducible results. @end deftypefun -@comment stdlib.h -@comment SVID @deftypefun {long int} mrand48 (void) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} The @code{mrand48} function is similar to @code{lrand48}. The only difference is that the numbers returned are in the range @code{-2^31} to @code{2^31} (exclusive). @end deftypefun -@comment stdlib.h -@comment SVID @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3]) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} The @code{jrand48} function is similar to @code{nrand48}. The only difference is that the numbers returned are in the range @code{-2^31} to @@ -1801,9 +1489,8 @@ The internal state of the random number generator can be initialized in several ways. The methods differ in the completeness of the information provided. -@comment stdlib.h -@comment SVID @deftypefun void srand48 (long int @var{seedval}) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} The @code{srand48} function sets the most significant 32 bits of the internal state of the random number generator to the least @@ -1821,9 +1508,8 @@ are reset to the default values given above. This is of importance once the user has called the @code{lcong48} function (see below). @end deftypefun -@comment stdlib.h -@comment SVID @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3]) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} The @code{seed48} function initializes all 48 bits of the state of the internal random number generator from the contents of the parameter @@ -1849,9 +1535,8 @@ There is one more function to initialize the random number generator which enables you to specify even more information by allowing you to change the parameters in the congruential formula. -@comment stdlib.h -@comment SVID @deftypefun void lcong48 (unsigned short int @var{param}[7]) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} The @code{lcong48} function allows the user to change the complete state of the random number generator. Unlike @code{srand48} and @@ -1882,9 +1567,8 @@ obtain an individual random number generator. The user-supplied buffer must be of type @code{struct drand48_data}. This type should be regarded as opaque and not manipulated directly. -@comment stdlib.h -@comment GNU @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} This function is equivalent to the @code{drand48} function with the difference that it does not modify the global random number generator @@ -1900,9 +1584,8 @@ This function is a GNU extension and should not be used in portable programs. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} The @code{erand48_r} function works like @code{erand48}, but in addition it takes an argument @var{buffer} which describes the random number @@ -1917,9 +1600,8 @@ This function is a GNU extension and should not be used in portable programs. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, long int *@var{result}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} This function is similar to @code{lrand48}, but in addition it takes a pointer to a buffer describing the state of the random number generator @@ -1932,9 +1614,8 @@ This function is a GNU extension and should not be used in portable programs. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} The @code{nrand48_r} function works like @code{nrand48} in that it produces a random number in the range @code{0} to @code{2^31}. But instead @@ -1949,9 +1630,8 @@ This function is a GNU extension and should not be used in portable programs. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, long int *@var{result}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} This function is similar to @code{mrand48} but like the other reentrant functions it uses the random number generator described by the value in @@ -1964,9 +1644,8 @@ This function is a GNU extension and should not be used in portable programs. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} The @code{jrand48_r} function is similar to @code{jrand48}. Like the other reentrant functions of this function family it uses the @@ -1999,9 +1678,8 @@ buffer from looking at the parameter to the function, it is highly recommended to use these functions since the result might not always be what you expect. -@comment stdlib.h -@comment GNU @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} The description of the random number generator represented by the information in @var{buffer} is initialized similarly to what the function @@ -2015,9 +1693,8 @@ This function is a GNU extension and should not be used in portable programs. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} This function is similar to @code{srand48_r} but like @code{seed48} it initializes all 48 bits of the state from the parameter @var{seed16v}. @@ -2032,9 +1709,8 @@ This function is a GNU extension and should not be used in portable programs. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} This function initializes all aspects of the random number generator described in @var{buffer} with the data in @var{param}. Here it is diff --git a/manual/memory.texi b/manual/memory.texi index fb6b594ef1..82f473806c 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -342,9 +342,9 @@ To allocate a block of memory, call @code{malloc}. The prototype for this function is in @file{stdlib.h}. @pindex stdlib.h -@comment malloc.h stdlib.h -@comment ISO @deftypefun {void *} malloc (size_t @var{size}) +@standards{ISO, malloc.h} +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c Malloc hooks and __morecore pointers, as well as such parameters as @c max_n_mmaps and max_mmapped_mem, are accessed without guards, so they @@ -683,9 +683,9 @@ function @code{free} to make the block available to be allocated again. The prototype for this function is in @file{stdlib.h}. @pindex stdlib.h -@comment malloc.h stdlib.h -@comment ISO @deftypefun void free (void *@var{ptr}) +@standards{ISO, malloc.h} +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c __libc_free @asulock @aculock @acsfd @acsmem @c releasing memory into fastbins modifies the arena without taking @@ -755,9 +755,9 @@ You can make the block longer by calling @code{realloc} or @code{reallocarray}. These functions are declared in @file{stdlib.h}. @pindex stdlib.h -@comment malloc.h stdlib.h -@comment ISO @deftypefun {void *} realloc (void *@var{ptr}, size_t @var{newsize}) +@standards{ISO, malloc.h} +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c It may call the implementations of malloc and free, so all of their @c issues arise, plus the realloc hook, also accessed without guards. @@ -816,9 +816,9 @@ behavior, and will probably crash when @code{realloc} is passed a null pointer. @end deftypefun -@comment malloc.h stdlib.h -@comment BSD @deftypefun {void *} reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size}) +@standards{BSD, malloc.h} +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} The @code{reallocarray} function changes the size of the block whose address @@ -877,9 +877,9 @@ The function @code{calloc} allocates memory and clears it to zero. It is declared in @file{stdlib.h}. @pindex stdlib.h -@comment malloc.h stdlib.h -@comment ISO @deftypefun {void *} calloc (size_t @var{count}, size_t @var{eltsize}) +@standards{ISO, malloc.h} +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c Same caveats as malloc. @@ -935,8 +935,8 @@ power of two than that, use @code{aligned_alloc} or @code{posix_memalign}. @code{aligned_alloc} and @code{posix_memalign} are declared in @file{stdlib.h}. -@comment stdlib.h @deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size}) +@standards{???, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c Alias to memalign. The @code{aligned_alloc} function allocates a block of @var{size} bytes whose @@ -959,9 +959,8 @@ portability to modern non-POSIX systems than @code{posix_memalign}. @end deftypefun -@comment malloc.h -@comment BSD @deftypefun {void *} memalign (size_t @var{boundary}, size_t @var{size}) +@standards{BSD, malloc.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c Same issues as malloc. The padding bytes are safely freed in @c _int_memalign, with the arena still locked. @@ -1007,9 +1006,8 @@ The @code{memalign} function is obsolete and @code{aligned_alloc} or @code{posix_memalign} should be used instead. @end deftypefun -@comment stdlib.h -@comment POSIX @deftypefun int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size}) +@standards{POSIX, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c Calls memalign unless the requirements are not met (powerof2 macro is @c safe given an automatic variable as an argument) or there's a @@ -1039,9 +1037,9 @@ superseded by @code{aligned_alloc}, it is more portable to older POSIX systems that do not support @w{ISO C11}. @end deftypefun -@comment malloc.h stdlib.h -@comment BSD @deftypefun {void *} valloc (size_t @var{size}) +@standards{BSD, malloc.h} +@standards{BSD, stdlib.h} @safety{@prelim{}@mtunsafe{@mtuinit{}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{} @acsfd{} @acsmem{}}} @c __libc_valloc @mtuinit @asuinit @asulock @aculock @acsfd @acsmem @c ptmalloc_init (once) @mtsenv @asulock @aculock @acsfd @acsmem @@ -1208,9 +1206,8 @@ using the @code{mcheck} function. This function is a GNU extension, declared in @file{mcheck.h}. @pindex mcheck.h -@comment mcheck.h -@comment GNU @deftypefun int mcheck (void (*@var{abortfn}) (enum mcheck_status @var{status})) +@standards{GNU, mcheck.h} @safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} @c The hooks must be set up before malloc is first used, which sort of @c implies @mtuinit/@asuinit but since the function is a no-op if malloc @@ -1351,9 +1348,8 @@ dynamic memory allocation, for example. The hook variables are declared in @file{malloc.h}. @pindex malloc.h -@comment malloc.h -@comment GNU @defvar __malloc_hook +@standards{GNU, malloc.h} The value of this variable is a pointer to the function that @code{malloc} uses whenever it is called. You should define this function to look like @code{malloc}; that is, like: @@ -1367,9 +1363,8 @@ the @code{malloc} function was called. This value allows you to trace the memory consumption of the program. @end defvar -@comment malloc.h -@comment GNU @defvar __realloc_hook +@standards{GNU, malloc.h} The value of this variable is a pointer to function that @code{realloc} uses whenever it is called. You should define this function to look like @code{realloc}; that is, like: @@ -1383,9 +1378,8 @@ the @code{realloc} function was called. This value allows you to trace the memory consumption of the program. @end defvar -@comment malloc.h -@comment GNU @defvar __free_hook +@standards{GNU, malloc.h} The value of this variable is a pointer to function that @code{free} uses whenever it is called. You should define this function to look like @code{free}; that is, like: @@ -1399,9 +1393,8 @@ the @code{free} function was called. This value allows you to trace the memory consumption of the program. @end defvar -@comment malloc.h -@comment GNU @defvar __memalign_hook +@standards{GNU, malloc.h} The value of this variable is a pointer to function that @code{aligned_alloc}, @code{memalign}, @code{posix_memalign} and @code{valloc} use whenever they are called. You should define this function to look like @code{aligned_alloc}; @@ -1520,9 +1513,8 @@ are declared in @file{malloc.h}; they are an extension of the standard SVID/XPG version. @pindex malloc.h -@comment malloc.h -@comment GNU @deftp {Data Type} {struct mallinfo} +@standards{GNU, malloc.h} This structure type is used to return information about the dynamic memory allocator. It contains the following members: @@ -1567,9 +1559,8 @@ space's data segment). @end table @end deftp -@comment malloc.h -@comment SVID @deftypefun {struct mallinfo} mallinfo (void) +@standards{SVID, malloc.h} @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}} @c Accessing mp_.n_mmaps and mp_.max_mmapped_mem, modified with atomics @c but non-atomically elsewhere, may get us inconsistent results. We @@ -1688,9 +1679,8 @@ penalties for the program if the debugging mode is not enabled. @node Tracing malloc @subsubsection How to install the tracing functionality -@comment mcheck.h -@comment GNU @deftypefun void mtrace (void) +@standards{GNU, mcheck.h} @safety{@prelim{}@mtunsafe{@mtsenv{} @mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtuinit{}}@asunsafe{@asuinit{} @ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Like the mcheck hooks, these are not designed with thread safety in @c mind, because the hook pointers are temporarily modified without @@ -1725,9 +1715,8 @@ This function is a GNU extension and generally not available on other systems. The prototype can be found in @file{mcheck.h}. @end deftypefun -@comment mcheck.h -@comment GNU @deftypefun void muntrace (void) +@standards{GNU, mcheck.h} @safety{@prelim{}@mtunsafe{@mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{} @aculock{} @acsfd{}}} @c muntrace @mtasurace:mtrace @mtslocale @asucorrupt @ascuheap @acucorrupt @acsmem @aculock @acsfd @@ -2030,9 +2019,8 @@ The utilities for manipulating obstacks are declared in the header file @file{obstack.h}. @pindex obstack.h -@comment obstack.h -@comment GNU @deftp {Data Type} {struct obstack} +@standards{GNU, obstack.h} An obstack is represented by a data structure of type @code{struct obstack}. This structure has a small fixed size; it records the status of the obstack and how to find the space in which objects are allocated. @@ -2102,9 +2090,8 @@ At run time, before the program can use a @code{struct obstack} object as an obstack, it must initialize the obstack by calling @code{obstack_init}. -@comment obstack.h -@comment GNU @deftypefun int obstack_init (struct obstack *@var{obstack-ptr}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{@acsmem{}}} @c obstack_init @mtsrace:obstack-ptr @acsmem @c _obstack_begin @acsmem @@ -2146,9 +2133,8 @@ struct obstack *myobstack_ptr obstack_init (myobstack_ptr); @end smallexample -@comment obstack.h -@comment GNU @defvar obstack_alloc_failed_handler +@standards{GNU, obstack.h} The value of this variable is a pointer to a function that @code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate memory. The default action is to print a message and abort. @@ -2171,9 +2157,8 @@ obstack_alloc_failed_handler = &my_obstack_alloc_failed; The most direct way to allocate an object in an obstack is with @code{obstack_alloc}, which is invoked almost like @code{malloc}. -@comment obstack.h -@comment GNU @deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_alloc @mtsrace:obstack-ptr @acucorrupt @acsmem @c obstack_blank dup @mtsrace:obstack-ptr @acucorrupt @acsmem @@ -2209,9 +2194,8 @@ copystring (char *string) To allocate a block with specified contents, use the function @code{obstack_copy}, declared like this: -@comment obstack.h -@comment GNU @deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_copy @mtsrace:obstack-ptr @acucorrupt @acsmem @c obstack_grow dup @mtsrace:obstack-ptr @acucorrupt @acsmem @@ -2222,9 +2206,8 @@ bytes of data starting at @var{address}. It calls @code{obstack_chunk_alloc} failed. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_copy0 @mtsrace:obstack-ptr @acucorrupt @acsmem @c obstack_grow0 dup @mtsrace:obstack-ptr @acucorrupt @acsmem @@ -2258,9 +2241,8 @@ To free an object allocated in an obstack, use the function one object automatically frees all other objects allocated more recently in the same obstack. -@comment obstack.h -@comment GNU @deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}} @c obstack_free @mtsrace:obstack-ptr @acucorrupt @c (obstack_free) @mtsrace:obstack-ptr @acucorrupt @@ -2366,9 +2348,8 @@ While the obstack is in use for a growing object, you cannot use it for ordinary allocation of another object. If you try to do so, the space already added to the growing object will become part of the other object. -@comment obstack.h -@comment GNU @deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_blank @mtsrace:obstack-ptr @acucorrupt @acsmem @c _obstack_newchunk @mtsrace:obstack-ptr @acucorrupt @acsmem @@ -2380,9 +2361,8 @@ The most basic function for adding to a growing object is @code{obstack_blank}, which adds space without initializing it. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_grow @mtsrace:obstack-ptr @acucorrupt @acsmem @c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem @@ -2393,9 +2373,8 @@ bytes of data to the growing object, copying the contents from @var{data}. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_grow0 @mtsrace:obstack-ptr @acucorrupt @acsmem @c (no sequence point between storing NUL and incrementing next_free) @@ -2407,9 +2386,8 @@ This is the growing-object analogue of @code{obstack_copy0}. It adds character. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_1grow @mtsrace:obstack-ptr @acucorrupt @acsmem @c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem @@ -2418,9 +2396,8 @@ To add one character at a time, use the function @code{obstack_1grow}. It adds a single byte containing @var{c} to the growing object. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_ptr_grow @mtsrace:obstack-ptr @acucorrupt @acsmem @c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem @@ -2430,9 +2407,8 @@ Adding the value of a pointer one can use the function containing the value of @var{data}. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_int_grow @mtsrace:obstack-ptr @acucorrupt @acsmem @c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem @@ -2442,9 +2418,8 @@ A single value of type @code{int} can be added by using the the growing object and initializes them with the value of @var{data}. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}} @c obstack_finish @mtsrace:obstack-ptr @acucorrupt When you are finished growing the object, use the function @@ -2463,9 +2438,8 @@ the object, because you can find out the length from the obstack just before finishing the object with the function @code{obstack_object_size}, declared as follows: -@comment obstack.h -@comment GNU @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}} This function returns the current size of the growing object, in bytes. Remember to call this function @emph{before} finishing the object. @@ -2507,9 +2481,8 @@ more efficiently, then you make the program faster. The function @code{obstack_room} returns the amount of room available in the current chunk. It is declared as follows: -@comment obstack.h -@comment GNU @deftypefun int obstack_room (struct obstack *@var{obstack-ptr}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}} This returns the number of bytes that can be added safely to the current growing object (or to an object about to be started) in obstack @@ -2519,9 +2492,8 @@ growing object (or to an object about to be started) in obstack While you know there is room, you can use these fast growth functions for adding data to a growing object: -@comment obstack.h -@comment GNU @deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}} @c obstack_1grow_fast @mtsrace:obstack-ptr @acucorrupt @acsmem @c (no sequence point between copying c and incrementing next_free) @@ -2529,9 +2501,8 @@ The function @code{obstack_1grow_fast} adds one byte containing the character @var{c} to the growing object in obstack @var{obstack-ptr}. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}} @c obstack_ptr_grow_fast @mtsrace:obstack-ptr The function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)} @@ -2539,9 +2510,8 @@ bytes containing the value of @var{data} to the growing object in obstack @var{obstack-ptr}. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}} @c obstack_int_grow_fast @mtsrace:obstack-ptr The function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes @@ -2549,9 +2519,8 @@ containing the value of @var{data} to the growing object in obstack @var{obstack-ptr}. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}} @c obstack_blank_fast @mtsrace:obstack-ptr The function @code{obstack_blank_fast} adds @var{size} bytes to the @@ -2609,9 +2578,8 @@ Here are functions that provide information on the current status of allocation in an obstack. You can use them to learn about an object while still growing it. -@comment obstack.h -@comment GNU @deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}} This function returns the tentative address of the beginning of the currently growing object in @var{obstack-ptr}. If you finish the object @@ -2623,9 +2591,8 @@ allocate will start (once again assuming it fits in the current chunk). @end deftypefun -@comment obstack.h -@comment GNU @deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}} This function returns the address of the first free byte in the current chunk of obstack @var{obstack-ptr}. This is the end of the currently @@ -2633,9 +2600,8 @@ growing object. If no object is growing, @code{obstack_next_free} returns the same value as @code{obstack_base}. @end deftypefun -@comment obstack.h -@comment GNU @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr}) +@standards{GNU, obstack.h} @c dup @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}} This function returns the size in bytes of the currently growing object. @@ -2659,9 +2625,8 @@ To access an obstack's alignment boundary, use the macro @code{obstack_alignment_mask}, whose function prototype looks like this: -@comment obstack.h -@comment GNU @deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The value is a bit mask; a bit that is 1 indicates that the corresponding bit in the address of an object should be 0. The mask value should be one @@ -2727,9 +2692,8 @@ power of 2. The default chunk size, 4096, was chosen because it is long enough to satisfy many typical requests on the obstack yet short enough not to waste too much memory in the portion of the last chunk not yet used. -@comment obstack.h -@comment GNU @deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr}) +@standards{GNU, obstack.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This returns the chunk size of the given obstack. @end deftypefn @@ -2847,9 +2811,9 @@ The prototype for @code{alloca} is in @file{stdlib.h}. This function is a BSD extension. @pindex stdlib.h -@comment stdlib.h -@comment GNU, BSD @deftypefun {void *} alloca (size_t @var{size}) +@standards{GNU, stdlib.h} +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The return value of @code{alloca} is the address of a block of @var{size} bytes of memory, allocated in the stack frame of the calling function. @@ -3030,9 +2994,8 @@ are interfaces to a @glibcadj{} memory allocator that uses the functions below itself. The functions below are simple interfaces to system calls. -@comment unistd.h -@comment BSD @deftypefun int brk (void *@var{addr}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{brk} sets the high end of the calling process' data segment to @@ -3073,9 +3036,8 @@ exceed the process' data storage limit. @end deftypefun -@comment unistd.h -@comment BSD @deftypefun void *sbrk (ptrdiff_t @var{delta}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is the same as @code{brk} except that you specify the new @@ -3214,9 +3176,8 @@ memory page in bytes. It requires that when the @code{mlockall} and define the macro @code{_POSIX_MEMLOCK}. @Theglibc{} conforms to this requirement. -@comment sys/mman.h -@comment POSIX.1b @deftypefun int mlock (const void *@var{addr}, size_t @var{len}) +@standards{POSIX.1b, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{mlock} locks a range of the calling process' virtual pages. @@ -3268,9 +3229,8 @@ wouldn't know what address to tell @code{mlock}. @end deftypefun -@comment sys/mman.h -@comment POSIX.1b @deftypefun int munlock (const void *@var{addr}, size_t @var{len}) +@standards{POSIX.1b, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{munlock} unlocks a range of the calling process' virtual pages. @@ -3281,9 +3241,8 @@ failure. @end deftypefun -@comment sys/mman.h -@comment POSIX.1b @deftypefun int mlockall (int @var{flags}) +@standards{POSIX.1b, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{mlockall} locks all the pages in a process' virtual memory address @@ -3358,9 +3317,8 @@ with @code{munlockall} and @code{munlock}. @end deftypefun -@comment sys/mman.h -@comment POSIX.1b @deftypefun int munlockall (void) +@standards{POSIX.1b, sys/mman.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{munlockall} unlocks every page in the calling process' virtual diff --git a/manual/message.texi b/manual/message.texi index 2dae3edeb9..4cdff66eba 100644 --- a/manual/message.texi +++ b/manual/message.texi @@ -83,9 +83,8 @@ are defined/declared in the @file{nl_types.h} header file. @node The catgets Functions @subsection The @code{catgets} function family -@comment nl_types.h -@comment X/Open @deftypefun nl_catd catopen (const char *@var{cat_name}, int @var{flag}) +@standards{X/Open, nl_types.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c catopen @mtsenv @ascuheap @acsmem @c strchr ok @@ -830,9 +829,8 @@ the @file{libintl.h} header file. On systems where these functions are not part of the C library they can be found in a separate library named @file{libintl.a} (or accordingly different for shared libraries). -@comment libintl.h -@comment GNU @deftypefun {char *} gettext (const char *@var{msgid}) +@standards{GNU, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcgettext. The @code{gettext} function searches the currently selected message @@ -879,9 +877,8 @@ uses the @code{gettext} functions but since it must not depend on a currently selected default message catalog it must specify all ambiguous information. -@comment libintl.h -@comment GNU @deftypefun {char *} dgettext (const char *@var{domainname}, const char *@var{msgid}) +@standards{GNU, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcgettext. The @code{dgettext} function acts just like the @code{gettext} @@ -895,9 +892,8 @@ As for @code{gettext} the return value type is @code{char *} which is an anachronism. The returned string must never be modified. @end deftypefun -@comment libintl.h -@comment GNU @deftypefun {char *} dcgettext (const char *@var{domainname}, const char *@var{msgid}, int @var{category}) +@standards{GNU, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c dcgettext @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem @c dcigettext @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem @@ -1115,9 +1111,8 @@ domain named @code{foo}. The important point is that at any time exactly one domain is active. This is controlled with the following function. -@comment libintl.h -@comment GNU @deftypefun {char *} textdomain (const char *@var{domainname}) +@standards{GNU, libintl.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} @c textdomain @asulock @ascuheap @aculock @acsmem @c libc_rwlock_wrlock @asulock @aculock @@ -1153,9 +1148,8 @@ This possibility is questionable to use since the domain @code{messages} really never should be used. @end deftypefun -@comment libintl.h -@comment GNU @deftypefun {char *} bindtextdomain (const char *@var{domainname}, const char *@var{dirname}) +@standards{GNU, libintl.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c bindtextdomain @ascuheap @acsmem @c set_binding_values @ascuheap @acsmem @@ -1276,9 +1270,8 @@ GNU package and the coding standards for the GNU project require programs to be written in English, this solution nevertheless fulfills its purpose. -@comment libintl.h -@comment GNU @deftypefun {char *} ngettext (const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}) +@standards{GNU, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcngettext. The @code{ngettext} function is similar to the @code{gettext} function @@ -1301,9 +1294,8 @@ Please note that the numeric value @var{n} has to be passed to the @code{ngettext}. @end deftypefun -@comment libintl.h -@comment GNU @deftypefun {char *} dngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}) +@standards{GNU, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcngettext. The @code{dngettext} is similar to the @code{dgettext} function in the @@ -1312,9 +1304,8 @@ two extra parameters to provide the correct plural form. These two parameters are handled in the same way @code{ngettext} handles them. @end deftypefun -@comment libintl.h -@comment GNU @deftypefun {char *} dcngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}, int @var{category}) +@standards{GNU, libintl.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Wrapper for dcigettext. The @code{dcngettext} is similar to the @code{dcgettext} function in the @@ -1570,9 +1561,8 @@ translation for @var{msgid}, it returns @var{msgid} unchanged -- independently of the current output character set. It is therefore recommended that all @var{msgid}s be US-ASCII strings. -@comment libintl.h -@comment GNU @deftypefun {char *} bind_textdomain_codeset (const char *@var{domainname}, const char *@var{codeset}) +@standards{GNU, libintl.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c bind_textdomain_codeset @ascuheap @acsmem @c set_binding_values dup @ascuheap @acsmem diff --git a/manual/pattern.texi b/manual/pattern.texi index 069a6a23ea..39ae97a3c4 100644 --- a/manual/pattern.texi +++ b/manual/pattern.texi @@ -25,9 +25,8 @@ particular string. The result is a yes or no answer: does the string fit the pattern or not. The symbols described here are all declared in @file{fnmatch.h}. -@comment fnmatch.h -@comment POSIX.2 @deftypefun int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) +@standards{POSIX.2, fnmatch.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c fnmatch @mtsenv @mtslocale @ascuheap @acsmem @c strnlen dup ok @@ -75,24 +74,21 @@ returning nonzero values that are not equal to @code{FNM_NOMATCH}. These are the available flags for the @var{flags} argument: @vtable @code -@comment fnmatch.h -@comment GNU @item FNM_FILE_NAME +@standards{GNU, fnmatch.h} Treat the @samp{/} character specially, for matching file names. If this flag is set, wildcard constructs in @var{pattern} cannot match @samp{/} in @var{string}. Thus, the only way to match @samp{/} is with an explicit @samp{/} in @var{pattern}. -@comment fnmatch.h -@comment POSIX.2 @item FNM_PATHNAME +@standards{POSIX.2, fnmatch.h} This is an alias for @code{FNM_FILE_NAME}; it comes from POSIX.2. We don't recommend this name because we don't use the term ``pathname'' for file names. -@comment fnmatch.h -@comment POSIX.2 @item FNM_PERIOD +@standards{POSIX.2, fnmatch.h} Treat the @samp{.} character specially if it appears at the beginning of @var{string}. If this flag is set, wildcard constructs in @var{pattern} cannot match @samp{.} as the first character of @var{string}. @@ -103,9 +99,8 @@ special treatment applies to @samp{.} following @samp{/} as well as to @code{FNM_PERIOD} and @code{FNM_FILE_NAME} flags together for matching file names.) -@comment fnmatch.h -@comment POSIX.2 @item FNM_NOESCAPE +@standards{POSIX.2, fnmatch.h} Don't treat the @samp{\} character specially in patterns. Normally, @samp{\} quotes the following character, turning off its special meaning (if any) so that it matches only itself. When quoting is enabled, the @@ -114,9 +109,8 @@ mark in the pattern acts like an ordinary character. If you use @code{FNM_NOESCAPE}, then @samp{\} is an ordinary character. -@comment fnmatch.h -@comment GNU @item FNM_LEADING_DIR +@standards{GNU, fnmatch.h} Ignore a trailing sequence of characters starting with a @samp{/} in @var{string}; that is to say, test whether @var{string} starts with a directory name that @var{pattern} matches. @@ -124,14 +118,12 @@ directory name that @var{pattern} matches. If this flag is set, either @samp{foo*} or @samp{foobar} as a pattern would match the string @samp{foobar/frobozz}. -@comment fnmatch.h -@comment GNU @item FNM_CASEFOLD +@standards{GNU, fnmatch.h} Ignore case in comparing @var{string} to @var{pattern}. -@comment fnmatch.h -@comment GNU @item FNM_EXTMATCH +@standards{GNU, fnmatch.h} @cindex Korn Shell @pindex ksh Besides the normal patterns, also recognize the extended patterns @@ -193,9 +185,8 @@ this vector, @code{glob} uses a special data type, @code{glob_t}, which is a structure. You pass @code{glob} the address of the structure, and it fills in the structure's fields to tell you about the results. -@comment glob.h -@comment POSIX.2 @deftp {Data Type} glob_t +@standards{POSIX.2, glob.h} This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size. The GNU implementation contains some more fields which are non-standard @@ -314,9 +305,8 @@ definition for a very similar type. @code{glob64_t} differs from @code{glob_t} only in the types of the members @code{gl_readdir}, @code{gl_stat}, and @code{gl_lstat}. -@comment glob.h -@comment GNU @deftp {Data Type} glob64_t +@standards{GNU, glob.h} This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size. The GNU implementation contains some more fields which are non-standard @@ -393,9 +383,8 @@ This is a GNU extension. @end table @end deftp -@comment glob.h -@comment POSIX.2 @deftypefun int glob (const char *@var{pattern}, int @var{flags}, int (*@var{errfunc}) (const char *@var{filename}, int @var{error-code}), glob_t *@var{vector-ptr}) +@standards{POSIX.2, glob.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtsenv{} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c glob @mtasurace:utent @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c strlen dup ok @@ -480,9 +469,8 @@ If @code{glob} succeeds, it returns 0. Otherwise, it returns one of these error codes: @vtable @code -@comment glob.h -@comment POSIX.2 @item GLOB_ABORTED +@standards{POSIX.2, glob.h} There was an error opening a directory, and you used the flag @code{GLOB_ERR} or your specified @var{errfunc} returned a nonzero value. @@ -494,17 +482,15 @@ See below @end ifinfo for an explanation of the @code{GLOB_ERR} flag and @var{errfunc}. -@comment glob.h -@comment POSIX.2 @item GLOB_NOMATCH +@standards{POSIX.2, glob.h} The pattern didn't match any existing files. If you use the @code{GLOB_NOCHECK} flag, then you never get this error code, because that flag tells @code{glob} to @emph{pretend} that the pattern matched at least one file. -@comment glob.h -@comment POSIX.2 @item GLOB_NOSPACE +@standards{POSIX.2, glob.h} It was impossible to allocate memory to hold the result. @end vtable @@ -521,9 +507,8 @@ bit. If these callback functions are used and a large file or directory is encountered @code{glob} @emph{can} fail. @end deftypefun -@comment glob.h -@comment GNU @deftypefun int glob64 (const char *@var{pattern}, int @var{flags}, int (*@var{errfunc}) (const char *@var{filename}, int @var{error-code}), glob64_t *@var{vector-ptr}) +@standards{GNU, glob.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtsenv{} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Same code as glob, but with glob64_t #defined as glob_t. The @code{glob64} function was added as part of the Large File Summit @@ -552,9 +537,8 @@ and combine them with the C bitwise OR operator @code{|}. Note that there are @ref{More Flags for Globbing} available as GNU extensions. @vtable @code -@comment glob.h -@comment POSIX.2 @item GLOB_APPEND +@standards{POSIX.2, glob.h} Append the words from this expansion to the vector of words produced by previous calls to @code{glob}. This way you can effectively expand several words as if they were concatenated with spaces between them. @@ -570,16 +554,14 @@ have relocated the vector. So always fetch @code{gl_pathv} from the @code{glob_t} structure after each @code{glob} call; @strong{never} save the pointer across calls. -@comment glob.h -@comment POSIX.2 @item GLOB_DOOFFS +@standards{POSIX.2, glob.h} Leave blank slots at the beginning of the vector of words. The @code{gl_offs} field says how many slots to leave. The blank slots contain null pointers. -@comment glob.h -@comment POSIX.2 @item GLOB_ERR +@standards{POSIX.2, glob.h} Give up right away and report an error if there is any difficulty reading the directories that must be read in order to expand @var{pattern} fully. Such difficulties might include a directory in which you don't @@ -604,23 +586,20 @@ The argument @var{filename} is the name of the directory that If the error handler function returns nonzero, then @code{glob} gives up right away. Otherwise, it continues. -@comment glob.h -@comment POSIX.2 @item GLOB_MARK +@standards{POSIX.2, glob.h} If the pattern matches the name of a directory, append @samp{/} to the directory's name when returning it. -@comment glob.h -@comment POSIX.2 @item GLOB_NOCHECK +@standards{POSIX.2, glob.h} If the pattern doesn't match any file names, return the pattern itself as if it were a file name that had been matched. (Normally, when the pattern doesn't match anything, @code{glob} returns that there were no matches.) -@comment glob.h -@comment POSIX.2 @item GLOB_NOESCAPE +@standards{POSIX.2, glob.h} Don't treat the @samp{\} character specially in patterns. Normally, @samp{\} quotes the following character, turning off its special meaning (if any) so that it matches only itself. When quoting is enabled, the @@ -633,9 +612,8 @@ If you use @code{GLOB_NOESCAPE}, then @samp{\} is an ordinary character. repeatedly. It handles the flag @code{GLOB_NOESCAPE} by turning on the @code{FNM_NOESCAPE} flag in calls to @code{fnmatch}. -@comment glob.h -@comment POSIX.2 @item GLOB_NOSORT +@standards{POSIX.2, glob.h} Don't sort the file names; return them in no particular order. (In practice, the order will depend on the order of the entries in the directory.) The only reason @emph{not} to sort is to save time. @@ -650,23 +628,20 @@ Beside the flags described in the last section, the GNU implementation of which is available in modern shell implementations. @vtable @code -@comment glob.h -@comment GNU @item GLOB_PERIOD +@standards{GNU, glob.h} The @code{.} character (period) is treated special. It cannot be matched by wildcards. @xref{Wildcard Matching}, @code{FNM_PERIOD}. -@comment glob.h -@comment GNU @item GLOB_MAGCHAR +@standards{GNU, glob.h} The @code{GLOB_MAGCHAR} value is not to be given to @code{glob} in the @var{flags} parameter. Instead, @code{glob} sets this bit in the @var{gl_flags} element of the @var{glob_t} structure provided as the result if the pattern used for matching contains any wildcard character. -@comment glob.h -@comment GNU @item GLOB_ALTDIRFUNC +@standards{GNU, glob.h} Instead of using the normal functions for accessing the filesystem the @code{glob} implementation uses the user-supplied functions specified in the structure pointed to by @var{pglob} @@ -674,9 +649,8 @@ parameter. For more information about the functions refer to the sections about directory handling see @ref{Accessing Directories}, and @ref{Reading Attributes}. -@comment glob.h -@comment GNU @item GLOB_BRACE +@standards{GNU, glob.h} If this flag is given, the handling of braces in the pattern is changed. It is now required that braces appear correctly grouped. I.e., for each opening brace there must be a closing one. Braces can be used @@ -710,15 +684,13 @@ glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result) @noindent if we leave aside error handling. -@comment glob.h -@comment GNU @item GLOB_NOMAGIC +@standards{GNU, glob.h} If the pattern contains no wildcard constructs (it is a literal file name), return it as the sole ``matching'' word, even if no file exists by that name. -@comment glob.h -@comment GNU @item GLOB_TILDE +@standards{GNU, glob.h} If this flag is used the character @code{~} (tilde) is handled specially if it appears at the beginning of the pattern. Instead of being taken verbatim it is used to represent the home directory of a known user. @@ -753,9 +725,8 @@ looking for a directory named @code{~homer}. This functionality is equivalent to what is available in C-shells if the @code{nonomatch} flag is set. -@comment glob.h -@comment GNU @item GLOB_TILDE_CHECK +@standards{GNU, glob.h} If this flag is used @code{glob} behaves as if @code{GLOB_TILDE} is given. The only difference is that if the user name is not available or the home directory cannot be determined for other reasons this leads to @@ -765,9 +736,8 @@ the pattern itself as the name. This functionality is equivalent to what is available in C-shells if the @code{nonomatch} flag is not set. -@comment glob.h -@comment GNU @item GLOB_ONLYDIR +@standards{GNU, glob.h} If this flag is used the globbing function takes this as a @strong{hint} that the caller is only interested in directories matching the pattern. If the information about the type of the file @@ -787,9 +757,8 @@ type @code{glob_t} is used in multiple call to @code{glob} the resources are freed or reused so that no leaks appear. But this does not include the time when all @code{glob} calls are done. -@comment glob.h -@comment POSIX.2 @deftypefun void globfree (glob_t *@var{pglob}) +@standards{POSIX.2, glob.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c globfree dup @asucorrupt @ascuheap @acucorrupt @acsmem @c free dup @ascuheap @acsmem @@ -799,9 +768,8 @@ calls to @code{glob} associated with the object pointed to by @code{glob_t} typed object isn't used anymore. @end deftypefun -@comment glob.h -@comment GNU @deftypefun void globfree64 (glob64_t *@var{pglob}) +@standards{GNU, glob.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} This function is equivalent to @code{globfree} but it frees records of type @code{glob64_t} which were allocated by @code{glob64}. @@ -842,9 +810,8 @@ compiled regular expression for matching.) There is a special data type for compiled regular expressions: -@comment regex.h -@comment POSIX.2 @deftp {Data Type} regex_t +@standards{POSIX.2, regex.h} This type of object holds a compiled regular expression. It is actually a structure. It has just one field that your programs should look at: @@ -862,9 +829,8 @@ only the functions in the library should use them. After you create a @code{regex_t} object, you can compile a regular expression into it by calling @code{regcomp}. -@comment regex.h -@comment POSIX.2 @deftypefun int regcomp (regex_t *restrict @var{compiled}, const char *restrict @var{pattern}, int @var{cflags}) +@standards{POSIX.2, regex.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c All of the issues have to do with memory allocation and multi-byte @c character handling present in the input string, or implied by ranges @@ -1144,71 +1110,59 @@ describing the reason for a nonzero value; see @ref{Regexp Cleanup}. Here are the possible nonzero values that @code{regcomp} can return: @vtable @code -@comment regex.h -@comment POSIX.2 @item REG_BADBR +@standards{POSIX.2, regex.h} There was an invalid @samp{\@{@dots{}\@}} construct in the regular expression. A valid @samp{\@{@dots{}\@}} construct must contain either a single number, or two numbers in increasing order separated by a comma. -@comment regex.h -@comment POSIX.2 @item REG_BADPAT +@standards{POSIX.2, regex.h} There was a syntax error in the regular expression. -@comment regex.h -@comment POSIX.2 @item REG_BADRPT +@standards{POSIX.2, regex.h} A repetition operator such as @samp{?} or @samp{*} appeared in a bad position (with no preceding subexpression to act on). -@comment regex.h -@comment POSIX.2 @item REG_ECOLLATE +@standards{POSIX.2, regex.h} The regular expression referred to an invalid collating element (one not defined in the current locale for string collation). @xref{Locale Categories}. -@comment regex.h -@comment POSIX.2 @item REG_ECTYPE +@standards{POSIX.2, regex.h} The regular expression referred to an invalid character class name. -@comment regex.h -@comment POSIX.2 @item REG_EESCAPE +@standards{POSIX.2, regex.h} The regular expression ended with @samp{\}. -@comment regex.h -@comment POSIX.2 @item REG_ESUBREG +@standards{POSIX.2, regex.h} There was an invalid number in the @samp{\@var{digit}} construct. -@comment regex.h -@comment POSIX.2 @item REG_EBRACK +@standards{POSIX.2, regex.h} There were unbalanced square brackets in the regular expression. -@comment regex.h -@comment POSIX.2 @item REG_EPAREN +@standards{POSIX.2, regex.h} An extended regular expression had unbalanced parentheses, or a basic regular expression had unbalanced @samp{\(} and @samp{\)}. -@comment regex.h -@comment POSIX.2 @item REG_EBRACE +@standards{POSIX.2, regex.h} The regular expression had unbalanced @samp{\@{} and @samp{\@}}. -@comment regex.h -@comment POSIX.2 @item REG_ERANGE +@standards{POSIX.2, regex.h} One of the endpoints in a range expression was invalid. -@comment regex.h -@comment POSIX.2 @item REG_ESPACE +@standards{POSIX.2, regex.h} @code{regcomp} ran out of memory. @end vtable @@ -1219,25 +1173,21 @@ These are the bit flags that you can use in the @var{cflags} operand when compiling a regular expression with @code{regcomp}. @vtable @code -@comment regex.h -@comment POSIX.2 @item REG_EXTENDED +@standards{POSIX.2, regex.h} Treat the pattern as an extended regular expression, rather than as a basic regular expression. -@comment regex.h -@comment POSIX.2 @item REG_ICASE +@standards{POSIX.2, regex.h} Ignore case when matching letters. -@comment regex.h -@comment POSIX.2 @item REG_NOSUB +@standards{POSIX.2, regex.h} Don't bother storing the contents of the @var{matchptr} array. -@comment regex.h -@comment POSIX.2 @item REG_NEWLINE +@standards{POSIX.2, regex.h} Treat a newline in @var{string} as dividing @var{string} into multiple lines, so that @samp{$} can match before the newline and @samp{^} can match after. Also, don't permit @samp{.} to match a newline, and don't @@ -1255,9 +1205,8 @@ Regexp Compilation}, you can match it against strings using unless the regular expression contains anchor characters (@samp{^} or @samp{$}). -@comment regex.h -@comment POSIX.2 @deftypefun int regexec (const regex_t *restrict @var{compiled}, const char *restrict @var{string}, size_t @var{nmatch}, regmatch_t @var{matchptr}[restrict], int @var{eflags}) +@standards{POSIX.2, regex.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c libc_lock_lock @asulock @aculock @c re_search_internal @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd @@ -1525,16 +1474,14 @@ The function @code{regexec} accepts the following flags in the @var{eflags} argument: @vtable @code -@comment regex.h -@comment POSIX.2 @item REG_NOTBOL +@standards{POSIX.2, regex.h} Do not regard the beginning of the specified string as the beginning of a line; more generally, don't make any assumptions about what text might precede it. -@comment regex.h -@comment POSIX.2 @item REG_NOTEOL +@standards{POSIX.2, regex.h} Do not regard the end of the specified string as the end of a line; more generally, don't make any assumptions about what text might follow it. @end vtable @@ -1542,14 +1489,12 @@ generally, don't make any assumptions about what text might follow it. Here are the possible nonzero values that @code{regexec} can return: @vtable @code -@comment regex.h -@comment POSIX.2 @item REG_NOMATCH +@standards{POSIX.2, regex.h} The pattern didn't match the string. This isn't really an error. -@comment regex.h -@comment POSIX.2 @item REG_ESPACE +@standards{POSIX.2, regex.h} @code{regexec} ran out of memory. @end vtable @@ -1565,9 +1510,8 @@ the entire regular expression. Each other element of the array records the beginning and end of the part that matched a single parenthetical subexpression. -@comment regex.h -@comment POSIX.2 @deftp {Data Type} regmatch_t +@standards{POSIX.2, regex.h} This is the data type of the @var{matchptr} array that you pass to @code{regexec}. It contains two structure fields, as follows: @@ -1581,9 +1525,8 @@ The offset in @var{string} of the end of the substring. @end table @end deftp -@comment regex.h -@comment POSIX.2 @deftp {Data Type} regoff_t +@standards{POSIX.2, regex.h} @code{regoff_t} is an alias for another signed integer type. The fields of @code{regmatch_t} have type @code{regoff_t}. @end deftp @@ -1658,9 +1601,8 @@ reports nonuse of the ``na'' subexpression. When you are finished using a compiled regular expression, you can free the storage it uses by calling @code{regfree}. -@comment regex.h -@comment POSIX.2 @deftypefun void regfree (regex_t *@var{compiled}) +@standards{POSIX.2, regex.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c (re_)free dup @ascuheap @acsmem @c free_dfa_content dup @ascuheap @acsmem @@ -1678,9 +1620,8 @@ expression. When @code{regcomp} or @code{regexec} reports an error, you can use the function @code{regerror} to turn it into an error message string. -@comment regex.h -@comment POSIX.2 @deftypefun size_t regerror (int @var{errcode}, const regex_t *restrict @var{compiled}, char *restrict @var{buffer}, size_t @var{length}) +@standards{POSIX.2, regex.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c regerror calls gettext, strcmp and mempcpy or memcpy. This function produces an error message string for the error code @@ -1816,9 +1757,8 @@ vector, @code{wordexp} uses a special data type, @code{wordexp_t}, which is a structure. You pass @code{wordexp} the address of the structure, and it fills in the structure's fields to tell you about the results. -@comment wordexp.h -@comment POSIX.2 @deftp {Data Type} {wordexp_t} +@standards{POSIX.2, wordexp.h} This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size. @@ -1845,9 +1785,8 @@ the beginning of the vector. @end table @end deftp -@comment wordexp.h -@comment POSIX.2 @deftypefun int wordexp (const char *@var{words}, wordexp_t *@var{word-vector-ptr}, int @var{flags}) +@standards{POSIX.2, wordexp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtasuconst{:@mtsenv{}} @mtsenv{} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuintl{} @ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c wordexp @mtasurace:utent @mtasuconst:@mtsenv @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuintl @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem @c w_newword ok @@ -2014,43 +1953,37 @@ If @code{wordexp} succeeds, it returns 0. Otherwise, it returns one of these error codes: @vtable @code -@comment wordexp.h -@comment POSIX.2 @item WRDE_BADCHAR +@standards{POSIX.2, wordexp.h} The input string @var{words} contains an unquoted invalid character such as @samp{|}. -@comment wordexp.h -@comment POSIX.2 @item WRDE_BADVAL +@standards{POSIX.2, wordexp.h} The input string refers to an undefined shell variable, and you used the flag @code{WRDE_UNDEF} to forbid such references. -@comment wordexp.h -@comment POSIX.2 @item WRDE_CMDSUB +@standards{POSIX.2, wordexp.h} The input string uses command substitution, and you used the flag @code{WRDE_NOCMD} to forbid command substitution. -@comment wordexp.h -@comment POSIX.2 @item WRDE_NOSPACE +@standards{POSIX.2, wordexp.h} It was impossible to allocate memory to hold the result. In this case, @code{wordexp} can store part of the results---as much as it could allocate room for. -@comment wordexp.h -@comment POSIX.2 @item WRDE_SYNTAX +@standards{POSIX.2, wordexp.h} There was a syntax error in the input string. For example, an unmatched quoting character is a syntax error. This error code is also used to signal division by zero and overflow in arithmetic expansion. @end vtable @end deftypefun -@comment wordexp.h -@comment POSIX.2 @deftypefun void wordfree (wordexp_t *@var{word-vector-ptr}) +@standards{POSIX.2, wordexp.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c wordfree dup @asucorrupt @ascuheap @acucorrupt @acsmem @c free dup @ascuheap @acsmem @@ -2068,9 +2001,8 @@ This section describes the flags that you can specify in the and combine them with the C operator @code{|}. @vtable @code -@comment wordexp.h -@comment POSIX.2 @item WRDE_APPEND +@standards{POSIX.2, wordexp.h} Append the words from this expansion to the vector of words produced by previous calls to @code{wordexp}. This way you can effectively expand several words as if they were concatenated with spaces between them. @@ -2080,22 +2012,19 @@ word vector structure between calls to @code{wordexp}. And, if you set @code{WRDE_DOOFFS} in the first call to @code{wordexp}, you must also set it when you append to the results. -@comment wordexp.h -@comment POSIX.2 @item WRDE_DOOFFS +@standards{POSIX.2, wordexp.h} Leave blank slots at the beginning of the vector of words. The @code{we_offs} field says how many slots to leave. The blank slots contain null pointers. -@comment wordexp.h -@comment POSIX.2 @item WRDE_NOCMD +@standards{POSIX.2, wordexp.h} Don't do command substitution; if the input requests command substitution, report an error. -@comment wordexp.h -@comment POSIX.2 @item WRDE_REUSE +@standards{POSIX.2, wordexp.h} Reuse a word vector made by a previous call to @code{wordexp}. Instead of allocating a new vector of words, this call to @code{wordexp} will use the vector that already exists (making it larger if necessary). @@ -2104,17 +2033,15 @@ Note that the vector may move, so it is not safe to save an old pointer and use it again after calling @code{wordexp}. You must fetch @code{we_pathv} anew after each call. -@comment wordexp.h -@comment POSIX.2 @item WRDE_SHOWERR +@standards{POSIX.2, wordexp.h} Do show any error messages printed by commands run by command substitution. More precisely, allow these commands to inherit the standard error output stream of the current process. By default, @code{wordexp} gives these commands a standard error stream that discards all output. -@comment wordexp.h -@comment POSIX.2 @item WRDE_UNDEF +@standards{POSIX.2, wordexp.h} If the input refers to a shell variable that is not defined, report an error. @end vtable diff --git a/manual/pipe.texi b/manual/pipe.texi index 2d7e30e796..483c40c5c3 100644 --- a/manual/pipe.texi +++ b/manual/pipe.texi @@ -53,9 +53,8 @@ The @code{pipe} function is declared in the header file @file{unistd.h}. @pindex unistd.h -@comment unistd.h -@comment POSIX.1 @deftypefun int pipe (int @var{filedes}@t{[2]}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} @c On Linux, syscall pipe2. On HURD, call socketpair. The @code{pipe} function creates a pipe and puts the file descriptors @@ -107,9 +106,10 @@ The advantage of using @code{popen} and @code{pclose} is that the interface is much simpler and easier to use. But it doesn't offer as much flexibility as using the low-level functions directly. -@comment stdio.h -@comment POSIX.2, SVID, BSD @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode}) +@standards{POSIX.2, stdio.h} +@standards{SVID, stdio.h} +@standards{BSD, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c popen @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem @c malloc dup @ascuheap @acsmem @@ -165,9 +165,10 @@ might happen if the pipe or stream cannot be created, if the subprocess cannot be forked, or if the program cannot be executed. @end deftypefun -@comment stdio.h -@comment POSIX.2, SVID, BSD @deftypefun int pclose (FILE *@var{stream}) +@standards{POSIX.2, stdio.h} +@standards{SVID, stdio.h} +@standards{BSD, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuplugin{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c Although the stream cannot be used after the call, even in case of @c async cancellation, because the stream must not be used after pclose @@ -273,9 +274,8 @@ The @code{mkfifo} function is declared in the header file @file{sys/stat.h}. @pindex sys/stat.h -@comment sys/stat.h -@comment POSIX.1 @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode}) +@standards{POSIX.1, sys/stat.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On generic Posix, calls xmknod. The @code{mkfifo} function makes a FIFO special file with name diff --git a/manual/process.texi b/manual/process.texi index 085fdec926..b82b91f9f1 100644 --- a/manual/process.texi +++ b/manual/process.texi @@ -51,9 +51,8 @@ function. This function does all the work of running a subprogram, but it doesn't give you much control over the details: you have to wait until the subprogram terminates before you can do anything else. -@comment stdlib.h -@comment ISO @deftypefun int system (const char *@var{command}) +@standards{ISO, stdlib.h} @pindex sh @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} @c system @ascuplugin @ascuheap @asulock @aculock @acsmem @@ -184,23 +183,20 @@ program should include the header files @file{unistd.h} and @pindex sys/types.h @pindex unistd.h -@comment sys/types.h -@comment POSIX.1 @deftp {Data Type} pid_t +@standards{POSIX.1, sys/types.h} The @code{pid_t} data type is a signed integer type which is capable of representing a process ID. In @theglibc{}, this is an @code{int}. @end deftp -@comment unistd.h -@comment POSIX.1 @deftypefun pid_t getpid (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getpid} function returns the process ID of the current process. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun pid_t getppid (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getppid} function returns the process ID of the parent of the current process. @@ -213,9 +209,8 @@ The @code{fork} function is the primitive for creating a process. It is declared in the header file @file{unistd.h}. @pindex unistd.h -@comment unistd.h -@comment POSIX.1 @deftypefun pid_t fork (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{}}@acunsafe{@aculock{}}} @c The nptl/.../linux implementation safely collects fork_handlers into @c an alloca()ed linked list and increments ref counters; it uses atomic @@ -291,9 +286,8 @@ signals and signal actions from the parent process.) @end itemize -@comment unistd.h -@comment BSD @deftypefun pid_t vfork (void) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{}}@acunsafe{@aculock{}}} @c The vfork implementation proper is a safe syscall, but it may fall @c back to fork if the vfork syscall is not available. @@ -339,9 +333,8 @@ The functions in this family differ in how you specify the arguments, but otherwise they all do the same thing. They are declared in the header file @file{unistd.h}. -@comment unistd.h -@comment POSIX.1 @deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{execv} function executes the file named by @var{filename} as a new process image. @@ -358,18 +351,16 @@ The environment for the new process image is taken from the @ref{Environment Variables}, for information about environments. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is similar to @code{execv}, but the @var{argv} strings are specified individually instead of as an array. A null pointer must be passed as the last such argument. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is similar to @code{execv}, but permits you to specify the environment for the new program explicitly as the @var{env} argument. This should @@ -377,9 +368,8 @@ be an array of strings in the same format as for the @code{environ} variable; see @ref{Environment Access}. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, @dots{}, char *const @var{env}@t{[]}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is similar to @code{execl}, but permits you to specify the environment for the new program explicitly. The environment argument is @@ -388,9 +378,8 @@ argument, and should be an array of strings in the same format as for the @code{environ} variable. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{execvp} function is similar to @code{execv}, except that it searches the directories listed in the @code{PATH} environment variable @@ -402,9 +391,8 @@ it looks for them in the places that the user has chosen. Shells use it to run the commands that users type. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function is like @code{execl}, except that it performs the same file name searching as the @code{execvp} function. @@ -520,9 +508,8 @@ process to terminate or stop, and determine its status. These functions are declared in the header file @file{sys/wait.h}. @pindex sys/wait.h -@comment sys/wait.h -@comment POSIX.1 @deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status-ptr}, int @var{options}) +@standards{POSIX.1, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{waitpid} function is used to request status information from a child process whose process ID is @var{pid}. Normally, the calling @@ -624,9 +611,8 @@ child processes that have been stopped as well as those that have terminated. @end vtable -@comment sys/wait.h -@comment POSIX.1 @deftypefun pid_t wait (int *@var{status-ptr}) +@standards{POSIX.1, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is a simplified version of @code{waitpid}, and is used to wait until any one child process terminates. The call: @@ -651,9 +637,8 @@ protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop @end deftypefun -@comment sys/wait.h -@comment BSD @deftypefun pid_t wait4 (pid_t @var{pid}, int *@var{status-ptr}, int @var{options}, struct rusage *@var{usage}) +@standards{BSD, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If @var{usage} is a null pointer, @code{wait4} is equivalent to @code{waitpid (@var{pid}, @var{status-ptr}, @var{options})}. @@ -704,58 +689,51 @@ encoded in the returned status value using the following macros. These macros are defined in the header file @file{sys/wait.h}. @pindex sys/wait.h -@comment sys/wait.h -@comment POSIX.1 @deftypefn Macro int WIFEXITED (int @var{status}) +@standards{POSIX.1, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if the child process terminated normally with @code{exit} or @code{_exit}. @end deftypefn -@comment sys/wait.h -@comment POSIX.1 @deftypefn Macro int WEXITSTATUS (int @var{status}) +@standards{POSIX.1, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If @code{WIFEXITED} is true of @var{status}, this macro returns the low-order 8 bits of the exit status value from the child process. @xref{Exit Status}. @end deftypefn -@comment sys/wait.h -@comment POSIX.1 @deftypefn Macro int WIFSIGNALED (int @var{status}) +@standards{POSIX.1, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if the child process terminated because it received a signal that was not handled. @xref{Signal Handling}. @end deftypefn -@comment sys/wait.h -@comment POSIX.1 @deftypefn Macro int WTERMSIG (int @var{status}) +@standards{POSIX.1, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If @code{WIFSIGNALED} is true of @var{status}, this macro returns the signal number of the signal that terminated the child process. @end deftypefn -@comment sys/wait.h -@comment BSD @deftypefn Macro int WCOREDUMP (int @var{status}) +@standards{BSD, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if the child process terminated and produced a core dump. @end deftypefn -@comment sys/wait.h -@comment POSIX.1 @deftypefn Macro int WIFSTOPPED (int @var{status}) +@standards{POSIX.1, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if the child process is stopped. @end deftypefn -@comment sys/wait.h -@comment POSIX.1 @deftypefn Macro int WSTOPSIG (int @var{status}) +@standards{POSIX.1, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If @code{WIFSTOPPED} is true of @var{status}, this macro returns the signal number of the signal that caused the child process to stop. @@ -771,9 +749,8 @@ predecessor to @code{wait4}, which is more flexible. @code{wait3} is now obsolete. @pindex sys/wait.h -@comment sys/wait.h -@comment BSD @deftypefun pid_t wait3 (int *@var{status-ptr}, int @var{options}, struct rusage *@var{usage}) +@standards{BSD, sys/wait.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If @var{usage} is a null pointer, @code{wait3} is equivalent to @code{waitpid (-1, @var{status-ptr}, @var{options})}. diff --git a/manual/resource.texi b/manual/resource.texi index 40160384fc..8bc2a803d4 100644 --- a/manual/resource.texi +++ b/manual/resource.texi @@ -22,9 +22,8 @@ The function @code{getrusage} and the data type @code{struct rusage} are used to examine the resource usage of a process. They are declared in @file{sys/resource.h}. -@comment sys/resource.h -@comment BSD @deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage}) +@standards{BSD, sys/resource.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On HURD, this calls task_info 3 times. On UNIX, it's a syscall. This function reports resource usage totals for processes specified by @@ -33,14 +32,12 @@ This function reports resource usage totals for processes specified by In most systems, @var{processes} has only two valid values: @vtable @code -@comment sys/resource.h -@comment BSD @item RUSAGE_SELF +@standards{BSD, sys/resource.h} Just the current process. -@comment sys/resource.h -@comment BSD @item RUSAGE_CHILDREN +@standards{BSD, sys/resource.h} All child processes (direct and indirect) that have already terminated. @end vtable @@ -57,9 +54,8 @@ One way of getting resource usage for a particular child process is with the function @code{wait4}, which returns totals for a child when it terminates. @xref{BSD Wait Functions}. -@comment sys/resource.h -@comment BSD @deftp {Data Type} {struct rusage} +@standards{BSD, sys/resource.h} This data type stores various resource usage statistics. It has the following members, and possibly others: @@ -132,8 +128,8 @@ scheduled). @file{sys/vtimes.h}. @pindex sys/vtimes.h -@comment sys/vtimes.h @deftypefun int vtimes (struct vtimes *@var{current}, struct vtimes *@var{child}) +@standards{???, sys/vtimes.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Calls getrusage twice. @@ -224,9 +220,8 @@ The symbols for use with @code{getrlimit}, @code{setrlimit}, @code{getrlimit64}, and @code{setrlimit64} are defined in @file{sys/resource.h}. -@comment sys/resource.h -@comment BSD @deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp}) +@standards{BSD, sys/resource.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on most systems. Read the current and maximum limits for the resource @var{resource} @@ -240,9 +235,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a LFS interface transparently replaces the old interface. @end deftypefun -@comment sys/resource.h -@comment Unix98 @deftypefun int getrlimit64 (int @var{resource}, struct rlimit64 *@var{rlp}) +@standards{Unix98, sys/resource.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on most systems, wrapper to getrlimit otherwise. This function is similar to @code{getrlimit} but its second parameter is @@ -255,9 +249,8 @@ If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a @code{getrlimit} and so transparently replaces the old interface. @end deftypefun -@comment sys/resource.h -@comment BSD @deftypefun int setrlimit (int @var{resource}, const struct rlimit *@var{rlp}) +@standards{BSD, sys/resource.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on most systems; lock-taking critical section on HURD. Store the current and maximum limits for the resource @var{resource} @@ -282,9 +275,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a LFS interface transparently replaces the old interface. @end deftypefun -@comment sys/resource.h -@comment Unix98 @deftypefun int setrlimit64 (int @var{resource}, const struct rlimit64 *@var{rlp}) +@standards{Unix98, sys/resource.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Wrapper for setrlimit or direct syscall. This function is similar to @code{setrlimit} but its second parameter is @@ -297,9 +289,8 @@ If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a @code{setrlimit} and so transparently replaces the old interface. @end deftypefun -@comment sys/resource.h -@comment BSD @deftp {Data Type} {struct rlimit} +@standards{BSD, sys/resource.h} This structure is used with @code{getrlimit} to receive limit values, and with @code{setrlimit} to specify limit values for a particular process and resource. It has two fields: @@ -318,9 +309,8 @@ values. For @code{setrlimit}, it specifies the new values. For the LFS functions a similar type is defined in @file{sys/resource.h}. -@comment sys/resource.h -@comment Unix98 @deftp {Data Type} {struct rlimit64} +@standards{Unix98, sys/resource.h} This structure is analogous to the @code{rlimit} structure above, but its components have wider ranges. It has two fields: @@ -338,90 +328,78 @@ Here is a list of resources for which you can specify a limit. Memory and file sizes are measured in bytes. @vtable @code -@comment sys/resource.h -@comment BSD @item RLIMIT_CPU +@standards{BSD, sys/resource.h} The maximum amount of CPU time the process can use. If it runs for longer than this, it gets a signal: @code{SIGXCPU}. The value is measured in seconds. @xref{Operation Error Signals}. -@comment sys/resource.h -@comment BSD @item RLIMIT_FSIZE +@standards{BSD, sys/resource.h} The maximum size of file the process can create. Trying to write a larger file causes a signal: @code{SIGXFSZ}. @xref{Operation Error Signals}. -@comment sys/resource.h -@comment BSD @item RLIMIT_DATA +@standards{BSD, sys/resource.h} The maximum size of data memory for the process. If the process tries to allocate data memory beyond this amount, the allocation function fails. -@comment sys/resource.h -@comment BSD @item RLIMIT_STACK +@standards{BSD, sys/resource.h} The maximum stack size for the process. If the process tries to extend its stack past this size, it gets a @code{SIGSEGV} signal. @xref{Program Error Signals}. -@comment sys/resource.h -@comment BSD @item RLIMIT_CORE +@standards{BSD, sys/resource.h} The maximum size core file that this process can create. If the process terminates and would dump a core file larger than this, then no core file is created. So setting this limit to zero prevents core files from ever being created. -@comment sys/resource.h -@comment BSD @item RLIMIT_RSS +@standards{BSD, sys/resource.h} The maximum amount of physical memory that this process should get. This parameter is a guide for the system's scheduler and memory allocator; the system may give the process more memory when there is a surplus. -@comment sys/resource.h -@comment BSD @item RLIMIT_MEMLOCK +@standards{BSD, sys/resource.h} The maximum amount of memory that can be locked into physical memory (so it will never be paged out). -@comment sys/resource.h -@comment BSD @item RLIMIT_NPROC +@standards{BSD, sys/resource.h} The maximum number of processes that can be created with the same user ID. If you have reached the limit for your user ID, @code{fork} will fail with @code{EAGAIN}. @xref{Creating a Process}. -@comment sys/resource.h -@comment BSD @item RLIMIT_NOFILE @itemx RLIMIT_OFILE +@standardsx{RLIMIT_NOFILE, BSD, sys/resource.h} The maximum number of files that the process can open. If it tries to open more files than this, its open attempt fails with @code{errno} @code{EMFILE}. @xref{Error Codes}. Not all systems support this limit; GNU does, and 4.4 BSD does. -@comment sys/resource.h -@comment Unix98 @item RLIMIT_AS +@standards{Unix98, sys/resource.h} The maximum size of total memory that this process should get. If the process tries to allocate more memory beyond this amount with, for example, @code{brk}, @code{malloc}, @code{mmap} or @code{sbrk}, the allocation function fails. -@comment sys/resource.h -@comment BSD @item RLIM_NLIMITS +@standards{BSD, sys/resource.h} The number of different resource limits. Any valid @var{resource} operand must be less than @code{RLIM_NLIMITS}. @end vtable -@comment sys/resource.h -@comment BSD @deftypevr Constant rlim_t RLIM_INFINITY +@standards{BSD, sys/resource.h} This constant stands for a value of ``infinity'' when supplied as the limit value in @code{setrlimit}. @end deftypevr @@ -433,9 +411,8 @@ above do. The functions above are better choices. @code{ulimit} and the command symbols are declared in @file{ulimit.h}. @pindex ulimit.h -@comment ulimit.h -@comment BSD @deftypefun {long int} ulimit (int @var{cmd}, @dots{}) +@standards{BSD, ulimit.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Wrapper for getrlimit, setrlimit or @c sysconf(_SC_OPEN_MAX)->getdtablesize->getrlimit. @@ -482,9 +459,8 @@ A process tried to increase a maximum limit, but is not superuser. @code{vlimit} and its resource symbols are declared in @file{sys/vlimit.h}. @pindex sys/vlimit.h -@comment sys/vlimit.h -@comment BSD @deftypefun int vlimit (int @var{resource}, int @var{limit}) +@standards{BSD, sys/vlimit.h} @safety{@prelim{}@mtunsafe{@mtasurace{:setrlimit}}@asunsafe{}@acsafe{}} @c It calls getrlimit and modifies the rlim_cur field before calling @c setrlimit. There's a window for a concurrent call to setrlimit that @@ -774,9 +750,8 @@ policy, if anything, only fine tunes the effect of that priority. The symbols in this section are declared by including file @file{sched.h}. -@comment sched.h -@comment POSIX @deftp {Data Type} {struct sched_param} +@standards{POSIX, sched.h} This structure describes an absolute priority. @table @code @item int sched_priority @@ -784,9 +759,8 @@ absolute priority value @end table @end deftp -@comment sched.h -@comment POSIX @deftypefun int sched_setscheduler (pid_t @var{pid}, int @var{policy}, const struct sched_param *@var{param}) +@standards{POSIX, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. @@ -856,9 +830,8 @@ tell you what the valid range is. @end deftypefun -@comment sched.h -@comment POSIX @deftypefun int sched_getscheduler (pid_t @var{pid}) +@standards{POSIX, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. @@ -891,9 +864,8 @@ absolute priority, use @code{sched_getparam}. @end deftypefun -@comment sched.h -@comment POSIX @deftypefun int sched_setparam (pid_t @var{pid}, const struct sched_param *@var{param}) +@standards{POSIX, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. @@ -906,9 +878,8 @@ It is functionally identical to @code{sched_setscheduler} with @end deftypefun -@comment sched.h -@comment POSIX @deftypefun int sched_getparam (pid_t @var{pid}, struct sched_param *@var{param}) +@standards{POSIX, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. @@ -937,9 +908,8 @@ There is no process with pid @var{pid} and it is not zero. @end deftypefun -@comment sched.h -@comment POSIX @deftypefun int sched_get_priority_min (int @var{policy}) +@standards{POSIX, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. @@ -959,9 +929,8 @@ to this function are: @end deftypefun -@comment sched.h -@comment POSIX @deftypefun int sched_get_priority_max (int @var{policy}) +@standards{POSIX, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. @@ -981,9 +950,8 @@ to this function are: @end deftypefun -@comment sched.h -@comment POSIX @deftypefun int sched_rr_get_interval (pid_t @var{pid}, struct timespec *@var{interval}) +@standards{POSIX, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. @@ -1007,9 +975,8 @@ function, so there are no specific @code{errno} values. @end deftypefun -@comment sched.h -@comment POSIX @deftypefun int sched_yield (void) +@standards{POSIX, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on Linux; alias to swtch on HURD. @@ -1149,20 +1116,18 @@ higher priority for the process. These constants describe the range of priority values: @vtable @code -@comment sys/resource.h -@comment BSD @item PRIO_MIN +@standards{BSD, sys/resource.h} The lowest valid nice value. -@comment sys/resource.h -@comment BSD @item PRIO_MAX +@standards{BSD, sys/resource.h} The highest valid nice value. @end vtable -@comment sys/resource.h -@comment BSD, POSIX @deftypefun int getpriority (int @var{class}, int @var{id}) +@standards{BSD, sys/resource.h} +@standards{POSIX, sys/resource.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on UNIX. On HURD, calls _hurd_priority_which_map. Return the nice value of a set of processes; @var{class} and @var{id} @@ -1189,9 +1154,9 @@ be the nice value. The only way to make certain is to set @code{errno = afterward as the criterion for failure. @end deftypefun -@comment sys/resource.h -@comment BSD, POSIX @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{niceval}) +@standards{BSD, sys/resource.h} +@standards{POSIX, sys/resource.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on UNIX. On HURD, calls _hurd_priority_which_map. Set the nice value of a set of processes to @var{niceval}; @var{class} @@ -1227,20 +1192,17 @@ processes in which you are interested. These are the possible values of @var{class}: @vtable @code -@comment sys/resource.h -@comment BSD @item PRIO_PROCESS +@standards{BSD, sys/resource.h} One particular process. The argument @var{id} is a process ID (pid). -@comment sys/resource.h -@comment BSD @item PRIO_PGRP +@standards{BSD, sys/resource.h} All the processes in a particular process group. The argument @var{id} is a process group ID (pgid). -@comment sys/resource.h -@comment BSD @item PRIO_USER +@standards{BSD, sys/resource.h} All the processes owned by a particular user (i.e., whose real uid indicates the user). The argument @var{id} is a user ID (uid). @end vtable @@ -1248,9 +1210,8 @@ indicates the user). The argument @var{id} is a user ID (uid). If the argument @var{id} is 0, it stands for the calling process, its process group, or its owner (real uid), according to @var{class}. -@comment unistd.h -@comment BSD @deftypefun int nice (int @var{increment}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:setpriority}}@asunsafe{}@acsafe{}} @c Calls getpriority before and after setpriority, using the result of @c the first call to compute the argument for setpriority. This creates @@ -1323,9 +1284,8 @@ schedule the thread or process on CPUs specified by the affinity masks. The interfaces which @theglibc{} define follow to some extent the Linux kernel interface. -@comment sched.h -@comment GNU @deftp {Data Type} cpu_set_t +@standards{GNU, sched.h} This data set is a bitset where each bit represents a CPU. How the system's CPUs are mapped to bits in the bitset is system dependent. The data type has a fixed size; in the unlikely case that the number @@ -1340,9 +1300,8 @@ defined. Some of the macros take a CPU number as a parameter. Here it is important to never exceed the size of the bitset. The following macro specifies the number of bits in the @code{cpu_set_t} bitset. -@comment sched.h -@comment GNU @deftypevr Macro int CPU_SETSIZE +@standards{GNU, sched.h} The value of this macro is the maximum number of CPUs which can be handled with a @code{cpu_set_t} object. @end deftypevr @@ -1350,9 +1309,8 @@ handled with a @code{cpu_set_t} object. The type @code{cpu_set_t} should be considered opaque; all manipulation should happen via the next four macros. -@comment sched.h -@comment GNU @deftypefn Macro void CPU_ZERO (cpu_set_t *@var{set}) +@standards{GNU, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c CPU_ZERO ok @c __CPU_ZERO_S ok @@ -1362,9 +1320,8 @@ This macro initializes the CPU set @var{set} to be the empty set. This macro is a GNU extension and is defined in @file{sched.h}. @end deftypefn -@comment sched.h -@comment GNU @deftypefn Macro void CPU_SET (int @var{cpu}, cpu_set_t *@var{set}) +@standards{GNU, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c CPU_SET ok @c __CPU_SET_S ok @@ -1378,9 +1335,8 @@ evaluated more than once. This macro is a GNU extension and is defined in @file{sched.h}. @end deftypefn -@comment sched.h -@comment GNU @deftypefn Macro void CPU_CLR (int @var{cpu}, cpu_set_t *@var{set}) +@standards{GNU, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c CPU_CLR ok @c __CPU_CLR_S ok @@ -1394,9 +1350,8 @@ evaluated more than once. This macro is a GNU extension and is defined in @file{sched.h}. @end deftypefn -@comment sched.h -@comment GNU @deftypefn Macro int CPU_ISSET (int @var{cpu}, const cpu_set_t *@var{set}) +@standards{GNU, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c CPU_ISSET ok @c __CPU_ISSET_S ok @@ -1415,9 +1370,8 @@ This macro is a GNU extension and is defined in @file{sched.h}. CPU bitsets can be constructed from scratch or the currently installed affinity mask can be retrieved from the system. -@comment sched.h -@comment GNU @deftypefun int sched_getaffinity (pid_t @var{pid}, size_t @var{cpusetsize}, cpu_set_t *@var{cpuset}) +@standards{GNU, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Wrapped syscall to zero out past the kernel cpu set size; Linux @c only. @@ -1446,9 +1400,8 @@ Note that it is not portably possible to use this information to retrieve the information for different POSIX threads. A separate interface must be provided for that. -@comment sched.h -@comment GNU @deftypefun int sched_setaffinity (pid_t @var{pid}, size_t @var{cpusetsize}, const cpu_set_t *@var{cpuset}) +@standards{GNU, sched.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Wrapped syscall to detect attempts to set bits past the kernel cpu @c set size; Linux only. @@ -1572,9 +1525,8 @@ The correct interface to query about the page size is @code{sysconf} (@pxref{Sysconf Definition}) with the parameter @code{_SC_PAGESIZE}. There is a much older interface available, too. -@comment unistd.h -@comment BSD @deftypefun int getpagesize (void) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Obtained from the aux vec at program startup time. GNU/Linux/m68k is @c the exception, with the possibility of a syscall. @@ -1618,9 +1570,8 @@ get this information two functions. They are declared in the file @file{sys/sysinfo.h}. Programmers should prefer to use the @code{sysconf} method described above. -@comment sys/sysinfo.h -@comment GNU @deftypefun {long int} get_phys_pages (void) +@standards{GNU, sys/sysinfo.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c This fopens a /proc file and scans it for the requested information. The @code{get_phys_pages} function returns the total number of pages of @@ -1630,9 +1581,8 @@ be multiplied by the page size. This function is a GNU extension. @end deftypefun -@comment sys/sysinfo.h -@comment GNU @deftypefun {long int} get_avphys_pages (void) +@standards{GNU, sys/sysinfo.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} The @code{get_avphys_pages} function returns the number of available pages of physical memory the system has. To get the amount of memory this number has to @@ -1676,9 +1626,8 @@ For these two pieces of information @theglibc{} also provides functions to get the information directly. The functions are declared in @file{sys/sysinfo.h}. -@comment sys/sysinfo.h -@comment GNU @deftypefun int get_nprocs_conf (void) +@standards{GNU, sys/sysinfo.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c This function reads from from /sys using dir streams (single user, so @c no @mtasurace issue), and on some arches, from /proc using streams. @@ -1688,9 +1637,8 @@ operating system configured. This function is a GNU extension. @end deftypefun -@comment sys/sysinfo.h -@comment GNU @deftypefun int get_nprocs (void) +@standards{GNU, sys/sysinfo.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} @c This function reads from /proc using file descriptor I/O. The @code{get_nprocs} function returns the number of available processors. @@ -1705,9 +1653,8 @@ are not already overused. Unix systems calculate something called the running. This number is an average over different periods of time (normally 1, 5, and 15 minutes). -@comment stdlib.h -@comment BSD @deftypefun int getloadavg (double @var{loadavg}[], int @var{nelem}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} @c Calls host_info on HURD; on Linux, opens /proc/loadavg, reads from @c it, closes it, without cancellation point, and calls strtod_l with diff --git a/manual/search.texi b/manual/search.texi index 1d9628d6e3..57dad7a56d 100644 --- a/manual/search.texi +++ b/manual/search.texi @@ -69,9 +69,8 @@ potentially all elements must be checked. @Theglibc{} contains functions to perform linear search. The prototypes for the following two functions can be found in @file{search.h}. -@comment search.h -@comment SVID @deftypefun {void *} lfind (const void *@var{key}, const void *@var{base}, size_t *@var{nmemb}, size_t @var{size}, comparison_fn_t @var{compar}) +@standards{SVID, search.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{lfind} function searches in the array with @code{*@var{nmemb}} elements of @var{size} bytes pointed to by @var{base} for an element @@ -88,9 +87,8 @@ the array in which case it might not be useful to sort the array before searching. @end deftypefun -@comment search.h -@comment SVID @deftypefun {void *} lsearch (const void *@var{key}, void *@var{base}, size_t *@var{nmemb}, size_t @var{size}, comparison_fn_t @var{compar}) +@standards{SVID, search.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c A signal handler that interrupted an insertion and performed an @c insertion itself would leave the array in a corrupt state (e.g. one @@ -126,9 +124,8 @@ To search a sorted array for an element matching the key, use the the header file @file{stdlib.h}. @pindex stdlib.h -@comment stdlib.h -@comment ISO @deftypefun {void *} bsearch (const void *@var{key}, const void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{bsearch} function searches the sorted array @var{array} for an object that is equivalent to @var{key}. The array contains @var{count} elements, @@ -160,9 +157,8 @@ To sort an array using an arbitrary comparison function, use the @file{stdlib.h}. @pindex stdlib.h -@comment stdlib.h -@comment ISO @deftypefun void qsort (void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} The @code{qsort} function sorts the array @var{array}. The array contains @var{count} elements, each of which is of size @var{size}. @@ -272,9 +268,8 @@ which later should be searched. The costs of insert, delete and search differ. One possible implementation is using hashing tables. The following functions are declared in the header file @file{search.h}. -@comment search.h -@comment SVID @deftypefun int hcreate (size_t @var{nel}) +@standards{SVID, search.h} @safety{@prelim{}@mtunsafe{@mtasurace{:hsearch}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c hcreate @mtasurace:hsearch @ascuheap @acucorrupt @acsmem @c hcreate_r dup @mtsrace:htab @ascuheap @acucorrupt @acsmem @@ -304,9 +299,8 @@ something went wrong. This could either mean there is already a hashing table in use or the program ran out of memory. @end deftypefun -@comment search.h -@comment SVID @deftypefun void hdestroy (void) +@standards{SVID, search.h} @safety{@prelim{}@mtunsafe{@mtasurace{:hsearch}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c hdestroy @mtasurace:hsearch @ascuheap @acucorrupt @acsmem @c hdestroy_r dup @mtsrace:htab @ascuheap @acucorrupt @acsmem @@ -350,9 +344,8 @@ this element might stay undefined since it is not used. @end table @end deftp -@comment search.h -@comment SVID @deftypefun {ENTRY *} hsearch (ENTRY @var{item}, ACTION @var{action}) +@standards{SVID, search.h} @safety{@prelim{}@mtunsafe{@mtasurace{:hsearch}}@asunsafe{}@acunsafe{@acucorrupt{/action==ENTER}}} @c hsearch @mtasurace:hsearch @acucorrupt/action==ENTER @c hsearch_r dup @mtsrace:htab @acucorrupt/action==ENTER @@ -383,9 +376,8 @@ which is described by the content of an object of the type @code{struct hsearch_data}. This type should be treated as opaque, none of its members should be changed directly. -@comment search.h -@comment GNU @deftypefun int hcreate_r (size_t @var{nel}, struct hsearch_data *@var{htab}) +@standards{GNU, search.h} @safety{@prelim{}@mtsafe{@mtsrace{:htab}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c Unlike the lsearch array, the htab is (at least in part) opaque, so @c let's make it absolutely clear that ensuring exclusive access is a @@ -419,9 +411,8 @@ return value is zero, something went wrong, which probably means the program ran out of memory. @end deftypefun -@comment search.h -@comment GNU @deftypefun void hdestroy_r (struct hsearch_data *@var{htab}) +@standards{GNU, search.h} @safety{@prelim{}@mtsafe{@mtsrace{:htab}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c The table is released while the table pointer still points to it. @c Async cancellation is thus unsafe, but it already was because we call @@ -438,9 +429,8 @@ The @code{hdestroy_r} function frees all resources allocated by the for the elements of the table. @end deftypefun -@comment search.h -@comment GNU @deftypefun int hsearch_r (ENTRY @var{item}, ACTION @var{action}, ENTRY **@var{retval}, struct hsearch_data *@var{htab}) +@standards{GNU, search.h} @safety{@prelim{}@mtsafe{@mtsrace{:htab}}@assafe{}@acunsafe{@acucorrupt{/action==ENTER}}} @c Callers have to ensure mutual exclusion; insertion, if cancelled, @c leaves the table in a corrupt state. @@ -496,9 +486,8 @@ initialize data structures is necessary. A simple pointer of type extended or searched. The prototypes for these functions can be found in the header file @file{search.h}. -@comment search.h -@comment SVID @deftypefun {void *} tsearch (const void *@var{key}, void **@var{rootp}, comparison_fn_t @var{compar}) +@standards{SVID, search.h} @safety{@prelim{}@mtsafe{@mtsrace{:rootp}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c The tree is not modified in a thread-safe manner, and rotations may @c leave the tree in an inconsistent state that could be observed in an @@ -531,9 +520,8 @@ fact @var{key}). If an entry had to be created and the program ran out of space @code{NULL} is returned. @end deftypefun -@comment search.h -@comment SVID @deftypefun {void *} tfind (const void *@var{key}, void *const *@var{rootp}, comparison_fn_t @var{compar}) +@standards{SVID, search.h} @safety{@prelim{}@mtsafe{@mtsrace{:rootp}}@assafe{}@acsafe{}} The @code{tfind} function is similar to the @code{tsearch} function. It locates an element matching the one pointed to by @var{key} and returns @@ -546,9 +534,8 @@ Another advantage of the @code{tsearch} functions in contrast to the @code{hsearch} functions is that there is an easy way to remove elements. -@comment search.h -@comment SVID @deftypefun {void *} tdelete (const void *@var{key}, void **@var{rootp}, comparison_fn_t @var{compar}) +@standards{SVID, search.h} @safety{@prelim{}@mtsafe{@mtsrace{:rootp}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} To remove a specific element matching @var{key} from the tree @code{tdelete} can be used. It locates the matching element using the @@ -560,9 +547,8 @@ is deleted @code{tdelete} returns some unspecified value not equal to @code{NULL}. @end deftypefun -@comment search.h -@comment GNU @deftypefun void tdestroy (void *@var{vroot}, __free_fn_t @var{freefct}) +@standards{GNU, search.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} If the complete search tree has to be removed one can use @code{tdestroy}. It frees all resources allocated by the @code{tsearch} @@ -615,9 +601,8 @@ The current node is a leaf. @end vtable @end deftp -@comment search.h -@comment SVID @deftypefun void twalk (const void *@var{root}, __action_fn_t @var{action}) +@standards{SVID, search.h} @safety{@prelim{}@mtsafe{@mtsrace{:root}}@assafe{}@acsafe{}} For each node in the tree with a node pointed to by @var{root}, the @code{twalk} function calls the function provided by the parameter diff --git a/manual/setjmp.texi b/manual/setjmp.texi index 94d16becdc..710252881c 100644 --- a/manual/setjmp.texi +++ b/manual/setjmp.texi @@ -96,17 +96,15 @@ performing non-local exits. These facilities are declared in @file{setjmp.h}. @pindex setjmp.h -@comment setjmp.h -@comment ISO @deftp {Data Type} jmp_buf +@standards{ISO, setjmp.h} Objects of type @code{jmp_buf} hold the state information to be restored by a non-local exit. The contents of a @code{jmp_buf} identify a specific place to return to. @end deftp -@comment setjmp.h -@comment ISO @deftypefn Macro int setjmp (jmp_buf @var{state}) +@standards{ISO, setjmp.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c _setjmp ok @c __sigsetjmp(!savemask) ok @@ -117,9 +115,8 @@ execution state of the program in @var{state} and returns zero. If @var{state}, @code{setjmp} returns a nonzero value. @end deftypefn -@comment setjmp.h -@comment ISO @deftypefun void longjmp (jmp_buf @var{state}, int @var{value}) +@standards{ISO, setjmp.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @asucorrupt{} @asulock{/hurd}}@acunsafe{@acucorrupt{} @aculock{/hurd}}} @c __libc_siglongjmp @ascuplugin @asucorrupt @asulock/hurd @acucorrupt @aculock/hurd @c _longjmp_unwind @ascuplugin @asucorrupt @acucorrupt @@ -207,16 +204,14 @@ The facilities in this section are declared in the header file @file{setjmp.h}. @pindex setjmp.h -@comment setjmp.h -@comment POSIX.1 @deftp {Data Type} sigjmp_buf +@standards{POSIX.1, setjmp.h} This is similar to @code{jmp_buf}, except that it can also store state information about the set of blocked signals. @end deftp -@comment setjmp.h -@comment POSIX.1 @deftypefun int sigsetjmp (sigjmp_buf @var{state}, int @var{savesigs}) +@standards{POSIX.1, setjmp.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c sigsetjmp @asulock/hurd @aculock/hurd @c __sigsetjmp(savemask) @asulock/hurd @aculock/hurd @@ -227,9 +222,8 @@ of blocked signals is saved in @var{state} and will be restored if a @code{siglongjmp} is later performed with this @var{state}. @end deftypefun -@comment setjmp.h -@comment POSIX.1 @deftypefun void siglongjmp (sigjmp_buf @var{state}, int @var{value}) +@standards{POSIX.1, setjmp.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @asucorrupt{} @asulock{/hurd}}@acunsafe{@acucorrupt{} @aculock{/hurd}}} @c Alias to longjmp. This is similar to @code{longjmp} except for the type of its @var{state} @@ -258,9 +252,8 @@ contained. The type is also used in a few more places as we will see. The types and functions described in this section are all defined and declared respectively in the @file{ucontext.h} header file. -@comment ucontext.h -@comment SVID @deftp {Data Type} ucontext_t +@standards{SVID, ucontext.h} The @code{ucontext_t} type is defined as a structure with at least the following elements: @@ -289,9 +282,8 @@ applications less portable. Objects of this type have to be created by the user. The initialization and modification happens through one of the following functions: -@comment ucontext.h -@comment SVID @deftypefun int getcontext (ucontext_t *@var{ucp}) +@standards{SVID, ucontext.h} @safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@assafe{}@acsafe{}} @c Linux-only implementations in assembly, including sigprocmask @c syscall. A few cases call the sigprocmask function, but that's safe @@ -318,9 +310,8 @@ Once the context variable is initialized it can be used as is or it can be modified using the @code{makecontext} function. The latter is normally done when implementing co-routines or similar constructs. -@comment ucontext.h -@comment SVID @deftypefun void makecontext (ucontext_t *@var{ucp}, void (*@var{func}) (void), int @var{argc}, @dots{}) +@standards{SVID, ucontext.h} @safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@assafe{}@acsafe{}} @c Linux-only implementations mostly in assembly, nothing unsafe. @@ -366,9 +357,8 @@ can, depending on the direction the stack grows, be different). This difference makes the @code{makecontext} function hard to use and it requires detection of the platform at compile time. -@comment ucontext.h -@comment SVID @deftypefun int setcontext (const ucontext_t *@var{ucp}) +@standards{SVID, ucontext.h} @safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} @c Linux-only implementations mostly in assembly. Some ports use @c sigreturn or swapcontext syscalls; others restore the signal mask @@ -411,9 +401,8 @@ The @code{setcontext} function simply replaces the current context with the one described by the @var{ucp} parameter. This is often useful but there are situations where the current context has to be preserved. -@comment ucontext.h -@comment SVID @deftypefun int swapcontext (ucontext_t *restrict @var{oucp}, const ucontext_t *restrict @var{ucp}) +@standards{SVID, ucontext.h} @safety{@prelim{}@mtsafe{@mtsrace{:oucp} @mtsrace{:ucp}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} @c Linux-only implementations mostly in assembly. Some ports call or @c inline getcontext and/or setcontext, adjusting the saved context in diff --git a/manual/signal.texi b/manual/signal.texi index d6a1bfe94a..9577ff091d 100644 --- a/manual/signal.texi +++ b/manual/signal.texi @@ -219,9 +219,8 @@ the names are standardized and fairly uniform. The signal names are defined in the header file @file{signal.h}. -@comment signal.h -@comment BSD @deftypevr Macro int NSIG +@standards{BSD, signal.h} The value of this symbolic constant is the total number of signals defined. Since the signal numbers are allocated consecutively, @code{NSIG} is also one greater than the largest defined signal number. @@ -279,9 +278,8 @@ the environment variable @code{COREFILE}.) The purpose of core dump files is so that you can examine them with a debugger to investigate what caused the error. -@comment signal.h -@comment ISO @deftypevr Macro int SIGFPE +@standards{ISO, signal.h} The @code{SIGFPE} signal reports a fatal arithmetic error. Although the name is derived from ``floating-point exception'', this signal actually covers all arithmetic errors, including division by zero and overflow. @@ -312,56 +310,45 @@ argument, but the value is meaningful only on operating systems that provide the information (BSD systems and @gnusystems{}). @vtable @code -@comment signal.h -@comment BSD @item FPE_INTOVF_TRAP +@standards{BSD, signal.h} Integer overflow (impossible in a C program unless you enable overflow trapping in a hardware-specific fashion). -@comment signal.h -@comment BSD @item FPE_INTDIV_TRAP +@standards{BSD, signal.h} Integer division by zero. -@comment signal.h -@comment BSD @item FPE_SUBRNG_TRAP +@standards{BSD, signal.h} Subscript-range (something that C programs never check for). -@comment signal.h -@comment BSD @item FPE_FLTOVF_TRAP +@standards{BSD, signal.h} Floating overflow trap. -@comment signal.h -@comment BSD @item FPE_FLTDIV_TRAP +@standards{BSD, signal.h} Floating/decimal division by zero. -@comment signal.h -@comment BSD @item FPE_FLTUND_TRAP +@standards{BSD, signal.h} Floating underflow trap. (Trapping on floating underflow is not normally enabled.) -@comment signal.h -@comment BSD @item FPE_DECOVF_TRAP +@standards{BSD, signal.h} Decimal overflow trap. (Only a few machines have decimal arithmetic and C never uses it.) @ignore @c These seem redundant -@comment signal.h -@comment BSD @item FPE_FLTOVF_FAULT +@standards{BSD, signal.h} Floating overflow fault. -@comment signal.h -@comment BSD @item FPE_FLTDIV_FAULT +@standards{BSD, signal.h} Floating divide by zero fault. -@comment signal.h -@comment BSD @item FPE_FLTUND_FAULT +@standards{BSD, signal.h} Floating underflow fault. @end ignore @end vtable -@comment signal.h -@comment ISO @deftypevr Macro int SIGILL +@standards{ISO, signal.h} The name of this signal is derived from ``illegal instruction''; it usually means your program is trying to execute garbage or a privileged instruction. Since the C compiler generates only valid instructions, @@ -378,9 +365,8 @@ the system has trouble running the handler for a signal. @end deftypevr @cindex illegal instruction -@comment signal.h -@comment ISO @deftypevr Macro int SIGSEGV +@standards{ISO, signal.h} @cindex segmentation violation This signal is generated when a program tries to read or write outside the memory that is allocated for it, or to write memory that can only be @@ -395,9 +381,8 @@ among systems whether dereferencing a null pointer generates @code{SIGSEGV} or @code{SIGBUS}. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SIGBUS +@standards{BSD, signal.h} This signal is generated when an invalid pointer is dereferenced. Like @code{SIGSEGV}, this signal is typically the result of dereferencing an uninitialized pointer. The difference between the two is that @@ -412,41 +397,36 @@ The name of this signal is an abbreviation for ``bus error''. @end deftypevr @cindex bus error -@comment signal.h -@comment ISO @deftypevr Macro int SIGABRT +@standards{ISO, signal.h} @cindex abort signal This signal indicates an error detected by the program itself and reported by calling @code{abort}. @xref{Aborting a Program}. @end deftypevr -@comment signal.h -@comment Unix @deftypevr Macro int SIGIOT +@standards{Unix, signal.h} Generated by the PDP-11 ``iot'' instruction. On most machines, this is just another name for @code{SIGABRT}. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SIGTRAP +@standards{BSD, signal.h} Generated by the machine's breakpoint instruction, and possibly other trap instructions. This signal is used by debuggers. Your program will probably only see @code{SIGTRAP} if it is somehow executing bad instructions. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SIGEMT +@standards{BSD, signal.h} Emulator trap; this results from certain unimplemented instructions which might be emulated in software, or the operating system's failure to properly emulate them. @end deftypevr -@comment signal.h -@comment Unix @deftypevr Macro int SIGSYS +@standards{Unix, signal.h} Bad system call; that is to say, the instruction to trap to the operating system was executed, but the code number for the system call to perform was invalid. @@ -471,9 +451,8 @@ not had a handler. (@xref{Termination in Handler}.) The (obvious) default action for all of these signals is to cause the process to terminate. -@comment signal.h -@comment ISO @deftypevr Macro int SIGTERM +@standards{ISO, signal.h} @cindex termination signal The @code{SIGTERM} signal is a generic signal used to cause program termination. Unlike @code{SIGKILL}, this signal can be blocked, @@ -484,9 +463,8 @@ The shell command @code{kill} generates @code{SIGTERM} by default. @pindex kill @end deftypevr -@comment signal.h -@comment ISO @deftypevr Macro int SIGINT +@standards{ISO, signal.h} @cindex interrupt signal The @code{SIGINT} (``program interrupt'') signal is sent when the user types the INTR character (normally @kbd{C-c}). @xref{Special @@ -494,9 +472,8 @@ Characters}, for information about terminal driver support for @kbd{C-c}. @end deftypevr -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGQUIT +@standards{POSIX.1, signal.h} @cindex quit signal @cindex quit signal The @code{SIGQUIT} signal is similar to @code{SIGINT}, except that it's @@ -516,9 +493,8 @@ is better for @code{SIGQUIT} not to delete them, so that the user can examine them in conjunction with the core dump. @end deftypevr -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGKILL +@standards{POSIX.1, signal.h} The @code{SIGKILL} signal is used to cause immediate program termination. It cannot be handled or ignored, and is therefore always fatal. It is also not possible to block this signal. @@ -538,9 +514,8 @@ unusual conditions where the program cannot possibly continue to run @end deftypevr @cindex kill signal -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGHUP +@standards{POSIX.1, signal.h} @cindex hangup signal The @code{SIGHUP} (``hang-up'') signal is used to report that the user's terminal is disconnected, perhaps because a network or telephone @@ -566,26 +541,23 @@ This default is rarely useful, but no other default would be useful; most of the ways of using these signals would require handler functions in any case. -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGALRM +@standards{POSIX.1, signal.h} This signal typically indicates expiration of a timer that measures real or clock time. It is used by the @code{alarm} function, for example. @end deftypevr @cindex alarm signal -@comment signal.h -@comment BSD @deftypevr Macro int SIGVTALRM +@standards{BSD, signal.h} This signal typically indicates expiration of a timer that measures CPU time used by the current process. The name is an abbreviation for ``virtual time alarm''. @end deftypevr @cindex virtual time alarm signal -@comment signal.h -@comment BSD @deftypevr Macro int SIGPROF +@standards{BSD, signal.h} This signal typically indicates expiration of a timer that measures both CPU time used by the current process, and CPU time expended on behalf of the process by the system. Such a timer is used to implement @@ -603,9 +575,8 @@ calling @code{fcntl} to enable a particular file descriptor to generate these signals (@pxref{Interrupt Input}). The default action for these signals is to ignore them. -@comment signal.h -@comment BSD @deftypevr Macro int SIGIO +@standards{BSD, signal.h} @cindex input available signal @cindex output possible signal This signal is sent when a file descriptor is ready to perform input @@ -619,17 +590,15 @@ On @gnusystems{} @code{SIGIO} will always be generated properly if you successfully set asynchronous mode with @code{fcntl}. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SIGURG +@standards{BSD, signal.h} @cindex urgent data signal This signal is sent when ``urgent'' or out-of-band data arrives on a socket. @xref{Out-of-Band Data}. @end deftypevr -@comment signal.h -@comment SVID @deftypevr Macro int SIGPOLL +@standards{SVID, signal.h} This is a System V signal name, more or less similar to @code{SIGIO}. It is defined only for compatibility. @end deftypevr @@ -645,9 +614,8 @@ signals themselves can't be raised or handled. You should generally leave these signals alone unless you really understand how job control works. @xref{Job Control}. -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGCHLD +@standards{POSIX.1, signal.h} @cindex child process signal This signal is sent to a parent process whenever one of its child processes terminates or stops. @@ -660,15 +628,13 @@ applies to those processes or not depends on the particular operating system. @end deftypevr -@comment signal.h -@comment SVID @deftypevr Macro int SIGCLD +@standards{SVID, signal.h} This is an obsolete name for @code{SIGCHLD}. @end deftypevr -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGCONT +@standards{POSIX.1, signal.h} @cindex continue signal You can send a @code{SIGCONT} signal to a process to make it continue. This signal is special---it always makes the process continue if it is @@ -683,17 +649,15 @@ it is stopped and continued---for example, to reprint a prompt when it is suspended while waiting for input. @end deftypevr -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGSTOP +@standards{POSIX.1, signal.h} The @code{SIGSTOP} signal stops the process. It cannot be handled, ignored, or blocked. @end deftypevr @cindex stop signal -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGTSTP +@standards{POSIX.1, signal.h} The @code{SIGTSTP} signal is an interactive stop signal. Unlike @code{SIGSTOP}, this signal can be handled and ignored. @@ -708,9 +672,8 @@ support, see @ref{Special Characters}. @end deftypevr @cindex interactive stop signal -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGTTIN +@standards{POSIX.1, signal.h} A process cannot read from the user's terminal while it is running as a background job. When any process in a background job tries to read from the terminal, all of the processes in the job are sent a @@ -720,9 +683,8 @@ the terminal driver, see @ref{Access to the Terminal}. @end deftypevr @cindex terminal input signal -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGTTOU +@standards{POSIX.1, signal.h} This is similar to @code{SIGTTIN}, but is generated when a process in a background job attempts to write to the terminal or set its modes. Again, the default action is to stop the process. @code{SIGTTOU} is @@ -769,9 +731,8 @@ programming error in the program, but an error that prevents an operating system call from completing. The default action for all of them is to cause the process to terminate. -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGPIPE +@standards{POSIX.1, signal.h} @cindex pipe signal @cindex broken pipe signal Broken pipe. If you use pipes or FIFOs, you have to design your @@ -788,9 +749,8 @@ Another cause of @code{SIGPIPE} is when you try to output to a socket that isn't connected. @xref{Sending Data}. @end deftypevr -@comment signal.h -@comment GNU @deftypevr Macro int SIGLOST +@standards{GNU, signal.h} @cindex lost resource signal Resource lost. This signal is generated when you have an advisory lock on an NFS file, and the NFS server reboots and forgets about your lock. @@ -800,16 +760,14 @@ dies unexpectedly. It is usually fine to ignore the signal; whatever call was made to the server that died just returns an error. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SIGXCPU +@standards{BSD, signal.h} CPU time limit exceeded. This signal is generated when the process exceeds its soft resource limit on CPU time. @xref{Limits on Resources}. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SIGXFSZ +@standards{BSD, signal.h} File size limit exceeded. This signal is generated when the process attempts to extend a file so it exceeds the process's soft resource limit on file size. @xref{Limits on Resources}. @@ -821,12 +779,9 @@ limit on file size. @xref{Limits on Resources}. These signals are used for various other purposes. In general, they will not affect your program unless it explicitly uses them for something. -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SIGUSR1 -@comment signal.h -@comment POSIX.1 @deftypevrx Macro int SIGUSR2 +@standards{POSIX.1, signal.h} @cindex user signals The @code{SIGUSR1} and @code{SIGUSR2} signals are set aside for you to use any way you want. They're useful for simple interprocess @@ -839,9 +794,8 @@ in @ref{Signaling Another Process}. The default action is to terminate the process. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SIGWINCH +@standards{BSD, signal.h} Window size change. This is generated on some systems (including GNU) when the terminal driver's record of the number of rows and columns on the screen is changed. The default action is to ignore it. @@ -851,9 +805,8 @@ When the signal arrives, it should fetch the new screen size and reformat its display accordingly. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SIGINFO +@standards{BSD, signal.h} Information request. On 4.4 BSD and @gnuhurdsystems{}, this signal is sent to all the processes in the foreground process group of the controlling terminal when the user types the STATUS character in canonical mode; @@ -876,9 +829,8 @@ kind of signal to describe. The signal number may come from the termination status of a child process (@pxref{Process Completion}) or it may come from a signal handler in the same process. -@comment string.h -@comment GNU @deftypefun {char *} strsignal (int @var{signum}) +@standards{GNU, string.h} @safety{@prelim{}@mtunsafe{@mtasurace{:strsignal} @mtslocale{}}@asunsafe{@asuinit{} @ascuintl{} @asucorrupt{} @ascuheap{}}@acunsafe{@acuinit{} @acucorrupt{} @acsmem{}}} @c strsignal @mtasurace:strsignal @mtslocale @asuinit @ascuintl @asucorrupt @ascuheap @acucorrupt @acsmem @c uses a static buffer if tsd key creation fails @@ -904,9 +856,8 @@ This function is a GNU extension, declared in the header file @file{string.h}. @end deftypefun -@comment signal.h -@comment BSD @deftypefun void psignal (int @var{signum}, const char *@var{message}) +@standards{BSD, signal.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} @c psignal @mtslocale @asucorrupt @ascuintl @ascuheap @aculock @acucorrupt @acsmem @c _ @ascuintl @@ -965,9 +916,8 @@ an action for a particular signal. The function and associated macros are declared in the header file @file{signal.h}. @pindex signal.h -@comment signal.h -@comment GNU @deftp {Data Type} sighandler_t +@standards{GNU, signal.h} This is the type of signal handler functions. Signal handlers take one integer argument specifying the signal number, and have return type @code{void}. So, you should define handler functions like this: @@ -979,9 +929,8 @@ void @var{handler} (int @code{signum}) @{ @dots{} @} The name @code{sighandler_t} for this data type is a GNU extension. @end deftp -@comment signal.h -@comment ISO @deftypefun sighandler_t signal (int @var{signum}, sighandler_t @var{action}) +@standards{ISO, signal.h} @safety{@prelim{}@mtsafe{@mtssigintr{}}@assafe{}@acsafe{}} @c signal ok @c sigemptyset dup ok @@ -1107,9 +1056,8 @@ We do not handle @code{SIGQUIT} or the program error signals in this example because these are designed to provide information for debugging (a core dump), and the temporary files may give useful information. -@comment signal.h -@comment GNU @deftypefun sighandler_t sysv_signal (int @var{signum}, sighandler_t @var{action}) +@standards{GNU, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c sysv_signal ok @c sigemptyset dup ok @@ -1123,18 +1071,16 @@ function should be avoided when possible. @code{sigaction} is the preferred method. @end deftypefun -@comment signal.h -@comment SVID @deftypefun sighandler_t ssignal (int @var{signum}, sighandler_t @var{action}) +@standards{SVID, signal.h} @safety{@prelim{}@mtsafe{@mtssigintr{}}@assafe{}@acsafe{}} @c Aliases signal and bsd_signal. The @code{ssignal} function does the same thing as @code{signal}; it is provided only for compatibility with SVID. @end deftypefun -@comment signal.h -@comment ISO @deftypevr Macro sighandler_t SIG_ERR +@standards{ISO, signal.h} The value of this macro is used as the return value from @code{signal} to indicate an error. @end deftypevr @@ -1163,9 +1109,8 @@ handler is invoked. The @code{sigaction} function is declared in @file{signal.h}. @pindex signal.h -@comment signal.h -@comment POSIX.1 @deftp {Data Type} {struct sigaction} +@standards{POSIX.1, signal.h} Structures of type @code{struct sigaction} are used in the @code{sigaction} function to specify all the information about how to handle a particular signal. This structure contains at least the @@ -1191,9 +1136,8 @@ the signal. These are described in more detail in @ref{Flags for Sigaction}. @end table @end deftp -@comment signal.h -@comment POSIX.1 @deftypefun int sigaction (int @var{signum}, const struct sigaction *restrict @var{action}, struct sigaction *restrict @var{old-action}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @var{action} argument is used to set up a new action for the signal @var{signum}, while the @var{old-action} argument is used to return @@ -1351,9 +1295,8 @@ Primitives}, to see what this is about. @pindex signal.h These macros are defined in the header file @file{signal.h}. -@comment signal.h -@comment POSIX.1 @deftypevr Macro int SA_NOCLDSTOP +@standards{POSIX.1, signal.h} This flag is meaningful only for the @code{SIGCHLD} signal. When the flag is set, the system delivers the signal for a terminated child process but not for one that is stopped. By default, @code{SIGCHLD} is @@ -1362,18 +1305,16 @@ delivered for both terminated children and stopped children. Setting this flag for a signal other than @code{SIGCHLD} has no effect. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SA_ONSTACK +@standards{BSD, signal.h} If this flag is set for a particular signal number, the system uses the signal stack when delivering that kind of signal. @xref{Signal Stack}. If a signal with this flag arrives and you have not set a signal stack, the system terminates the program with @code{SIGILL}. @end deftypevr -@comment signal.h -@comment BSD @deftypevr Macro int SA_RESTART +@standards{BSD, signal.h} This flag controls what happens when a signal is delivered during certain primitives (such as @code{open}, @code{read} or @code{write}), and the signal handler returns normally. There are two alternatives: @@ -2045,9 +1986,8 @@ The type @code{sig_atomic_t} is always an integer data type, but which one it is, and how many bits it contains, may vary from machine to machine. -@comment signal.h -@comment ISO @deftp {Data Type} sig_atomic_t +@standards{ISO, signal.h} This is an integer data type. Objects of this type are always accessed atomically. @end deftp @@ -2103,9 +2043,8 @@ to check, which is a common source of error. @Theglibc{} provides a convenient way to retry a call after a temporary failure, with the macro @code{TEMP_FAILURE_RETRY}: -@comment unistd.h -@comment GNU @defmac TEMP_FAILURE_RETRY (@var{expression}) +@standards{GNU, unistd.h} This macro evaluates @var{expression} once, and examines its value as type @code{long int}. If the value equals @code{-1}, that indicates a failure and @code{errno} should be set to show what kind of failure. @@ -2181,9 +2120,8 @@ A process can send itself a signal with the @code{raise} function. This function is declared in @file{signal.h}. @pindex signal.h -@comment signal.h -@comment ISO @deftypefun int raise (int @var{signum}) +@standards{ISO, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c raise ok @c [posix] @@ -2198,9 +2136,8 @@ About the only reason for failure would be if the value of @var{signum} is invalid. @end deftypefun -@comment signal.h -@comment SVID @deftypefun int gsignal (int @var{signum}) +@standards{SVID, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Aliases raise. The @code{gsignal} function does the same thing as @code{raise}; it is @@ -2292,9 +2229,8 @@ work. For more information on this subject, see @ref{Processes}. The @code{kill} function is declared in @file{signal.h}. @pindex signal.h -@comment signal.h -@comment POSIX.1 @deftypefun int kill (pid_t @var{pid}, int @var{signum}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c The hurd implementation is not a critical section, so it's not @c immediately obvious that, in case of cancellation, it won't leak @@ -2353,9 +2289,8 @@ The @var{pid} argument does not refer to an existing process or group. @end table @end deftypefun -@comment signal.h -@comment BSD @deftypefun int killpg (int @var{pgid}, int @var{signum}) +@standards{BSD, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Calls kill with -pgid. This is similar to @code{kill}, but sends signal @var{signum} to the @@ -2502,9 +2437,8 @@ it as an argument to a library function. These facilities are declared in the header file @file{signal.h}. @pindex signal.h -@comment signal.h -@comment POSIX.1 @deftp {Data Type} sigset_t +@standards{POSIX.1, signal.h} The @code{sigset_t} data type is used to represent a signal set. Internally, it may be implemented as either an integer or structure type. @@ -2527,26 +2461,23 @@ well. (In addition, it's not wise to put into your program an assumption that the system has no signals aside from the ones you know about.) -@comment signal.h -@comment POSIX.1 @deftypefun int sigemptyset (sigset_t *@var{set}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Just memsets all of set to zero. This function initializes the signal set @var{set} to exclude all of the defined signals. It always returns @code{0}. @end deftypefun -@comment signal.h -@comment POSIX.1 @deftypefun int sigfillset (sigset_t *@var{set}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function initializes the signal set @var{set} to include all of the defined signals. Again, the return value is @code{0}. @end deftypefun -@comment signal.h -@comment POSIX.1 @deftypefun int sigaddset (sigset_t *@var{set}, int @var{signum}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function adds the signal @var{signum} to the signal set @var{set}. All @code{sigaddset} does is modify @var{set}; it does not block or @@ -2561,9 +2492,8 @@ The @var{signum} argument doesn't specify a valid signal. @end table @end deftypefun -@comment signal.h -@comment POSIX.1 @deftypefun int sigdelset (sigset_t *@var{set}, int @var{signum}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function removes the signal @var{signum} from the signal set @var{set}. All @code{sigdelset} does is modify @var{set}; it does not @@ -2573,9 +2503,8 @@ the same as for @code{sigaddset}. Finally, there is a function to test what signals are in a signal set: -@comment signal.h -@comment POSIX.1 @deftypefun int sigismember (const sigset_t *@var{set}, int @var{signum}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{sigismember} function tests whether the signal @var{signum} is a member of the signal set @var{set}. It returns @code{1} if the signal @@ -2612,9 +2541,8 @@ Instead, use @code{pthread_sigmask}. @xref{Threads and Signal Handling}. @end ifset -@comment signal.h -@comment POSIX.1 @deftypefun int sigprocmask (int @var{how}, const sigset_t *restrict @var{set}, sigset_t *restrict @var{oldset}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/bsd(SIG_UNBLOCK)}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c This takes the hurd_self_sigstate-returned object's lock on HURD. On @c BSD, SIG_UNBLOCK is emulated with two sigblock calls, which @@ -2624,21 +2552,18 @@ process's signal mask. The @var{how} argument determines how the signal mask is changed, and must be one of the following values: @vtable @code -@comment signal.h -@comment POSIX.1 @item SIG_BLOCK +@standards{POSIX.1, signal.h} Block the signals in @code{set}---add them to the existing mask. In other words, the new mask is the union of the existing mask and @var{set}. -@comment signal.h -@comment POSIX.1 @item SIG_UNBLOCK +@standards{POSIX.1, signal.h} Unblock the signals in @var{set}---remove them from the existing mask. -@comment signal.h -@comment POSIX.1 @item SIG_SETMASK +@standards{POSIX.1, signal.h} Use @var{set} for the mask; ignore the previous value of the mask. @end vtable @@ -2796,9 +2721,8 @@ You can find out which signals are pending at any time by calling @code{sigpending}. This function is declared in @file{signal.h}. @pindex signal.h -@comment signal.h -@comment POSIX.1 @deftypefun int sigpending (sigset_t *@var{set}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c Direct rt_sigpending syscall on most systems. On hurd, calls @c hurd_self_sigstate, it copies the sigstate's pending while holding @@ -2963,9 +2887,8 @@ The simple way to wait until a signal arrives is to call @code{pause}. Please read about its disadvantages, in the following section, before you use it. -@comment unistd.h -@comment POSIX.1 @deftypefun int pause (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c The signal mask read by sigprocmask may be overridden by another @c thread or by a signal handler before we call sigsuspend. Is this a @@ -3069,9 +2992,8 @@ and then use @code{sigsuspend}. By using @code{sigsuspend} in a loop, you can wait for certain kinds of signals, while letting other kinds of signals be handled by their handlers. -@comment signal.h -@comment POSIX.1 @deftypefun int sigsuspend (const sigset_t *@var{set}) +@standards{POSIX.1, signal.h} @safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c sigsuspend @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd @c [posix] @mtasurace:sigprocmask/!bsd!linux @@ -3166,9 +3088,8 @@ BSD. The @code{sigaltstack} interface has the advantage that it does not require your program to know which direction the stack grows, which depends on the specific machine and operating system. -@comment signal.h -@comment XPG @deftp {Data Type} stack_t +@standards{XPG, signal.h} This structure describes a signal stack. It contains the following members: @table @code @@ -3214,9 +3135,8 @@ delivered on the normal user stack. @end table @end deftp -@comment signal.h -@comment XPG @deftypefun int sigaltstack (const stack_t *restrict @var{stack}, stack_t *restrict @var{oldstack}) +@standards{XPG, signal.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c Syscall on Linux and BSD; the HURD implementation takes a lock on @c the hurd_self_sigstate-returned struct. @@ -3247,9 +3167,8 @@ It must be greater than @code{MINSIGSTKSZ}. Here is the older @code{sigstack} interface. You should use @code{sigaltstack} instead on systems that have it. -@comment signal.h -@comment BSD @deftp {Data Type} {struct sigstack} +@standards{BSD, signal.h} This structure describes a signal stack. It contains the following members: @table @code @@ -3263,9 +3182,8 @@ This field is true if the process is currently using this stack. @end table @end deftp -@comment signal.h -@comment BSD @deftypefun int sigstack (struct sigstack *@var{stack}, struct sigstack *@var{oldstack}) +@standards{BSD, signal.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c Lossy and dangerous (no size limit) wrapper for sigaltstack. The @code{sigstack} function specifies an alternate stack for use during @@ -3300,9 +3218,8 @@ represents signal masks as an @code{int} bit mask, rather than as a The BSD facilities are declared in @file{signal.h}. @pindex signal.h -@comment signal.h -@comment XPG @deftypefun int siginterrupt (int @var{signum}, int @var{failflag}) +@standards{XPG, signal.h} @safety{@prelim{}@mtunsafe{@mtasuconst{:@mtssigintr{}}}@asunsafe{}@acunsafe{@acucorrupt{}}} @c This calls sigaction twice, once to get the current sigaction for the @c specified signal, another to apply the flags change. This could @@ -3318,9 +3235,8 @@ true, handling @var{signum} causes these primitives to fail with error code @code{EINTR}. @xref{Interrupted Primitives}. @end deftypefun -@comment signal.h -@comment BSD @deftypefn Macro int sigmask (int @var{signum}) +@standards{BSD, signal.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c This just shifts signum. This macro returns a signal mask that has the bit for signal @var{signum} @@ -3336,9 +3252,8 @@ together to specify more than one signal. For example, specifies a mask that includes all the job-control stop signals. @end deftypefn -@comment signal.h -@comment BSD @deftypefun int sigblock (int @var{mask}) +@standards{BSD, signal.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c On most POSIX systems, this is a wrapper for sigprocmask(SIG_BLOCK). @c The exception are BSD systems other than 4.4, where it is a syscall. @@ -3350,9 +3265,8 @@ signals specified by @var{mask} to the calling process's set of blocked signals. The return value is the previous set of blocked signals. @end deftypefun -@comment signal.h -@comment BSD @deftypefun int sigsetmask (int @var{mask}) +@standards{BSD, signal.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c On most POSIX systems, this is a wrapper for sigprocmask(SIG_SETMASK). @c The exception are BSD systems other than 4.4, where it is a syscall. @@ -3364,9 +3278,8 @@ the calling process's signal mask to @var{mask}. The return value is the previous set of blocked signals. @end deftypefun -@comment signal.h -@comment BSD @deftypefun int sigpause (int @var{mask}) +@standards{BSD, signal.h} @safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} @c sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd @c [posix] diff --git a/manual/socket.texi b/manual/socket.texi index 21b672badc..79eb4208be 100644 --- a/manual/socket.texi +++ b/manual/socket.texi @@ -161,9 +161,8 @@ supported socket types. The symbolic constants listed here are defined in @file{sys/socket.h}. @pindex sys/socket.h -@comment sys/socket.h -@comment BSD @deftypevr Macro int SOCK_STREAM +@standards{BSD, sys/socket.h} The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}). It operates over a connection with a particular remote socket and transmits data reliably as a stream of bytes. @@ -171,9 +170,8 @@ transmits data reliably as a stream of bytes. Use of this style is covered in detail in @ref{Connections}. @end deftypevr -@comment sys/socket.h -@comment BSD @deftypevr Macro int SOCK_DGRAM +@standards{BSD, sys/socket.h} The @code{SOCK_DGRAM} style is used for sending individually-addressed packets unreliably. It is the diametrical opposite of @code{SOCK_STREAM}. @@ -199,9 +197,8 @@ sockets. @ignore @c This appears to be only for the NS domain, which we aren't @c discussing and probably won't support either. -@comment sys/socket.h -@comment BSD @deftypevr Macro int SOCK_SEQPACKET +@standards{BSD, sys/socket.h} This style is like @code{SOCK_STREAM} except that the data are structured into packets. @@ -216,9 +213,8 @@ Many protocols do not support this communication style. @end ignore @ignore -@comment sys/socket.h -@comment BSD @deftypevr Macro int SOCK_RDM +@standards{BSD, sys/socket.h} This style is a reliable version of @code{SOCK_DGRAM}: it sends individually addressed packets, but guarantees that each packet sent arrives exactly once. @@ -228,9 +224,8 @@ by any operating system. @end deftypevr @end ignore -@comment sys/socket.h -@comment BSD @deftypevr Macro int SOCK_RAW +@standards{BSD, sys/socket.h} This style provides access to low-level network protocols and interfaces. Ordinary user programs usually have no need to use this style. @@ -304,9 +299,8 @@ you which data type to use to understand the address fully. The symbols in this section are defined in the header file @file{sys/socket.h}. -@comment sys/socket.h -@comment BSD @deftp {Data Type} {struct sockaddr} +@standards{BSD, sys/socket.h} The @code{struct sockaddr} type itself has the following members: @table @code @@ -326,16 +320,15 @@ Each of them corresponds to a @samp{PF_} symbol which designates the corresponding namespace. Here is a list of address format names: @vtable @code -@comment sys/socket.h -@comment POSIX @item AF_LOCAL +@standards{POSIX, sys/socket.h} This designates the address format that goes with the local namespace. (@code{PF_LOCAL} is the name of that namespace.) @xref{Local Namespace Details}, for information about this address format. -@comment sys/socket.h -@comment BSD, Unix98 @item AF_UNIX +@standards{BSD, sys/socket.h} +@standards{Unix98, sys/socket.h} This is a synonym for @code{AF_LOCAL}. Although @code{AF_LOCAL} is mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems. @code{AF_UNIX} was the traditional name stemming from BSD, so even most @@ -343,28 +336,24 @@ POSIX systems support it. It is also the name of choice in the Unix98 specification. (The same is true for @code{PF_UNIX} vs. @code{PF_LOCAL}). -@comment sys/socket.h -@comment GNU @item AF_FILE +@standards{GNU, sys/socket.h} This is another synonym for @code{AF_LOCAL}, for compatibility. (@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.) -@comment sys/socket.h -@comment BSD @item AF_INET +@standards{BSD, sys/socket.h} This designates the address format that goes with the Internet namespace. (@code{PF_INET} is the name of that namespace.) @xref{Internet Address Formats}. -@comment sys/socket.h -@comment IPv6 Basic API @item AF_INET6 +@standards{IPv6 Basic API, sys/socket.h} This is similar to @code{AF_INET}, but refers to the IPv6 protocol. (@code{PF_INET6} is the name of the corresponding namespace.) -@comment sys/socket.h -@comment BSD @item AF_UNSPEC +@standards{BSD, sys/socket.h} This designates no particular address format. It is used only in rare cases, such as to clear out the default destination address of a ``connected'' datagram socket. @xref{Sending Datagrams}. @@ -386,9 +375,8 @@ Use the @code{bind} function to assign an address to a socket. The prototype for @code{bind} is in the header file @file{sys/socket.h}. For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}. -@comment sys/socket.h -@comment BSD @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, except on Hurd. The @code{bind} function assigns an address to the socket @@ -436,9 +424,8 @@ Use the function @code{getsockname} to examine the address of an Internet socket. The prototype for this function is in the header file @file{sys/socket.h}. -@comment sys/socket.h -@comment BSD @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsmem{/hurd}}} @c Direct syscall, except on Hurd, where it seems like it might leak @c VM if cancelled. @@ -492,15 +479,14 @@ an arbitrarily-assigned small positive integer. The following functions, constants and data types are declared in the header file @file{net/if.h}. -@comment net/if.h @deftypevr Constant size_t IFNAMSIZ +@standards{???, net/if.h} This constant defines the maximum buffer size needed to hold an interface name, including its terminating zero byte. @end deftypevr -@comment net/if.h -@comment IPv6 basic API @deftypefun {unsigned int} if_nametoindex (const char *@var{ifname}) +@standards{IPv6 basic API, net/if.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c It opens a socket to use ioctl on the fd to get the index. @c opensock may call socket and access multiple times until it finds a @@ -513,9 +499,8 @@ This function yields the interface index corresponding to a particular name. If no interface exists with the name given, it returns 0. @end deftypefun -@comment net/if.h -@comment IPv6 basic API @deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname}) +@standards{IPv6 basic API, net/if.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c It opens a socket with opensock to use ioctl on the fd to get the @c name from the index. @@ -526,9 +511,8 @@ invalid, the function's return value is a null pointer, otherwise it is @code{ifname}. @end deftypefun -@comment net/if.h -@comment IPv6 basic API @deftp {Data Type} {struct if_nameindex} +@standards{IPv6 basic API, net/if.h} This data type is used to hold the information about a single interface. It has the following members: @@ -542,9 +526,8 @@ This is the null-terminated index name. @end table @end deftp -@comment net/if.h -@comment IPv6 basic API @deftypefun {struct if_nameindex *} if_nameindex (void) +@standards{IPv6 basic API, net/if.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@aculock{/hurd} @acsfd{} @acsmem{}}} @c if_nameindex @ascuheap @asulock/hurd @aculock/hurd @acsfd @acsmem @c [linux] @@ -587,9 +570,8 @@ The returned structure must be freed with @code{if_freenameindex} after use. @end deftypefun -@comment net/if.h -@comment IPv6 basic API @deftypefun void if_freenameindex (struct if_nameindex *@var{ptr}) +@standards{IPv6 basic API, net/if.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c if_freenameindex @ascuheap @acsmem @c free dup @ascuheap @acsmem @@ -653,23 +635,20 @@ To create a socket in the local namespace, use the constant @code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or @code{socketpair}. This constant is defined in @file{sys/socket.h}. -@comment sys/socket.h -@comment POSIX @deftypevr Macro int PF_LOCAL +@standards{POSIX, sys/socket.h} This designates the local namespace, in which socket addresses are local names, and its associated family of protocols. @code{PF_LOCAL} is the macro used by POSIX.1g. @end deftypevr -@comment sys/socket.h -@comment BSD @deftypevr Macro int PF_UNIX +@standards{BSD, sys/socket.h} This is a synonym for @code{PF_LOCAL}, for compatibility's sake. @end deftypevr -@comment sys/socket.h -@comment GNU @deftypevr Macro int PF_FILE +@standards{GNU, sys/socket.h} This is a synonym for @code{PF_LOCAL}, for compatibility's sake. @end deftypevr @@ -677,9 +656,8 @@ The structure for specifying socket names in the local namespace is defined in the header file @file{sys/un.h}: @pindex sys/un.h -@comment sys/un.h -@comment BSD @deftp {Data Type} {struct sockaddr_un} +@standards{BSD, sys/un.h} This structure is used to specify local namespace socket addresses. It has the following members: @@ -704,9 +682,8 @@ the local namespace as the sum of the size of the @code{sun_family} component and the string length (@emph{not} the allocation size!) of the file name string. This can be done using the macro @code{SUN_LEN}: -@comment sys/un.h -@comment BSD @deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr}) +@standards{BSD, sys/un.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro computes the length of the socket address in the local namespace. @end deftypefn @@ -740,16 +717,14 @@ To create a socket in the IPv4 Internet namespace, use the symbolic name macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}. @pindex sys/socket.h -@comment sys/socket.h -@comment BSD @deftypevr Macro int PF_INET +@standards{BSD, sys/socket.h} This designates the IPv4 Internet namespace and associated family of protocols. @end deftypevr -@comment sys/socket.h -@comment X/Open @deftypevr Macro int PF_INET6 +@standards{X/Open, sys/socket.h} This designates the IPv6 Internet namespace and associated family of protocols. @end deftypevr @@ -796,9 +771,8 @@ The data types for representing socket addresses in the Internet namespace are defined in the header file @file{netinet/in.h}. @pindex netinet/in.h -@comment netinet/in.h -@comment BSD @deftp {Data Type} {struct sockaddr_in} +@standards{BSD, netinet/in.h} This is the data type used to represent socket addresses in the Internet namespace. It has the following members: @@ -1002,17 +976,15 @@ The following basic definitions for Internet addresses are declared in the header file @file{netinet/in.h}: @pindex netinet/in.h -@comment netinet/in.h -@comment BSD @deftp {Data Type} {struct in_addr} +@standards{BSD, netinet/in.h} This data type is used in certain contexts to contain an IPv4 Internet host address. It has just one field, named @code{s_addr}, which records the host address number as an @code{uint32_t}. @end deftp -@comment netinet/in.h -@comment BSD @deftypevr Macro {uint32_t} INADDR_LOOPBACK +@standards{BSD, netinet/in.h} You can use this constant to stand for ``the address of this machine,'' instead of finding its actual address. It is the IPv4 Internet address @samp{127.0.0.1}, which is usually called @samp{localhost}. This @@ -1022,47 +994,41 @@ specially, avoiding any network traffic for the case of one machine talking to itself. @end deftypevr -@comment netinet/in.h -@comment BSD @deftypevr Macro {uint32_t} INADDR_ANY +@standards{BSD, netinet/in.h} You can use this constant to stand for ``any incoming address'' when binding to an address. @xref{Setting Address}. This is the usual address to give in the @code{sin_addr} member of @w{@code{struct sockaddr_in}} when you want to accept Internet connections. @end deftypevr -@comment netinet/in.h -@comment BSD @deftypevr Macro {uint32_t} INADDR_BROADCAST +@standards{BSD, netinet/in.h} This constant is the address you use to send a broadcast message. @c !!! broadcast needs further documented @end deftypevr -@comment netinet/in.h -@comment BSD @deftypevr Macro {uint32_t} INADDR_NONE +@standards{BSD, netinet/in.h} This constant is returned by some functions to indicate an error. @end deftypevr -@comment netinet/in.h -@comment IPv6 basic API @deftp {Data Type} {struct in6_addr} +@standards{IPv6 basic API, netinet/in.h} This data type is used to store an IPv6 address. It stores 128 bits of data, which can be accessed (via a union) in a variety of ways. @end deftp -@comment netinet/in.h -@comment IPv6 basic API @deftypevr Constant {struct in6_addr} in6addr_loopback +@standards{IPv6 basic API, netinet/in.h} This constant is the IPv6 address @samp{::1}, the loopback address. See above for a description of what this means. The macro @code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your own variables to this value. @end deftypevr -@comment netinet/in.h -@comment IPv6 basic API @deftypevr Constant {struct in6_addr} in6addr_any +@standards{IPv6 basic API, netinet/in.h} This constant is the IPv6 address @samp{::}, the unspecified address. See above for a description of what this means. The macro @code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your @@ -1080,9 +1046,8 @@ addresses in network byte order, and network numbers and local-address-within-network numbers in host byte order. @xref{Byte Order}, for an explanation of network and host byte order. -@comment arpa/inet.h -@comment BSD @deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr}) +@standards{BSD, arpa/inet.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c inet_aton @mtslocale @c isdigit dup @mtslocale @@ -1096,9 +1061,8 @@ it in the @code{struct in_addr} that @var{addr} points to. @code{inet_aton} returns nonzero if the address is valid, zero if not. @end deftypefun -@comment arpa/inet.h -@comment BSD @deftypefun {uint32_t} inet_addr (const char *@var{name}) +@standards{BSD, arpa/inet.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c inet_addr @mtslocale @c inet_aton dup @mtslocale @@ -1111,9 +1075,8 @@ is obsolete because @code{INADDR_NONE} is a valid address indicate error return. @end deftypefun -@comment arpa/inet.h -@comment BSD @deftypefun {uint32_t} inet_network (const char *@var{name}) +@standards{BSD, arpa/inet.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c inet_network @mtslocale @c isdigit dup @mtslocale @@ -1130,9 +1093,8 @@ types. It doesn't work with classless addresses and shouldn't be used anymore. @end deftypefun -@comment arpa/inet.h -@comment BSD @deftypefun {char *} inet_ntoa (struct in_addr @var{addr}) +@standards{BSD, arpa/inet.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asurace{}}@acsafe{}} @c inet_ntoa @mtslocale @asurace @c writes to a thread-local static buffer @@ -1152,9 +1114,8 @@ described below should be used since it handles both IPv4 and IPv6 addresses. @end deftypefun -@comment arpa/inet.h -@comment BSD @deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local}) +@standards{BSD, arpa/inet.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c inet_makeaddr ok @c htonl dup ok @@ -1163,9 +1124,8 @@ number @var{net} with the local-address-within-network number @var{local}. @end deftypefun -@comment arpa/inet.h -@comment BSD @deftypefun uint32_t inet_lnaof (struct in_addr @var{addr}) +@standards{BSD, arpa/inet.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c inet_lnaof ok @c ntohl dup ok @@ -1179,9 +1139,8 @@ types. It doesn't work with classless addresses and shouldn't be used anymore. @end deftypefun -@comment arpa/inet.h -@comment BSD @deftypefun uint32_t inet_netof (struct in_addr @var{addr}) +@standards{BSD, arpa/inet.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c inet_netof ok @c ntohl dup ok @@ -1195,9 +1154,8 @@ types. It doesn't work with classless addresses and shouldn't be used anymore. @end deftypefun -@comment arpa/inet.h -@comment IPv6 basic API @deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf}) +@standards{IPv6 basic API, arpa/inet.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c inet_pton @mtslocale @c inet_pton4 ok @@ -1216,9 +1174,8 @@ address being converted. @var{cp} is a pointer to the input string, and responsibility to make sure the buffer is large enough. @end deftypefun -@comment arpa/inet.h -@comment IPv6 basic API @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len}) +@standards{IPv6 basic API, arpa/inet.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c inet_ntop @mtslocale @c inet_ntop4 @mtslocale @@ -1259,9 +1216,8 @@ The functions and other symbols for accessing this database are declared in @file{netdb.h}. They are BSD features, defined unconditionally if you include @file{netdb.h}. -@comment netdb.h -@comment BSD @deftp {Data Type} {struct hostent} +@standards{BSD, netdb.h} This data type is used to represent an entry in the hosts database. It has the following members: @@ -1309,9 +1265,8 @@ statically-allocated structure; you must copy the information if you need to save it across calls. You can also use @code{getaddrinfo} and @code{getnameinfo} to obtain this information. -@comment netdb.h -@comment BSD @deftypefun {struct hostent *} gethostbyname (const char *@var{name}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} @c gethostbyname @mtasurace:hostbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd @c libc_lock_lock dup @asulock @aculock @@ -1381,9 +1336,8 @@ The @code{gethostbyname} function returns information about the host named @var{name}. If the lookup fails, it returns a null pointer. @end deftypefun -@comment netdb.h -@comment IPv6 Basic API @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af}) +@standards{IPv6 Basic API, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname2} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} @c gethostbyname2 @mtasurace:hostbyname2 @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd @c libc_lock_lock dup @asulock @aculock @@ -1399,9 +1353,8 @@ allows the caller to specify the desired address family (e.g.@: @code{AF_INET} or @code{AF_INET6}) of the result. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun {struct hostent *} gethostbyaddr (const void *@var{addr}, socklen_t @var{length}, int @var{format}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyaddr} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} @c gethostbyaddr @mtasurace:hostbyaddr @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd @c libc_lock_lock dup @asulock @aculock @@ -1432,25 +1385,21 @@ with other systems.) Here are the error codes that you may find in @code{h_errno}: @vtable @code -@comment netdb.h -@comment BSD @item HOST_NOT_FOUND +@standards{BSD, netdb.h} No such host is known in the database. -@comment netdb.h -@comment BSD @item TRY_AGAIN +@standards{BSD, netdb.h} This condition happens when the name server could not be contacted. If you try again later, you may succeed then. -@comment netdb.h -@comment BSD @item NO_RECOVERY +@standards{BSD, netdb.h} A non-recoverable error occurred. -@comment netdb.h -@comment BSD @item NO_ADDRESS +@standards{BSD, netdb.h} The host database contains an entry for the name, but it doesn't have an associated Internet address. @end vtable @@ -1460,9 +1409,8 @@ reentrant and therefore unusable in multi-threaded applications. Therefore provides @theglibc{} a new set of functions which can be used in this context. -@comment netdb.h -@comment GNU @deftypefun int gethostbyname_r (const char *restrict @var{name}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) +@standards{GNU, netdb.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} @c gethostbyname_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd @c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -1585,9 +1533,8 @@ gethostname (char *host) @end smallexample @end deftypefun -@comment netdb.h -@comment GNU @deftypefun int gethostbyname2_r (const char *@var{name}, int @var{af}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) +@standards{GNU, netdb.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} @c gethostbyname2_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd @c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -1604,9 +1551,8 @@ allows the caller to specify the desired address family (e.g.@: @code{AF_INET} or @code{AF_INET6}) for the result. @end deftypefun -@comment netdb.h -@comment GNU @deftypefun int gethostbyaddr_r (const void *@var{addr}, socklen_t @var{length}, int @var{format}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) +@standards{GNU, netdb.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} @c gethostbyaddr_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd @c memcmp dup ok @@ -1641,9 +1587,8 @@ You can also scan the entire hosts database one entry at a time using @code{sethostent}, @code{gethostent} and @code{endhostent}. Be careful when using these functions because they are not reentrant. -@comment netdb.h -@comment BSD @deftypefun void sethostent (int @var{stayopen}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c sethostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -1668,9 +1613,8 @@ efficiency if you call those functions several times, by avoiding reopening the database for each call. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun {struct hostent *} gethostent (void) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtasurace{:hostentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c gethostent @mtasurace:hostent @mtasurace:hostentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -1696,9 +1640,8 @@ This function returns the next entry in the hosts database. It returns a null pointer if there are no more entries. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun void endhostent (void) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c endhostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock @asulock @aculock @@ -1748,16 +1691,14 @@ socket option @code{SO_REUSEADDR}. @xref{Socket-Level Options}. @pindex netinet/in.h These macros are defined in the header file @file{netinet/in.h}. -@comment netinet/in.h -@comment BSD @deftypevr Macro int IPPORT_RESERVED +@standards{BSD, netinet/in.h} Port numbers less than @code{IPPORT_RESERVED} are reserved for superuser use. @end deftypevr -@comment netinet/in.h -@comment BSD @deftypevr Macro int IPPORT_USERRESERVED +@standards{BSD, netinet/in.h} Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are reserved for explicit use; they will never be allocated automatically. @end deftypevr @@ -1775,9 +1716,8 @@ You can use these utilities, declared in @file{netdb.h}, to access the services database. @pindex netdb.h -@comment netdb.h -@comment BSD @deftp {Data Type} {struct servent} +@standards{BSD, netdb.h} This data type holds information about entries from the services database. It has the following members: @@ -1804,9 +1744,8 @@ To get information about a particular service, use the is returned in a statically-allocated structure; you must copy the information if you need to save it across calls. -@comment netdb.h -@comment BSD @deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:servbyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getservbyname =~ getpwuid @mtasurace:servbyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -1843,9 +1782,8 @@ This function is useful for servers as well as for clients; servers use it to determine which port they should listen on (@pxref{Listening}). @end deftypefun -@comment netdb.h -@comment BSD @deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:servbyport} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getservbyport =~ getservbyname @mtasurace:servbyport @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -1871,9 +1809,8 @@ You can also scan the services database using @code{setservent}, @code{getservent} and @code{endservent}. Be careful when using these functions because they are not reentrant. -@comment netdb.h -@comment BSD @deftypefun void setservent (int @var{stayopen}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c setservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -1893,9 +1830,8 @@ efficiency if you call those functions several times, by avoiding reopening the database for each call. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun {struct servent *} getservent (void) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtasurace{:serventbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getservent @mtasurace:servent @mtasurace:serventbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -1919,9 +1855,8 @@ This function returns the next entry in the services database. If there are no more entries, it returns a null pointer. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun void endservent (void) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c endservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock @asulock @aculock @@ -1972,9 +1907,8 @@ to @code{uint32_t}.) These functions are declared in @file{netinet/in.h}. @pindex netinet/in.h -@comment netinet/in.h -@comment BSD @deftypefun {uint16_t} htons (uint16_t @var{hostshort}) +@standards{BSD, netinet/in.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c htons ok @c bswap_16 ok @@ -1984,18 +1918,16 @@ This function converts the @code{uint16_t} integer @var{hostshort} from host byte order to network byte order. @end deftypefun -@comment netinet/in.h -@comment BSD @deftypefun {uint16_t} ntohs (uint16_t @var{netshort}) +@standards{BSD, netinet/in.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Alias to htons. This function converts the @code{uint16_t} integer @var{netshort} from network byte order to host byte order. @end deftypefun -@comment netinet/in.h -@comment BSD @deftypefun {uint32_t} htonl (uint32_t @var{hostlong}) +@standards{BSD, netinet/in.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c htonl ok @c bswap_32 dup ok @@ -2005,9 +1937,8 @@ host byte order to network byte order. This is used for IPv4 Internet addresses. @end deftypefun -@comment netinet/in.h -@comment BSD @deftypefun {uint32_t} ntohl (uint32_t @var{netlong}) +@standards{BSD, netinet/in.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Alias to htonl. This function converts the @code{uint32_t} integer @var{netlong} from @@ -2046,9 +1977,8 @@ Here are detailed descriptions of the utilities for accessing the protocols database. These are declared in @file{netdb.h}. @pindex netdb.h -@comment netdb.h -@comment BSD @deftp {Data Type} {struct protoent} +@standards{BSD, netdb.h} This data type is used to represent entries in the network protocols database. It has the following members: @@ -2071,9 +2001,8 @@ the protocols database for a specific protocol. The information is returned in a statically-allocated structure; you must copy the information if you need to save it across calls. -@comment netdb.h -@comment BSD @deftypefun {struct protoent *} getprotobyname (const char *@var{name}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:protobyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getprotobyname =~ getpwuid @mtasurace:protobyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -2093,9 +2022,8 @@ network protocol named @var{name}. If there is no such protocol, it returns a null pointer. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun {struct protoent *} getprotobynumber (int @var{protocol}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:protobynumber} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getprotobynumber =~ getpwuid @mtasurace:protobynumber @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -2119,9 +2047,8 @@ You can also scan the whole protocols database one protocol at a time by using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}. Be careful when using these functions because they are not reentrant. -@comment netdb.h -@comment BSD @deftypefun void setprotoent (int @var{stayopen}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c setprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -2141,9 +2068,8 @@ efficiency if you call those functions several times, by avoiding reopening the database for each call. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun {struct protoent *} getprotoent (void) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtasurace{:protoentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getprotoent @mtasurace:protoent @mtasurace:protoentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -2167,9 +2093,8 @@ This function returns the next entry in the protocols database. It returns a null pointer if there are no more entries. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun void endprotoent (void) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c endprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock @asulock @aculock @@ -2244,9 +2169,8 @@ The primitive for creating a socket is the @code{socket} function, declared in @file{sys/socket.h}. @pindex sys/socket.h -@comment sys/socket.h -@comment BSD @deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function creates a socket and specifies communication style @var{style}, which should be one of the socket styles listed in @@ -2307,9 +2231,8 @@ You can also shut down only reception or transmission on a connection by calling @code{shutdown}, which is declared in @file{sys/socket.h}. -@comment sys/socket.h -@comment BSD @deftypefun int shutdown (int @var{socket}, int @var{how}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{shutdown} function shuts down the connection of socket @var{socket}. The argument @var{how} specifies what action to @@ -2359,9 +2282,8 @@ main difference is that the socket pair is bidirectional, whereas the pipe has one input-only end and one output-only end (@pxref{Pipes and FIFOs}). -@comment sys/socket.h -@comment BSD @deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function creates a socket pair, returning the file descriptors in @code{@var{filedes}[0]} and @code{@var{filedes}[1]}. The socket pair @@ -2453,9 +2375,8 @@ waits for and accepts the connection. Here we discuss what the client program must do with the @code{connect} function, which is declared in @file{sys/socket.h}. -@comment sys/socket.h -@comment BSD @deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{connect} function initiates a connection from the socket with file descriptor @var{socket} to the socket whose address is @@ -2553,9 +2474,8 @@ protocol. In the local namespace, the ordinary file protection bits control who has access to connect to the socket. -@comment sys/socket.h -@comment BSD @deftypefun int listen (int @var{socket}, int @var{n}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} The @code{listen} function enables the socket @var{socket} to accept connections, thus making it a server socket. @@ -2606,9 +2526,8 @@ this queue as an argument to the @code{listen} function, although the system may also impose its own internal limit on the length of this queue. -@comment sys/socket.h -@comment BSD @deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length_ptr}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function is used to accept a connection request on the server socket @var{socket}. @@ -2665,9 +2584,8 @@ connectionless communication styles. @node Who is Connected @subsection Who is Connected to Me? -@comment sys/socket.h -@comment BSD @deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getpeername} function returns the address of the socket that @var{socket} is connected to; it stores the address in the memory space @@ -2734,9 +2652,8 @@ Primitives}. If the socket was connected but the connection has broken, you get a @code{SIGPIPE} signal for any use of @code{send} or @code{write} (@pxref{Miscellaneous Signals}). -@comment sys/socket.h -@comment BSD @deftypefun ssize_t send (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{send} function is like @code{write}, but with the additional flags @var{flags}. The possible values of @var{flags} are described @@ -2802,9 +2719,8 @@ The @code{recv} function is declared in the header file just as well use @code{read} instead of @code{recv}; see @ref{I/O Primitives}. -@comment sys/socket.h -@comment BSD @deftypefun ssize_t recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{recv} function is like @code{read}, but with the additional flags @var{flags}. The possible values of @var{flags} are described @@ -2853,23 +2769,20 @@ mask. You can bitwise-OR the values of the following macros together to obtain a value for this argument. All are defined in the header file @file{sys/socket.h}. -@comment sys/socket.h -@comment BSD @deftypevr Macro int MSG_OOB +@standards{BSD, sys/socket.h} Send or receive out-of-band data. @xref{Out-of-Band Data}. @end deftypevr -@comment sys/socket.h -@comment BSD @deftypevr Macro int MSG_PEEK +@standards{BSD, sys/socket.h} Look at the data but don't remove it from the input queue. This is only meaningful with input functions such as @code{recv}, not with @code{send}. @end deftypevr -@comment sys/socket.h -@comment BSD @deftypevr Macro int MSG_DONTROUTE +@standards{BSD, sys/socket.h} Don't include routing information in the message. This is only meaningful with output operations, and is usually only of interest for diagnostic or routing programs. We don't try to explain it here. @@ -3131,9 +3044,8 @@ destination by calling @code{connect} using an address format of @code{AF_UNSPEC} in the @var{addr} argument. @xref{Connecting}, for more information about the @code{connect} function. -@comment sys/socket.h -@comment BSD @deftypefun ssize_t sendto (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{sendto} function transmits the data in the @var{buffer} through the socket @var{socket} to the destination address specified @@ -3167,9 +3079,8 @@ The @code{recvfrom} function reads a packet from a datagram socket and also tells you where it was sent from. This function is declared in @file{sys/socket.h}. -@comment sys/socket.h -@comment BSD @deftypefun ssize_t recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{recvfrom} function reads one packet from the socket @var{socket} into the buffer @var{buffer}. The @var{size} argument @@ -3210,14 +3121,12 @@ you don't want to specify @var{flags} (@pxref{I/O Primitives}). @c supporting or that we support them. @c !!! they can do more; it is hairy -@comment sys/socket.h -@comment BSD @deftp {Data Type} {struct msghdr} +@standards{BSD, sys/socket.h} @end deftp -@comment sys/socket.h -@comment BSD @deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is defined as a cancellation point in multi-threaded @@ -3227,9 +3136,8 @@ whatever) are freed even if the thread is cancel. @c @xref{pthread_cleanup_push}, for a method how to do this. @end deftypefun -@comment sys/socket.h -@comment BSD @deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is defined as a cancellation point in multi-threaded @@ -3415,9 +3323,8 @@ protocol interface. Here are the functions for examining and modifying socket options. They are declared in @file{sys/socket.h}. -@comment sys/socket.h -@comment BSD @deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getsockopt} function gets information about the value of option @var{optname} at level @var{level} for socket @var{socket}. @@ -3446,9 +3353,8 @@ The @var{optname} doesn't make sense for the given @var{level}. @end table @end deftypefun -@comment sys/socket.h -@comment BSD @deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, const void *@var{optval}, socklen_t @var{optlen}) +@standards{BSD, sys/socket.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is used to set the socket option @var{optname} at level @var{level} for socket @var{socket}. The value of the option is passed @@ -3470,9 +3376,8 @@ for @code{getsockopt}. @node Socket-Level Options @subsection Socket-Level Options -@comment sys/socket.h -@comment BSD @deftypevr Constant int SOL_SOCKET +@standards{BSD, sys/socket.h} Use this constant as the @var{level} argument to @code{getsockopt} or @code{setsockopt} to manipulate the socket-level options described in this section. @@ -3484,9 +3389,8 @@ Here is a table of socket-level option names; all are defined in the header file @file{sys/socket.h}. @vtable @code -@comment sys/socket.h -@comment BSD @item SO_DEBUG +@standards{BSD, sys/socket.h} @c Extra blank line here makes the table look better. This option toggles recording of debugging information in the underlying @@ -3495,9 +3399,8 @@ protocol modules. The value has type @code{int}; a nonzero value means @c !!! should say how this is used @c OK, anyone who knows, please explain. -@comment sys/socket.h -@comment BSD @item SO_REUSEADDR +@standards{BSD, sys/socket.h} This option controls whether @code{bind} (@pxref{Setting Address}) should permit reuse of local addresses for this socket. If you enable this option, you can actually have two sockets with the same Internet @@ -3508,34 +3411,30 @@ including FTP, require you to keep reusing the same port number. The value has type @code{int}; a nonzero value means ``yes''. -@comment sys/socket.h -@comment BSD @item SO_KEEPALIVE +@standards{BSD, sys/socket.h} This option controls whether the underlying protocol should periodically transmit messages on a connected socket. If the peer fails to respond to these messages, the connection is considered broken. The value has type @code{int}; a nonzero value means ``yes''. -@comment sys/socket.h -@comment BSD @item SO_DONTROUTE +@standards{BSD, sys/socket.h} This option controls whether outgoing messages bypass the normal message routing facilities. If set, messages are sent directly to the network interface instead. The value has type @code{int}; a nonzero value means ``yes''. -@comment sys/socket.h -@comment BSD @item SO_LINGER +@standards{BSD, sys/socket.h} This option specifies what should happen when the socket of a type that promises reliable delivery still has untransmitted messages when it is closed; see @ref{Closing a Socket}. The value has type @code{struct linger}. -@comment sys/socket.h -@comment BSD @deftp {Data Type} {struct linger} +@standards{BSD, sys/socket.h} This structure type has the following members: @table @code @@ -3548,48 +3447,41 @@ This specifies the timeout period, in seconds. @end table @end deftp -@comment sys/socket.h -@comment BSD @item SO_BROADCAST +@standards{BSD, sys/socket.h} This option controls whether datagrams may be broadcast from the socket. The value has type @code{int}; a nonzero value means ``yes''. -@comment sys/socket.h -@comment BSD @item SO_OOBINLINE +@standards{BSD, sys/socket.h} If this option is set, out-of-band data received on the socket is placed in the normal input queue. This permits it to be read using @code{read} or @code{recv} without specifying the @code{MSG_OOB} flag. @xref{Out-of-Band Data}. The value has type @code{int}; a nonzero value means ``yes''. -@comment sys/socket.h -@comment BSD @item SO_SNDBUF +@standards{BSD, sys/socket.h} This option gets or sets the size of the output buffer. The value is a @code{size_t}, which is the size in bytes. -@comment sys/socket.h -@comment BSD @item SO_RCVBUF +@standards{BSD, sys/socket.h} This option gets or sets the size of the input buffer. The value is a @code{size_t}, which is the size in bytes. -@comment sys/socket.h -@comment GNU @item SO_STYLE -@comment sys/socket.h -@comment BSD @itemx SO_TYPE +@standards{GNU, sys/socket.h} +@standardsx{SO_TYPE, BSD, sys/socket.h} This option can be used with @code{getsockopt} only. It is used to get the socket's communication style. @code{SO_TYPE} is the historical name, and @code{SO_STYLE} is the preferred name in GNU. The value has type @code{int} and its value designates a communication style; see @ref{Communication Styles}. -@comment sys/socket.h -@comment BSD @item SO_ERROR +@standards{BSD, sys/socket.h} @c Extra blank line here makes the table look better. This option can be used with @code{getsockopt} only. It is used to reset @@ -3614,9 +3506,8 @@ useful for programs that simply communicate over the network. We provide functions to access this database, which are declared in @file{netdb.h}. -@comment netdb.h -@comment BSD @deftp {Data Type} {struct netent} +@standards{BSD, netdb.h} This data type is used to represent information about entries in the networks database. It has the following members: @@ -3643,9 +3534,8 @@ the networks database for information about a specific network. The information is returned in a statically-allocated structure; you must copy the information if you need to save it. -@comment netdb.h -@comment BSD @deftypefun {struct netent *} getnetbyname (const char *@var{name}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getnetbyname =~ getpwuid @mtasurace:netbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -3666,9 +3556,8 @@ named @var{name}. It returns a null pointer if there is no such network. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun {struct netent *} getnetbyaddr (uint32_t @var{net}, int @var{type}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netbyaddr} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getnetbyaddr =~ getpwuid @mtasurace:netbyaddr @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -3695,9 +3584,8 @@ You can also scan the networks database using @code{setnetent}, @code{getnetent} and @code{endnetent}. Be careful when using these functions because they are not reentrant. -@comment netdb.h -@comment BSD @deftypefun void setnetent (int @var{stayopen}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c setnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -3718,9 +3606,8 @@ efficiency if you call those functions several times, by avoiding reopening the database for each call. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun {struct netent *} getnetent (void) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtasurace{:netentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getnetent @mtasurace:netent @mtasurace:netentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -3745,9 +3632,8 @@ This function returns the next entry in the networks database. It returns a null pointer if there are no more entries. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun void endnetent (void) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c endnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock @asulock @aculock diff --git a/manual/startup.texi b/manual/startup.texi index e4c983ada6..7395d32dd0 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -219,8 +219,8 @@ argument which itself is a comma separated list of options. To ease the programming of code like this the function @code{getsubopt} is available. -@comment stdlib.h @deftypefun int getsubopt (char **@var{optionp}, char *const *@var{tokens}, char **@var{valuep}) +@standards{???, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c getsubopt ok @c strchrnul dup ok @@ -324,9 +324,8 @@ Modifications of environment variables are not allowed in multi-threaded programs. The @code{getenv} and @code{secure_getenv} functions can be safely used in multi-threaded programs. -@comment stdlib.h -@comment ISO @deftypefun {char *} getenv (const char *@var{name}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}} @c Unguarded access to __environ. This function returns a string that is the value of the environment @@ -337,9 +336,8 @@ environment variable @var{name} is not defined, the value is a null pointer. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun {char *} secure_getenv (const char *@var{name}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}} @c Calls getenv unless secure mode is enabled. This function is similar to @code{getenv}, but it returns a null @@ -352,9 +350,8 @@ This function is a GNU extension. @end deftypefun -@comment stdlib.h -@comment SVID @deftypefun int putenv (char *@var{string}) +@standards{SVID, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c putenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem @c strchr dup ok @@ -384,9 +381,8 @@ This function is part of the extended Unix interface. You should define @end deftypefun -@comment stdlib.h -@comment BSD @deftypefun int setenv (const char *@var{name}, const char *@var{value}, int @var{replace}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c setenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem @c add_to_environ @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem @@ -425,9 +421,8 @@ This function was originally part of the BSD library but is now part of the Unix standard. @end deftypefun -@comment stdlib.h -@comment BSD @deftypefun int unsetenv (const char *@var{name}) +@standards{BSD, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c unsetenv @mtasuconst:@mtsenv @asulock @aculock @c strchr dup ok @@ -455,9 +450,8 @@ function is said to be used in the POSIX.9 (POSIX bindings for Fortran never happened. But we still provide this function as a GNU extension to enable writing standard compliant Fortran environments. -@comment stdlib.h -@comment GNU @deftypefun int clearenv (void) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} @c clearenv @mtasuconst:@mtsenv @ascuheap @asulock @aculock @acsmem @c libc_lock_lock @asulock @aculock @@ -477,9 +471,8 @@ objects to add more variables to the environment (for example, to communicate with another program you are about to execute; @pxref{Executing a File}). -@comment unistd.h -@comment POSIX.1 @deftypevar {char **} environ +@standards{POSIX.1, unistd.h} The environment is represented as an array of strings. Each string is of the format @samp{@var{name}=@var{value}}. The order in which strings appear in the environment is not significant, but the same @@ -665,8 +658,8 @@ interfaces, such as @code{sysconf}. However, on a platform-by-platform basis there may be information that is not available any other way. @subsection Definition of @code{getauxval} -@comment sys/auxv.h @deftypefun {unsigned long int} getauxval (unsigned long int @var{type}) +@standards{???, sys/auxv.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Reads from hwcap or iterates over constant auxv. This function is used to inquire about the entries in the auxiliary @@ -722,9 +715,8 @@ anyway. @code{syscall} is declared in @file{unistd.h}. -@comment unistd.h -@comment ??? @deftypefun {long int} syscall (long int @var{sysno}, @dots{}) +@standards{???, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{syscall} performs a generic system call. @@ -828,9 +820,8 @@ calling @code{exit}. Returning from @code{main} is equivalent to calling @code{exit}, and the value that @code{main} returns is used as the argument to @code{exit}. -@comment stdlib.h -@comment ISO @deftypefun void exit (int @var{status}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:exit}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} @c Access to the atexit/on_exit list, the libc_atexit hook and tls dtors @c is not guarded. Streams must be flushed, and that triggers the usual @@ -905,9 +896,8 @@ conventional status value for success and failure, respectively. They are declared in the file @file{stdlib.h}. @pindex stdlib.h -@comment stdlib.h -@comment ISO @deftypevr Macro int EXIT_SUCCESS +@standards{ISO, stdlib.h} This macro can be used with the @code{exit} function to indicate successful program completion. @@ -916,9 +906,8 @@ systems, the value might be some other (possibly non-constant) integer expression. @end deftypevr -@comment stdlib.h -@comment ISO @deftypevr Macro int EXIT_FAILURE +@standards{ISO, stdlib.h} This macro can be used with the @code{exit} function to indicate unsuccessful program completion in a general sense. @@ -948,9 +937,8 @@ exiting. It is much more robust to make the cleanup invisible to the application, by setting up a cleanup function in the library itself using @code{atexit} or @code{on_exit}. -@comment stdlib.h -@comment ISO @deftypefun int atexit (void (*@var{function}) (void)) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} @c atexit @ascuheap @asulock @aculock @acsmem @c cxa_atexit @ascuheap @asulock @aculock @acsmem @@ -968,9 +956,8 @@ The return value from @code{atexit} is zero on success and nonzero if the function cannot be registered. @end deftypefun -@comment stdlib.h -@comment SunOS @deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg}) +@standards{SunOS, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} @c on_exit @ascuheap @asulock @aculock @acsmem @c new_exitfn dup @ascuheap @asulock @aculock @acsmem @@ -1003,9 +990,8 @@ You can abort your program using the @code{abort} function. The prototype for this function is in @file{stdlib.h}. @pindex stdlib.h -@comment stdlib.h -@comment ISO @deftypefun void abort (void) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} @c The implementation takes a recursive lock and attempts to support @c calls from signal handlers, but if we're in the middle of flushing or @@ -1034,9 +1020,8 @@ The @code{_exit} function is the primitive used for process termination by @code{exit}. It is declared in the header file @file{unistd.h}. @pindex unistd.h -@comment unistd.h -@comment POSIX.1 @deftypefun void _exit (int @var{status}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall (exit_group or exit); calls __task_terminate on hurd, @c and abort in the generic posix implementation. @@ -1046,9 +1031,8 @@ execute cleanup functions registered with @code{atexit} or @code{on_exit}. @end deftypefun -@comment stdlib.h -@comment ISO @deftypefun void _Exit (int @var{status}) +@standards{ISO, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Alias for _exit. The @code{_Exit} function is the @w{ISO C} equivalent to @code{_exit}. diff --git a/manual/stdio.texi b/manual/stdio.texi index 29f3fed89b..5d7b50c442 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -55,9 +55,8 @@ only in the technical sense. @pindex stdio.h The @code{FILE} type is declared in the header file @file{stdio.h}. -@comment stdio.h -@comment ISO @deftp {Data Type} FILE +@standards{ISO, stdio.h} This is the data type used to represent stream objects. A @code{FILE} object holds all of the internal state information about the connection to the associated file, including such things as the file position @@ -86,25 +85,22 @@ for the process. These streams are declared in the header file @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftypevar {FILE *} stdin +@standards{ISO, stdio.h} The @dfn{standard input} stream, which is the normal source of input for the program. @end deftypevar @cindex standard input stream -@comment stdio.h -@comment ISO @deftypevar {FILE *} stdout +@standards{ISO, stdio.h} The @dfn{standard output} stream, which is used for normal output from the program. @end deftypevar @cindex standard output stream -@comment stdio.h -@comment ISO @deftypevar {FILE *} stderr +@standards{ISO, stdio.h} The @dfn{standard error} stream, which is used for error messages and diagnostics issued by the program. @end deftypevar @@ -145,9 +141,8 @@ involve creating a new file. Everything described in this section is declared in the header file @file{stdio.h}. -@comment stdio.h -@comment ISO @deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} @c fopen may leak the list lock if cancelled within _IO_link_in. The @code{fopen} function opens a stream for I/O to the file @@ -264,9 +259,8 @@ programs (which can easily happen). It may be advantageous to use the file locking facilities to avoid simultaneous access. @xref{File Locks}. -@comment stdio.h -@comment Unix98 @deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype}) +@standards{Unix98, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} This function is similar to @code{fopen} but the stream it returns a pointer for is opened using @code{open64}. Therefore this stream can be @@ -280,9 +274,8 @@ bits machine this function is available under the name @code{fopen} and so transparently replaces the old interface. @end deftypefun -@comment stdio.h -@comment ISO @deftypevr Macro int FOPEN_MAX +@standards{ISO, stdio.h} The value of this macro is an integer constant expression that represents the minimum number of streams that the implementation guarantees can be open simultaneously. You might be able to open more @@ -294,9 +287,8 @@ Limits}. In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}. @end deftypevr -@comment stdio.h -@comment ISO @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}} @c Like most I/O operations, this one is guarded by a recursive lock, @c released even upon cancellation, but cancellation may leak file @@ -338,9 +330,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a interface replaces transparently the old interface. @end deftypefun -@comment stdio.h -@comment Unix98 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream}) +@standards{Unix98, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}} This function is similar to @code{freopen}. The only difference is that on 32 bit machine the stream returned is able to read beyond the @@ -360,9 +351,8 @@ available and would have to be remembered separately. Solaris introduced a few functions to get this information from the stream descriptor and these functions are also available in @theglibc{}. -@comment stdio_ext.h -@comment GNU @deftypefun int __freadable (FILE *@var{stream}) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__freadable} function determines whether the stream @var{stream} was opened to allow reading. In this case the return value @@ -371,9 +361,8 @@ is nonzero. For write-only streams the function returns zero. This function is declared in @file{stdio_ext.h}. @end deftypefun -@comment stdio_ext.h -@comment GNU @deftypefun int __fwritable (FILE *@var{stream}) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__fwritable} function determines whether the stream @var{stream} was opened to allow writing. In this case the return value @@ -385,9 +374,8 @@ This function is declared in @file{stdio_ext.h}. For slightly different kinds of problems there are two more functions. They provide even finer-grained information. -@comment stdio_ext.h -@comment GNU @deftypefun int __freading (FILE *@var{stream}) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__freading} function determines whether the stream @var{stream} was last read from or whether it is opened read-only. In @@ -399,9 +387,8 @@ buffer, among other things. This function is declared in @file{stdio_ext.h}. @end deftypefun -@comment stdio_ext.h -@comment GNU @deftypefun int __fwriting (FILE *@var{stream}) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__fwriting} function determines whether the stream @var{stream} was last written to or whether it is opened write-only. In @@ -419,9 +406,8 @@ When a stream is closed with @code{fclose}, the connection between the stream and the file is canceled. After you have closed a stream, you cannot perform any additional operations on it. -@comment stdio.h -@comment ISO @deftypefun int fclose (FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c After fclose, it is undefined behavior to use the stream it points @c to. Therefore, one must only call fclose when the stream is @@ -456,9 +442,8 @@ The function @code{fclose} is declared in @file{stdio.h}. To close all streams currently available @theglibc{} provides another function. -@comment stdio.h -@comment GNU @deftypefun int fcloseall (void) +@standards{GNU, stdio.h} @safety{@prelim{}@mtunsafe{@mtasurace{:streams}}@asunsafe{}@acsafe{}} @c Like fclose, using any previously-opened streams after fcloseall is @c undefined. However, the implementation of fcloseall isn't equivalent @@ -518,9 +503,8 @@ themselves would ensure only atomicity of their own operation, but not atomicity over all the function calls. For this it is necessary to perform the stream locking in the application code. -@comment stdio.h -@comment POSIX @deftypefun void flockfile (FILE *@var{stream}) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} @c There's no way to tell whether the lock was acquired before or after @c cancellation so as to unlock only when appropriate. @@ -532,9 +516,8 @@ thread will block until the lock is acquired. An explicit call to @code{funlockfile} has to be used to release the lock. @end deftypefun -@comment stdio.h -@comment POSIX @deftypefun int ftrylockfile (FILE *@var{stream}) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} The @code{ftrylockfile} function tries to acquire the internal locking object associated with the stream @var{stream} just like @@ -544,9 +527,8 @@ the lock was successfully acquired. Otherwise the stream is locked by another thread. @end deftypefun -@comment stdio.h -@comment POSIX @deftypefun void funlockfile (FILE *@var{stream}) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} The @code{funlockfile} function releases the internal locking object of the stream @var{stream}. The stream must have been locked before by a @@ -670,9 +652,8 @@ manipulation of the buffer of the stream. A second way to avoid locking is by using a non-standard function which was introduced in Solaris and is available in @theglibc{} as well. -@comment stdio_ext.h -@comment GNU @deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type}) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asulock{}}@acsafe{}} @c Changing the implicit-locking status of a stream while it's in use by @c another thread may cause a lock to be implicitly acquired and not @@ -783,9 +764,8 @@ a stream. There are no diagnostics issued. The application behavior will simply be strange or the application will simply crash. The @code{fwide} function can help avoid this. -@comment wchar.h -@comment ISO @deftypefun int fwide (FILE *@var{stream}, int @var{mode}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{}}} @c Querying is always safe, but changing the stream when it's in use @c upthread may be problematic. Like most lock-acquiring functions, @@ -873,9 +853,8 @@ These narrow stream functions are declared in the header file @pindex stdio.h @pindex wchar.h -@comment stdio.h -@comment ISO @deftypefun int fputc (int @var{c}, FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} @c If the stream is in use when interrupted by a signal, the recursive @c lock won't help ensure the stream is consistent; indeed, if fputc @@ -892,18 +871,16 @@ The @code{fputc} function converts the character @var{c} to type character @var{c} is returned. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The @code{fputwc} function writes the wide character @var{wc} to the stream @var{stream}. @code{WEOF} is returned if a write error occurs; otherwise the character @var{wc} is returned. @end deftypefun -@comment stdio.h -@comment POSIX @deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream}) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} @c The unlocked functions can't possibly satisfy the MT-Safety @c requirements on their own, because they require external locking for @@ -912,9 +889,8 @@ The @code{fputc_unlocked} function is equivalent to the @code{fputc} function except that it does not implicitly lock the stream. @end deftypefun -@comment wchar.h -@comment POSIX @deftypefun wint_t fputwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) +@standards{POSIX, wchar.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fputwc_unlocked} function is equivalent to the @code{fputwc} function except that it does not implicitly lock the stream. @@ -922,9 +898,8 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int putc (int @var{c}, FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} This is just like @code{fputc}, except that most systems implement it as a macro, making it faster. One consequence is that it may evaluate the @@ -933,9 +908,8 @@ general rule for macros. @code{putc} is usually the best function to use for writing a single character. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} This is just like @code{fputwc}, except that it can be implement as a macro, making it faster. One consequence is that it may evaluate the @@ -944,17 +918,15 @@ general rule for macros. @code{putwc} is usually the best function to use for writing a single wide character. @end deftypefun -@comment stdio.h -@comment POSIX @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream}) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putc_unlocked} function is equivalent to the @code{putc} function except that it does not implicitly lock the stream. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putwc_unlocked} function is equivalent to the @code{putwc} function except that it does not implicitly lock the stream. @@ -962,33 +934,29 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int putchar (int @var{c}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The @code{putchar} function is equivalent to @code{putc} with @code{stdout} as the value of the @var{stream} argument. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun wint_t putwchar (wchar_t @var{wc}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The @code{putwchar} function is equivalent to @code{putwc} with @code{stdout} as the value of the @var{stream} argument. @end deftypefun -@comment stdio.h -@comment POSIX @deftypefun int putchar_unlocked (int @var{c}) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putchar_unlocked} function is equivalent to the @code{putchar} function except that it does not implicitly lock the stream. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun wint_t putwchar_unlocked (wchar_t @var{wc}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putwchar_unlocked} function is equivalent to the @code{putwchar} function except that it does not implicitly lock the stream. @@ -996,9 +964,8 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int fputs (const char *@var{s}, FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The function @code{fputs} writes the string @var{s} to the stream @var{stream}. The terminating null character is not written. @@ -1020,9 +987,8 @@ fputs ("hungry?\n", stdout); outputs the text @samp{Are you hungry?} followed by a newline. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The function @code{fputws} writes the wide character string @var{ws} to the stream @var{stream}. The terminating null character is not written. @@ -1033,9 +999,8 @@ This function returns @code{WEOF} if a write error occurs, and otherwise a non-negative value. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fputs_unlocked} function is equivalent to the @code{fputs} function except that it does not implicitly lock the stream. @@ -1043,9 +1008,8 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fputws_unlocked} function is equivalent to the @code{fputws} function except that it does not implicitly lock the stream. @@ -1053,9 +1017,8 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int puts (const char *@var{s}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{puts} function writes the string @var{s} to the stream @code{stdout} followed by a newline. The terminating null character of @@ -1073,9 +1036,8 @@ puts ("This is a message."); outputs the text @samp{This is a message.} followed by a newline. @end deftypefun -@comment stdio.h -@comment SVID @deftypefun int putw (int @var{w}, FILE *@var{stream}) +@standards{SVID, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function writes the word @var{w} (that is, an @code{int}) to @var{stream}. It is provided for compatibility with SVID, but we @@ -1106,9 +1068,8 @@ that it is no longer distinguishable from the valid character you've verified that the result is not @code{EOF}, you can be sure that it will fit in a @samp{char} variable without loss of information. -@comment stdio.h -@comment ISO @deftypefun int fgetc (FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} @c Same caveats as fputc, but instead of losing a write in case of async @c signals, we may read the same character more than once, and the @@ -1120,26 +1081,23 @@ the stream @var{stream} and returns its value, converted to an @code{EOF} is returned instead. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun wint_t fgetwc (FILE *@var{stream}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function reads the next wide character from the stream @var{stream} and returns its value. If an end-of-file condition or read error occurs, @code{WEOF} is returned instead. @end deftypefun -@comment stdio.h -@comment POSIX @deftypefun int fgetc_unlocked (FILE *@var{stream}) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fgetc_unlocked} function is equivalent to the @code{fgetc} function except that it does not implicitly lock the stream. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun wint_t fgetwc_unlocked (FILE *@var{stream}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc} function except that it does not implicitly lock the stream. @@ -1147,9 +1105,8 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int getc (FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This is just like @code{fgetc}, except that it is permissible (and typical) for it to be implemented as a macro that evaluates the @@ -1158,9 +1115,8 @@ optimized, so it is usually the best function to use to read a single character. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun wint_t getwc (FILE *@var{stream}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This is just like @code{fgetwc}, except that it is permissible for it to be implemented as a macro that evaluates the @var{stream} argument more @@ -1168,17 +1124,15 @@ than once. @code{getwc} can be highly optimized, so it is usually the best function to use to read a single wide character. @end deftypefun -@comment stdio.h -@comment POSIX @deftypefun int getc_unlocked (FILE *@var{stream}) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getc_unlocked} function is equivalent to the @code{getc} function except that it does not implicitly lock the stream. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun wint_t getwc_unlocked (FILE *@var{stream}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getwc_unlocked} function is equivalent to the @code{getwc} function except that it does not implicitly lock the stream. @@ -1186,33 +1140,29 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int getchar (void) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{getchar} function is equivalent to @code{getc} with @code{stdin} as the value of the @var{stream} argument. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun wint_t getwchar (void) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin} as the value of the @var{stream} argument. @end deftypefun -@comment stdio.h -@comment POSIX @deftypefun int getchar_unlocked (void) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getchar_unlocked} function is equivalent to the @code{getchar} function except that it does not implicitly lock the stream. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun wint_t getwchar_unlocked (void) +@standards{GNU, wchar.h} @safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getwchar_unlocked} function is equivalent to the @code{getwchar} function except that it does not implicitly lock the stream. @@ -1253,9 +1203,8 @@ y_or_n_p (const char *question) @} @end smallexample -@comment stdio.h -@comment SVID @deftypefun int getw (FILE *@var{stream}) +@standards{SVID, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function reads a word (that is, an @code{int}) from @var{stream}. It's provided for compatibility with SVID. We recommend you use @@ -1282,9 +1231,8 @@ occurrence of a specified delimiter character. All these functions are declared in @file{stdio.h}. -@comment stdio.h -@comment GNU @deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} @c Besides the usual possibility of getting an inconsistent stream in a @c signal handler or leaving it inconsistent in case of cancellation, @@ -1324,9 +1272,8 @@ If an error occurs or end of file is reached without any bytes read, @code{getline} returns @code{-1}. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} @c See the getline @acucorrupt note. This function is like @code{getline} except that the character which @@ -1350,9 +1297,8 @@ getline (char **lineptr, size_t *n, FILE *stream) @end smallexample @end deftypefun -@comment stdio.h -@comment ISO @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{fgets} function reads characters from the stream @var{stream} up to and including a newline character and stores them in the string @@ -1374,9 +1320,8 @@ a null character, you should either handle it properly or print a clear error message. We recommend using @code{getline} instead of @code{fgets}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{fgetws} function reads wide characters from the stream @var{stream} up to and including a newline character and stores them in @@ -1400,9 +1345,8 @@ message. @comment XXX We need getwline!!! @end deftypefun -@comment stdio.h -@comment GNU @deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fgets_unlocked} function is equivalent to the @code{fgets} function except that it does not implicitly lock the stream. @@ -1410,9 +1354,8 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fgetws_unlocked} function is equivalent to the @code{fgetws} function except that it does not implicitly lock the stream. @@ -1420,9 +1363,8 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment stdio.h -@comment ISO @deftypefn {Deprecated function} {char *} gets (char *@var{s}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The function @code{gets} reads characters from the stream @code{stdin} up to the next newline character, and stores them in the string @var{s}. @@ -1511,9 +1453,8 @@ so that the next input characters will be @samp{9} and @samp{b}. The function to unread a character is called @code{ungetc}, because it reverses the action of @code{getc}. -@comment stdio.h -@comment ISO @deftypefun int ungetc (int @var{c}, FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{ungetc} function pushes back the character @var{c} onto the input stream @var{stream}. So the next input from @var{stream} will @@ -1549,9 +1490,8 @@ input available. After you read that character, trying to read again will encounter end of file. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{ungetwc} function behaves just like @code{ungetc} just that it pushes back a wide character. @@ -1608,9 +1548,8 @@ different kinds of computers. These functions are declared in @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function reads up to @var{count} objects of size @var{size} into the array @var{data}, from the stream @var{stream}. It returns the @@ -1624,9 +1563,8 @@ returns the number of complete objects read, and discards the partial object. Therefore, the stream remains at the actual end of the file. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fread_unlocked} function is equivalent to the @code{fread} function except that it does not implicitly lock the stream. @@ -1634,9 +1572,8 @@ function except that it does not implicitly lock the stream. This function is a GNU extension. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function writes up to @var{count} objects of size @var{size} from the array @var{data}, to the stream @var{stream}. The return value is @@ -1644,9 +1581,8 @@ normally @var{count}, if the call succeeds. Any other value indicates some sort of error, such as running out of space. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fwrite_unlocked} function is equivalent to the @code{fwrite} function except that it does not implicitly lock the stream. @@ -2387,9 +2323,8 @@ the easiest way to make sure you have all the right prototypes is to just include @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftypefun int printf (const char *@var{template}, @dots{}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} The @code{printf} function prints the optional arguments under the control of the template string @var{template} to the stream @@ -2397,9 +2332,8 @@ control of the template string @var{template} to the stream negative value if there was an output error. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int wprintf (const wchar_t *@var{template}, @dots{}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} The @code{wprintf} function prints the optional arguments under the control of the wide template string @var{template} to the stream @@ -2407,25 +2341,22 @@ control of the wide template string @var{template} to the stream negative value if there was an output error. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is just like @code{printf}, except that the output is written to the stream @var{stream} instead of @code{stdout}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is just like @code{wprintf}, except that the output is written to the stream @var{stream} instead of @code{stdout}. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is like @code{printf}, except that the output is stored in the character array @var{s} instead of written to a stream. A null character is written @@ -2448,9 +2379,8 @@ To avoid this problem, you can use @code{snprintf} or @code{asprintf}, described below. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun int swprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, @dots{}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is like @code{wprintf}, except that the output is stored in the wide character array @var{ws} instead of written to a stream. A null @@ -2473,9 +2403,8 @@ again and decided to not define a function exactly corresponding to @code{sprintf}. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{snprintf} function is similar to @code{sprintf}, except that the @var{size} argument specifies the maximum number of characters to @@ -2544,9 +2473,8 @@ changed in order to comply with the @w{ISO C99} standard. The functions in this section do formatted output and place the results in dynamically allocated memory. -@comment stdio.h -@comment GNU @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function is similar to @code{sprintf}, except that it dynamically allocates a string (as with @code{malloc}; @pxref{Unconstrained @@ -2577,9 +2505,8 @@ make_message (char *name, char *value) @end smallexample @end deftypefun -@comment stdio.h -@comment GNU @deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} This function is similar to @code{asprintf}, except that it uses the obstack @var{obstack} to allocate the space. @xref{Obstacks}. @@ -2644,27 +2571,24 @@ it. Prototypes for these functions are declared in @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftypefun int vprintf (const char *@var{template}, va_list @var{ap}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is similar to @code{printf} except that, instead of taking a variable number of arguments directly, it takes an argument list pointer @var{ap}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is similar to @code{wprintf} except that, instead of taking a variable number of arguments directly, it takes an argument list pointer @var{ap}. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} @c Although vfprintf sets up a cleanup region to release the lock on the @c output stream, it doesn't use it to release args_value or string in @@ -2711,49 +2635,43 @@ This is the equivalent of @code{fprintf} with the variable argument list specified directly as for @code{vprintf}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This is the equivalent of @code{fwprintf} with the variable argument list specified directly as for @code{vwprintf}. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{sprintf} with the variable argument list specified directly as for @code{vprintf}. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun int vswprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{swprintf} with the variable argument list specified directly as for @code{vwprintf}. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{snprintf} with the variable argument list specified directly as for @code{vprintf}. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{vasprintf} function is the equivalent of @code{asprintf} with the variable argument list specified directly as for @code{vprintf}. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c The obstack is not guarded by mutexes, it might be at an inconsistent @c state within a signal handler, and it could be left at an @@ -2827,9 +2745,8 @@ arguments from the user's program, which could cause a crash. All the symbols described in this section are declared in the header file @file{printf.h}. -@comment printf.h -@comment GNU @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes}) +@standards{GNU, printf.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function returns information about the number and types of arguments expected by the @code{printf} template string @var{template}. @@ -2851,9 +2768,8 @@ array and call @code{parse_printf_format} again. The argument types are encoded as a combination of a basic type and modifier flag bits. -@comment printf.h -@comment GNU @deftypevr Macro int PA_FLAG_MASK +@standards{GNU, printf.h} This macro is a bitmask for the type modifier flag bits. You can write the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to @@ -2864,39 +2780,32 @@ Here are symbolic constants that represent the basic types; they stand for integer values. @vtable @code -@comment printf.h -@comment GNU @item PA_INT +@standards{GNU, printf.h} This specifies that the base type is @code{int}. -@comment printf.h -@comment GNU @item PA_CHAR +@standards{GNU, printf.h} This specifies that the base type is @code{int}, cast to @code{char}. -@comment printf.h -@comment GNU @item PA_STRING +@standards{GNU, printf.h} This specifies that the base type is @code{char *}, a null-terminated string. -@comment printf.h -@comment GNU @item PA_POINTER +@standards{GNU, printf.h} This specifies that the base type is @code{void *}, an arbitrary pointer. -@comment printf.h -@comment GNU @item PA_FLOAT +@standards{GNU, printf.h} This specifies that the base type is @code{float}. -@comment printf.h -@comment GNU @item PA_DOUBLE +@standards{GNU, printf.h} This specifies that the base type is @code{double}. -@comment printf.h -@comment GNU @item PA_LAST +@standards{GNU, printf.h} You can define additional base types for your own programs as offsets from @code{PA_LAST}. For example, if you have data types @samp{foo} and @samp{bar} with their own specialized @code{printf} conversions, @@ -2912,34 +2821,29 @@ Here are the flag bits that modify a basic type. They are combined with the code for the basic type using inclusive-or. @vtable @code -@comment printf.h -@comment GNU @item PA_FLAG_PTR +@standards{GNU, printf.h} If this bit is set, it indicates that the encoded type is a pointer to the base type, rather than an immediate value. For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}. -@comment printf.h -@comment GNU @item PA_FLAG_SHORT +@standards{GNU, printf.h} If this bit is set, it indicates that the base type is modified with @code{short}. (This corresponds to the @samp{h} type modifier.) -@comment printf.h -@comment GNU @item PA_FLAG_LONG +@standards{GNU, printf.h} If this bit is set, it indicates that the base type is modified with @code{long}. (This corresponds to the @samp{l} type modifier.) -@comment printf.h -@comment GNU @item PA_FLAG_LONG_LONG +@standards{GNU, printf.h} If this bit is set, it indicates that the base type is modified with @code{long long}. (This corresponds to the @samp{L} type modifier.) -@comment printf.h -@comment GNU @item PA_FLAG_LONG_DOUBLE +@standards{GNU, printf.h} This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}. @end vtable @@ -3068,9 +2972,8 @@ The function to register a new output conversion is @code{register_printf_function}, declared in @file{printf.h}. @pindex printf.h -@comment printf.h -@comment GNU @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function}) +@standards{GNU, printf.h} @safety{@prelim{}@mtunsafe{@mtasuconst{:printfext}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} @c This function is guarded by the global non-recursive libc lock, but @c users of the variables it sets aren't, and those should be MT-Safe, @@ -3134,9 +3037,8 @@ specifier. This data type is declared in the header file @file{printf.h}. @pindex printf.h -@comment printf.h -@comment GNU @deftp {Type} {struct printf_info} +@standards{GNU, printf.h} This structure is used to pass information about the options appearing in an instance of a conversion specifier in a @code{printf} template string to the handler and arginfo functions for that specifier. It @@ -3259,9 +3161,8 @@ Your handler function should return a value just like @code{printf} does: it should return the number of characters it has written, or a negative value to indicate an error. -@comment printf.h -@comment GNU @deftp {Data Type} printf_function +@standards{GNU, printf.h} This is the data type that a handler function should have. @end deftp @@ -3284,9 +3185,8 @@ types of each of these arguments. This information is encoded using the various @samp{PA_} macros. (You will notice that this is the same calling convention @code{parse_printf_format} itself uses.) -@comment printf.h -@comment GNU @deftp {Data Type} printf_arginfo_function +@standards{GNU, printf.h} This type is used to describe functions that return information about the number and type of arguments used by a conversion specifier. @end deftp @@ -3320,9 +3220,8 @@ The output produced by this program looks like: @code{printf} handler extension. There are two functions available which implement a special way to print floating-point numbers. -@comment printf.h -@comment GNU @deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args}) +@standards{GNU, printf.h} @safety{@prelim{}@mtsafe{@mtsrace{:fp} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @acucorrupt{}}} @c This is meant to be called by vfprintf, that should hold the lock on @c the stream, but if this function is called directly, output will be @@ -3384,9 +3283,8 @@ format character as if it were @code{%.3fk} and will yield @code{1.000k}. Due to the requirements of @code{register_printf_function} we must also provide the function which returns information about the arguments. -@comment printf.h -@comment GNU @deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes}) +@standards{GNU, printf.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function will return in @var{argtypes} the information about the used parameters in the way the @code{vfprintf} implementation expects @@ -4005,9 +3903,8 @@ input. Prototypes for these functions are in the header file @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftypefun int scanf (const char *@var{template}, @dots{}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} The @code{scanf} function reads formatted input from the stream @code{stdin} under the control of the template string @var{template}. @@ -4020,9 +3917,8 @@ including matches against whitespace and literal characters in the template, then @code{EOF} is returned. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int wscanf (const wchar_t *@var{template}, @dots{}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} The @code{wscanf} function reads formatted input from the stream @code{stdin} under the control of the template string @var{template}. @@ -4035,25 +3931,22 @@ including matches against whitespace and literal characters in the template, then @code{WEOF} is returned. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is just like @code{scanf}, except that the input is read from the stream @var{stream} instead of @code{stdin}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is just like @code{wscanf}, except that the input is read from the stream @var{stream} instead of @code{stdin}. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is like @code{scanf}, except that the characters are taken from the null-terminated string @var{s} instead of from a stream. Reaching the @@ -4065,9 +3958,8 @@ as an argument to receive a string read under control of the @samp{%s}, @samp{%S}, or @samp{%[} conversion. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int swscanf (const wchar_t *@var{ws}, const wchar_t *@var{template}, @dots{}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is like @code{wscanf}, except that the characters are taken from the null-terminated string @var{ws} instead of from a stream. Reaching the @@ -4092,51 +3984,45 @@ information on how to use them. @strong{Portability Note:} The functions listed in this section were introduced in @w{ISO C99} and were before available as GNU extensions. -@comment stdio.h -@comment ISO @deftypefun int vscanf (const char *@var{template}, va_list @var{ap}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is similar to @code{scanf}, but instead of taking a variable number of arguments directly, it takes an argument list pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}). @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is similar to @code{wscanf}, but instead of taking a variable number of arguments directly, it takes an argument list pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}). @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This is the equivalent of @code{fscanf} with the variable argument list specified directly as for @code{vscanf}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This is the equivalent of @code{fwscanf} with the variable argument list specified directly as for @code{vwscanf}. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{sscanf} with the variable argument list specified directly as for @code{vscanf}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{swscanf} with the variable argument list specified directly as for @code{vwscanf}. @@ -4162,9 +4048,8 @@ check indicators that are part of the internal state of the stream object, indicators set if the appropriate condition was detected by a previous I/O operation on that stream. -@comment stdio.h -@comment ISO @deftypevr Macro int EOF +@standards{ISO, stdio.h} This macro is an integer value that is returned by a number of narrow stream functions to indicate an end-of-file condition, or some other error situation. With @theglibc{}, @code{EOF} is @code{-1}. In @@ -4173,9 +4058,8 @@ other libraries, its value may be some other negative number. This symbol is declared in @file{stdio.h}. @end deftypevr -@comment wchar.h -@comment ISO @deftypevr Macro int WEOF +@standards{ISO, wchar.h} This macro is an integer value that is returned by a number of wide stream functions to indicate an end-of-file condition, or some other error situation. With @theglibc{}, @code{WEOF} is @code{-1}. In @@ -4184,9 +4068,8 @@ other libraries, its value may be some other negative number. This symbol is declared in @file{wchar.h}. @end deftypevr -@comment stdio.h -@comment ISO @deftypefun int feof (FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} The @code{feof} function returns nonzero if and only if the end-of-file indicator for the stream @var{stream} is set. @@ -4194,9 +4077,8 @@ indicator for the stream @var{stream} is set. This symbol is declared in @file{stdio.h}. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun int feof_unlocked (FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c There isn't much of a thread unsafety risk in reading a flag word and @c testing a bit in it. @@ -4208,9 +4090,8 @@ This function is a GNU extension. This symbol is declared in @file{stdio.h}. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int ferror (FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} The @code{ferror} function returns nonzero if and only if the error indicator for the stream @var{stream} is set, indicating that an error @@ -4219,9 +4100,8 @@ has occurred on a previous operation on the stream. This symbol is declared in @file{stdio.h}. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun int ferror_unlocked (FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{ferror_unlocked} function is equivalent to the @code{ferror} function except that it does not implicitly lock the stream. @@ -4247,9 +4127,8 @@ For more information about the descriptor-level I/O functions, see You may explicitly clear the error and EOF flags with the @code{clearerr} function. -@comment stdio.h -@comment ISO @deftypefun void clearerr (FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} This function clears the end-of-file and error indicators for the stream @var{stream}. @@ -4258,9 +4137,8 @@ The file positioning functions (@pxref{File Positioning}) also clear the end-of-file indicator for the stream. @end deftypefun -@comment stdio.h -@comment GNU @deftypefun void clearerr_unlocked (FILE *@var{stream}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@assafe{}@acsafe{}} The @code{clearerr_unlocked} function is equivalent to the @code{clearerr} function except that it does not implicitly lock the stream. @@ -4372,9 +4250,8 @@ position indicator associated with a stream. The symbols listed below are declared in the header file @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftypefun {long int} ftell (FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function returns the current file position of the stream @var{stream}. @@ -4385,9 +4262,8 @@ possibly for other reasons as well. If a failure occurs, a value of @code{-1} is returned. @end deftypefun -@comment stdio.h -@comment Unix98 @deftypefun off_t ftello (FILE *@var{stream}) +@standards{Unix98, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{ftello} function is similar to @code{ftell}, except that it returns a value of type @code{off_t}. Systems which support this type @@ -4409,9 +4285,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a LFS interface transparently replaces the old interface. @end deftypefun -@comment stdio.h -@comment Unix98 @deftypefun off64_t ftello64 (FILE *@var{stream}) +@standards{Unix98, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{ftello} with the only difference that the return value is of type @code{off64_t}. This also requires that the @@ -4425,9 +4300,8 @@ bits machine this function is available under the name @code{ftello} and so transparently replaces the old interface. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{fseek} function is used to change the file position of the stream @var{stream}. The value of @var{whence} must be one of the @@ -4445,9 +4319,8 @@ position or else remembers it so it will be written later in its proper place in the file. @end deftypefun -@comment stdio.h -@comment Unix98 @deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence}) +@standards{Unix98, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{fseek} but it corrects a problem with @code{fseek} in a system with POSIX types. Using a value of type @@ -4469,9 +4342,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a LFS interface transparently replaces the old interface. @end deftypefun -@comment stdio.h -@comment Unix98 @deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence}) +@standards{Unix98, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{fseeko} with the only difference that the @var{offset} parameter is of type @code{off64_t}. This also @@ -4494,33 +4366,29 @@ argument to @code{fseek}. They are also used with the @code{lseek} function (@pxref{I/O Primitives}) and to specify offsets for file locks (@pxref{Control Operations}). -@comment stdio.h -@comment ISO @deftypevr Macro int SEEK_SET +@standards{ISO, stdio.h} This is an integer constant which, when used as the @var{whence} argument to the @code{fseek} or @code{fseeko} functions, specifies that the offset provided is relative to the beginning of the file. @end deftypevr -@comment stdio.h -@comment ISO @deftypevr Macro int SEEK_CUR +@standards{ISO, stdio.h} This is an integer constant which, when used as the @var{whence} argument to the @code{fseek} or @code{fseeko} functions, specifies that the offset provided is relative to the current file position. @end deftypevr -@comment stdio.h -@comment ISO @deftypevr Macro int SEEK_END +@standards{ISO, stdio.h} This is an integer constant which, when used as the @var{whence} argument to the @code{fseek} or @code{fseeko} functions, specifies that the offset provided is relative to the end of the file. @end deftypevr -@comment stdio.h -@comment ISO @deftypefun void rewind (FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{rewind} function positions the stream @var{stream} at the beginning of the file. It is equivalent to calling @code{fseek} or @@ -4535,19 +4403,16 @@ sake of compatibility with older BSD systems. They are defined in two different header files: @file{fcntl.h} and @file{sys/file.h}. @vtable @code -@comment sys/file.h -@comment BSD @item L_SET +@standards{BSD, sys/file.h} An alias for @code{SEEK_SET}. -@comment sys/file.h -@comment BSD @item L_INCR +@standards{BSD, sys/file.h} An alias for @code{SEEK_CUR}. -@comment sys/file.h -@comment BSD @item L_XTND +@standards{BSD, sys/file.h} An alias for @code{SEEK_END}. @end vtable @@ -4607,9 +4472,8 @@ from system to system. These symbols are declared in the header file @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftp {Data Type} fpos_t +@standards{ISO, stdio.h} This is the type of an object that can encode information about the file position of a stream, for use by the functions @code{fgetpos} and @code{fsetpos}. @@ -4624,9 +4488,8 @@ this type is in fact equivalent to @code{fpos64_t} since the LFS interface transparently replaces the old interface. @end deftp -@comment stdio.h -@comment Unix98 @deftp {Data Type} fpos64_t +@standards{Unix98, stdio.h} This is the type of an object that can encode information about the file position of a stream, for use by the functions @code{fgetpos64} and @code{fsetpos64}. @@ -4637,9 +4500,8 @@ information. In other systems, it might have a different internal representation. @end deftp -@comment stdio.h -@comment ISO @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function stores the value of the file position indicator for the stream @var{stream} in the @code{fpos_t} object pointed to by @@ -4652,9 +4514,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a interface transparently replaces the old interface. @end deftypefun -@comment stdio.h -@comment Unix98 @deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position}) +@standards{Unix98, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{fgetpos} but the file position is returned in a variable of type @code{fpos64_t} to which @var{position} @@ -4665,9 +4526,8 @@ bits machine this function is available under the name @code{fgetpos} and so transparently replaces the old interface. @end deftypefun -@comment stdio.h -@comment ISO @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function sets the file position indicator for the stream @var{stream} to the position @var{position}, which must have been set by a previous @@ -4682,9 +4542,8 @@ When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a interface transparently replaces the old interface. @end deftypefun -@comment stdio.h -@comment Unix98 @deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position}) +@standards{Unix98, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{fsetpos} but the file position used for positioning is provided in a variable of type @code{fpos64_t} to @@ -4794,9 +4653,8 @@ If you want to flush the buffered output at another time, call @code{fflush}, which is declared in the header file @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftypefun int fflush (FILE *@var{stream}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function causes any buffered output on @var{stream} to be delivered to the file. If @var{stream} is a null pointer, then @@ -4807,9 +4665,8 @@ This function returns @code{EOF} if a write error occurs, or zero otherwise. @end deftypefun -@comment stdio.h -@comment POSIX @deftypefun int fflush_unlocked (FILE *@var{stream}) +@standards{POSIX, stdio.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fflush_unlocked} function is equivalent to the @code{fflush} function except that it does not implicitly lock the stream. @@ -4824,9 +4681,8 @@ flushed. Solaris introduced a function especially for this. It was always available in @theglibc{} in some form but never officially exported. -@comment stdio_ext.h -@comment GNU @deftypefun void _flushlbf (void) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{_flushlbf} function flushes all line buffered streams currently opened. @@ -4846,9 +4702,8 @@ and the output is not needed anymore this is valid reasoning. In this situation a non-standard function introduced in Solaris and available in @theglibc{} can be used. -@comment stdio_ext.h -@comment GNU @deftypefun void __fpurge (FILE *@var{stream}) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{__fpurge} function causes the buffer of the stream @var{stream} to be emptied. If the stream is currently in read mode all @@ -4871,9 +4726,8 @@ The facilities listed in this section are declared in the header file @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment ISO @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is used to specify that the stream @var{stream} should have the buffering mode @var{mode}, which can be either @code{_IOFBF} @@ -4902,33 +4756,29 @@ if the value of @var{mode} is not valid or if the request could not be honored. @end deftypefun -@comment stdio.h -@comment ISO @deftypevr Macro int _IOFBF +@standards{ISO, stdio.h} The value of this macro is an integer constant expression that can be used as the @var{mode} argument to the @code{setvbuf} function to specify that the stream should be fully buffered. @end deftypevr -@comment stdio.h -@comment ISO @deftypevr Macro int _IOLBF +@standards{ISO, stdio.h} The value of this macro is an integer constant expression that can be used as the @var{mode} argument to the @code{setvbuf} function to specify that the stream should be line buffered. @end deftypevr -@comment stdio.h -@comment ISO @deftypevr Macro int _IONBF +@standards{ISO, stdio.h} The value of this macro is an integer constant expression that can be used as the @var{mode} argument to the @code{setvbuf} function to specify that the stream should be unbuffered. @end deftypevr -@comment stdio.h -@comment ISO @deftypevr Macro int BUFSIZ +@standards{ISO, stdio.h} The value of this macro is an integer constant expression that is good to use for the @var{size} argument to @code{setvbuf}. This value is guaranteed to be at least @code{256}. @@ -4949,9 +4799,8 @@ integer, except that it might lead to doing I/O in chunks of an efficient size. @end deftypevr -@comment stdio.h -@comment ISO @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf}) +@standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} If @var{buf} is a null pointer, the effect of this function is equivalent to calling @code{setvbuf} with a @var{mode} argument of @@ -4963,9 +4812,8 @@ The @code{setbuf} function is provided for compatibility with old code; use @code{setvbuf} in all new programs. @end deftypefun -@comment stdio.h -@comment BSD @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size}) +@standards{BSD, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} If @var{buf} is a null pointer, this function makes @var{stream} unbuffered. Otherwise, it makes @var{stream} fully buffered using @var{buf} as the @@ -4975,9 +4823,8 @@ This function is provided for compatibility with old BSD code. Use @code{setvbuf} instead. @end deftypefun -@comment stdio.h -@comment BSD @deftypefun void setlinebuf (FILE *@var{stream}) +@standards{BSD, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function makes @var{stream} be line buffered, and allocates the buffer for you. @@ -4990,9 +4837,8 @@ It is possible to query whether a given stream is line buffered or not using a non-standard function introduced in Solaris and available in @theglibc{}. -@comment stdio_ext.h -@comment GNU @deftypefun int __flbf (FILE *@var{stream}) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__flbf} function will return a nonzero value in case the stream @var{stream} is line buffered. Otherwise the return value is @@ -5004,9 +4850,8 @@ This function is declared in the @file{stdio_ext.h} header. Two more extensions allow to determine the size of the buffer and how much of it is used. These functions were also introduced in Solaris. -@comment stdio_ext.h -@comment GNU @deftypefun size_t __fbufsize (FILE *@var{stream}) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}} The @code{__fbufsize} function return the size of the buffer in the stream @var{stream}. This value can be used to optimize the use of the @@ -5015,9 +4860,8 @@ stream. This function is declared in the @file{stdio_ext.h} header. @end deftypefun -@comment stdio_ext.h -@comment GNU @deftypefun size_t __fpending (FILE *@var{stream}) +@standards{GNU, stdio_ext.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}} The @code{__fpending} function returns the number of bytes currently in the output buffer. @@ -5063,9 +4907,8 @@ I/O to a string or memory buffer. These facilities are declared in @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment GNU @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} @c Unlike open_memstream, fmemopen does (indirectly) call _IO_link_in, @c bringing with it additional potential for async trouble with @@ -5119,9 +4962,8 @@ Got a Got r @end smallexample -@comment stdio.h -@comment GNU @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function opens a stream for writing to a buffer. The buffer is allocated dynamically and grown as necessary, using @code{malloc}. @@ -5202,9 +5044,8 @@ and also the four hook functions stored in a structure of type These facilities are declared in @file{stdio.h}. @pindex stdio.h -@comment stdio.h -@comment GNU @deftp {Data Type} {cookie_io_functions_t} +@standards{GNU, stdio.h} This is a structure type that holds the functions that define the communications protocol between the stream and its cookie. It has the following members: @@ -5235,9 +5076,8 @@ closed. @end table @end deftp -@comment stdio.h -@comment GNU @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions}) +@standards{GNU, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} This function actually creates the stream for communicating with the @var{cookie} using the functions in the @var{io-functions} argument. @@ -5305,28 +5145,24 @@ int @var{cleaner} (void *@var{cookie}) Your function should return @code{-1} to indicate an error, and @code{0} otherwise. -@comment stdio.h -@comment GNU @deftp {Data Type} cookie_read_function_t +@standards{GNU, stdio.h} This is the data type that the read function for a custom stream should have. If you declare the function as shown above, this is the type it will have. @end deftp -@comment stdio.h -@comment GNU @deftp {Data Type} cookie_write_function_t +@standards{GNU, stdio.h} The data type of the write function for a custom stream. @end deftp -@comment stdio.h -@comment GNU @deftp {Data Type} cookie_seek_function_t +@standards{GNU, stdio.h} The data type of the seek function for a custom stream. @end deftp -@comment stdio.h -@comment GNU @deftp {Data Type} cookie_close_function_t +@standards{GNU, stdio.h} The data type of the close function for a custom stream. @end deftp @@ -5417,9 +5253,8 @@ It is a recoverable error. It is a non-recoverable error. @end vtable -@comment fmtmsg.h -@comment XPG @deftypefun int fmtmsg (long int @var{classification}, const char *@var{label}, int @var{severity}, const char *@var{text}, const char *@var{action}, const char *@var{tag}) +@standards{XPG, fmtmsg.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acsafe{}} Display a message described by its parameters on the device(s) specified in the @var{classification} parameter. The @var{label} parameter diff --git a/manual/string.texi b/manual/string.texi index b8810d66b7..272148f388 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -227,9 +227,8 @@ You can get the length of a string using the @code{strlen} function. This function is declared in the header file @file{string.h}. @pindex string.h -@comment string.h -@comment ISO @deftypefun size_t strlen (const char *@var{s}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strlen} function returns the length of the string @var{s} in bytes. (In other words, it returns the offset of the @@ -294,9 +293,8 @@ bytes) is needed often it is better to work with wide characters. The wide character equivalent is declared in @file{wchar.h}. -@comment wchar.h -@comment ISO @deftypefun size_t wcslen (const wchar_t *@var{ws}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcslen} function is the wide character equivalent to @code{strlen}. The return value is the number of wide characters in the @@ -310,9 +308,8 @@ also the number of wide characters. This function was introduced in @w{Amendment 1} to @w{ISO C90}. @end deftypefun -@comment string.h -@comment GNU @deftypefun size_t strnlen (const char *@var{s}, size_t @var{maxlen}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If the array @var{s} of size @var{maxlen} contains a null byte, the @code{strnlen} function returns the length of the string @var{s} in @@ -334,9 +331,8 @@ strnlen (string, 5) This function is a GNU extension and is declared in @file{string.h}. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun size_t wcsnlen (const wchar_t *@var{ws}, size_t @var{maxlen}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{wcsnlen} is the wide character equivalent to @code{strnlen}. The @var{maxlen} parameter specifies the maximum number of wide characters. @@ -381,9 +377,8 @@ section, there are a few others like @code{sprintf} (@pxref{Formatted Output Functions}) and @code{scanf} (@pxref{Formatted Input Functions}). -@comment string.h -@comment ISO @deftypefun {void *} memcpy (void *restrict @var{to}, const void *restrict @var{from}, size_t @var{size}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{memcpy} function copies @var{size} bytes from the object beginning at @var{from} into the object beginning at @var{to}. The @@ -403,9 +398,8 @@ memcpy (new, old, arraysize * sizeof (struct foo)); @end smallexample @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wmemcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wmemcpy} function copies @var{size} wide characters from the object beginning at @var{wfrom} into the object beginning at @var{wto}. The @@ -429,9 +423,8 @@ The value returned by @code{wmemcpy} is the value of @var{wto}. This function was introduced in @w{Amendment 1} to @w{ISO C90}. @end deftypefun -@comment string.h -@comment GNU @deftypefun {void *} mempcpy (void *restrict @var{to}, const void *restrict @var{from}, size_t @var{size}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{mempcpy} function is nearly identical to the @code{memcpy} function. It copies @var{size} bytes from the object beginning at @@ -457,9 +450,8 @@ combine (void *o1, size_t s1, void *o2, size_t s2) This function is a GNU extension. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun {wchar_t *} wmempcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wmempcpy} function is nearly identical to the @code{wmemcpy} function. It copies @var{size} wide characters from the object @@ -486,9 +478,8 @@ wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom, This function is a GNU extension. @end deftypefun -@comment string.h -@comment ISO @deftypefun {void *} memmove (void *@var{to}, const void *@var{from}, size_t @var{size}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{memmove} copies the @var{size} bytes at @var{from} into the @var{size} bytes at @var{to}, even if those two blocks of space @@ -499,9 +490,8 @@ bytes which also belong to the block at @var{to}. The value returned by @code{memmove} is the value of @var{to}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wmemmove (wchar_t *@var{wto}, const wchar_t *@var{wfrom}, size_t @var{size}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{wmemmove} copies the @var{size} wide characters at @var{wfrom} into the @var{size} wide characters at @var{wto}, even if those two @@ -527,9 +517,8 @@ The value returned by @code{wmemmove} is the value of @var{wto}. This function is a GNU extension. @end deftypefun -@comment string.h -@comment SVID @deftypefun {void *} memccpy (void *restrict @var{to}, const void *restrict @var{from}, int @var{c}, size_t @var{size}) +@standards{SVID, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies no more than @var{size} bytes from @var{from} to @var{to}, stopping if a byte matching @var{c} is found. The return @@ -538,27 +527,24 @@ or a null pointer if no byte matching @var{c} appeared in the first @var{size} bytes of @var{from}. @end deftypefun -@comment string.h -@comment ISO @deftypefun {void *} memset (void *@var{block}, int @var{c}, size_t @var{size}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies the value of @var{c} (converted to an @code{unsigned char}) into each of the first @var{size} bytes of the object beginning at @var{block}. It returns the value of @var{block}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wmemset (wchar_t *@var{block}, wchar_t @var{wc}, size_t @var{size}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies the value of @var{wc} into each of the first @var{size} wide characters of the object beginning at @var{block}. It returns the value of @var{block}. @end deftypefun -@comment string.h -@comment ISO @deftypefun {char *} strcpy (char *restrict @var{to}, const char *restrict @var{from}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This copies bytes from the string @var{from} (up to and including the terminating null byte) into the string @var{to}. Like @@ -566,9 +552,8 @@ the terminating null byte) into the string @var{to}. Like overlap. The return value is the value of @var{to}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wcscpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This copies wide characters from the wide string @var{wfrom} (up to and including the terminating null wide character) into the string @@ -576,8 +561,8 @@ including the terminating null wide character) into the string the strings overlap. The return value is the value of @var{wto}. @end deftypefun -@comment SVID @deftypefun {char *} strdup (const char *@var{s}) +@standards{SVID, ???} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function copies the string @var{s} into a newly allocated string. The string is allocated using @code{malloc}; see @@ -586,9 +571,8 @@ for the new string, @code{strdup} returns a null pointer. Otherwise it returns a pointer to the new string. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun {wchar_t *} wcsdup (const wchar_t *@var{ws}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function copies the wide string @var{ws} into a newly allocated string. The string is allocated using @@ -599,9 +583,8 @@ pointer. Otherwise it returns a pointer to the new wide string. This function is a GNU extension. @end deftypefun -@comment string.h -@comment Unknown origin @deftypefun {char *} stpcpy (char *restrict @var{to}, const char *restrict @var{from}) +@standards{Unknown origin, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is like @code{strcpy}, except that it returns a pointer to the end of the string @var{to} (that is, the address of the terminating @@ -622,9 +605,8 @@ Its behavior is undefined if the strings overlap. The function is declared in @file{string.h}. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun {wchar_t *} wcpcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is like @code{wcscpy}, except that it returns a pointer to the end of the string @var{wto} (that is, the address of the terminating @@ -638,9 +620,8 @@ The behavior of @code{wcpcpy} is undefined if the strings overlap. @code{wcpcpy} is a GNU extension and is declared in @file{wchar.h}. @end deftypefun -@comment string.h -@comment GNU @deftypefn {Macro} {char *} strdupa (const char *@var{s}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro is similar to @code{strdup} but allocates the new string using @code{alloca} instead of @code{malloc} (@pxref{Variable Size @@ -665,18 +646,16 @@ passing. This function is only available if GNU CC is used. @end deftypefn -@comment string.h -@comment BSD @deftypefun void bcopy (const void *@var{from}, void *@var{to}, size_t @var{size}) +@standards{BSD, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is a partially obsolete alternative for @code{memmove}, derived from BSD. Note that it is not quite equivalent to @code{memmove}, because the arguments are not in the same order and there is no return value. @end deftypefun -@comment string.h -@comment BSD @deftypefun void bzero (void *@var{block}, size_t @var{size}) +@standards{BSD, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is a partially obsolete alternative for @code{memset}, derived from BSD. Note that it is not as general as @code{memset}, because the only @@ -696,9 +675,8 @@ functions in their conventions. @xref{Copying Strings and Arrays}. @samp{strcat} is declared in the header file @file{string.h} while @samp{wcscat} is declared in @file{wchar.h}. -@comment string.h -@comment ISO @deftypefun {char *} strcat (char *restrict @var{to}, const char *restrict @var{from}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strcat} function is similar to @code{strcpy}, except that the bytes from @var{from} are concatenated or appended to the end of @@ -721,9 +699,8 @@ This function has undefined results if the strings overlap. As noted below, this function has significant performance issues. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wcscat (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcscat} function is similar to @code{wcscpy}, except that the wide characters from @var{wfrom} are concatenated or appended to the end of @@ -885,8 +862,8 @@ in their header conventions. @xref{Copying Strings and Arrays}. The @samp{str} functions are declared in the header file @file{string.h} and the @samp{wc} functions are declared in the file @file{wchar.h}. -@comment string.h @deftypefun {char *} strncpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) +@standards{???, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{strcpy} but always copies exactly @var{size} bytes into @var{to}. @@ -908,9 +885,8 @@ greater than the length of @var{from}. As noted below, this function is generally a poor choice for processing text. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wcsncpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{wcscpy} but always copies exactly @var{size} wide characters into @var{wto}. @@ -933,9 +909,8 @@ example, as noted below, this function is generally a poor choice for processing text. @end deftypefun -@comment string.h -@comment GNU @deftypefun {char *} strndup (const char *@var{s}, size_t @var{size}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function is similar to @code{strdup} but always copies at most @var{size} bytes into the newly allocated string. @@ -953,9 +928,8 @@ processing text. @code{strndup} is a GNU extension. @end deftypefun -@comment string.h -@comment GNU @deftypefn {Macro} {char *} strndupa (const char *@var{s}, size_t @var{size}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{strndup} but like @code{strdupa} it allocates the new string using @code{alloca} @pxref{Variable Size @@ -972,9 +946,8 @@ processing text. @code{strndupa} is only available if GNU CC is used. @end deftypefn -@comment string.h -@comment GNU @deftypefun {char *} stpncpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{stpcpy} but copies always exactly @var{size} bytes into @var{to}. @@ -1001,9 +974,8 @@ As noted below, this function is generally a poor choice for processing text. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun {wchar_t *} wcpncpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{wcpcpy} but copies always exactly @var{wsize} wide characters into @var{wto}. @@ -1032,9 +1004,8 @@ processing text. @code{wcpncpy} is a GNU extension. @end deftypefun -@comment string.h -@comment ISO @deftypefun {char *} strncat (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is like @code{strcat} except that not more than @var{size} bytes from @var{from} are appended to the end of @var{to}, and @@ -1067,9 +1038,8 @@ choice for processing text. Also, this function has significant performance issues. @xref{Concatenating Strings}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wcsncat (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is like @code{wcscat} except that not more than @var{size} wide characters from @var{from} are appended to the end of @var{to}, @@ -1156,9 +1126,8 @@ This is canonically done with an expression like @w{@samp{! strcmp (s1, s2)}}. All of these functions are declared in the header file @file{string.h}. @pindex string.h -@comment string.h -@comment ISO @deftypefun int memcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{memcmp} compares the @var{size} bytes of memory beginning at @var{a1} against the @var{size} bytes of memory beginning @@ -1170,9 +1139,8 @@ If the contents of the two blocks are equal, @code{memcmp} returns @code{0}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int wmemcmp (const wchar_t *@var{a1}, const wchar_t *@var{a2}, size_t @var{size}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{wmemcmp} compares the @var{size} wide characters beginning at @var{a1} against the @var{size} wide characters beginning @@ -1223,9 +1191,8 @@ struct foo you are better off writing a specialized comparison function to compare @code{struct foo} objects instead of comparing them with @code{memcmp}. -@comment string.h -@comment ISO @deftypefun int strcmp (const char *@var{s1}, const char *@var{s2}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strcmp} function compares the string @var{s1} against @var{s2}, returning a value that has the same sign as the difference @@ -1243,9 +1210,8 @@ strings are written in into account. To get that one has to use @code{strcoll}. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int wcscmp (const wchar_t *@var{ws1}, const wchar_t *@var{ws2}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcscmp} function compares the wide string @var{ws1} @@ -1264,9 +1230,8 @@ strings are written in into account. To get that one has to use @code{wcscoll}. @end deftypefun -@comment string.h -@comment BSD @deftypefun int strcasecmp (const char *@var{s1}, const char *@var{s2}) +@standards{BSD, string.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c Although this calls tolower multiple times, it's a macro, and @c strcasecmp is optimized so that the locale pointer is read only once. @@ -1283,9 +1248,8 @@ regards these characters as parts of the alphabet they do match. @code{strcasecmp} is derived from BSD. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun int wcscasecmp (const wchar_t *@var{ws1}, const wchar_t *@var{ws2}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c Since towlower is not a macro, the locale object may be read multiple @c times. @@ -1299,9 +1263,8 @@ regards these characters as parts of the alphabet they do match. @code{wcscasecmp} is a GNU extension. @end deftypefun -@comment string.h -@comment ISO @deftypefun int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{size}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is the similar to @code{strcmp}, except that no more than @var{size} bytes are compared. In other words, if the two @@ -1309,9 +1272,8 @@ strings are the same in their first @var{size} bytes, the return value is zero. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int wcsncmp (const wchar_t *@var{ws1}, const wchar_t *@var{ws2}, size_t @var{size}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{wcscmp}, except that no more than @var{size} wide characters are compared. In other words, if the two @@ -1319,9 +1281,8 @@ strings are the same in their first @var{size} wide characters, the return value is zero. @end deftypefun -@comment string.h -@comment BSD @deftypefun int strncasecmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) +@standards{BSD, string.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is like @code{strncmp}, except that differences in case are ignored, and the compared parts of the arguments should consist of @@ -1333,9 +1294,8 @@ uppercase and lowercase characters are related. @code{strncasecmp} is a GNU extension. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun int wcsncasecmp (const wchar_t *@var{ws1}, const wchar_t *@var{s2}, size_t @var{n}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is like @code{wcsncmp}, except that differences in case are ignored. Like @code{wcscasecmp}, it is locale dependent how @@ -1367,9 +1327,8 @@ strncmp ("hello, world", "hello, stupid world!!!", 5) @result{} 0 /* @r{The initial 5 bytes are the same.} */ @end smallexample -@comment string.h -@comment GNU @deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c Calls isdigit multiple times, locale may change in between. The @code{strverscmp} function compares the string @var{s1} against @@ -1448,9 +1407,8 @@ strverscmp ("foo.009", "foo.0") @code{strverscmp} is a GNU extension. @end deftypefun -@comment string.h -@comment BSD @deftypefun int bcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size}) +@standards{BSD, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is an obsolete alias for @code{memcmp}, derived from BSD. @end deftypefun @@ -1496,9 +1454,8 @@ likely to be more efficient to use @code{strxfrm} or @code{wcsxfrm} to transform all the strings just once, and subsequently compare the transformed strings with @code{strcmp} or @code{wcscmp}. -@comment string.h -@comment ISO @deftypefun int strcoll (const char *@var{s1}, const char *@var{s2}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c Calls strcoll_l with the current locale, which dereferences only the @c LC_COLLATE data pointer. @@ -1507,9 +1464,8 @@ collating sequence of the current locale for collation (the @code{LC_COLLATE} locale). The arguments are multibyte strings. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun int wcscoll (const wchar_t *@var{ws1}, const wchar_t *@var{ws2}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c Same as strcoll, but calling wcscoll_l. The @code{wcscoll} function is similar to @code{wcscmp} but uses the @@ -1549,9 +1505,8 @@ sort_strings (char **array, int nstrings) @end smallexample @cindex converting string to collation order -@comment string.h -@comment ISO @deftypefun size_t strxfrm (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The function @code{strxfrm} transforms the multibyte string @var{from} using the @@ -1580,9 +1535,8 @@ what size the allocated array should be. It does not matter what @var{to} is if @var{size} is zero; @var{to} may even be a null pointer. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun size_t wcsxfrm (wchar_t *restrict @var{wto}, const wchar_t *@var{wfrom}, size_t @var{size}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The function @code{wcsxfrm} transforms wide string @var{wfrom} using the collation transformation determined by the locale currently @@ -1740,9 +1694,8 @@ declared in the header file @file{string.h}. @cindex search functions (for strings) @cindex string search functions -@comment string.h -@comment ISO @deftypefun {void *} memchr (const void *@var{block}, int @var{c}, size_t @var{size}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function finds the first occurrence of the byte @var{c} (converted to an @code{unsigned char}) in the initial @var{size} bytes of the @@ -1750,9 +1703,8 @@ object beginning at @var{block}. The return value is a pointer to the located byte, or a null pointer if no match was found. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wmemchr (const wchar_t *@var{block}, wchar_t @var{wc}, size_t @var{size}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function finds the first occurrence of the wide character @var{wc} in the initial @var{size} wide characters of the object beginning at @@ -1760,9 +1712,8 @@ in the initial @var{size} wide characters of the object beginning at character, or a null pointer if no match was found. @end deftypefun -@comment string.h -@comment GNU @deftypefun {void *} rawmemchr (const void *@var{block}, int @var{c}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Often the @code{memchr} function is used with the knowledge that the byte @var{c} is available in the memory block specified by the @@ -1791,9 +1742,8 @@ will never go beyond the end of the string. This function is a GNU extension. @end deftypefun -@comment string.h -@comment GNU @deftypefun {void *} memrchr (const void *@var{block}, int @var{c}, size_t @var{size}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{memrchr} is like @code{memchr}, except that it searches backwards from the end of the block defined by @var{block} and @var{size} @@ -1802,9 +1752,8 @@ backwards from the end of the block defined by @var{block} and @var{size} This function is a GNU extension. @end deftypefun -@comment string.h -@comment ISO @deftypefun {char *} strchr (const char *@var{string}, int @var{c}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strchr} function finds the first occurrence of the byte @var{c} (converted to a @code{char}) in the string @@ -1829,9 +1778,8 @@ need that information, it is better (but less portable) to use @code{strchrnul} than to search for it a second time. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wcschr (const wchar_t *@var{wstring}, int @var{wc}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcschr} function finds the first occurrence of the wide character @var{wc} in the wide string @@ -1845,9 +1793,8 @@ value of the @var{wc} argument. It would be better (but less portable) to use @code{wcschrnul} in this case, though. @end deftypefun -@comment string.h -@comment GNU @deftypefun {char *} strchrnul (const char *@var{string}, int @var{c}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{strchrnul} is the same as @code{strchr} except that if it does not find the byte, it returns a pointer to string's terminating @@ -1856,9 +1803,8 @@ null byte rather than a null pointer. This function is a GNU extension. @end deftypefun -@comment wchar.h -@comment GNU @deftypefun {wchar_t *} wcschrnul (const wchar_t *@var{wstring}, wchar_t @var{wc}) +@standards{GNU, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{wcschrnul} is the same as @code{wcschr} except that if it does not find the wide character, it returns a pointer to the wide string's @@ -1892,9 +1838,8 @@ criteria. This is right. But in @theglibc{} the implementation of @code{strchr} is optimized in a special way so that @code{strchr} actually is faster. -@comment string.h -@comment ISO @deftypefun {char *} strrchr (const char *@var{string}, int @var{c}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{strrchr} is like @code{strchr}, except that it searches backwards from the end of the string @var{string} (instead of forwards @@ -1907,18 +1852,16 @@ strrchr ("hello, world", 'l') @end smallexample @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wcsrchr (const wchar_t *@var{wstring}, wchar_t @var{c}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{wcsrchr} is like @code{wcschr}, except that it searches backwards from the end of the string @var{wstring} (instead of forwards from the front). @end deftypefun -@comment string.h -@comment ISO @deftypefun {char *} strstr (const char *@var{haystack}, const char *@var{needle}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{strchr}, except that it searches @var{haystack} for a substring @var{needle} rather than just a single byte. It @@ -1935,9 +1878,8 @@ strstr ("hello, world", "wo") @end smallexample @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wcsstr (const wchar_t *@var{haystack}, const wchar_t *@var{needle}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{wcschr}, except that it searches @var{haystack} for a substring @var{needle} rather than just a single wide character. It @@ -1946,9 +1888,8 @@ character of the substring, or a null pointer if no match was found. If @var{needle} is an empty string, the function returns @var{haystack}. @end deftypefun -@comment wchar.h -@comment XPG @deftypefun {wchar_t *} wcswcs (const wchar_t *@var{haystack}, const wchar_t *@var{needle}) +@standards{XPG, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{wcswcs} is a deprecated alias for @code{wcsstr}. This is the name originally used in the X/Open Portability Guide before the @@ -1956,9 +1897,8 @@ name originally used in the X/Open Portability Guide before the @end deftypefun -@comment string.h -@comment GNU @deftypefun {char *} strcasestr (const char *@var{haystack}, const char *@var{needle}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c There may be multiple calls of strncasecmp, each accessing the locale @c object independently. @@ -1978,9 +1918,8 @@ strcasestr ("hello, World", "wo") @end deftypefun -@comment string.h -@comment GNU @deftypefun {void *} memmem (const void *@var{haystack}, size_t @var{haystack-len},@*const void *@var{needle}, size_t @var{needle-len}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{strstr}, but @var{needle} and @var{haystack} are byte arrays rather than strings. @var{needle-len} is the @@ -1990,9 +1929,8 @@ length of @var{needle} and @var{haystack-len} is the length of This function is a GNU extension. @end deftypefun -@comment string.h -@comment ISO @deftypefun size_t strspn (const char *@var{string}, const char *@var{skipset}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strspn} (``string span'') function returns the length of the initial substring of @var{string} that consists entirely of bytes that @@ -2010,9 +1948,8 @@ more than one byte are not treated as single entities. Each byte is treated separately. The function is not locale-dependent. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun size_t wcsspn (const wchar_t *@var{wstring}, const wchar_t *@var{skipset}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcsspn} (``wide character string span'') function returns the length of the initial substring of @var{wstring} that consists entirely @@ -2021,9 +1958,8 @@ of wide characters that are members of the set specified by the string important. @end deftypefun -@comment string.h -@comment ISO @deftypefun size_t strcspn (const char *@var{string}, const char *@var{stopset}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strcspn} (``string complement span'') function returns the length of the initial substring of @var{string} that consists entirely of bytes @@ -2042,9 +1978,8 @@ more than one byte are not treated as a single entities. Each byte is treated separately. The function is not locale-dependent. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun size_t wcscspn (const wchar_t *@var{wstring}, const wchar_t *@var{stopset}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcscspn} (``wide character string complement span'') function returns the length of the initial substring of @var{wstring} that @@ -2054,9 +1989,8 @@ the offset of the first wide character in @var{string} that is a member of the set @var{stopset}.) @end deftypefun -@comment string.h -@comment ISO @deftypefun {char *} strpbrk (const char *@var{string}, const char *@var{stopset}) +@standards{ISO, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strpbrk} (``string pointer break'') function is related to @code{strcspn}, except that it returns a pointer to the first byte @@ -2078,9 +2012,8 @@ more than one byte are not treated as single entities. Each byte is treated separately. The function is not locale-dependent. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wcspbrk (const wchar_t *@var{wstring}, const wchar_t *@var{stopset}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcspbrk} (``wide character string pointer break'') function is related to @code{wcscspn}, except that it returns a pointer to the first @@ -2092,9 +2025,8 @@ returns a null pointer if no such wide character from @var{stopset} is found. @subsection Compatibility String Search Functions -@comment string.h -@comment BSD @deftypefun {char *} index (const char *@var{string}, int @var{c}) +@standards{BSD, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{index} is another name for @code{strchr}; they are exactly the same. New code should always use @code{strchr} since this name is defined in @@ -2102,9 +2034,8 @@ New code should always use @code{strchr} since this name is defined in on @w{System V} derived systems. @end deftypefun -@comment string.h -@comment BSD @deftypefun {char *} rindex (const char *@var{string}, int @var{c}) +@standards{BSD, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{rindex} is another name for @code{strrchr}; they are exactly the same. New code should always use @code{strrchr} since this name is defined in @@ -2124,9 +2055,8 @@ into tokens. You can do this with the @code{strtok} function, declared in the header file @file{string.h}. @pindex string.h -@comment string.h -@comment ISO @deftypefun {char *} strtok (char *restrict @var{newstring}, const char *restrict @var{delimiters}) +@standards{ISO, string.h} @safety{@prelim{}@mtunsafe{@mtasurace{:strtok}}@asunsafe{}@acsafe{}} A string can be split into tokens by making a series of calls to the function @code{strtok}. @@ -2163,9 +2093,8 @@ more than one byte are not treated as single entities. Each byte is treated separately. The function is not locale-dependent. @end deftypefun -@comment wchar.h -@comment ISO @deftypefun {wchar_t *} wcstok (wchar_t *@var{newstring}, const wchar_t *@var{delimiters}, wchar_t **@var{save_ptr}) +@standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} A string can be split into tokens by making a series of calls to the function @code{wcstok}. @@ -2254,9 +2183,8 @@ token = strtok (NULL, delimiters); /* token => NULL */ which overcome the limitation of non-reentrancy. They are not available available for wide strings. -@comment string.h -@comment POSIX @deftypefun {char *} strtok_r (char *@var{newstring}, const char *@var{delimiters}, char **@var{save_ptr}) +@standards{POSIX, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Just like @code{strtok}, this function splits the string into several tokens which can be accessed by successive calls to @code{strtok_r}. @@ -2271,9 +2199,8 @@ This function is defined in POSIX.1 and can be found on many systems which support multi-threading. @end deftypefun -@comment string.h -@comment BSD @deftypefun {char *} strsep (char **@var{string_ptr}, const char *@var{delimiter}) +@standards{BSD, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function has a similar functionality as @code{strtok_r} with the @var{newstring} argument replaced by the @var{save_ptr} argument. The @@ -2323,9 +2250,8 @@ token = strsep (&running, delimiters); /* token => "" */ token = strsep (&running, delimiters); /* token => NULL */ @end smallexample -@comment string.h -@comment GNU @deftypefun {char *} basename (const char *@var{filename}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The GNU version of the @code{basename} function returns the last component of the path in @var{filename}. This function is the preferred @@ -2359,9 +2285,8 @@ on different systems. @end deftypefun -@comment libgen.h -@comment XPG @deftypefun {char *} basename (char *@var{path}) +@standards{XPG, libgen.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is the standard XPG defined @code{basename}. It is similar in spirit to the GNU version, but may modify the @var{path} by removing @@ -2395,9 +2320,8 @@ main (int argc, char *argv[]) @end smallexample @end deftypefun -@comment libgen.h -@comment XPG @deftypefun {char *} dirname (char *@var{path}) +@standards{XPG, libgen.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{dirname} function is the compliment to the XPG version of @code{basename}. It returns the parent directory of the file specified @@ -2477,9 +2401,8 @@ language. We anticipate that future compilers will recognize calls to @code{explicit_bzero} and take appropriate steps to erase all the copies of the affected data, whereever they may be. -@comment string.h -@comment BSD @deftypefun void explicit_bzero (void *@var{block}, size_t @var{len}) +@standards{BSD, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{explicit_bzero} writes zero into @var{len} bytes of memory @@ -2515,9 +2438,8 @@ destroying string data. The prototype for this function is in @file{string.h}. -@comment string.h -@comment GNU @deftypefun {char *} strfry (char *@var{string}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Calls initstate_r, time, getpid, strlen, and random_r. @@ -2552,9 +2474,8 @@ For true encryption, @xref{Cryptographic Functions}. This function is declared in @file{string.h}. @pindex string.h -@comment string.h -@comment GNU @deftypefun {void *} memfrob (void *@var{mem}, size_t @var{length}) +@standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{memfrob} transforms (frobnicates) each byte of the data structure @@ -2583,9 +2504,8 @@ bytes in the range allowed for storing or transferring. SVID systems (and nowadays XPG compliant systems) provide minimal support for this task. -@comment stdlib.h -@comment XPG @deftypefun {char *} l64a (long int @var{n}) +@standards{XPG, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:l64a}}@asunsafe{}@acsafe{}} This function encodes a 32-bit input value using bytes from the basic character set. It returns a pointer to a 7 byte buffer which @@ -2659,9 +2579,8 @@ functionality needed but so be it. To decode data produced with @code{l64a} the following function should be used. -@comment stdlib.h -@comment XPG @deftypefun {long int} a64l (const char *@var{string}) +@standards{XPG, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The parameter @var{string} should contain a string which was produced by a call to @code{l64a}. The function processes at least 6 bytes of @@ -2746,9 +2665,8 @@ allocation error occurs. @pindex argz.h These functions are declared in the standard include file @file{argz.h}. -@comment argz.h -@comment GNU @deftypefun {error_t} argz_create (char *const @var{argv}[], char **@var{argz}, size_t *@var{argz_len}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{argz_create} function converts the Unix-style argument vector @var{argv} (a vector of pointers to normal C strings, terminated by @@ -2756,9 +2674,8 @@ The @code{argz_create} function converts the Unix-style argument vector the same elements, which is returned in @var{argz} and @var{argz_len}. @end deftypefun -@comment argz.h -@comment GNU @deftypefun {error_t} argz_create_sep (const char *@var{string}, int @var{sep}, char **@var{argz}, size_t *@var{argz_len}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{argz_create_sep} function converts the string @var{string} into an argz vector (returned in @var{argz} and @@ -2766,17 +2683,15 @@ The @code{argz_create_sep} function converts the string byte @var{sep}. @end deftypefun -@comment argz.h -@comment GNU @deftypefun {size_t} argz_count (const char *@var{argz}, size_t @var{argz_len}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns the number of elements in the argz vector @var{argz} and @var{argz_len}. @end deftypefun -@comment argz.h -@comment GNU @deftypefun {void} argz_extract (const char *@var{argz}, size_t @var{argz_len}, char **@var{argv}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{argz_extract} function converts the argz vector @var{argz} and @var{argz_len} into a Unix-style argument vector stored in @var{argv}, @@ -2792,9 +2707,8 @@ still active. This function is useful for passing the elements in @var{argz} to an exec function (@pxref{Executing a File}). @end deftypefun -@comment argz.h -@comment GNU @deftypefun {void} argz_stringify (char *@var{argz}, size_t @var{len}, int @var{sep}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{argz_stringify} converts @var{argz} into a normal string with the elements separated by the byte @var{sep}, by replacing each @@ -2803,9 +2717,8 @@ string) with @var{sep}. This is handy for printing @var{argz} in a readable manner. @end deftypefun -@comment argz.h -@comment GNU @deftypefun {error_t} argz_add (char **@var{argz}, size_t *@var{argz_len}, const char *@var{str}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c Calls strlen and argz_append. The @code{argz_add} function adds the string @var{str} to the end of the @@ -2813,9 +2726,8 @@ argz vector @code{*@var{argz}}, and updates @code{*@var{argz}} and @code{*@var{argz_len}} accordingly. @end deftypefun -@comment argz.h -@comment GNU @deftypefun {error_t} argz_add_sep (char **@var{argz}, size_t *@var{argz_len}, const char *@var{str}, int @var{delim}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{argz_add_sep} function is similar to @code{argz_add}, but @var{str} is split into separate elements in the result at occurrences of @@ -2824,9 +2736,8 @@ adding the components of a Unix search path to an argz vector, by using a value of @code{':'} for @var{delim}. @end deftypefun -@comment argz.h -@comment GNU @deftypefun {error_t} argz_append (char **@var{argz}, size_t *@var{argz_len}, const char *@var{buf}, size_t @var{buf_len}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{argz_append} function appends @var{buf_len} bytes starting at @var{buf} to the argz vector @code{*@var{argz}}, reallocating @@ -2834,9 +2745,8 @@ The @code{argz_append} function appends @var{buf_len} bytes starting at @code{*@var{argz_len}}. @end deftypefun -@comment argz.h -@comment GNU @deftypefun {void} argz_delete (char **@var{argz}, size_t *@var{argz_len}, char *@var{entry}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c Calls free if no argument is left. If @var{entry} points to the beginning of one of the elements in the @@ -2847,9 +2757,8 @@ destructive argz functions usually reallocate their argz argument, pointers into argz vectors such as @var{entry} will then become invalid. @end deftypefun -@comment argz.h -@comment GNU @deftypefun {error_t} argz_insert (char **@var{argz}, size_t *@var{argz_len}, char *@var{before}, const char *@var{entry}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c Calls argz_add or realloc and memmove. The @code{argz_insert} function inserts the string @var{entry} into the @@ -2862,9 +2771,8 @@ is @code{0}, @var{entry} is added to the end instead (as if by @var{before} will result in @var{entry} being inserted at the beginning. @end deftypefun -@comment argz.h -@comment GNU @deftypefun {char *} argz_next (const char *@var{argz}, size_t @var{argz_len}, const char *@var{entry}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{argz_next} function provides a convenient way of iterating over the elements in the argz vector @var{argz}. It returns a pointer @@ -2896,9 +2804,8 @@ it is empty (rather than a pointer to an empty block of memory); this invariant is maintained for argz vectors created by the functions here. @end deftypefun -@comment argz.h -@comment GNU @deftypefun error_t argz_replace (@w{char **@var{argz}, size_t *@var{argz_len}}, @w{const char *@var{str}, const char *@var{with}}, @w{unsigned *@var{replace_count}}) +@standards{GNU, argz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} Replace any occurrences of the string @var{str} in @var{argz} with @var{with}, reallocating @var{argz} as necessary. If @@ -2932,9 +2839,8 @@ fail) have a return type of @code{error_t}, and return either @code{0} or @pindex envz.h These functions are declared in the standard include file @file{envz.h}. -@comment envz.h -@comment GNU @deftypefun {char *} envz_entry (const char *@var{envz}, size_t @var{envz_len}, const char *@var{name}) +@standards{GNU, envz.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{envz_entry} function finds the entry in @var{envz} with the name @var{name}, and returns a pointer to the whole entry---that is, the argz @@ -2942,9 +2848,8 @@ element which begins with @var{name} followed by a @code{'='} byte. If there is no entry with that name, @code{0} is returned. @end deftypefun -@comment envz.h -@comment GNU @deftypefun {char *} envz_get (const char *@var{envz}, size_t @var{envz_len}, const char *@var{name}) +@standards{GNU, envz.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{envz_get} function finds the entry in @var{envz} with the name @var{name} (like @code{envz_entry}), and returns a pointer to the value @@ -2952,9 +2857,8 @@ portion of that entry (following the @code{'='}). If there is no entry with that name (or only a null entry), @code{0} is returned. @end deftypefun -@comment envz.h -@comment GNU @deftypefun {error_t} envz_add (char **@var{envz}, size_t *@var{envz_len}, const char *@var{name}, const char *@var{value}) +@standards{GNU, envz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c Calls envz_remove, which calls enz_entry and argz_delete, and then @c argz_add or equivalent code that reallocs and appends name=value. @@ -2966,9 +2870,8 @@ already exists in @var{envz}, it is removed first. If @var{value} is (mentioned above). @end deftypefun -@comment envz.h -@comment GNU @deftypefun {error_t} envz_merge (char **@var{envz}, size_t *@var{envz_len}, const char *@var{envz2}, size_t @var{envz2_len}, int @var{override}) +@standards{GNU, envz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{envz_merge} function adds each entry in @var{envz2} to @var{envz}, as if with @code{envz_add}, updating @code{*@var{envz}} and @@ -2980,17 +2883,15 @@ entry in @var{envz} can prevent an entry of the same name in @var{envz2} from being added to @var{envz}, if @var{override} is false. @end deftypefun -@comment envz.h -@comment GNU @deftypefun {void} envz_strip (char **@var{envz}, size_t *@var{envz_len}) +@standards{GNU, envz.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{envz_strip} function removes any null entries from @var{envz}, updating @code{*@var{envz}} and @code{*@var{envz_len}}. @end deftypefun -@comment envz.h -@comment GNU @deftypefun {void} envz_remove (char **@var{envz}, size_t *@var{envz_len}, const char *@var{name}) +@standards{GNU, envz.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{envz_remove} function removes an entry named @var{name} from @var{envz}, updating @code{*@var{envz}} and @code{*@var{envz_len}}. diff --git a/manual/summary.awk b/manual/summary.awk deleted file mode 100644 index 1defe616f7..0000000000 --- a/manual/summary.awk +++ /dev/null @@ -1,133 +0,0 @@ -# awk script to create summary.texinfo from the library texinfo files. -# Copyright (C) 1992-2017 Free Software Foundation, Inc. -# This file is part of the GNU C Library. - -# The GNU C Library is free software; you can redistribute it and/or -# modify it under the terms of the GNU Lesser General Public -# License as published by the Free Software Foundation; either -# version 2.1 of the License, or (at your option) any later version. - -# The GNU C Library is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# Lesser General Public License for more details. - -# You should have received a copy of the GNU Lesser General Public -# License along with the GNU C Library; if not, see -# <http://www.gnu.org/licenses/>. - -# This script recognizes sequences that look like: -# @comment HEADER.h -# @comment STANDARD -# @def... ITEM | @item ITEM | @vindex ITEM - -BEGIN { header = 0; -nameword["@defun"]=1 -nameword["@defunx"]=1 -nameword["@defmac"]=1 -nameword["@defmacx"]=1 -nameword["@defspec"]=1 -nameword["@defspecx"]=1 -nameword["@defvar"]=1 -nameword["@defvarx"]=1 -nameword["@defopt"]=1 -nameword["@defoptx"]=1 -nameword["@deffn"]=2 -nameword["@deffnx"]=2 -nameword["@defvr"]=2 -nameword["@defvrx"]=2 -nameword["@deftp"]=2 -nameword["@deftpx"]=2 -nameword["@deftypefun"]=2 -nameword["@deftypefunx"]=2 -nameword["@deftypevar"]=2 -nameword["@deftypevarx"]=2 -nameword["@deftypefn"]=3 -nameword["@deftypefnx"]=3 -nameword["@deftypevr"]=3 -nameword["@deftypevrx"]=3 -firstword["@defun"]=1 -firstword["@defunx"]=1 -firstword["@defmac"]=1 -firstword["@defmacx"]=1 -firstword["@defspec"]=1 -firstword["@defspecx"]=1 -firstword["@defvar"]=1 -firstword["@defvarx"]=1 -firstword["@defopt"]=1 -firstword["@defoptx"]=1 -firstword["@deffn"]=2 -firstword["@deffnx"]=2 -firstword["@defvr"]=2 -firstword["@defvrx"]=2 -firstword["@deftp"]=2 -firstword["@deftpx"]=2 -firstword["@deftypefun"]=1 -firstword["@deftypefunx"]=1 -firstword["@deftypevar"]=1 -firstword["@deftypevarx"]=1 -firstword["@deftypefn"]=2 -firstword["@deftypefnx"]=2 -firstword["@deftypevr"]=2 -firstword["@deftypevrx"]=2 -nameword["@item"]=1 -firstword["@item"]=1 -nameword["@itemx"]=1 -firstword["@itemx"]=1 -nameword["@vindex"]=1 -firstword["@vindex"]=1 - -print "@c DO NOT EDIT THIS FILE!" -print "@c This file is generated by summary.awk from the Texinfo sources." -} - -$1 == "@node" { node=$2; - for (i = 3; i <= NF; ++i) - { node=node " " $i; if ( $i ~ /,/ ) break; } - sub (/,[, ]*$/, "", node); - } - -$1 == "@comment" && $2 ~ /\.h$/ { header="@file{" $2 "}"; - for (i = 3; i <= NF; ++i) - header=header ", @file{" $i "}" - } - -$1 == "@comment" && $2 == "(none)" { header = -1; } - -$1 == "@comment" && header != 0 { std=$2; - for (i=3;i<=NF;++i) std=std " " $i } - -header != 0 && $1 ~ /@def|@item|@vindex/ \ - { defn=""; name=""; curly=0; n=1; - for (i = 2; i <= NF; ++i) { - if ($i ~ /^{/ && $i !~ /}/) { - curly=1 - word=substr ($i, 2, length ($i)) - } - else { - if (curly) { - if ($i ~ /}$/) { - curly=0 - word=word " " substr ($i, 1, length ($i) - 1) - } else - word=word " " $i - } - # Handle a single word in braces. - else if ($i ~ /^{.*}$/) - word=substr ($i, 2, length ($i) - 2) - else - word=$i - if (!curly) { - if (n >= firstword[$1]) - defn=defn " " word - if (n == nameword[$1]) - name=word - ++n - } - } - } - printf "@comment %s%c", name, 12 # FF - printf "@item%s%c%c", defn, 12, 12 - if (header != -1) printf "%s ", header; - printf "(%s): @ref{%s}.%c\n", std, node, 12; - header = 0 } diff --git a/manual/summary.pl b/manual/summary.pl new file mode 100755 index 0000000000..5da8f1893f --- /dev/null +++ b/manual/summary.pl @@ -0,0 +1,403 @@ +#!/usr/bin/perl +# Generate the Summary of Library Facilities (summary.texi). + +# Copyright (C) 2017 Free Software Foundation, Inc. +# This file is part of the GNU C Library. +# Contributed by Rical Jasan <ricaljasan@pacific.net>, 2017. + +# The GNU C Library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public License +# as published by the Free Software Foundation; either version 2.1 of +# the License, or (at your option) any later version. + +# The GNU C Library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. + +# You should have received a copy of the GNU Lesser General Public +# License along with the GNU C Library; if not, see +# <http://www.gnu.org/licenses/>. + +# Anything declared in a header or defined in a standard should have +# its origins annotated using the @standards macro (see macro.texi). +# This script checks all such elements in the manual (generally, +# @def|item*-commands), ensuring annotations are present and correct. +# If any errors are detected, they are all reported at the end and +# failure is indicated. + +use strict; +use warnings; +use locale; +use File::Basename; + +$| = 1; +my $script = basename $0; + +&help if $ARGV[0] eq "--help"; # Will exit(0). + +my @texis = @ARGV; + +# Various regexes. +my $nde = qr/^\@node /; +my $def = qr/^\@def/; +my $itm = qr/^\@item /; +my $itms = qr/^\@itemx? /; # Don't match @itemize. +my $ann = qr/^\@(def\w+|item)x? /; # Annotatable. +my $std = qr/^\@standards\{/; +my $stx = qr/^\@standardsx\{/; +my $stds = qr/^\@standardsx?\{/; +my $strict_std = qr/^\@standards\{([^,]+, )[^,\}]+\}$/; +my $strict_stx = qr/^\@standardsx\{([^,]+, ){2}[^,\}]+\}$/; +my $lcon = qr/([vf]?table|itemize|enumerate)/; +my $list = qr/^\@${lcon}/; +my $endl = qr/^\@end ${lcon}/; +my $ign = qr/^\@ignore/; +my $eig = qr/^\@end ignore/; + +# Global scope. +my $node; +our $texi; +my $input; +my %entries; +my %errors; + +for $texi (@texis) { + open $input, '<', $texi or die "open $texi: $!"; + while (my $line = <$input>) { + if ($line =~ $nde) { + $node = &get_node($line); + } elsif ($line =~ $def) { + &process_annotation($line); + } elsif ($line =~ $list) { + &process_list($1); # @items occur in list or table context. + } elsif ($line =~ $stds) { + &record_error("Misplaced annotation", ["[$.] ".$line]); + } elsif ($line =~ $ign) { + while (<$input> !~ $eig) {} + } + } + close $input or die "close $texi: $!"; +} + +# Disabled until annotations are complete. +&print_errors() if %errors && 0; # Will exit(1). + +print("\@c DO NOT EDIT THIS FILE!\n". + "\@c This file is generated by $script from the Texinfo sources.\n". + "\@c The \@items are \@include'd from a \@table in header.texi.\n\n"); + +&print_entry($_) for sort keys %entries; + +# Processes an annotatable element, including any subsequent elements +# in an @*x chain, ensuring @standards are present, with valid syntax, +# either recording any errors detected or creating Summary entries. +# This function is the heart of the script. +# +# Prototypes and standards are gathered into separate lists and used +# to evaluate the completeness and correctness of annotations before +# generating the Summary entries. "Prototype" is used to refer to an +# element's entire definition while avoiding conflation with +# @def*-commands. "Element" is strictly used here to refer to the +# name extracted from the prototype, as used in @standardsx, for +# sorting the Summary. +sub process_annotation +{ + my $line = shift; + my (@prototypes, @standards, $i, @tmp); + + # Gather prototypes and standards. + push @prototypes, $line; + while ($line = <$input>) { + last if $line !~ $ann; + push @prototypes, $line; + } + if ($line !~ $stds) { # The fundamental error. + return &record_error('Missing annotation', \@prototypes); + } + push @standards, $line; + push @standards, $line while ($line = <$input>) =~ $stds; + + # If next line is an @item, seek back to catch it on the next + # iteration. This avoids imposing a non-Texinfo syntax + # requirement of blank lines between consecutive annotated @items. + if ($line =~ $itm) { + seek $input, -length($line), 1 or die "seek: $!"; + } + + # Strict check for syntax errors. Other matches are loose, which + # aids error detection and reporting by ensuring things that look + # like standards aren't simply passed over, but caught here. + for ($i=0; $i<@standards; ++$i) { + my $standard = $standards[$i]; + if ($standard !~ $strict_std && $standard !~ $strict_stx) { + push @tmp, $standard; + } + } + return &record_error('Invalid syntax', \@tmp) if @tmp; + + # @standardsx should not be in non-@*x chains. + if (@prototypes == 1) { + for ($i=0; $i<@standards; ++$i) { + return &record_error('Misplaced @standardsx', \@prototypes) + if $standards[$i] =~ $stx; + } + } + # @standards may only occur once in @*x chains, at the beginning. + if (@prototypes > 1) { + for ($i=1; $i<@standards; ++$i) { + return &record_error('Misplaced @standards', \@prototypes) + if $standards[$i] =~ $std; + } + } + + # The @standards are aligned. + &add_entries(\@prototypes, \@standards); +} + +# Goes through the prototypes, cleaning them up and extracting the +# elements, pairing them with the appropriate annotations to create +# Summary entries. +sub add_entries +{ + my ($prototypes, $standards) = @_; + my $isx = @{$prototypes} > 1 ? 1 : 0; + my $allx = $standards->[0] =~ $stx ? 1 : 0; + my ($defstd, $defhdr, %standardsx, $i, $j); + + # Grab the default annotation and index any @standardsx. Take + # care in case there is no default. + if ($isx) { + if (!$allx) { + ($defstd, $defhdr) + = $standards->[0] =~ /${std}([^,]+), (.*)\}$/; + } + for ($i = $allx ? 0 : 1; $i<@{$standards}; ++$i) { + my ($e, $s, $h) + = $standards->[$i] =~ /${stx}([^,]+), ([^,]+), (.*)\}$/; + push @{$standardsx{$e}{hs}}, [$h, $s]; + } + } + + for ($i=0; $i<@{$prototypes}; ++$i) { + my $e = &get_element($prototypes->[$i]); + my $p = &get_prototype($prototypes->[$i]); + my ($s, $h); + if ($isx && exists $standardsx{$e}) { + for ($j=0; $j<@{$standardsx{$e}{hs}}; ++$j) { + $h = $standardsx{$e}{hs}[$j]->[0]; + $s = $standardsx{$e}{hs}[$j]->[1]; + &record_entry($e, $p, $h, $s, $node); + ++$standardsx{$e}{seen}; + } + } elsif ($isx && $allx) { + &record_error('Missing annotation', [$prototypes->[$i]]); + } elsif ($isx) { + &record_entry($e, $p, $defhdr, $defstd, $node); + } else { + for ($j=0; $j<@{$standards}; ++$j) { + ($s, $h) = $standards->[$j] =~ /${std}([^,]+), ([^,\}]+)\}$/; + &record_entry($e, $p, $h, $s, $node); + } + } + } + + # Check if there were any unmatched @standardsx. + for my $e (keys %standardsx) { + if (!exists $standardsx{$e}{seen}) { + &record_error('Spurious @standardsx', [$e."\n"]) + } + } +} + +# Stores a Summary entry in %entries. May be called multiple times +# per element if multiple header and standard annotations exist. Also +# keys on prototypes, as some elements have multiple prototypes. See +# isnan in arith.texi for one example. +sub record_entry +{ + my ($ele, $proto, $hdr, $std, $node) = @_; + push @{$entries{$ele}{$proto}}, [$hdr, $std, $node]; +} + +# Processes list or table contexts, with nesting. +sub process_list +{ + my $type = shift; + my $in_vtbl = $type eq "vtable" ? 1 : 0; + + while (my $line = <$input>) { + if ($line =~ $itms) { + next if ! $in_vtbl; # Not an annotatable context. + &process_annotation($line); + } elsif ($line =~ $def) { + &process_annotation($line); + } elsif ($line =~ $stds) { + &record_error('Misplaced annotation', ["[$.] ".$line]); + } elsif ($line =~ $endl) { + return; # All done. + } elsif ($line =~ $list) { + &process_list($1); # Nested list. + } + } +} + +# Returns the current node from an @node line. Used for referencing +# from the Summary. +sub get_node +{ + my $line = shift; + chomp $line; + $line =~ s/$nde//; + my ($n) = split ',', $line; + return $n +} + +# Returns the cleaned up prototype from @def|item* lines. +sub get_prototype +{ + my $dfn = shift; + chomp $dfn; + $dfn =~ s/\s+/ /g; # Collapse whitespace. + $dfn =~ s/ \{([^\}]*)\} / $1 /g; # Remove grouping braces. + $dfn =~ s/^\@\S+ //; # Remove @-command. + $dfn =~ s/^Macro //i; # Scrape off cruft... + $dfn =~ s/^Data Type //i; + $dfn =~ s/^Variable //i; + $dfn =~ s/^Deprecated Function //i; + $dfn =~ s/^SVID Macro //i; + $dfn =~ s/^Obsolete function //i; + $dfn =~ s/^Constant //i; + $dfn =~ s/^Type //i; + $dfn =~ s/^Function //i; + $dfn =~ s/^\{(.*)\}$/$1/; # Debrace yourself. + $dfn =~ s/^\{([^\}]*)\} /$1 /; # These ones too. + return $dfn; +} + +# Returns an annotated element's name. +# +# Takes a line defining an annotatable element (e.g., @def|item*), +# splitting it on whitespace. The element is generally detected as +# the member immediately preceding the first parenthesized expression +# (e.g., a function), or the last token in the list. Some additional +# cleanup is applied to the element before returning it. +sub get_element +{ + my $i = 0; + my @toks = split /\s+/, shift; + # tzname array uses '['; don't match function pointers. + ++$i while $toks[$i] && $toks[$i] !~ /^[\(\[](?!\*)/; + $toks[$i-1] =~ s/^\*//; # Strip pointer type syntax. + $toks[$i-1] =~ s/^\{?([^\}]+)\}?$/$1/; # Strip braces. + $toks[$i-1] =~ s/^\(\*([^\)]+)\)$/$1/; # Function pointers. + return $toks[$i-1]; +} + +# Records syntax errors detected in the manual related to @standards. +# The @def|item*s are grouped by file, then errors, to make it easier +# to track down exactly where and what the problems are. +sub record_error +{ + my ($err, $list) = @_; + push @{$errors{$texi}{$err}}, $_ for (@{$list}); + return 0; +} + +# Reports all detected errors and exits with failure. Indentation is +# used for readability, and "ERROR" is used for visibility. +sub print_errors +{ + for $texi (sort keys %errors) { + print STDERR "ERRORS in $texi:\n"; + for my $err (sort keys %{$errors{$texi}}) { + print STDERR " $err:\n"; + print STDERR " $_" for (@{$errors{$texi}{$err}}); + } + } + print(STDERR "\nFor a description of expected syntax, see ". + "\`$script --help'\n\n"); + exit 1; +} + +# Prints an entry in the Summary. +# +# All the blank lines in summary.texi may seem strange at first, but +# they have significant impact on how Texinfo renders the output. +# Essentially, each line is its own paragraph. There is a @comment +# with the element name, arguably unnecessary, but useful for seeing +# the sorting order and extracted element names, and maintains the +# format established by summary.awk. Each @item in the @table is the +# prototype, which may be anything from just a variable name to a +# function declaration. The body of each @item contains lines +# annotating the headers and standards each element is declared +# in/comes from, with a reference to the @node documenting the element +# wrt. each header and standard combination. +sub print_entry +{ + my $element = shift; + for my $prototype (sort keys %{$entries{$element}}) { + print "\@comment $element\n\@item $prototype\n\n"; + for (@{$entries{$element}{$prototype}}) { + my ($header, $standard, $node) + = ($_->[0], $_->[1], $_->[2]); + if ($header =~ /^\(none\)$/i) { + $header = "\@emph{no header}"; + } elsif ($header =~ /\(optional\)$/) { + $header =~ s/^(\S+) \((.*)\)$/\@file{$1} \@emph{$2}/; + } elsif ($header ne '???') { + $header = "\@file{$header}"; + } + print "$header ($standard): \@ref{$node}.\n\n"; + } + } +} + +# Document the syntax of @standards. +sub help +{ + print "$script "; + print <<'EOH'; +generates the Summary of Library Facilities (summary.texi) +from @standards and @standardsx macros in the Texinfo sources (see +macros.texi). While generating the Summary, it also checks that +@standards are used, correctly. + +In general, any @def*-command or @item in a @vtable is considered +annotatable. "Misplaced annotation" refers to @standards macros +detected outside an annotatable context. "Missing annotation" refers +to annotatable elements without @standards. @standards are expected +to immediately follow the elements being annotated. In @*x lists, +@standards sets the default annotation and may only occur as the first +annotation ("Misplaced @standards"). @standardsx may not be used +outside @*x lists ("Misplaced @standardsx"). "Spurious @standardsx" +refers to otherwise valid @standardsx macros that were not matched to +an element in an @*x list. "Invalid syntax" means just that. + +The syntax of @standards annotations is designed to accomodate +multiple header and standards annotations, as necessary. + +Examples: + + @deftp FOO + @standards{STD, HDR} + + @defvar BAR + @standards{STD, HDR1} + @standards{STD, HDR2} + + @deftypefun foo + @deftypefunx fool + @standards{STD, HDR} + + @item bar + @itemx baz + @standardsx{bar, STD1, HDR1} + @standardsx{baz, STD1, HDR1} + @standardsx{baz, STD2, HDR2} + +Note that @standardsx deviates from the usual Texinfo syntax in that +it is optional and may be used without @standards. +EOH + ; exit 0; +} diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi index 9a8b79d66b..4beee0129b 100644 --- a/manual/sysinfo.texi +++ b/manual/sysinfo.texi @@ -88,9 +88,8 @@ Prototypes for these functions appear in @file{unistd.h}. The programs @code{hostname}, @code{hostid}, and @code{domainname} work by calling these functions. -@comment unistd.h -@comment BSD @deftypefun int gethostname (char *@var{name}, size_t @var{size}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on unix; implemented in terms of uname on posix and of @c hurd_get_host_config on hurd. @@ -121,9 +120,8 @@ truncated host name is good enough. If it is, you can ignore the error code. @end deftypefun -@comment unistd.h -@comment BSD @deftypefun int sethostname (const char *@var{name}, size_t @var{length}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on unix; implemented in terms of hurd_set_host_config @c on hurd. @@ -148,9 +146,8 @@ This process cannot set the host name because it is not privileged. @end table @end deftypefun -@comment unistd.h -@comment ??? @deftypefun int getdomainnname (char *@var{name}, size_t @var{length}) +@standards{???, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Syscalls uname, then strlen and memcpy. @cindex NIS domain name @@ -164,9 +161,8 @@ The specifics of this function are analogous to @code{gethostname}, above. @end deftypefun -@comment unistd.h -@comment ??? @deftypefun int setdomainname (const char *@var{name}, size_t @var{length}) +@standards{???, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall. @cindex NIS domain name @@ -180,9 +176,8 @@ The specifics of this function are analogous to @code{sethostname}, above. @end deftypefun -@comment unistd.h -@comment BSD @deftypefun {long int} gethostid (void) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{@mtshostid{} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} @c On HURD, calls _hurd_get_host_config and strtol. On Linux, open @c HOSTIDFILE, reads an int32_t and closes; if that fails, it calls @@ -201,9 +196,8 @@ on the results of @code{gethostname}. For more information on IP addresses, @xref{Host Addresses}. @end deftypefun -@comment unistd.h -@comment BSD @deftypefun int sethostid (long int @var{id}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtunsafe{@mtasuconst{:@mtshostid{}}}@asunsafe{}@acunsafe{@acucorrupt{} @acsfd{}}} The @code{sethostid} function sets the ``host ID'' of the host machine to @var{id}. Only privileged processes are permitted to do this. Usually @@ -245,9 +239,8 @@ which you can get with functions targeted to this purpose described in @ref{Host Identification}. -@comment sys/utsname.h -@comment POSIX.1 @deftp {Data Type} {struct utsname} +@standards{POSIX.1, sys/utsname.h} The @code{utsname} structure is used to hold information returned by the @code{uname} function. It has the following members: @@ -308,9 +301,8 @@ use of the rest of the structure. @end table @end deftp -@comment sys/utsname.h -@comment POSIX.1 @deftypefun int uname (struct utsname *@var{info}) +@standards{POSIX.1, sys/utsname.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on unix; the posix fallback is to call gethostname and @c then fills in the other fields with constants; on HURD, it calls @@ -413,9 +405,8 @@ The names @code{_PATH_MNTTAB} and @code{_PATH_MOUNTED} should always be used. The internal representation for entries of the file is @w{@code{struct fstab}}, defined in @file{fstab.h}. -@comment fstab.h -@comment BSD @deftp {Data Type} {struct fstab} +@standards{BSD, fstab.h} This structure is used with the @code{getfsent}, @code{getfsspec}, and @code{getfsfile} functions. @@ -487,9 +478,8 @@ related to the @code{dump} utility used on Unix systems. To read the entire content of the of the @file{fstab} file @theglibc{} contains a set of three functions which are designed in the usual way. -@comment fstab.h -@comment BSD @deftypefun int setfsent (void) +@standards{BSD, fstab.h} @safety{@prelim{}@mtunsafe{@mtasurace{:fsent}}@asunsafe{@ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c setfsent @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd @c fstab_init(1) @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd @@ -508,9 +498,8 @@ and the @code{getfs*} functions can be used to read the entries of the file. @end deftypefun -@comment fstab.h -@comment BSD @deftypefun void endfsent (void) +@standards{BSD, fstab.h} @safety{@prelim{}@mtunsafe{@mtasurace{:fsent}}@asunsafe{@ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c endfsent @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd @c endmntent dup @ascuheap @asulock @aculock @acsmem @acsfd @@ -519,9 +508,8 @@ This function makes sure that all resources acquired by a prior call to freed. @end deftypefun -@comment fstab.h -@comment BSD @deftypefun {struct fstab *} getfsent (void) +@standards{BSD, fstab.h} @safety{@prelim{}@mtunsafe{@mtasurace{:fsent} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c getfsent @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @asulock @acucorrupt @aculock @acsmem @c fstab_init(0) dup @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd @@ -540,9 +528,8 @@ function is not thread-safe. If an error occurred @code{getfsent} returns a @code{NULL} pointer. @end deftypefun -@comment fstab.h -@comment BSD @deftypefun {struct fstab *} getfsspec (const char *@var{name}) +@standards{BSD, fstab.h} @safety{@prelim{}@mtunsafe{@mtasurace{:fsent} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c getffsspec @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @asulock @acucorrupt @aculock @acsmem @c fstab_init(1) dup @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd @@ -563,9 +550,8 @@ function is not thread-safe. If an error occurred @code{getfsent} returns a @code{NULL} pointer. @end deftypefun -@comment fstab.h -@comment BSD @deftypefun {struct fstab *} getfsfile (const char *@var{name}) +@standards{BSD, fstab.h} @safety{@prelim{}@mtunsafe{@mtasurace{:fsent} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c getffsfile @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @asulock @acucorrupt @aculock @acsmem @c fstab_init(1) dup @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd @@ -591,9 +577,8 @@ returns a @code{NULL} pointer. @subsubsection The @file{mtab} file The following functions and data structure access the @file{mtab} file. -@comment mntent.h -@comment BSD @deftp {Data Type} {struct mntent} +@standards{BSD, mntent.h} This structure is used with the @code{getmntent}, @code{getmntent_r}, @code{addmntent}, and @code{hasmntopt} functions. @@ -684,9 +669,8 @@ handle @file{fstab} these functions do not access a fixed file and there is even a thread safe variant of the get function. Besides this @theglibc{} contains functions to alter the file and test for specific options. -@comment mntent.h -@comment BSD @deftypefun {FILE *} setmntent (const char *@var{file}, const char *@var{mode}) +@standards{BSD, mntent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} @c setmntent @ascuheap @asulock @acsmem @acsfd @aculock @c strlen dup ok @@ -706,9 +690,8 @@ handle for future use. Otherwise the return value is @code{NULL} and @code{errno} is set accordingly. @end deftypefun -@comment mntent.h -@comment BSD @deftypefun int endmntent (FILE *@var{stream}) +@standards{BSD, mntent.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c endmntent @ascuheap @asulock @aculock @acsmem @acsfd @c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd @@ -720,9 +703,8 @@ The return value is @math{1} unless an error occurred in which case it is @math{0}. @end deftypefun -@comment mntent.h -@comment BSD @deftypefun {struct mntent *} getmntent (FILE *@var{stream}) +@standards{BSD, mntent.h} @safety{@prelim{}@mtunsafe{@mtasurace{:mntentbuf} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asuinit{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsmem{}}} @c getmntent @mtasurace:mntentbuf @mtslocale @asucorrupt @ascuheap @asuinit @acuinit @acucorrupt @aculock @acsmem @c libc_once @ascuheap @asuinit @acuinit @acsmem @@ -752,9 +734,8 @@ a pointer to the same static variable. @code{getmntent_r} should be used in situations where multiple threads access the file. @end deftypefun -@comment mntent.h -@comment BSD @deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mntent *@var{result}, char *@var{buffer}, int @var{bufsize}) +@standards{BSD, mntent.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} @c getmntent_r @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem @c flockfile dup @aculock @@ -787,9 +768,8 @@ end of file reached, @end itemize @end deftypefun -@comment mntent.h -@comment BSD @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt}) +@standards{BSD, mntent.h} @safety{@prelim{}@mtsafe{@mtsrace{:stream} @mtslocale{}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} @c addmntent @mtasurace:stream @mtslocale @asucorrupt @acucorrupt @c fseek dup @asucorrupt @acucorrupt [no @aculock] @@ -816,9 +796,8 @@ Otherwise the return value is @math{1} and @code{errno} is set appropriately. @end deftypefun -@comment mntent.h -@comment BSD @deftypefun {char *} hasmntopt (const struct mntent *@var{mnt}, const char *@var{opt}) +@standards{BSD, mntent.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c hasmntopt ok @c strlen dup ok @@ -859,9 +838,9 @@ should maintain and use these separately. @xref{Mount Information}. The symbols in this section are declared in @file{sys/mount.h}. -@comment sys/mount.h -@comment SVID, BSD @deftypefun {int} mount (const char *@var{special_file}, const char *@var{dir}, const char *@var{fstype}, unsigned long int @var{options}, const void *@var{data}) +@standards{SVID, sys/mount.h} +@standards{BSD, sys/mount.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall. @@ -1051,9 +1030,8 @@ not one that uses a device. @end deftypefun -@comment sys/mount.h -@comment GNU @deftypefun {int} umount2 (const char *@var{file}, int @var{flags}) +@standards{GNU, sys/mount.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall. @@ -1118,9 +1096,9 @@ point nor a device special file of a currently mounted filesystem. This function is not available on all systems. @end deftypefun -@comment sys/mount.h -@comment SVID, GNU @deftypefun {int} umount (const char *@var{file}) +@standards{SVID, sys/mount.h} +@standards{GNU, sys/mount.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall or wrapper for umount2. @@ -1140,9 +1118,8 @@ a variety of system parameters. The symbols used in this section are declared in the file @file{sys/sysctl.h}. -@comment sys/sysctl.h -@comment BSD @deftypefun int sysctl (int *@var{names}, int @var{nlen}, void *@var{oldval}, size_t *@var{oldlenp}, void *@var{newval}, size_t @var{newlen}) +@standards{BSD, sys/sysctl.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. diff --git a/manual/syslog.texi b/manual/syslog.texi index 7b73a091fe..02f84d6e6f 100644 --- a/manual/syslog.texi +++ b/manual/syslog.texi @@ -144,9 +144,8 @@ system, use the socket I/O functions to write a UDP datagram to the The symbols referred to in this section are declared in the file @file{syslog.h}. -@comment syslog.h -@comment BSD @deftypefun void openlog (const char *@var{ident}, int @var{option}, int @var{facility}) +@standards{BSD, syslog.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c openlog @asulock @aculock @acsfd @c libc_lock_lock @asulock @aculock @@ -284,9 +283,8 @@ The symbols referred to in this section are declared in the file @file{syslog.h}. @c syslog() is implemented as a call to vsyslog(). -@comment syslog.h -@comment BSD @deftypefun void syslog (int @var{facility_priority}, const char *@var{format}, @dots{}) +@standards{BSD, syslog.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c syslog @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd @c va_start dup ok @@ -444,9 +442,8 @@ syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR), @end deftypefun -@comment syslog.h -@comment BSD @deftypefun void vsyslog (int @var{facility_priority}, const char *@var{format}, va_list @var{arglist}) +@standards{BSD, syslog.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c vsyslog @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd @c vsyslog_chk dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd @@ -463,9 +460,8 @@ length argument. The symbols referred to in this section are declared in the file @file{syslog.h}. -@comment syslog.h -@comment BSD @deftypefun void closelog (void) +@standards{BSD, syslog.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c closelog @asulock @aculock @acsfd @c libc_lock_lock @asulock @aculock @@ -500,9 +496,8 @@ Syslog connections are automatically closed on exec or exit. The symbols referred to in this section are declared in the file @file{syslog.h}. -@comment syslog.h -@comment BSD @deftypefun int setlogmask (int @var{mask}) +@standards{BSD, syslog.h} @safety{@prelim{}@mtunsafe{@mtasurace{:LogMask}}@asunsafe{}@acsafe{}} @c Read and modify are not guarded by syslog_lock, so concurrent changes @c or even uses are undefined. This should use an atomic swap instead, diff --git a/manual/terminal.texi b/manual/terminal.texi index 0c5fdd1a76..4fef5045b8 100644 --- a/manual/terminal.texi +++ b/manual/terminal.texi @@ -41,9 +41,8 @@ function. Prototypes for the functions in this section are declared in the header file @file{unistd.h}. -@comment unistd.h -@comment POSIX.1 @deftypefun int isatty (int @var{filedes}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c isatty ok @c tcgetattr dup ok @@ -55,9 +54,8 @@ If a file descriptor is associated with a terminal, you can get its associated file name using the @code{ttyname} function. See also the @code{ctermid} function, described in @ref{Identifying the Terminal}. -@comment unistd.h -@comment POSIX.1 @deftypefun {char *} ttyname (int @var{filedes}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:ttyname}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c ttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd @c isatty dup ok @@ -79,9 +77,8 @@ the terminal file. The value is a null pointer if the file descriptor isn't associated with a terminal, or the file name cannot be determined. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} @c ttyname_r @ascuheap @acsmem @acsfd @c isatty dup ok @@ -232,9 +229,8 @@ structure of type @code{struct termios}. This structure is used with the functions @code{tcgetattr} and @code{tcsetattr} to read and set the attributes. -@comment termios.h -@comment POSIX.1 @deftp {Data Type} {struct termios} +@standards{POSIX.1, termios.h} A @code{struct termios} records all the I/O attributes of a terminal. The structure includes at least the following members: @@ -265,23 +261,20 @@ speed values. The following sections describe the details of the members of the @code{struct termios} structure. -@comment termios.h -@comment POSIX.1 @deftp {Data Type} tcflag_t +@standards{POSIX.1, termios.h} This is an unsigned integer type used to represent the various bit masks for terminal flags. @end deftp -@comment termios.h -@comment POSIX.1 @deftp {Data Type} cc_t +@standards{POSIX.1, termios.h} This is an unsigned integer type used to represent characters associated with various terminal control functions. @end deftp -@comment termios.h -@comment POSIX.1 @deftypevr Macro int NCCS +@standards{POSIX.1, termios.h} The value of this macro is the number of elements in the @code{c_cc} array. @end deftypevr @@ -290,9 +283,8 @@ array. @subsection Terminal Mode Functions @cindex terminal mode functions -@comment termios.h -@comment POSIX.1 @deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Converting the kernel-returned termios data structure to the userland @c format does not ensure atomic or consistent writing. @@ -313,9 +305,8 @@ The @var{filedes} is not associated with a terminal. @end table @end deftypefun -@comment termios.h -@comment POSIX.1 @deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Converting the incoming termios data structure to the kernel format @c does not ensure atomic or consistent reading. @@ -327,26 +318,22 @@ The @var{when} argument specifies how to deal with input and output already queued. It can be one of the following values: @vtable @code -@comment termios.h -@comment POSIX.1 @item TCSANOW +@standards{POSIX.1, termios.h} Make the change immediately. -@comment termios.h -@comment POSIX.1 @item TCSADRAIN +@standards{POSIX.1, termios.h} Make the change after waiting until all queued output has been written. You should usually use this option when changing parameters that affect output. -@comment termios.h -@comment POSIX.1 @item TCSAFLUSH +@standards{POSIX.1, termios.h} This is like @code{TCSADRAIN}, but also discards any queued input. -@comment termios.h -@comment BSD @item TCSASOFT +@standards{BSD, termios.h} This is a flag bit that you can add to any of the above alternatives. Its meaning is to inhibit alteration of the state of the terminal hardware. It is a BSD extension; it is only supported on BSD systems @@ -476,9 +463,8 @@ try to specify the entire value for @code{c_iflag}---instead, change only specific flags and leave the rest untouched (@pxref{Setting Modes}). -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t INPCK +@standards{POSIX.1, termios.h} @cindex parity checking If this bit is set, input parity checking is enabled. If it is not set, no checking at all is done for parity errors on input; the @@ -496,16 +482,14 @@ of these bits are set, a byte with a parity error is passed to the application as a @code{'\0'} character. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t IGNPAR +@standards{POSIX.1, termios.h} If this bit is set, any byte with a framing or parity error is ignored. This is only useful if @code{INPCK} is also set. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t PARMRK +@standards{POSIX.1, termios.h} If this bit is set, input bytes with parity or framing errors are marked when passed to the program. This bit is meaningful only when @code{INPCK} is set and @code{IGNPAR} is not set. @@ -520,16 +504,14 @@ parity error. So a valid byte @code{0377} is passed to the program as two bytes, @code{0377} @code{0377}, in this case. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t ISTRIP +@standards{POSIX.1, termios.h} If this bit is set, valid input bytes are stripped to seven bits; otherwise, all eight bits are available for programs to read. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t IGNBRK +@standards{POSIX.1, termios.h} If this bit is set, break conditions are ignored. @cindex break condition, detecting @@ -538,9 +520,8 @@ serial data transmission as a series of zero-value bits longer than a single byte. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t BRKINT +@standards{POSIX.1, termios.h} If this bit is set and @code{IGNBRK} is not set, a break condition clears the terminal input and output queues and raises a @code{SIGINT} signal for the foreground process group associated with the terminal. @@ -551,33 +532,29 @@ passed to the application as a single @code{'\0'} character if @code{'\377'}, @code{'\0'}, @code{'\0'}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t IGNCR +@standards{POSIX.1, termios.h} If this bit is set, carriage return characters (@code{'\r'}) are discarded on input. Discarding carriage return may be useful on terminals that send both carriage return and linefeed when you type the @key{RET} key. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t ICRNL +@standards{POSIX.1, termios.h} If this bit is set and @code{IGNCR} is not set, carriage return characters (@code{'\r'}) received as input are passed to the application as newline characters (@code{'\n'}). @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t INLCR +@standards{POSIX.1, termios.h} If this bit is set, newline characters (@code{'\n'}) received as input are passed to the application as carriage return characters (@code{'\r'}). @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t IXOFF +@standards{POSIX.1, termios.h} If this bit is set, start/stop control on input is enabled. In other words, the computer sends STOP and START characters as necessary to prevent input from coming in faster than programs are reading it. The @@ -586,9 +563,8 @@ data responds to a STOP character by suspending transmission, and to a START character by resuming transmission. @xref{Start/Stop Characters}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t IXON +@standards{POSIX.1, termios.h} If this bit is set, start/stop control on output is enabled. In other words, if the computer receives a STOP character, it suspends output until a START character is received. In this case, the STOP and START @@ -598,9 +574,8 @@ not set, then START and STOP can be read as ordinary characters. @c !!! mention this interferes with using C-s and C-q for programs like emacs @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t IXANY +@standards{BSD, termios.h} If this bit is set, any input character restarts output when output has been suspended with the STOP character. Otherwise, only the START character restarts output. @@ -609,9 +584,8 @@ This is a BSD extension; it exists only on BSD systems and @gnulinuxhurdsystems{}. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t IMAXBEL +@standards{BSD, termios.h} If this bit is set, then filling up the terminal input buffer sends a BEL character (code @code{007}) to the terminal to ring the bell. @@ -632,9 +606,8 @@ try to specify the entire value for @code{c_oflag}---instead, change only specific flags and leave the rest untouched (@pxref{Setting Modes}). -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t OPOST +@standards{POSIX.1, termios.h} If this bit is set, output data is processed in some unspecified way so that it is displayed appropriately on the terminal device. This typically includes mapping newline characters (@code{'\n'}) onto @@ -645,25 +618,22 @@ If this bit isn't set, the characters are transmitted as-is. The following three bits are effective only if @code{OPOST} is set. -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t ONLCR +@standards{POSIX.1, termios.h} If this bit is set, convert the newline character on output into a pair of characters, carriage return followed by linefeed. @end deftypevr -@comment termios.h (optional) -@comment BSD @deftypevr Macro tcflag_t OXTABS +@standards{BSD, termios.h (optional)} If this bit is set, convert tab characters on output into the appropriate number of spaces to emulate a tab stop every eight columns. This bit exists only on BSD systems and @gnuhurdsystems{}; on @gnulinuxsystems{} it is available as @code{XTABS}. @end deftypevr -@comment termios.h (optional) -@comment BSD @deftypevr Macro tcflag_t ONOEOT +@standards{BSD, termios.h (optional)} If this bit is set, discard @kbd{C-d} characters (code @code{004}) on output. These characters cause many dial-up terminals to disconnect. This bit exists only on BSD systems and @gnuhurdsystems{}. @@ -685,9 +655,8 @@ try to specify the entire value for @code{c_cflag}---instead, change only specific flags and leave the rest untouched (@pxref{Setting Modes}). -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t CLOCAL +@standards{POSIX.1, termios.h} If this bit is set, it indicates that the terminal is connected ``locally'' and that the modem status lines (such as carrier detect) should be ignored. @@ -708,30 +677,26 @@ clear the condition. @cindex modem disconnect @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t HUPCL +@standards{POSIX.1, termios.h} If this bit is set, a modem disconnect is generated when all processes that have the terminal device open have either closed the file or exited. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t CREAD +@standards{POSIX.1, termios.h} If this bit is set, input can be read from the terminal. Otherwise, input is discarded when it arrives. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t CSTOPB +@standards{POSIX.1, termios.h} If this bit is set, two stop bits are used. Otherwise, only one stop bit is used. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t PARENB +@standards{POSIX.1, termios.h} If this bit is set, generation and detection of a parity bit are enabled. @xref{Input Modes}, for information on how input parity errors are handled. @@ -739,9 +704,8 @@ If this bit is not set, no parity bit is added to output characters, and input characters are not checked for correct parity. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t PARODD +@standards{POSIX.1, termios.h} This bit is only useful if @code{PARENB} is set. If @code{PARODD} is set, odd parity is used, otherwise even parity is used. @end deftypevr @@ -750,62 +714,53 @@ The control mode flags also includes a field for the number of bits per character. You can use the @code{CSIZE} macro as a mask to extract the value, like this: @code{settings.c_cflag & CSIZE}. -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t CSIZE +@standards{POSIX.1, termios.h} This is a mask for the number of bits per character. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t CS5 +@standards{POSIX.1, termios.h} This specifies five bits per byte. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t CS6 +@standards{POSIX.1, termios.h} This specifies six bits per byte. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t CS7 +@standards{POSIX.1, termios.h} This specifies seven bits per byte. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t CS8 +@standards{POSIX.1, termios.h} This specifies eight bits per byte. @end deftypevr The following four bits are BSD extensions; these exist only on BSD systems and @gnuhurdsystems{}. -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t CCTS_OFLOW +@standards{BSD, termios.h} If this bit is set, enable flow control of output based on the CTS wire (RS232 protocol). @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t CRTS_IFLOW +@standards{BSD, termios.h} If this bit is set, enable flow control of input based on the RTS wire (RS232 protocol). @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t MDMBUF +@standards{BSD, termios.h} If this bit is set, enable carrier-based flow control of output. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t CIGNORE +@standards{BSD, termios.h} If this bit is set, it says to ignore the control modes and line speed values entirely. This is only meaningful in a call to @code{tcsetattr}. @@ -834,24 +789,21 @@ try to specify the entire value for @code{c_lflag}---instead, change only specific flags and leave the rest untouched (@pxref{Setting Modes}). -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t ICANON +@standards{POSIX.1, termios.h} This bit, if set, enables canonical input processing mode. Otherwise, input is processed in noncanonical mode. @xref{Canonical or Not}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t ECHO +@standards{POSIX.1, termios.h} If this bit is set, echoing of input characters back to the terminal is enabled. @cindex echo of terminal input @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t ECHOE +@standards{POSIX.1, termios.h} If this bit is set, echoing indicates erasure of input with the ERASE character by erasing the last character in the current line from the screen. Otherwise, the character erased is re-echoed to show what has @@ -862,9 +814,8 @@ itself controls actual recognition of the ERASE character and erasure of input, without which @code{ECHOE} is simply irrelevant. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t ECHOPRT +@standards{BSD, termios.h} This bit, like @code{ECHOE}, enables display of the ERASE character in a way that is geared to a hardcopy terminal. When you type the ERASE character, a @samp{\} character is printed followed by the first @@ -876,9 +827,8 @@ This is a BSD extension, and exists only in BSD systems and @gnulinuxhurdsystems{}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t ECHOK +@standards{POSIX.1, termios.h} This bit enables special display of the KILL character by moving to a new line after echoing the KILL character normally. The behavior of @code{ECHOKE} (below) is nicer to look at. @@ -893,26 +843,23 @@ itself controls actual recognition of the KILL character and erasure of input, without which @code{ECHOK} is simply irrelevant. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t ECHOKE +@standards{BSD, termios.h} This bit is similar to @code{ECHOK}. It enables special display of the KILL character by erasing on the screen the entire line that has been killed. This is a BSD extension, and exists only in BSD systems and @gnulinuxhurdsystems{}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t ECHONL +@standards{POSIX.1, termios.h} If this bit is set and the @code{ICANON} bit is also set, then the newline (@code{'\n'}) character is echoed even if the @code{ECHO} bit is not set. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t ECHOCTL +@standards{BSD, termios.h} If this bit is set and the @code{ECHO} bit is also set, echo control characters with @samp{^} followed by the corresponding text character. Thus, control-A echoes as @samp{^A}. This is usually the preferred mode @@ -923,9 +870,8 @@ This is a BSD extension, and exists only in BSD systems and @gnulinuxhurdsystems{}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t ISIG +@standards{POSIX.1, termios.h} This bit controls whether the INTR, QUIT, and SUSP characters are recognized. The functions associated with these characters are performed if and only if this bit is set. Being in canonical or noncanonical @@ -941,9 +887,8 @@ signals associated with these characters, or to escape from the program. @xref{Signal Characters}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t IEXTEN +@standards{POSIX.1, termios.h} POSIX.1 gives @code{IEXTEN} implementation-defined meaning, so you cannot rely on this interpretation on all systems. @@ -952,17 +897,15 @@ DISCARD characters. @xref{Other Special}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t NOFLSH +@standards{POSIX.1, termios.h} Normally, the INTR, QUIT, and SUSP characters cause input and output queues for the terminal to be cleared. If this bit is set, the queues are not cleared. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro tcflag_t TOSTOP +@standards{POSIX.1, termios.h} If this bit is set and the system supports job control, then @code{SIGTTOU} signals are generated by background processes that attempt to write to the terminal. @xref{Access to the Terminal}. @@ -971,9 +914,8 @@ attempt to write to the terminal. @xref{Access to the Terminal}. The following bits are BSD extensions; they exist only on BSD systems and @gnuhurdsystems{}. -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t ALTWERASE +@standards{BSD, termios.h} This bit determines how far the WERASE character should erase. The WERASE character erases back to the beginning of a word; the question is, where do words begin? @@ -986,23 +928,20 @@ a character which is none of those. @xref{Editing Characters}, for more information about the WERASE character. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t FLUSHO +@standards{BSD, termios.h} This is the bit that toggles when the user types the DISCARD character. While this bit is set, all output is discarded. @xref{Other Special}. @end deftypevr -@comment termios.h (optional) -@comment BSD @deftypevr Macro tcflag_t NOKERNINFO +@standards{BSD, termios.h (optional)} Setting this bit disables handling of the STATUS character. @xref{Other Special}. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro tcflag_t PENDIN +@standards{BSD, termios.h} If this bit is set, it indicates that there is a line of input that needs to be reprinted. Typing the REPRINT character sets this bit; the bit remains set until reprinting is finished. @xref{Editing Characters}. @@ -1044,9 +983,8 @@ don't try to access them in the @code{struct termios} structure directly. Instead, you should use the following functions to read and store them: -@comment termios.h -@comment POSIX.1 @deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct access to a single termios field, except on Linux, where @c multiple accesses may take place. No worries either way, callers @@ -1055,17 +993,15 @@ This function returns the output line speed stored in the structure @code{*@var{termios-p}}. @end deftypefun -@comment termios.h -@comment POSIX.1 @deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns the input line speed stored in the structure @code{*@var{termios-p}}. @end deftypefun -@comment termios.h -@comment POSIX.1 @deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function stores @var{speed} in @code{*@var{termios-p}} as the output speed. The normal return value is @math{0}; a value of @math{-1} @@ -1073,9 +1009,8 @@ indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} returns @math{-1}. @end deftypefun -@comment termios.h -@comment POSIX.1 @deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function stores @var{speed} in @code{*@var{termios-p}} as the input speed. The normal return value is @math{0}; a value of @math{-1} @@ -1083,9 +1018,8 @@ indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} returns @math{-1}. @end deftypefun -@comment termios.h -@comment BSD @deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@standards{BSD, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c There's no guarantee that the two calls are atomic, but since this is @c not an opaque type, callers ought to ensure mutual exclusion to the @@ -1101,9 +1035,8 @@ of @math{-1} indicates an error. If @var{speed} is not a speed, 4.4 BSD. @end deftypefun -@comment termios.h -@comment POSIX.1 @deftp {Data Type} speed_t +@standards{POSIX.1, termios.h} The @code{speed_t} type is an unsigned integer data type used to represent line speeds. @end deftp @@ -1243,9 +1176,8 @@ system you are using supports @code{_POSIX_VDISABLE}. These special characters are active only in canonical input mode. @xref{Canonical or Not}. -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VEOF +@standards{POSIX.1, termios.h} @cindex EOF character This is the subscript for the EOF character in the special control character array. @code{@var{termios}.c_cc[VEOF]} holds the character @@ -1260,9 +1192,8 @@ character itself is discarded. Usually, the EOF character is @kbd{C-d}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VEOL +@standards{POSIX.1, termios.h} @cindex EOL character This is the subscript for the EOL character in the special control character array. @code{@var{termios}.c_cc[VEOL]} holds the character @@ -1280,9 +1211,8 @@ Just set the ICRNL flag. In fact, this is the default state of affairs. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro int VEOL2 +@standards{BSD, termios.h} @cindex EOL2 character This is the subscript for the EOL2 character in the special control character array. @code{@var{termios}.c_cc[VEOL2]} holds the character @@ -1297,9 +1227,8 @@ The EOL2 character is a BSD extension; it exists only on BSD systems and @gnulinuxhurdsystems{}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VERASE +@standards{POSIX.1, termios.h} @cindex ERASE character This is the subscript for the ERASE character in the special control character array. @code{@var{termios}.c_cc[VERASE]} holds the @@ -1316,9 +1245,8 @@ The ERASE character itself is discarded. Usually, the ERASE character is @key{DEL}. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro int VWERASE +@standards{BSD, termios.h} @cindex WERASE character This is the subscript for the WERASE character in the special control character array. @code{@var{termios}.c_cc[VWERASE]} holds the character @@ -1343,9 +1271,8 @@ The WERASE character is usually @kbd{C-w}. This is a BSD extension. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VKILL +@standards{POSIX.1, termios.h} @cindex KILL character This is the subscript for the KILL character in the special control character array. @code{@var{termios}.c_cc[VKILL]} holds the character @@ -1358,9 +1285,8 @@ of input are discarded. The kill character itself is discarded too. The KILL character is usually @kbd{C-u}. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro int VREPRINT +@standards{BSD, termios.h} @cindex REPRINT character This is the subscript for the REPRINT character in the special control character array. @code{@var{termios}.c_cc[VREPRINT]} holds the character @@ -1382,9 +1308,8 @@ These special characters may be active in either canonical or noncanonical input mode, but only when the @code{ISIG} flag is set (@pxref{Local Modes}). -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VINTR +@standards{POSIX.1, termios.h} @cindex INTR character @cindex interrupt character This is the subscript for the INTR character in the special control @@ -1399,9 +1324,8 @@ information about signals. Typically, the INTR character is @kbd{C-c}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VQUIT +@standards{POSIX.1, termios.h} @cindex QUIT character This is the subscript for the QUIT character in the special control character array. @code{@var{termios}.c_cc[VQUIT]} holds the character @@ -1415,9 +1339,8 @@ about signals. Typically, the QUIT character is @kbd{C-\}. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VSUSP +@standards{POSIX.1, termios.h} @cindex SUSP character @cindex suspend character This is the subscript for the SUSP character in the special control @@ -1440,9 +1363,8 @@ mechanism, the program should send a @code{SIGTSTP} signal to the process group of the process, not just to the process itself. @xref{Signaling Another Process}. -@comment termios.h -@comment BSD @deftypevr Macro int VDSUSP +@standards{BSD, termios.h} @cindex DSUSP character @cindex delayed suspend character This is the subscript for the DSUSP character in the special control @@ -1467,9 +1389,8 @@ These special characters may be active in either canonical or noncanonical input mode, but their use is controlled by the flags @code{IXON} and @code{IXOFF} (@pxref{Input Modes}). -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VSTART +@standards{POSIX.1, termios.h} @cindex START character This is the subscript for the START character in the special control character array. @code{@var{termios}.c_cc[VSTART]} holds the @@ -1488,9 +1409,8 @@ able to change this value---the hardware may insist on using @kbd{C-q} regardless of what you specify. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VSTOP +@standards{POSIX.1, termios.h} @cindex STOP character This is the subscript for the STOP character in the special control character array. @code{@var{termios}.c_cc[VSTOP]} holds the character @@ -1510,9 +1430,8 @@ regardless of what you specify. @node Other Special @subsubsection Other Special Characters -@comment termios.h -@comment BSD @deftypevr Macro int VLNEXT +@standards{BSD, termios.h} @cindex LNEXT character This is the subscript for the LNEXT character in the special control character array. @code{@var{termios}.c_cc[VLNEXT]} holds the character @@ -1530,9 +1449,8 @@ The LNEXT character is usually @kbd{C-v}. This character is available on BSD systems and @gnulinuxhurdsystems{}. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro int VDISCARD +@standards{BSD, termios.h} @cindex DISCARD character This is the subscript for the DISCARD character in the special control character array. @code{@var{termios}.c_cc[VDISCARD]} holds the character @@ -1547,9 +1465,8 @@ output buffer. Typing any other character resets the flag. This character is available on BSD systems and @gnulinuxhurdsystems{}. @end deftypevr -@comment termios.h -@comment BSD @deftypevr Macro int VSTATUS +@standards{BSD, termios.h} @cindex STATUS character This is the subscript for the STATUS character in the special control character array. @code{@var{termios}.c_cc[VSTATUS]} holds the character @@ -1587,9 +1504,8 @@ constant that stands for the index of that element. @code{VMIN} and @code{VTIME} are the names for the indices in the array of the MIN and TIME slots. -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VMIN +@standards{POSIX.1, termios.h} @cindex MIN termios slot This is the subscript for the MIN slot in the @code{c_cc} array. Thus, @code{@var{termios}.c_cc[VMIN]} is the value itself. @@ -1599,9 +1515,8 @@ specifies the minimum number of bytes that must be available in the input queue in order for @code{read} to return. @end deftypevr -@comment termios.h -@comment POSIX.1 @deftypevr Macro int VTIME +@standards{POSIX.1, termios.h} @cindex TIME termios slot This is the subscript for the TIME slot in the @code{c_cc} array. Thus, @code{@var{termios}.c_cc[VTIME]} is the value itself. @@ -1668,9 +1583,8 @@ input and the EOF and EOL slots are used only in canonical input, but it isn't very clean. @Theglibc{} allocates separate slots for these uses. -@comment termios.h -@comment BSD @deftypefun void cfmakeraw (struct termios *@var{termios-p}) +@standards{BSD, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c There's no guarantee the changes are atomic, but since this is not an @c opaque type, callers ought to ensure mutual exclusion to the termios @@ -1705,9 +1619,8 @@ kernels, including Linux. The symbols used in this section are declared in @file{sgtty.h}. -@comment termios.h -@comment BSD @deftp {Data Type} {struct sgttyb} +@standards{BSD, termios.h} This structure is an input or output parameter list for @code{gtty} and @code{stty}. @@ -1725,9 +1638,8 @@ Various flags @end table @end deftp -@comment sgtty.h -@comment BSD @deftypefun int gtty (int @var{filedes}, struct sgttyb *@var{attributes}) +@standards{BSD, sgtty.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct ioctl, BSD only. This function gets the attributes of a terminal. @@ -1736,9 +1648,8 @@ This function gets the attributes of a terminal. of the terminal which is open with file descriptor @var{filedes}. @end deftypefun -@comment sgtty.h -@comment BSD @deftypefun int stty (int @var{filedes}, const struct sgttyb *@var{attributes}) +@standards{BSD, sgtty.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct ioctl, BSD only. @@ -1761,9 +1672,8 @@ itself is ignoring or blocking @code{SIGTTOU} signals, in which case the operation is performed and no signal is sent. @xref{Job Control}. @cindex break condition, generating -@comment termios.h -@comment POSIX.1 @deftypefun int tcsendbreak (int @var{filedes}, int @var{duration}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acunsafe{@acucorrupt{/bsd}}} @c On Linux, this calls just one out of two ioctls; on BSD, it's two @c ioctls with a select (for the delay only) in between, the first @@ -1795,9 +1705,8 @@ The @var{filedes} is not associated with a terminal device. @cindex flushing terminal output queue @cindex terminal output queue, flushing -@comment termios.h -@comment POSIX.1 @deftypefun int tcdrain (int @var{filedes}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct ioctl. The @code{tcdrain} function waits until all queued @@ -1831,9 +1740,8 @@ The operation was interrupted by delivery of a signal. @cindex clearing terminal input queue @cindex terminal input queue, clearing -@comment termios.h -@comment POSIX.1 @deftypefun int tcflush (int @var{filedes}, int @var{queue}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct ioctl. The @code{tcflush} function is used to clear the input and/or output @@ -1880,9 +1788,8 @@ from POSIX and we cannot change it. @cindex flow control, terminal @cindex terminal flow control -@comment termios.h -@comment POSIX.1 @deftypefun int tcflow (int @var{filedes}, int @var{action}) +@standards{POSIX.1, termios.h} @safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acsafe{}} @c Direct ioctl on Linux. On BSD, the TCO* actions are a single ioctl, @c whereas the TCI actions first call tcgetattr and then write to the fd @@ -1990,9 +1897,8 @@ This subsection describes functions for allocating a pseudo-terminal, and for making this pseudo-terminal available for actual use. These functions are declared in the header file @file{stdlib.h}. -@comment stdlib.h -@comment GNU @deftypefun int getpt (void) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} @c On BSD, tries to open multiple potential pty names, returning on the @c first success. On Linux, try posix_openpt first, then fallback to @@ -2015,9 +1921,9 @@ There are no free master pseudo-terminals available. This function is a GNU extension. @end deftypefun -@comment stdlib.h -@comment SVID, XPG4.2 @deftypefun int grantpt (int @var{filedes}) +@standards{SVID, stdlib.h} +@standards{XPG4.2, stdlib.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c unix/grantpt:pts_name @acsuheap @acsmem @@ -2078,9 +1984,9 @@ with @var{filedes} could not be accessed. @end deftypefun -@comment stdlib.h -@comment SVID, XPG4.2 @deftypefun int unlockpt (int @var{filedes}) +@standards{SVID, stdlib.h} +@standards{XPG4.2, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} @c unlockpt @ascuheap/bsd @acsmem @acsfd @c /bsd @@ -2108,9 +2014,9 @@ device. @end table @end deftypefun -@comment stdlib.h -@comment SVID, XPG4.2 @deftypefun {char *} ptsname (int @var{filedes}) +@standards{SVID, stdlib.h} +@standards{XPG4.2, stdlib.h} @safety{@prelim{}@mtunsafe{@mtasurace{:ptsname}}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} @c ptsname @mtasurace:ptsname @ascuheap/bsd @acsmem @acsfd @c ptsname_r dup @ascuheap/bsd @acsmem @acsfd @@ -2121,9 +2027,8 @@ file name of the associated slave pseudo-terminal file. This string might be overwritten by subsequent calls to @code{ptsname}. @end deftypefun -@comment stdlib.h -@comment GNU @deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len}) +@standards{GNU, stdlib.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} @c ptsname_r @ascuheap/bsd @acsmem @acsfd @c /hurd @@ -2217,9 +2122,8 @@ close_master: These functions, derived from BSD, are available in the separate @file{libutil} library, and declared in @file{pty.h}. -@comment pty.h -@comment BSD @deftypefun int openpty (int *@var{amaster}, int *@var{aslave}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp}) +@standards{BSD, pty.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c openpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c getpt @acsfd @@ -2264,9 +2168,8 @@ the @code{ttyname} function on the file descriptor returned in device instead. @end deftypefun -@comment pty.h -@comment BSD @deftypefun int forkpty (int *@var{amaster}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp}) +@standards{BSD, pty.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c forkpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c openpty dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem diff --git a/manual/threads.texi b/manual/threads.texi index d7fac825c8..769d974d50 100644 --- a/manual/threads.texi +++ b/manual/threads.texi @@ -20,9 +20,8 @@ The @glibcadj{} implements functions to allow users to create and manage data specific to a thread. Such data may be destroyed at thread exit, if a destructor is provided. The following functions are defined: -@comment pthread.h -@comment POSIX @deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*)) +@standards{POSIX, pthread.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c pthread_key_create ok @c KEY_UNUSED ok @@ -36,9 +35,8 @@ data destructors or even as members of the thread-specific data, since the latter is passed as an argument to the destructor function. @end deftypefun -@comment pthread.h -@comment POSIX @deftypefun int pthread_key_delete (pthread_key_t @var{key}) +@standards{POSIX, pthread.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c pthread_key_delete ok @c This uses atomic compare and exchange to increment the seq number @@ -49,18 +47,16 @@ destructor for the thread-specific data is not called during destruction, nor is it called during thread exit. @end deftypefun -@comment pthread.h -@comment POSIX @deftypefun void *pthread_getspecific (pthread_key_t @var{key}) +@standards{POSIX, pthread.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c pthread_getspecific ok Return the thread-specific data associated with @var{key} in the calling thread. @end deftypefun -@comment pthread.h -@comment POSIX @deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value}) +@standards{POSIX, pthread.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c pthread_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem @c a level2 block may be allocated by a signal handler after @@ -92,9 +88,8 @@ the standard. @Theglibc{} provides non-standard API functions to set and get the default attributes used in the creation of threads in a process. -@comment pthread.h -@comment GNU @deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr}) +@standards{GNU, pthread.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c Takes lock around read from default_pthread_attr. Get the default attribute values and set @var{attr} to match. This @@ -102,9 +97,8 @@ function returns @math{0} on success and a non-zero error code on failure. @end deftypefun -@comment pthread.h -@comment GNU @deftypefun int pthread_setattr_default_np (pthread_attr_t *@var{attr}) +@standards{GNU, pthread.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} @c pthread_setattr_default_np @ascuheap @asulock @aculock @acsmem @c check_sched_policy_attr ok diff --git a/manual/time.texi b/manual/time.texi index dccb979955..33aa221428 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -76,9 +76,8 @@ One way to represent an elapsed time is with a simple arithmetic data type, as with the following function to compute the elapsed time between two calendar times. This function is declared in @file{time.h}. -@comment time.h -@comment ISO @deftypefun double difftime (time_t @var{time1}, time_t @var{time0}) +@standards{ISO, time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{difftime} function returns the number of seconds of elapsed time between calendar time @var{time1} and calendar time @var{time0}, as @@ -96,9 +95,8 @@ you can use them for your own purposes too. They're exactly the same except that one has a resolution in microseconds, and the other, newer one, is in nanoseconds. -@comment sys/time.h -@comment BSD @deftp {Data Type} {struct timeval} +@standards{BSD, sys/time.h} @cindex timeval The @code{struct timeval} structure represents an elapsed time. It is declared in @file{sys/time.h} and has the following members: @@ -115,9 +113,8 @@ million. @end table @end deftp -@comment sys/time.h -@comment POSIX.1 @deftp {Data Type} {struct timespec} +@standards{POSIX.1, sys/time.h} @cindex timespec The @code{struct timespec} structure represents an elapsed time. It is declared in @file{time.h} and has the following members: @@ -229,24 +226,21 @@ track of CPU time. It's common for the internal processor clock to have a resolution somewhere between a hundredth and millionth of a second. -@comment time.h -@comment ISO @deftypevr Macro int CLOCKS_PER_SEC +@standards{ISO, time.h} The value of this macro is the number of clock ticks per second measured by the @code{clock} function. POSIX requires that this value be one million independent of the actual resolution. @end deftypevr -@comment time.h -@comment ISO @deftp {Data Type} clock_t +@standards{ISO, time.h} This is the type of the value returned by the @code{clock} function. Values of type @code{clock_t} are numbers of clock ticks. @end deftp -@comment time.h -@comment ISO @deftypefun clock_t clock (void) +@standards{ISO, time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On Hurd, this calls task_info twice and adds user and system time @c from both basic and thread time info structs. On generic posix, @@ -270,9 +264,8 @@ include the header file @file{sys/times.h} to use this facility. @cindex CPU time @pindex sys/times.h -@comment sys/times.h -@comment POSIX.1 @deftp {Data Type} {struct tms} +@standards{POSIX.1, sys/times.h} The @code{tms} structure is used to return information about process times. It contains at least the following members: @@ -307,16 +300,14 @@ these are the actual amounts of time; not relative to any event. @xref{Creating a Process}. @end deftp -@comment time.h -@comment POSIX.1 @deftypevr Macro int CLK_TCK +@standards{POSIX.1, time.h} This is an obsolete name for the number of clock ticks per second. Use @code{sysconf (_SC_CLK_TCK)} instead. @end deftypevr -@comment sys/times.h -@comment POSIX.1 @deftypefun clock_t times (struct tms *@var{buffer}) +@standards{POSIX.1, sys/times.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On HURD, this calls task_info twice, for basic and thread times info, @c adding user and system times into tms, and then gettimeofday, to @@ -395,9 +386,8 @@ These facilities are declared in the header file @file{time.h}. @pindex time.h @cindex epoch -@comment time.h -@comment ISO @deftp {Data Type} time_t +@standards{ISO, time.h} This is the data type used to represent simple time. Sometimes, it also represents an elapsed time. When interpreted as a calendar time value, it represents the number of seconds elapsed since 00:00:00 on January 1, @@ -419,9 +409,8 @@ The function @code{difftime} tells you the elapsed time between two simple calendar times, which is not always as easy to compute as just subtracting. @xref{Elapsed Time}. -@comment time.h -@comment ISO @deftypefun time_t time (time_t *@var{result}) +@standards{ISO, time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{time} function returns the current calendar time as a value of type @code{time_t}. If the argument @var{result} is not a null pointer, @@ -432,9 +421,9 @@ current calendar time is not available, the value @c The GNU C library implements stime() with a call to settimeofday() on @c Linux. -@comment time.h -@comment SVID, XPG @deftypefun int stime (const time_t *@var{newtime}) +@standards{SVID, time.h} +@standards{XPG, time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On unix, this is implemented in terms of settimeofday. @code{stime} sets the system clock, i.e., it tells the system that the @@ -470,9 +459,8 @@ functions and the associated data types described in this section are declared in @file{sys/time.h}. @pindex sys/time.h -@comment sys/time.h -@comment BSD @deftp {Data Type} {struct timezone} +@standards{BSD, sys/time.h} The @code{struct timezone} structure is used to hold minimal information about the local time zone. It has the following members: @@ -488,9 +476,8 @@ The @code{struct timezone} type is obsolete and should never be used. Instead, use the facilities described in @ref{Time Zone Functions}. @end deftp -@comment sys/time.h -@comment BSD @deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp}) +@standards{BSD, sys/time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On most GNU/Linux systems this is a direct syscall, but the posix/ @c implementation (not used on GNU/Linux or GNU/Hurd) relies on time and @@ -517,9 +504,8 @@ Instead, use the facilities described in @ref{Time Zone Functions}. @end table @end deftypefun -@comment sys/time.h -@comment BSD @deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp}) +@standards{BSD, sys/time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On HURD, it calls host_set_time with a privileged port. On other @c unix systems, it's a syscall. @@ -561,9 +547,8 @@ The operating system does not support setting time zone information, and @end deftypefun @c On Linux, GNU libc implements adjtime() as a call to adjtimex(). -@comment sys/time.h -@comment BSD @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta}) +@standards{BSD, sys/time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On hurd and mach, call host_adjust_time with a privileged port. On @c Linux, it's implemented in terms of adjtimex. On other unixen, it's @@ -603,9 +588,8 @@ and @code{adjtime} functions are derived from BSD. Symbols for the following function are declared in @file{sys/timex.h}. -@comment sys/timex.h -@comment GNU @deftypefun int adjtimex (struct timex *@var{timex}) +@standards{GNU, sys/timex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c It's a syscall, only available on linux. @@ -634,9 +618,8 @@ zone, and it also indicates which time zone that is. The symbols in this section are declared in the header file @file{time.h}. -@comment time.h -@comment ISO @deftp {Data Type} {struct tm} +@standards{ISO, time.h} This is the data type used to represent a broken-down time. The structure contains at least the following members, which can appear in any order. @@ -702,9 +685,8 @@ GNU extension, and is not visible in a strict @w{ISO C} environment. @end deftp -@comment time.h -@comment ISO @deftypefun {struct tm *} localtime (const time_t *@var{time}) +@standards{ISO, time.h} @safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c Calls tz_convert with a static buffer. @c localtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -730,9 +712,8 @@ Using the @code{localtime} function is a big problem in multi-threaded programs. The result is returned in a static buffer and this is used in all threads. POSIX.1c introduced a variant of this function. -@comment time.h -@comment POSIX.1c @deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp}) +@standards{POSIX.1c, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c localtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c tz_convert(use_localtime) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -827,9 +808,8 @@ object the result was written into, i.e., it returns @var{resultp}. @end deftypefun -@comment time.h -@comment ISO @deftypefun {struct tm *} gmtime (const time_t *@var{time}) +@standards{ISO, time.h} @safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c gmtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -843,9 +823,8 @@ As for the @code{localtime} function we have the problem that the result is placed in a static variable. POSIX.1c also provides a replacement for @code{gmtime}. -@comment time.h -@comment POSIX.1c @deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp}) +@standards{POSIX.1c, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c You'd think tz_convert could avoid some safety issues with @c !use_localtime, but no such luck: tzset_internal will always bring @@ -863,9 +842,8 @@ object the result was written into, i.e., it returns @var{resultp}. @end deftypefun -@comment time.h -@comment ISO @deftypefun time_t mktime (struct tm *@var{brokentime}) +@standards{ISO, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c mktime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c passes a static localtime_offset to mktime_internal; it is read @@ -913,9 +891,8 @@ of @var{brokentime}'s initial @code{tm_gmtoff} and @code{tm_zone} members. @xref{Time Zone Functions}. @end deftypefun -@comment time.h -@comment ??? @deftypefun time_t timelocal (struct tm *@var{brokentime}) +@standards{???, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c Alias to mktime. @@ -928,9 +905,8 @@ available. @code{timelocal} is rather rare. @end deftypefun -@comment time.h -@comment ??? @deftypefun time_t timegm (struct tm *@var{brokentime}) +@standards{???, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c timegm @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c gmtime_offset triggers the same caveats as localtime_offset in mktime. @@ -1002,9 +978,8 @@ system clock from the true calendar time. @end table @end deftp -@comment sys/timex.h -@comment GNU @deftypefun int ntp_gettime (struct ntptimeval *@var{tptr}) +@standards{GNU, sys/timex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Wrapper for adjtimex. The @code{ntp_gettime} function sets the structure pointed to by @@ -1121,9 +1096,8 @@ exceeded the threshold. @end table @end deftp -@comment sys/timex.h -@comment GNU @deftypefun int ntp_adjtime (struct timex *@var{tptr}) +@standards{GNU, sys/timex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Alias to adjtimex syscall. The @code{ntp_adjtime} function sets the structure specified by @@ -1177,9 +1151,8 @@ The functions described in this section format calendar time values as strings. These functions are declared in the header file @file{time.h}. @pindex time.h -@comment time.h -@comment ISO @deftypefun {char *} asctime (const struct tm *@var{brokentime}) +@standards{ISO, time.h} @safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}} @c asctime @mtasurace:asctime @mtslocale @c Uses a static buffer. @@ -1207,9 +1180,8 @@ overwritten by subsequent calls to @code{asctime} or @code{ctime}. string.) @end deftypefun -@comment time.h -@comment POSIX.1c @deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) +@standards{POSIX.1c, time.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c asctime_r @mtslocale @c asctime_internal dup @mtslocale @@ -1224,9 +1196,8 @@ it returns @code{NULL}. @end deftypefun -@comment time.h -@comment ISO @deftypefun {char *} ctime (const time_t *@var{time}) +@standards{ISO, time.h} @safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtasurace{:asctime} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c ctime @mtasurace:tmbuf @mtasurace:asctime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c localtime dup @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -1243,9 +1214,8 @@ Calling @code{ctime} also sets the current time zone as if @code{tzset} were called. @xref{Time Zone Functions}. @end deftypefun -@comment time.h -@comment POSIX.1c @deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) +@standards{POSIX.1c, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c ctime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -1264,9 +1234,8 @@ it returns @code{NULL}. @end deftypefun -@comment time.h -@comment ISO @deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime}) +@standards{ISO, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c strftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd @c strftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd @@ -1648,9 +1617,8 @@ members. @xref{Time Zone Functions}. For an example of @code{strftime}, see @ref{Time Functions Example}. @end deftypefun -@comment time.h -@comment ISO/Amend1 @deftypefun size_t wcsftime (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, const struct tm *@var{brokentime}) +@standards{ISO/Amend1, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c wcsftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd @c wcsftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd @@ -1745,9 +1713,8 @@ used in software since it is better known. Its interface and implementation are heavily influenced by the @code{getdate} function, which is defined and implemented in terms of calls to @code{strptime}. -@comment time.h -@comment XPG4 @deftypefun {char *} strptime (const char *@var{s}, const char *@var{fmt}, struct tm *@var{tp}) +@standards{XPG4, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c strptime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c strptime_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -2155,9 +2122,8 @@ in multi-threaded programs or libraries, since it returns a pointer to a static variable, and uses a global variable and global state (an environment variable). -@comment time.h -@comment Unix98 @defvar getdate_err +@standards{Unix98, time.h} This variable of type @code{int} contains the error code of the last unsuccessful call to @code{getdate}. Defined values are: @@ -2184,9 +2150,8 @@ in a @code{time_t} variable. @end table @end defvar -@comment time.h -@comment Unix98 @deftypefun {struct tm *} getdate (const char *@var{string}) +@standards{Unix98, time.h} @safety{@prelim{}@mtunsafe{@mtasurace{:getdate} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c getdate @mtasurace:getdate @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c getdate_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @@ -2298,9 +2263,8 @@ any arbitrary file and chances are high that with some bogus input (such as a binary file) the program will crash. @end deftypefun -@comment time.h -@comment GNU @deftypefun int getdate_r (const char *@var{string}, struct tm *@var{tp}) +@standards{GNU, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c getdate_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c getenv dup @mtsenv @@ -2528,9 +2492,8 @@ community of volunteers and put in the public domain. @node Time Zone Functions @subsection Functions and Variables for Time Zones -@comment time.h -@comment POSIX.1 @deftypevar {char *} tzname [2] +@standards{POSIX.1, time.h} The array @code{tzname} contains two strings, which are the standard names of the pair of time zones (standard and Daylight Saving) that the user has selected. @code{tzname[0]} is the name of @@ -2558,9 +2521,8 @@ lead to trouble. @end deftypevar -@comment time.h -@comment POSIX.1 @deftypefun void tzset (void) +@standards{POSIX.1, time.h} @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c tzset @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd @c libc_lock_lock dup @asulock @aculock @@ -2577,9 +2539,8 @@ The following variables are defined for compatibility with System V Unix. Like @code{tzname}, these variables are set by calling @code{tzset} or the other time conversion functions. -@comment time.h -@comment SVID @deftypevar {long int} timezone +@standards{SVID, time.h} This contains the difference between UTC and the latest local standard time, in seconds west of UTC. For example, in the U.S. Eastern time zone, the value is @code{5*60*60}. Unlike the @code{tm_gmtoff} member @@ -2589,9 +2550,8 @@ to use @code{tm_gmtoff}, since it contains the correct offset even when it is not the latest one. @end deftypevar -@comment time.h -@comment SVID @deftypevar int daylight +@standards{SVID, time.h} This variable has a nonzero value if Daylight Saving Time rules apply. A nonzero value does not necessarily mean that Daylight Saving Time is now in effect; it means only that Daylight Saving Time is sometimes in @@ -2683,9 +2643,8 @@ simpler interface for setting the real-time timer. @pindex unistd.h @pindex sys/time.h -@comment sys/time.h -@comment BSD @deftp {Data Type} {struct itimerval} +@standards{BSD, sys/time.h} This structure is used to specify when a timer should expire. It contains the following members: @table @code @@ -2701,9 +2660,8 @@ the alarm is disabled. The @code{struct timeval} data type is described in @ref{Elapsed Time}. @end deftp -@comment sys/time.h -@comment BSD @deftypefun int setitimer (int @var{which}, const struct itimerval *@var{new}, struct itimerval *@var{old}) +@standards{BSD, sys/time.h} @safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}} @c This function is marked with @mtstimer because the same set of timers @c is shared by all threads of a process, so calling it in one thread @@ -2730,9 +2688,8 @@ The timer period is too large. @end table @end deftypefun -@comment sys/time.h -@comment BSD @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old}) +@standards{BSD, sys/time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getitimer} function stores information about the timer specified by @var{which} in the structure pointed at by @var{old}. @@ -2741,31 +2698,27 @@ The return value and error conditions are the same as for @code{setitimer}. @end deftypefun @vtable @code -@comment sys/time.h -@comment BSD @item ITIMER_REAL +@standards{BSD, sys/time.h} This constant can be used as the @var{which} argument to the @code{setitimer} and @code{getitimer} functions to specify the real-time timer. -@comment sys/time.h -@comment BSD @item ITIMER_VIRTUAL +@standards{BSD, sys/time.h} This constant can be used as the @var{which} argument to the @code{setitimer} and @code{getitimer} functions to specify the virtual timer. -@comment sys/time.h -@comment BSD @item ITIMER_PROF +@standards{BSD, sys/time.h} This constant can be used as the @var{which} argument to the @code{setitimer} and @code{getitimer} functions to specify the profiling timer. @end vtable -@comment unistd.h -@comment POSIX.1 @deftypefun {unsigned int} alarm (unsigned int @var{seconds}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}} @c Wrapper for setitimer. The @code{alarm} function sets the real-time timer to expire in @@ -2824,9 +2777,8 @@ signals, use @code{select} (@pxref{Waiting for I/O}) and don't specify any descriptors to wait for. @c !!! select can get EINTR; using SA_RESTART makes sleep win too. -@comment unistd.h -@comment POSIX.1 @deftypefun {unsigned int} sleep (unsigned int @var{seconds}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtunsafe{@mtascusig{:SIGCHLD/linux}}@asunsafe{}@acunsafe{}} @c On Mach, it uses ports and calls time. On generic posix, it calls @c nanosleep. On Linux, it temporarily blocks SIGCHLD, which is MT- and @@ -2872,9 +2824,8 @@ On @gnusystems{}, it is safe to use @code{sleep} and @code{SIGALRM} in the same program, because @code{sleep} does not work by means of @code{SIGALRM}. -@comment time.h -@comment POSIX.1 @deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining}) +@standards{POSIX.1, time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c On Linux, it's a syscall. On Mach, it calls gettimeofday and uses @c ports. diff --git a/manual/users.texi b/manual/users.texi index 47e28febdc..8690b65633 100644 --- a/manual/users.texi +++ b/manual/users.texi @@ -204,53 +204,46 @@ facilities, you must include the header files @file{sys/types.h} and @pindex unistd.h @pindex sys/types.h -@comment sys/types.h -@comment POSIX.1 @deftp {Data Type} uid_t +@standards{POSIX.1, sys/types.h} This is an integer data type used to represent user IDs. In @theglibc{}, this is an alias for @code{unsigned int}. @end deftp -@comment sys/types.h -@comment POSIX.1 @deftp {Data Type} gid_t +@standards{POSIX.1, sys/types.h} This is an integer data type used to represent group IDs. In @theglibc{}, this is an alias for @code{unsigned int}. @end deftp -@comment unistd.h -@comment POSIX.1 @deftypefun uid_t getuid (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Atomic syscall, except on hurd, where it takes a lock within a hurd @c critical section. The @code{getuid} function returns the real user ID of the process. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun gid_t getgid (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getgid} function returns the real group ID of the process. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun uid_t geteuid (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{geteuid} function returns the effective user ID of the process. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun gid_t getegid (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getegid} function returns the effective group ID of the process. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int getgroups (int @var{count}, gid_t *@var{groups}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getgroups} function is used to inquire about the supplementary group IDs of the process. Up to @var{count} of these group IDs are @@ -295,9 +288,8 @@ include the header files @file{sys/types.h} and @file{unistd.h}. @pindex unistd.h @pindex sys/types.h -@comment unistd.h -@comment POSIX.1 @deftypefun int seteuid (uid_t @var{neweuid}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c seteuid @asulock @aculock @c INLINE_SETXID_SYSCALL @asulock @aculock @@ -350,9 +342,8 @@ Older systems (those without the @code{_POSIX_SAVED_IDS} feature) do not have this function. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int setuid (uid_t @var{newuid}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c setuid @asulock @aculock @c INLINE_SETXID_SYSCALL dup @asulock @aculock @@ -369,9 +360,8 @@ If the process is not privileged, and the system supports the The return values and error conditions are the same as for @code{seteuid}. @end deftypefun -@comment unistd.h -@comment BSD @deftypefun int setreuid (uid_t @var{ruid}, uid_t @var{euid}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c setreuid @asulock @aculock @c INLINE_SETXID_SYSCALL dup @asulock @aculock @@ -407,9 +397,8 @@ the header files @file{sys/types.h} and @file{unistd.h}. @pindex unistd.h @pindex sys/types.h -@comment unistd.h -@comment POSIX.1 @deftypefun int setegid (gid_t @var{newgid}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c setegid @asulock @aculock @c INLINE_SETXID_SYSCALL dup @asulock @aculock @@ -429,9 +418,8 @@ as those for @code{seteuid}. This function is only present if @code{_POSIX_SAVED_IDS} is defined. @end deftypefun -@comment unistd.h -@comment POSIX.1 @deftypefun int setgid (gid_t @var{newgid}) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c setgid @asulock @aculock @c INLINE_SETXID_SYSCALL dup @asulock @aculock @@ -446,9 +434,8 @@ The return values and error conditions for @code{setgid} are the same as those for @code{seteuid}. @end deftypefun -@comment unistd.h -@comment BSD @deftypefun int setregid (gid_t @var{rgid}, gid_t @var{egid}) +@standards{BSD, unistd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c setregid @asulock @aculock @c INLINE_SETXID_SYSCALL dup @asulock @aculock @@ -485,9 +472,8 @@ group IDs. To use @code{setgroups} or @code{initgroups}, your programs should include the header file @file{grp.h}. @pindex grp.h -@comment grp.h -@comment BSD @deftypefun int setgroups (size_t @var{count}, const gid_t *@var{groups}) +@standards{BSD, grp.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c setgroups @asulock @aculock @c INLINE_SETXID_SYSCALL dup @asulock @aculock @@ -505,9 +491,8 @@ The calling process is not privileged. @end table @end deftypefun -@comment grp.h -@comment BSD @deftypefun int initgroups (const char *@var{user}, gid_t @var{group}) +@standards{BSD, grp.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @acsmem{} @acsfd{} @aculock{}}} @c initgroups @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c sysconf(_SC_NGROUPS_MAX) dup @acsfd @@ -556,9 +541,8 @@ not want to change the process's supplementary group IDs, you can use include the header file @file{grp.h}. @pindex grp.h -@comment grp.h -@comment BSD @deftypefun int getgrouplist (const char *@var{user}, gid_t @var{group}, gid_t *@var{groups}, int *@var{ngroups}) +@standards{BSD, grp.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @acsmem{} @acsfd{} @aculock{}}} @c getgrouplist @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c MAX dup ok @@ -879,9 +863,8 @@ The @code{getlogin} function is declared in @file{unistd.h}, while @pindex stdio.h @pindex unistd.h -@comment unistd.h -@comment POSIX.1 @deftypefun {char *} getlogin (void) +@standards{POSIX.1, unistd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:getlogin} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getlogin (linux) @mtasurace:getlogin @mtasurace:utent @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c getlogin_r_loginuid dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @@ -924,9 +907,8 @@ is statically allocated and might be overwritten on subsequent calls to this function or to @code{cuserid}. @end deftypefun -@comment stdio.h -@comment POSIX.1 @deftypefun {char *} cuserid (char *@var{string}) +@standards{POSIX.1, stdio.h} @safety{@prelim{}@mtunsafe{@mtasurace{:cuserid/!string} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c cuserid @mtasurace:cuserid/!string @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c if string is NULL, cuserid will overwrite and return a static buffer @@ -946,9 +928,8 @@ withdrawn in XPG4.2 and has already been removed from newer revisions of POSIX.1. @end deftypefun -@comment stdio.h -@comment POSIX.1 @deftypevr Macro int L_cuserid +@standards{POSIX.1, stdio.h} An integer constant that indicates how long an array you might need to store a user name. @end deftypevr @@ -997,9 +978,8 @@ These functions and the corresponding data structures are declared in the header file @file{utmp.h}. @pindex utmp.h -@comment utmp.h -@comment SVID @deftp {Data Type} {struct exit_status} +@standards{SVID, utmp.h} The @code{exit_status} data structure is used to hold information about the exit status of processes marked as @code{DEAD_PROCESS} in the user accounting database. @@ -1070,55 +1050,45 @@ The following macros are defined for use as values for the integer constants. @vtable @code -@comment utmp.h -@comment SVID @item EMPTY +@standards{SVID, utmp.h} This macro is used to indicate that the entry contains no valid user accounting information. -@comment utmp.h -@comment SVID @item RUN_LVL +@standards{SVID, utmp.h} This macro is used to identify the system's runlevel. -@comment utmp.h -@comment SVID @item BOOT_TIME +@standards{SVID, utmp.h} This macro is used to identify the time of system boot. -@comment utmp.h -@comment SVID @item OLD_TIME +@standards{SVID, utmp.h} This macro is used to identify the time when the system clock changed. -@comment utmp.h -@comment SVID @item NEW_TIME +@standards{SVID, utmp.h} This macro is used to identify the time after the system clock changed. -@comment utmp.h -@comment SVID @item INIT_PROCESS +@standards{SVID, utmp.h} This macro is used to identify a process spawned by the init process. -@comment utmp.h -@comment SVID @item LOGIN_PROCESS +@standards{SVID, utmp.h} This macro is used to identify the session leader of a logged in user. -@comment utmp.h -@comment SVID @item USER_PROCESS +@standards{SVID, utmp.h} This macro is used to identify a user process. -@comment utmp.h -@comment SVID @item DEAD_PROCESS +@standards{SVID, utmp.h} This macro is used to identify a terminated process. -@comment utmp.h -@comment SVID @item ACCOUNTING +@standards{SVID, utmp.h} ??? @end vtable @@ -1131,9 +1101,8 @@ the time associated with the entry. Therefore, for backwards compatibility only, @file{utmp.h} defines @code{ut_time} as an alias for @code{ut_tv.tv_sec}. -@comment utmp.h -@comment SVID @deftypefun void setutent (void) +@standards{SVID, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c Besides the static variables in utmp_file.c, there's the jump_table. @c They're both modified while holding a lock, but other threads may @@ -1158,9 +1127,8 @@ If the database is already open, it resets the input to the beginning of the database. @end deftypefun -@comment utmp.h -@comment SVID @deftypefun {struct utmp *} getutent (void) +@standards{SVID, utmp.h} @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtasurace{:utentbuf} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c The static buffer that holds results is allocated with malloc at @c the first call; the test is not thread-safe, so multiple concurrent @@ -1179,9 +1147,8 @@ function which stores the data in a user-provided buffer. A null pointer is returned in case no further entry is available. @end deftypefun -@comment utmp.h -@comment SVID @deftypefun void endutent (void) +@standards{SVID, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c endutent @mtasurace:utent @asulock @aculock @acsfd @c libc_lock_lock dup @asulock @aculock @@ -1193,9 +1160,8 @@ A null pointer is returned in case no further entry is available. This function closes the user accounting database. @end deftypefun -@comment utmp.h -@comment SVID @deftypefun {struct utmp *} getutid (const struct utmp *@var{id}) +@standards{SVID, utmp.h} @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} @c Same caveats as getutline. @c @@ -1230,9 +1196,8 @@ is necessary to zero out the static data after each call. Otherwise over again. @end deftypefun -@comment utmp.h -@comment SVID @deftypefun {struct utmp *} getutline (const struct utmp *@var{line}) +@standards{SVID, utmp.h} @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c The static buffer that holds results is allocated with malloc at @c the first call; the test is not thread-safe, so multiple concurrent @@ -1260,9 +1225,8 @@ is necessary to zero out the static data after each call. Otherwise over again. @end deftypefun -@comment utmp.h -@comment SVID @deftypefun {struct utmp *} pututline (const struct utmp *@var{utmp}) +@standards{SVID, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c pututline @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd @c libc_lock_lock dup @asulock @aculock @@ -1313,9 +1277,8 @@ return value data in another thread. Therefore @theglibc{} provides as extensions three more functions which return the data in a user-provided buffer. -@comment utmp.h -@comment GNU @deftypefun int getutent_r (struct utmp *@var{buffer}, struct utmp **@var{result}) +@standards{GNU, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c getutent_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd @c libc_lock_lock dup @asulock @aculock @@ -1351,9 +1314,8 @@ execution of @code{getutent_r} the function returns @code{-1}. This function is a GNU extension. @end deftypefun -@comment utmp.h -@comment GNU @deftypefun int getutid_r (const struct utmp *@var{id}, struct utmp *@var{buffer}, struct utmp **@var{result}) +@standards{GNU, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c getutid_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd @c libc_lock_lock dup @asulock @aculock @@ -1382,9 +1344,8 @@ successful the function return @code{-1}. This function is a GNU extension. @end deftypefun -@comment utmp.h -@comment GNU @deftypefun int getutline_r (const struct utmp *@var{line}, struct utmp *@var{buffer}, struct utmp **@var{result}) +@standards{GNU, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} @c getutline_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd @c libc_lock_lock dup @asulock @aculock @@ -1427,9 +1388,8 @@ previous logins (usually in @file{/etc/wtmp} or @file{/var/log/wtmp}). For specifying which database to examine, the following function should be used. -@comment utmp.h -@comment SVID @deftypefun int utmpname (const char *@var{file}) +@standards{SVID, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} @c utmpname @mtasurace:utent @asulock @ascuheap @aculock @acsmem @c libc_lock_lock dup @asulock @aculock @@ -1463,9 +1423,8 @@ database can be successfully opened. Specially for maintaining log-like databases @theglibc{} provides the following function: -@comment utmp.h -@comment SVID @deftypefun void updwtmp (const char *@var{wtmp_file}, const struct utmp *@var{utmp}) +@standards{SVID, utmp.h} @safety{@prelim{}@mtunsafe{@mtascusig{:ALRM} @mtascutimer{}}@asunsafe{}@acunsafe{@acsfd{}}} @c updwtmp @mtascusig:ALRM @mtascutimer @acsfd @c TRANSFORM_UTMP_FILE_NAME dup ok @@ -1538,102 +1497,87 @@ integer constants and are, in @theglibc{}, identical to the definitions in @file{utmp.h}. @vtable @code -@comment utmpx.h -@comment XPG4.2 @item EMPTY +@standards{XPG4.2, utmpx.h} This macro is used to indicate that the entry contains no valid user accounting information. -@comment utmpx.h -@comment XPG4.2 @item RUN_LVL +@standards{XPG4.2, utmpx.h} This macro is used to identify the system's runlevel. -@comment utmpx.h -@comment XPG4.2 @item BOOT_TIME +@standards{XPG4.2, utmpx.h} This macro is used to identify the time of system boot. -@comment utmpx.h -@comment XPG4.2 @item OLD_TIME +@standards{XPG4.2, utmpx.h} This macro is used to identify the time when the system clock changed. -@comment utmpx.h -@comment XPG4.2 @item NEW_TIME +@standards{XPG4.2, utmpx.h} This macro is used to identify the time after the system clock changed. -@comment utmpx.h -@comment XPG4.2 @item INIT_PROCESS +@standards{XPG4.2, utmpx.h} This macro is used to identify a process spawned by the init process. -@comment utmpx.h -@comment XPG4.2 @item LOGIN_PROCESS +@standards{XPG4.2, utmpx.h} This macro is used to identify the session leader of a logged in user. -@comment utmpx.h -@comment XPG4.2 @item USER_PROCESS +@standards{XPG4.2, utmpx.h} This macro is used to identify a user process. -@comment utmpx.h -@comment XPG4.2 @item DEAD_PROCESS +@standards{XPG4.2, utmpx.h} This macro is used to identify a terminated process. @end vtable The size of the @code{ut_line}, @code{ut_id} and @code{ut_user} arrays can be found using the @code{sizeof} operator. -@comment utmpx.h -@comment XPG4.2 @deftypefun void setutxent (void) +@standards{XPG4.2, utmpx.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} This function is similar to @code{setutent}. In @theglibc{} it is simply an alias for @code{setutent}. @end deftypefun -@comment utmpx.h -@comment XPG4.2 @deftypefun {struct utmpx *} getutxent (void) +@standards{XPG4.2, utmpx.h} @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} The @code{getutxent} function is similar to @code{getutent}, but returns a pointer to a @code{struct utmpx} instead of @code{struct utmp}. In @theglibc{} it simply is an alias for @code{getutent}. @end deftypefun -@comment utmpx.h -@comment XPG4.2 @deftypefun void endutxent (void) +@standards{XPG4.2, utmpx.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} This function is similar to @code{endutent}. In @theglibc{} it is simply an alias for @code{endutent}. @end deftypefun -@comment utmpx.h -@comment XPG4.2 @deftypefun {struct utmpx *} getutxid (const struct utmpx *@var{id}) +@standards{XPG4.2, utmpx.h} @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} This function is similar to @code{getutid}, but uses @code{struct utmpx} instead of @code{struct utmp}. In @theglibc{} it is simply an alias for @code{getutid}. @end deftypefun -@comment utmpx.h -@comment XPG4.2 @deftypefun {struct utmpx *} getutxline (const struct utmpx *@var{line}) +@standards{XPG4.2, utmpx.h} @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} This function is similar to @code{getutid}, but uses @code{struct utmpx} instead of @code{struct utmp}. In @theglibc{} it is simply an alias for @code{getutline}. @end deftypefun -@comment utmpx.h -@comment XPG4.2 @deftypefun {struct utmpx *} pututxline (const struct utmpx *@var{utmp}) +@standards{XPG4.2, utmpx.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} The @code{pututxline} function is functionally identical to @code{pututline}, but uses @code{struct utmpx} instead of @code{struct @@ -1641,9 +1585,8 @@ utmp}. In @theglibc{}, @code{pututxline} is simply an alias for @code{pututline}. @end deftypefun -@comment utmpx.h -@comment XPG4.2 @deftypefun int utmpxname (const char *@var{file}) +@standards{XPG4.2, utmpx.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} The @code{utmpxname} function is functionally identical to @code{utmpname}. In @theglibc{}, @code{utmpxname} is simply an @@ -1655,17 +1598,17 @@ You can translate between a traditional @code{struct utmp} and an XPG these functions are merely copies, since the two structures are identical. -@comment utmp.h utmpx.h -@comment GNU @deftypefun int getutmp (const struct utmpx *@var{utmpx}, struct utmp *@var{utmp}) +@standards{GNU, utmp.h} +@standards{GNU, utmpx.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{getutmp} copies the information, insofar as the structures are compatible, from @var{utmpx} to @var{utmp}. @end deftypefun -@comment utmp.h utmpx.h -@comment GNU @deftypefun int getutmpx (const struct utmp *@var{utmp}, struct utmpx *@var{utmpx}) +@standards{GNU, utmp.h} +@standards{GNU, utmpx.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{getutmpx} copies the information, insofar as the structures are compatible, from @var{utmp} to @var{utmpx}. @@ -1683,9 +1626,8 @@ Note that the @code{ut_user} member of @code{struct utmp} is called @code{ut_name} in BSD. Therefore, @code{ut_name} is defined as an alias for @code{ut_user} in @file{utmp.h}. -@comment utmp.h -@comment BSD @deftypefun int login_tty (int @var{filedes}) +@standards{BSD, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:ttyname}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c If this function is canceled, it may have succeeded in redirecting @c only some of the standard streams to the newly opened terminal. @@ -1705,9 +1647,8 @@ This function returns @code{0} on successful completion, and @code{-1} on error. @end deftypefun -@comment utmp.h -@comment BSD @deftypefun void login (const struct utmp *@var{entry}) +@standards{BSD, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsfd{} @acsmem{}}} @c login @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @ascuheap @aculock @acucorrupt @acsfd @acsmem @c getpid dup ok @@ -1738,9 +1679,8 @@ process. The remaining entries are copied from @var{entry}. A copy of the entry is written to the user accounting log file. @end deftypefun -@comment utmp.h -@comment BSD @deftypefun int logout (const char *@var{ut_line}) +@standards{BSD, utmp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} @c logout @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @ascuheap @aculock @acsfd @acsmem @c utmpname dup @mtasurace:utent @asulock @ascuheap @aculock @acsmem @@ -1759,9 +1699,8 @@ The @code{logout} function returns @code{1} if the entry was successfully written to the database, or @code{0} on error. @end deftypefun -@comment utmp.h -@comment BSD @deftypefun void logwtmp (const char *@var{ut_line}, const char *@var{ut_name}, const char *@var{ut_host}) +@standards{BSD, utmp.h} @safety{@prelim{}@mtunsafe{@mtascusig{:ALRM} @mtascutimer{}}@asunsafe{}@acunsafe{@acsfd{}}} @c logwtmp @mtascusig:ALRM @mtascutimer @acsfd @c memset dup ok @@ -1805,9 +1744,8 @@ The functions and data structures for accessing the system user database are declared in the header file @file{pwd.h}. @pindex pwd.h -@comment pwd.h -@comment POSIX.1 @deftp {Data Type} {struct passwd} +@standards{POSIX.1, pwd.h} The @code{passwd} data structure is used to hold information about entries in the system user data base. It has at least the following members: @@ -1848,9 +1786,8 @@ You can search the system user database for information about a specific user using @code{getpwuid} or @code{getpwnam}. These functions are declared in @file{pwd.h}. -@comment pwd.h -@comment POSIX.1 @deftypefun {struct passwd *} getpwuid (uid_t @var{uid}) +@standards{POSIX.1, pwd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:pwuid} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getpwuid @mtasurace:pwuid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -1867,9 +1804,8 @@ A null pointer value indicates there is no user in the data base with user ID @var{uid}. @end deftypefun -@comment pwd.h -@comment POSIX.1c @deftypefun int getpwuid_r (uid_t @var{uid}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) +@standards{POSIX.1c, pwd.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c nscd_getpwuid_r @ascuheap @acsfd @acsmem @@ -2091,9 +2027,8 @@ error code @code{ERANGE} is returned and @var{errno} is set to @end deftypefun -@comment pwd.h -@comment POSIX.1 @deftypefun {struct passwd *} getpwnam (const char *@var{name}) +@standards{POSIX.1, pwd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:pwnam} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getpwnam @mtasurace:pwnam @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -2110,9 +2045,8 @@ This structure may be overwritten on subsequent calls to A null pointer return indicates there is no user named @var{name}. @end deftypefun -@comment pwd.h -@comment POSIX.1c @deftypefun int getpwnam_r (const char *@var{name}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) +@standards{POSIX.1c, pwd.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getpwnam_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c nscd_getpwnam_r @ascuheap @asulock @aculock @acsfd @acsmem @@ -2153,9 +2087,8 @@ declared in @file{pwd.h}. You can use the @code{fgetpwent} function to read user entries from a particular file. -@comment pwd.h -@comment SVID @deftypefun {struct passwd *} fgetpwent (FILE *@var{stream}) +@standards{SVID, pwd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:fpwent}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{}}} @c fgetpwent @mtasurace:fpwent @asucorrupt @asulock @acucorrupt @aculock @c fgetpos dup @asucorrupt @aculock @acucorrupt @@ -2175,9 +2108,8 @@ The stream must correspond to a file in the same format as the standard password database file. @end deftypefun -@comment pwd.h -@comment GNU @deftypefun int fgetpwent_r (FILE *@var{stream}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) +@standards{GNU, pwd.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} @c fgetpwent_r @asucorrupt @acucorrupt @aculock @c flockfile dup @aculock @@ -2205,9 +2137,9 @@ pointer. The way to scan all the entries in the user database is with @code{setpwent}, @code{getpwent}, and @code{endpwent}. -@comment pwd.h -@comment SVID, BSD @deftypefun void setpwent (void) +@standards{SVID, pwd.h} +@standards{BSD, pwd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c setpwent @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock @asulock @aculock @@ -2223,9 +2155,8 @@ This function initializes a stream which @code{getpwent} and @code{getpwent_r} use to read the user database. @end deftypefun -@comment pwd.h -@comment POSIX.1 @deftypefun {struct passwd *} getpwent (void) +@standards{POSIX.1, pwd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtasurace{:pwentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getpwent @mtasurace:pwent @mtasurace:pwentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -2244,9 +2175,8 @@ wish to save the information. A null pointer is returned when no more entries are available. @end deftypefun -@comment pwd.h -@comment GNU @deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) +@standards{GNU, pwd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c The static buffer here is not the result_buf, but rather the @c variables that keep track of what nss backend we've last used, and @@ -2270,9 +2200,9 @@ The return values are the same as for @code{fgetpwent_r}. @end deftypefun -@comment pwd.h -@comment SVID, BSD @deftypefun void endpwent (void) +@standards{SVID, pwd.h} +@standards{BSD, pwd.h} @safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c endpwent @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock @asulock @aculock @@ -2289,9 +2219,8 @@ This function closes the internal stream used by @code{getpwent} or @node Writing a User Entry @subsection Writing a User Entry -@comment pwd.h -@comment SVID @deftypefun int putpwent (const struct passwd *@var{p}, FILE *@var{stream}) +@standards{SVID, pwd.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} @c putpwent @mtslocale @asucorrupt @aculock @acucorrupt @c fprintf dup @mtslocale @asucorrupt @aculock @acucorrupt [no @ascuheap @acsmem] @@ -2336,9 +2265,8 @@ The functions and data structures for accessing the system group database are declared in the header file @file{grp.h}. @pindex grp.h -@comment grp.h -@comment POSIX.1 @deftp {Data Type} {struct group} +@standards{POSIX.1, grp.h} The @code{group} structure is used to hold information about an entry in the system group database. It has at least the following members: @@ -2365,9 +2293,8 @@ You can search the group database for information about a specific group using @code{getgrgid} or @code{getgrnam}. These functions are declared in @file{grp.h}. -@comment grp.h -@comment POSIX.1 @deftypefun {struct group *} getgrgid (gid_t @var{gid}) +@standards{POSIX.1, grp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:grgid} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getgrgid =~ getpwuid dup @mtasurace:grgid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c getgrgid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @@ -2379,9 +2306,8 @@ This structure may be overwritten by subsequent calls to A null pointer indicates there is no group with ID @var{gid}. @end deftypefun -@comment grp.h -@comment POSIX.1c @deftypefun int getgrgid_r (gid_t @var{gid}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result}) +@standards{POSIX.1c, grp.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getgrgid_r =~ getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c nscd_getgrgid_r @ascuheap @acsfd @acsmem @@ -2420,9 +2346,9 @@ error code @code{ERANGE} is returned and @var{errno} is set to @code{ERANGE}. @end deftypefun -@comment grp.h -@comment SVID, BSD @deftypefun {struct group *} getgrnam (const char *@var{name}) +@standards{SVID, grp.h} +@standards{BSD, grp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:grnam} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getgrnam =~ getpwnam dup @mtasurace:grnam @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c getgrnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @@ -2434,9 +2360,8 @@ This structure may be overwritten by subsequent calls to A null pointer indicates there is no group named @var{name}. @end deftypefun -@comment grp.h -@comment POSIX.1c @deftypefun int getgrnam_r (const char *@var{name}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result}) +@standards{POSIX.1c, grp.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getgrnam_r =~ getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c nscd_getgrnam_r @ascuheap @asulock @aculock @acsfd @acsmem @@ -2464,9 +2389,8 @@ declared in @file{grp.h}. You can use the @code{fgetgrent} function to read group entries from a particular file. -@comment grp.h -@comment SVID @deftypefun {struct group *} fgetgrent (FILE *@var{stream}) +@standards{SVID, grp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:fgrent}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{}}} @c fgetgrent @mtasurace:fgrent @asucorrupt @asulock @acucorrupt @aculock @c fgetpos dup @asucorrupt @aculock @acucorrupt @@ -2487,9 +2411,8 @@ The stream must correspond to a file in the same format as the standard group database file. @end deftypefun -@comment grp.h -@comment GNU @deftypefun int fgetgrent_r (FILE *@var{stream}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result}) +@standards{GNU, grp.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} @c fgetgrent_r @asucorrupt @acucorrupt @aculock @c flockfile dup @aculock @@ -2517,9 +2440,9 @@ pointer. The way to scan all the entries in the group database is with @code{setgrent}, @code{getgrent}, and @code{endgrent}. -@comment grp.h -@comment SVID, BSD @deftypefun void setgrent (void) +@standards{SVID, grp.h} +@standards{BSD, grp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c setgrent =~ setpwent dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c ...*lookup_fct = nss_group_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @@ -2527,9 +2450,9 @@ This function initializes a stream for reading from the group data base. You use this stream by calling @code{getgrent} or @code{getgrent_r}. @end deftypefun -@comment grp.h -@comment SVID, BSD @deftypefun {struct group *} getgrent (void) +@standards{SVID, grp.h} +@standards{BSD, grp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtasurace{:grentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getgrent =~ getpwent dup @mtasurace:grent @mtasurace:grentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c *func = getgrent_r dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @@ -2540,9 +2463,8 @@ to @code{getgrent}. You must copy the contents of the structure if you wish to save the information. @end deftypefun -@comment grp.h -@comment GNU @deftypefun int getgrent_r (struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result}) +@standards{GNU, grp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getgrent_r =~ getpwent_r dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem This function is similar to @code{getgrent} in that it returns the next @@ -2555,9 +2477,9 @@ If the function returns zero @var{result} contains a pointer to the data value is non-zero and @var{result} contains a null pointer. @end deftypefun -@comment grp.h -@comment SVID, BSD @deftypefun void endgrent (void) +@standards{SVID, grp.h} +@standards{BSD, grp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c endgrent =~ endpwent dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem This function closes the internal stream used by @code{getgrent} or @@ -2641,9 +2563,8 @@ many entries a two-step process is needed. First a single netgroup is selected and then one can iterate over all entries in this netgroup. These functions are declared in @file{netdb.h}. -@comment netdb.h -@comment BSD @deftypefun int setnetgrent (const char *@var{netgroup}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c setnetgrent @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -2700,9 +2621,8 @@ Some other functions also use the netgroups state. Currently these are the @code{innetgr} function and parts of the implementation of the @code{compat} service part of the NSS implementation. -@comment netdb.h -@comment BSD @deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtasurace{:netgrentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getnetgrent @mtasurace:netgrent @mtasurace:netgrentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c uses unsafely a static buffer allocated within a libc_once call @@ -2721,9 +2641,8 @@ The return value is @code{1} if the next entry was successfully read. A value of @code{0} means no further entries exist or internal errors occurred. @end deftypefun -@comment netdb.h -@comment GNU @deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, size_t @var{buflen}) +@standards{GNU, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c getnetgrent_r @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -2752,9 +2671,8 @@ This function is a GNU extension. The original implementation in the SunOS libc does not provide this function. @end deftypefun -@comment netdb.h -@comment BSD @deftypefun void endnetgrent (void) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netgrent}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c endnetgrent @mtasurace:netgrent @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c libc_lock_lock dup @asulock @aculock @@ -2774,9 +2692,8 @@ It is often not necessary to scan the whole netgroup since often the only interesting question is whether a given entry is part of the selected netgroup. -@comment netdb.h -@comment BSD @deftypefun int innetgr (const char *@var{netgroup}, const char *@var{host}, const char *@var{user}, const char *@var{domain}) +@standards{BSD, netdb.h} @safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} @c This function does not use the static data structure that the @c *netgrent* ones do, but since each nss must maintains internal state |