AuroraMiddleware/glibc
1
0
Fork 0
mirror of https://sourceware.org/git/glibc.git synced 2024-11-21 12:30:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

manual: Replace summary.awk with summary.pl.

Browse Source 
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.
This commit is contained in:
Rical Jasan 2017-06-15 21:12:39 -07:00
parent 27691d5cec
commit d08a7e4cbe
41 changed files with 2611 additions and 4870 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
ChangeLog
View File

@ -1,3 +1,49 @@
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

9
manual/Makefile
View File

@ -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

126
manual/argp.texi
View File

@ -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

697
manual/arith.texi
View File

File diff suppressed because it is too large Load Diff

96
manual/charset.texi
View File

@ -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

651
manual/conf.texi
View File

File diff suppressed because it is too large Load Diff

44
manual/creature.texi
View File

@ -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}.

65
manual/crypt.texi
View File

@ -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

116
manual/ctype.texi
View File

@ -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.

9
manual/debug.texi
View File

@ -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

504
manual/errno.texi
View File

File diff suppressed because it is too large Load Diff

389
manual/filesys.texi
View File

File diff suppressed because it is too large Load Diff

24
manual/getopt.texi
View File

@ -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.

2
manual/header.texi
View File

@ -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

33
manual/job.texi
View File

@ -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

190
manual/lang.texi
View File

@ -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

345
manual/llio.texi
View File

File diff suppressed because it is too large Load Diff

39
manual/locale.texi
View File

@ -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.

1
manual/macros.texi
View File

@ -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.

524
manual/math.texi
View File

File diff suppressed because it is too large Load Diff

156
manual/memory.texi
View File

@ -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

30
manual/message.texi
View File

@ -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

219
manual/pattern.texi
View File

@ -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

16
manual/pipe.texi
View File

@ -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

69
manual/process.texi
View File

@ -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})}.

169
manual/resource.texi
View File

@ -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

45
manual/search.texi
View File

@ -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

33
manual/setjmp.texi
View File

@ -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

257
manual/signal.texi
View File

@ -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]

348
manual/socket.texi
View File

File diff suppressed because it is too large Load Diff

52
manual/startup.texi
View File

@ -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}.

495
manual/stdio.texi
View File

File diff suppressed because it is too large Load Diff

301
manual/string.texi
View File

File diff suppressed because it is too large Load Diff

133
manual/summary.awk
View File

@ -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 }

403
manual/summary.pl Executable file
View File

@ -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;
}

77
manual/sysinfo.texi
View File

@ -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.

15
manual/syslog.texi
View File

@ -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,

303
manual/terminal.texi
View File

@ -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

18
manual/threads.texi
View File

@ -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

151
manual/time.texi
View File

@ -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.

281
manual/users.texi
View File

@ -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