# # Synchronize RHEL 7.1 manual with upstream manual. # # Include updates that don't impact material differences # between the upstream master and 2.17-based RHEL implemenation. # diff -urN glibc-2.17-c758a686/manual/argp.texi glibc-2.17-c758a686/manual/argp.texi --- glibc-2.17-c758a686/manual/argp.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/argp.texi 2014-09-12 16:10:06.043792722 -0400 @@ -36,6 +36,35 @@ @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}) +@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. +@c parser_init +@c calc_sizes ok +@c option_is_end ok +@c malloc @ascuheap @acsmem +@c parser_convert @mtslocale +@c convert_options @mtslocale +@c option_is_end ok +@c option_is_short ok +@c isprint, but locale may change within the loop +@c find_long_option ok +@c group_parse +@c group->parser (from argp->parser) +@c parser_parse_next +@c getopt_long(_only)_r many issues, same as non_r minus @mtasurace +@c parser_parse_arg +@c group_parse dup +@c parser_parse_opt +@c group_parse dup +@c argp_error dup @mtasurace:argpbuf @mtsenv @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock +@c dgettext (bad key error) dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem +@c parser_finalize +@c group_parse +@c fprintf dup @mtslocale @asucorrupt @aculock @acucorrupt [no @ascuheap @acsmem] +@c dgettext dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem +@c arg_state_help +@c free dup @ascuhelp @acsmem The @code{argp_parse} function parses the arguments in @var{argv}, of length @var{argc}, using the argp parser @var{argp}. @xref{Argp Parsers}. Passing a null pointer for @var{argp} is the same as using @@ -660,6 +689,8 @@ @comment argp.h @comment GNU @deftypefun void argp_usage (const struct argp_state *@var{state}) +@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 @var{state} to @code{@var{state}->err_stream} and terminate the program with @code{exit (argp_err_exit_status)}. @xref{Argp Global Variables}. @@ -669,6 +700,13 @@ @comment argp.h @comment GNU @deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{}) +@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, +@c argp_short_program_name is a macro that expands to +@c program_invocation_short_name), releases the buffer, then call +@c argp_state_help with stream and ARGP_HELP_STD_ERR, unlocking the +@c stream at the end. Prints the printf format string @var{fmt} and following args, preceded by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{} --help}} message, and terminates the program with an exit status of @@ -679,6 +717,12 @@ @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{}) +@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 +@c blank, release the buffer, call strerror_r with an automatic buffer, +@c print it out after colon and blank, put[w]c a line break, unlock the +@c stream, then exit unless ARGP_NO_EXIT. Similar to the standard gnu error-reporting function @code{error}, this prints the program name and @samp{:}, the printf format string @var{fmt}, and the appropriate following args. If it is non-zero, the @@ -695,6 +739,142 @@ @comment argp.h @comment GNU @deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags}) +@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 +@c and translation, are the use of a static buffer (uparams, thus +@c @mtasurace:argpbuf) that makes the whole thing thread-unsafe, reading +@c from the environment for ARGP_HELP_FMT, accessing the locale object +@c multiple times. + +@c _help @mtsenv @mtasurace:argpbuf @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock +@c dgettext @ascuintl +@c flockfile @aculock +@c funlockfile @aculock +@c fill_in_uparams @mtsenv @mtasurace:argpbuf @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem +@c argp_failure dup (status = errnum = 0) +@c atoi dup @mtslocale +@c argp_hol @ascuheap @acsmem +@c make_hol @ascuheap @acsmem +@c hol_add_cluster @ascuheap @acsmem +@c hol_append @ascuheap @acsmem +@c hol_set_group ok +@c hol_find_entry ok +@c hol_sort @mtslocale @acucorrupt +@c qsort dup @acucorrupt +@c hol_entry_qcmp @mtslocale +@c hol_entry_cmp @mtslocale +@c group_cmp ok +@c hol_cluster_cmp ok +@c group_cmp ok +@c hol_entry_first_short @mtslocale +@c hol_entry_short_iterate [@mtslocale] +@c until_short ok +@c oshort ok +@c isprint ok +@c odoc ok +@c hol_entry_first_long ok +@c canon_doc_option @mtslocale +@c tolower dup +@c hol_usage @mtslocale @ascuintl @ascuheap @acsmem +@c hol_entry_short_iterate ok +@c add_argless_short_opt ok +@c argp_fmtstream_printf dup +@c hol_entry_short_iterate @mtslocale @ascuintl @ascuheap @acsmem +@c usage_argful_short_opt @mtslocale @ascuintl @ascuheap @acsmem +@c dgettext dup +@c argp_fmtstream_printf dup +@c hol_entry_long_iterate @mtslocale @ascuintl @ascuheap @acsmem +@c usage_long_opt @mtslocale @ascuintl @ascuheap @acsmem +@c dgettext dup +@c argp_fmtstream_printf dup +@c hol_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock +@c hol_entry_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock +@c argp_fmtstream_set_lmargin dup +@c argp_fmtstream_wmargin dup +@c argp_fmtstream_set_wmargin dup +@c comma @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock +@c argp_fmtstream_putc dup +@c hol_cluster_is_child ok +@c argp_fmtstream_wmargin dup +@c print_header dup +@c argp_fmtstream_set_wmargin dup +@c argp_fmtstream_puts dup +@c indent_to dup +@c argp_fmtstream_putc dup +@c arg @mtslocale @ascuheap @acsmem +@c argp_fmtstream_printf dup +@c odoc dup +@c argp_fmtstream_puts dup +@c argp_fmtstream_printf dup +@c print_header @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock +@c dgettext dup +@c filter_doc dup +@c argp_fmtstream_putc dup +@c indent_to dup +@c argp_fmtstream_set_lmargin dup +@c argp_fmtstream_set_wmargin dup +@c argp_fmtstream_puts dup +@c free dup +@c filter_doc dup +@c argp_fmtstream_point dup +@c indent_to @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock +@c argp_fmtstream_point dup +@c argp_fmtstream_putc dup +@c dgettext dup +@c filter_doc dup +@c argp_fmtstream_putc dup +@c argp_fmtstream_puts dup +@c free dup +@c hol_free @ascuheap @acsmem +@c free dup +@c argp_args_levels ok +@c argp_args_usage @mtslocale @ascuintl @ascuheap @asucorrupt @acsmem @acucorrupt @aculock +@c dgettext dup +@c filter_doc ok +@c argp_input ok +@c argp->help_filter +@c space @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock +@c argp_fmtstream_point dup +@c argp_fmtstream_rmargin @mtslocale @asucorrupt @acucorrupt @aculock +@c argp_fmtstream_update dup +@c argp_fmtstream_putc dup +@c argp_fmtstream_write dup +@c free dup +@c argp_doc @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock +@c dgettext @ascuintl +@c strndup @ascuheap @acsmem +@c argp_input dup +@c argp->help_filter +@c argp_fmtstream_putc @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock +@c argp_fmtstream_ensure dup +@c argp_fmtstream_write dup +@c argp_fmtstream_puts dup +@c argp_fmtstream_point @mtslocale @asucorrupt @acucorrupt @aculock +@c argp_fmtstream_update dup +@c argp_fmtstream_lmargin dup +@c free dup +@c argp_make_fmtstream @ascuheap @acsmem +@c argp_fmtstream_free @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock +@c argp_fmtstream_update @mtslocale @asucorrupt @acucorrupt @aculock +@c put[w]c_unlocked dup +@c isblank in loop @mtslocale +@c fxprintf @aculock +@c fxprintf @aculock +@c free dup +@c argp_fmtstream_set_wmargin @mtslocale @asucorrupt @acucorrupt @aculock +@c argp_fmtstream_update dup +@c argp_fmtstream_printf @mtslocale @ascuheap @acsmem +@c argp_fmtstream_ensure dup +@c vsnprintf dup +@c argp_fmtstream_set_lmargin @mtslocale @asucorrupt @acucorrupt @aculock +@c argp_fmtstream_update dup +@c argp_fmtstream_puts @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock +@c argp_fmtstream_write @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock +@c argp_fmtstream_ensure @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock +@c argp_fmtstream_update dup +@c fxprintf @aculock +@c realloc @ascuheap @acsmem Outputs a help message for the argp parser referred to by @var{state}, to @var{stream}. The @var{flags} argument determines what sort of help message is produced. @xref{Argp Help Flags}. @@ -928,6 +1108,8 @@ @comment argp.h @comment GNU @deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name}) +@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 @var{stream}. The type of messages printed will be determined by @var{flags}. diff -urN glibc-2.17-c758a686/manual/arith.texi glibc-2.17-c758a686/manual/arith.texi --- glibc-2.17-c758a686/manual/arith.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/arith.texi 2014-09-12 16:10:06.043792722 -0400 @@ -160,6 +160,8 @@ @comment stdlib.h @comment ISO @deftypefun div_t div (int @var{numerator}, int @var{denominator}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Functions in this section are pure, and thus safe. This function @code{div} computes the quotient and remainder from the division of @var{numerator} by @var{denominator}, returning the result in a structure of type @code{div_t}. @@ -199,6 +201,7 @@ @comment stdlib.h @comment ISO @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{ldiv} function is similar to @code{div}, except that the arguments are of type @code{long int} and the result is returned as a structure of type @code{ldiv_t}. @@ -225,6 +228,7 @@ @comment stdlib.h @comment ISO @deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{lldiv} function is like the @code{div} function, but the arguments are of type @code{long long int} and the result is returned as a structure of type @code{lldiv_t}. @@ -256,6 +260,7 @@ @comment inttypes.h @comment ISO @deftypefun imaxdiv_t imaxdiv (intmax_t @var{numerator}, intmax_t @var{denominator}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{imaxdiv} function is like the @code{div} function, but the arguments are of type @code{intmax_t} and the result is returned as a structure of type @code{imaxdiv_t}. @@ -318,6 +323,7 @@ @comment math.h @comment ISO @deftypefn {Macro} int fpclassify (@emph{float-type} @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is a generic macro which works on all floating-point types and which returns a value of type @code{int}. The possible values are: @@ -354,6 +360,7 @@ @comment math.h @comment ISO @deftypefn {Macro} int isfinite (@emph{float-type} @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if @var{x} is finite: not plus or minus infinity, and not NaN. It is equivalent to @@ -368,6 +375,7 @@ @comment math.h @comment ISO @deftypefn {Macro} int isnormal (@emph{float-type} @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if @var{x} is finite and normalized. It is equivalent to @@ -379,6 +387,7 @@ @comment math.h @comment ISO @deftypefn {Macro} int isnan (@emph{float-type} @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if @var{x} is NaN. It is equivalent to @@ -387,6 +396,15 @@ @end smallexample @end deftypefn +@comment math.h +@comment GNU +@deftypefn {Macro} int issignaling (@emph{float-type} @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This macro returns a nonzero value if @var{x} is a signaling NaN +(sNaN). It is based on draft TS 18661 and currently enabled as a GNU +extension. +@end deftypefn + Another set of floating-point classification functions was provided by BSD. @Theglibc{} also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard @@ -402,6 +420,7 @@ @comment math.h @comment BSD @deftypefunx int isinfl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns @code{-1} if @var{x} represents negative infinity, @code{1} if @var{x} represents positive infinity, and @code{0} otherwise. @end deftypefun @@ -415,6 +434,7 @@ @comment math.h @comment BSD @deftypefunx int isnanl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns a nonzero value if @var{x} is a ``not a number'' value, and zero otherwise. @@ -437,6 +457,7 @@ @comment math.h @comment BSD @deftypefunx int finitel (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns a nonzero value if @var{x} is finite or a ``not a number'' value, and zero otherwise. @end deftypefun @@ -489,7 +510,8 @@ is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in -new programs. +new programs. When this interface is used, exceptions may not be +raised. @noindent The exceptions defined in @w{IEEE 754} are: @@ -705,6 +727,14 @@ @comment fenv.h @comment ISO @deftypefun int feclearexcept (int @var{excepts}) +@safety{@prelim{}@mtsafe{}@assafe{@assposix{}}@acsafe{@acsposix{}}} +@c The other functions in this section that modify FP status register +@c mostly do so with non-atomic load-modify-store sequences, but since +@c the register is thread-specific, this should be fine, and safe for +@c cancellation. As long as the FP environment is restored before the +@c signal handler returns control to the interrupted thread (like any +@c kernel should do), the functions are also safe for use in signal +@c handlers. This function clears all of the supported exception flags indicated by @var{excepts}. @@ -715,6 +745,7 @@ @comment fenv.h @comment ISO @deftypefun int feraiseexcept (int @var{excepts}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function raises the supported exceptions indicated by @var{excepts}. If more than one exception bit in @var{excepts} is set the order in which the exceptions are raised is undefined except that @@ -730,6 +761,7 @@ @comment fenv.h @comment ISO @deftypefun int fetestexcept (int @var{excepts}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Test whether the exception flags indicated by the parameter @var{except} are currently set. If any of them are, a nonzero value is returned which specifies which exceptions are set. Otherwise the result is zero. @@ -766,6 +798,7 @@ @comment fenv.h @comment ISO @deftypefun int fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function stores in the variable pointed to by @var{flagp} an implementation-defined value representing the current setting of the exception flags indicated by @var{excepts}. @@ -777,6 +810,7 @@ @comment fenv.h @comment ISO @deftypefun int fesetexceptflag (const fexcept_t *@var{flagp}, int @var{excepts}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function restores the flags for the exceptions indicated by @var{excepts} to the values stored in the variable pointed to by @var{flagp}. @@ -798,7 +832,8 @@ Many of the math functions are defined only over a subset of the real or complex numbers. Even if they are mathematically defined, their result may be larger or smaller than the range representable by their return -type. These are known as @dfn{domain errors}, @dfn{overflows}, and +type without loss of accuracy. These are known as @dfn{domain errors}, +@dfn{overflows}, and @dfn{underflows}, respectively. Math functions do several things when one of these errors occurs. In this manual we will refer to the complete response as @dfn{signalling} a domain error, overflow, or @@ -808,11 +843,20 @@ exception and returns NaN. It also sets @var{errno} to @code{EDOM}; this is for compatibility with old systems that do not support @w{IEEE 754} exception handling. Likewise, when overflow occurs, math -functions raise the overflow exception and return @math{@infinity{}} or -@math{-@infinity{}} as appropriate. They also set @var{errno} to -@code{ERANGE}. When underflow occurs, the underflow exception is -raised, and zero (appropriately signed) is returned. @var{errno} may be -set to @code{ERANGE}, but this is not guaranteed. +functions raise the overflow exception and, in the default rounding +mode, return @math{@infinity{}} or @math{-@infinity{}} as appropriate +(in other rounding modes, the largest finite value of the appropriate +sign is returned when appropriate for that rounding mode). They also +set @var{errno} to @code{ERANGE} if returning @math{@infinity{}} or +@math{-@infinity{}}; @var{errno} may or may not be set to +@code{ERANGE} when a finite value is returned on overflow. When +underflow occurs, the underflow exception is raised, and zero +(appropriately signed) or a subnormal value, as appropriate for the +mathematical result of the function and the rounding mode, is +returned. @var{errno} may be set to @code{ERANGE}, but this is not +guaranteed; it is intended that @theglibc{} should set it when the +underflow is to an appropriately signed zero, but not necessarily for +other underflows. Some of the math functions are defined mathematically to result in a complex value over parts of their domains. The most familiar example of @@ -932,6 +976,7 @@ @comment fenv.h @comment ISO @deftypefun int fegetround (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns the currently selected rounding mode, represented by one of the values of the defined rounding mode macros. @end deftypefun @@ -942,6 +987,7 @@ @comment fenv.h @comment ISO @deftypefun int fesetround (int @var{round}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Changes the currently selected rounding mode to @var{round}. If @var{round} does not correspond to one of the supported rounding modes nothing is changed. @code{fesetround} returns zero if it changed the @@ -986,6 +1032,7 @@ @comment fenv.h @comment ISO @deftypefun int fegetenv (fenv_t *@var{envp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Store the floating-point environment in the variable pointed to by @var{envp}. @@ -996,6 +1043,7 @@ @comment fenv.h @comment ISO @deftypefun int feholdexcept (fenv_t *@var{envp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Store the current floating-point environment in the object pointed to by @var{envp}. Then clear all exception flags, and set the FPU to trap no exceptions. Not all FPUs support trapping no exceptions; if @@ -1034,6 +1082,7 @@ @comment fenv.h @comment ISO @deftypefun int fesetenv (const fenv_t *@var{envp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Set the floating-point environment to that described by @var{envp}. The function returns zero in case the operation was successful, a @@ -1043,6 +1092,7 @@ @comment fenv.h @comment ISO @deftypefun int feupdateenv (const fenv_t *@var{envp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Like @code{fesetenv}, this function sets the floating-point environment to that described by @var{envp}. However, if any exceptions were flagged in the status word before @code{feupdateenv} was called, they @@ -1063,6 +1113,7 @@ @comment fenv.h @comment GNU @deftypefun int feenableexcept (int @var{excepts}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This functions enables traps for each of the exceptions as indicated by the parameter @var{except}. The individual exceptions are described in @ref{Status bit operations}. Only the specified exceptions are @@ -1075,6 +1126,7 @@ @comment fenv.h @comment GNU @deftypefun int fedisableexcept (int @var{excepts}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This functions disables traps for each of the exceptions as indicated by the parameter @var{except}. The individual exceptions are described in @ref{Status bit operations}. Only the specified exceptions are @@ -1086,7 +1138,8 @@ @comment fenv.h @comment GNU -@deftypefun int fegetexcept (int @var{excepts}) +@deftypefun int fegetexcept (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function returns a bitmask of all currently enabled exceptions. It returns @code{-1} in case of failure. @end deftypefun @@ -1138,6 +1191,7 @@ @comment inttypes.h @comment ISO @deftypefunx intmax_t imaxabs (intmax_t @var{number}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the absolute value of @var{number}. Most computers use a two's complement integer representation, in which @@ -1159,6 +1213,7 @@ @comment math.h @comment ISO @deftypefunx {long double} fabsl (long double @var{number}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns the absolute value of the floating-point number @var{number}. @end deftypefun @@ -1172,6 +1227,7 @@ @comment complex.h @comment ISO @deftypefunx {long double} cabsl (complex long double @var{z}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the absolute value of the complex number @var{z} (@pxref{Complex Numbers}). The absolute value of a complex number is: @@ -1181,7 +1237,7 @@ This function should always be used instead of the direct formula because it takes special care to avoid losing precision. It may also -take advantage of hardware support for this operation. See @code{hypot} +take advantage of hardware support for this operation. See @code{hypot} in @ref{Exponents and Logarithms}. @end deftypefun @@ -1209,12 +1265,13 @@ @comment math.h @comment ISO @deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are used to split the number @var{value} into a normalized fraction and an exponent. If the argument @var{value} is not zero, the return value is @var{value} -times a power of two, and is always in the range 1/2 (inclusive) to 1 -(exclusive). The corresponding exponent is stored in +times a power of two, and its magnitude is always in the range 1/2 +(inclusive) to 1 (exclusive). The corresponding exponent is stored in @code{*@var{exponent}}; the return value multiplied by 2 raised to this exponent equals the original number @var{value}. @@ -1234,6 +1291,7 @@ @comment math.h @comment ISO @deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the result of multiplying the floating-point number @var{value} by 2 raised to the power @var{exponent}. (It can be used to reassemble floating-point numbers that were taken apart @@ -1248,51 +1306,55 @@ @comment math.h @comment BSD -@deftypefun double scalb (double @var{value}, int @var{exponent}) +@deftypefun double scalb (double @var{value}, double @var{exponent}) @comment math.h @comment BSD -@deftypefunx float scalbf (float @var{value}, int @var{exponent}) +@deftypefunx float scalbf (float @var{value}, float @var{exponent}) @comment math.h @comment BSD -@deftypefunx {long double} scalbl (long double @var{value}, int @var{exponent}) +@deftypefunx {long double} scalbl (long double @var{value}, long double @var{exponent}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{scalb} function is the BSD name for @code{ldexp}. @end deftypefun @comment math.h @comment BSD -@deftypefun {long long int} scalbn (double @var{x}, int @var{n}) +@deftypefun double scalbn (double @var{x}, int @var{n}) @comment math.h @comment BSD -@deftypefunx {long long int} scalbnf (float @var{x}, int @var{n}) +@deftypefunx float scalbnf (float @var{x}, int @var{n}) @comment math.h @comment BSD -@deftypefunx {long long int} scalbnl (long double @var{x}, int @var{n}) +@deftypefunx {long double} scalbnl (long double @var{x}, int @var{n}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{scalbn} is identical to @code{scalb}, except that the exponent @var{n} is an @code{int} instead of a floating-point number. @end deftypefun @comment math.h @comment BSD -@deftypefun {long long int} scalbln (double @var{x}, long int @var{n}) +@deftypefun double scalbln (double @var{x}, long int @var{n}) @comment math.h @comment BSD -@deftypefunx {long long int} scalblnf (float @var{x}, long int @var{n}) +@deftypefunx float scalblnf (float @var{x}, long int @var{n}) @comment math.h @comment BSD -@deftypefunx {long long int} scalblnl (long double @var{x}, long int @var{n}) +@deftypefunx {long double} scalblnl (long double @var{x}, long int @var{n}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{scalbln} is identical to @code{scalb}, except that the exponent @var{n} is a @code{long int} instead of a floating-point number. @end deftypefun @comment math.h @comment BSD -@deftypefun {long long int} significand (double @var{x}) +@deftypefun double significand (double @var{x}) @comment math.h @comment BSD -@deftypefunx {long long int} significandf (float @var{x}) +@deftypefunx float significandf (float @var{x}) @comment math.h @comment BSD -@deftypefunx {long long int} significandl (long double @var{x}) +@deftypefunx {long double} significandl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{significand} returns the mantissa of @var{x} scaled to the range @math{[1, 2)}. It is equivalent to @w{@code{scalb (@var{x}, (double) -ilogb (@var{x}))}}. @@ -1307,7 +1369,7 @@ @pindex math.h The functions listed here perform operations such as rounding and -truncation of floating-point values. Some of these functions convert +truncation of floating-point values. Some of these functions convert floating point numbers to integer values. They are all declared in @file{math.h}. @@ -1327,6 +1389,7 @@ @comment math.h @comment ISO @deftypefunx {long double} ceill (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions round @var{x} upwards to the nearest integer, returning that value as a @code{double}. Thus, @code{ceil (1.5)} is @code{2.0}. @@ -1341,6 +1404,7 @@ @comment math.h @comment ISO @deftypefunx {long double} floorl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions round @var{x} downwards to the nearest integer, returning that value as a @code{double}. Thus, @code{floor (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}. @@ -1355,6 +1419,7 @@ @comment math.h @comment ISO @deftypefunx {long double} truncl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{trunc} functions round @var{x} towards zero to the nearest integer (returned in floating-point format). Thus, @code{trunc (1.5)} is @code{1.0} and @code{trunc (-1.5)} is @code{-1.0}. @@ -1369,6 +1434,7 @@ @comment math.h @comment ISO @deftypefunx {long double} rintl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions round @var{x} to an integer value according to the current rounding mode. @xref{Floating Point Parameters}, for information about the various rounding modes. The default @@ -1389,6 +1455,7 @@ @comment math.h @comment ISO @deftypefunx {long double} nearbyintl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the same value as the @code{rint} functions, but do not raise the inexact exception if @var{x} is not an integer. @end deftypefun @@ -1402,6 +1469,7 @@ @comment math.h @comment ISO @deftypefunx {long double} roundl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are similar to @code{rint}, but they round halfway cases away from zero instead of to the nearest integer (or other current rounding mode). @@ -1416,6 +1484,7 @@ @comment math.h @comment ISO @deftypefunx {long int} lrintl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are just like @code{rint}, but they return a @code{long int} instead of a floating-point number. @end deftypefun @@ -1429,6 +1498,7 @@ @comment math.h @comment ISO @deftypefunx {long long int} llrintl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are just like @code{rint}, but they return a @code{long long int} instead of a floating-point number. @end deftypefun @@ -1442,6 +1512,7 @@ @comment math.h @comment ISO @deftypefunx {long int} lroundl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are just like @code{round}, but they return a @code{long int} instead of a floating-point number. @end deftypefun @@ -1455,6 +1526,7 @@ @comment math.h @comment ISO @deftypefunx {long long int} llroundl (long double @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are just like @code{round}, but they return a @code{long long int} instead of a floating-point number. @end deftypefun @@ -1469,6 +1541,7 @@ @comment math.h @comment ISO @deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions break the argument @var{value} into an integer part and a fractional part (between @code{-1} and @code{1}, exclusive). Their sum equals @var{value}. Each of the parts has the same sign as @var{value}, @@ -1495,6 +1568,7 @@ @comment math.h @comment ISO @deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions compute the remainder from the division of @var{numerator} by @var{denominator}. Specifically, the return value is @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n} @@ -1517,6 +1591,7 @@ @comment math.h @comment BSD @deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are like @code{fmod} except that they round the internal quotient @var{n} to the nearest integer instead of towards zero to an integer. For example, @code{drem (6.5, 2.3)} returns @code{-0.4}, @@ -1540,6 +1615,7 @@ @comment math.h @comment BSD @deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is another name for @code{drem}. @end deftypefun @@ -1561,6 +1637,7 @@ @comment math.h @comment ISO @deftypefunx {long double} copysignl (long double @var{x}, long double @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return @var{x} but with the sign of @var{y}. They work even if @var{x} or @var{y} are NaN or zero. Both of these can carry a sign (although not all implementations support it) and this is one of @@ -1576,6 +1653,7 @@ @comment math.h @comment ISO @deftypefun int signbit (@emph{float-type} @var{x}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{signbit} is a generic macro which can work on all floating-point types. It returns a nonzero value if the value of @var{x} has its sign bit set. @@ -1594,6 +1672,7 @@ @comment math.h @comment ISO @deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{nextafter} function returns the next representable neighbor of @var{x} in the direction towards @var{y}. The size of the step between @var{x} and the result depends on the type of the result. If @@ -1617,6 +1696,7 @@ @comment math.h @comment ISO @deftypefunx {long double} nexttowardl (long double @var{x}, long double @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions are identical to the corresponding versions of @code{nextafter} except that their second argument is a @code{long double}. @@ -1632,6 +1712,8 @@ @comment math.h @comment ISO @deftypefunx {long double} nanl (const char *@var{tagp}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c The unsafe-but-ruled-safe locale use comes from strtod. The @code{nan} function returns a representation of NaN, provided that NaN is supported by the target platform. @code{nan ("@var{n-char-sequence}")} is equivalent to @@ -1666,6 +1748,7 @@ @comment math.h @comment ISO @deftypefn Macro int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is greater than @var{y}. It is equivalent to @code{(@var{x}) > (@var{y})}, but no exception is raised if @var{x} or @var{y} are NaN. @@ -1674,6 +1757,7 @@ @comment math.h @comment ISO @deftypefn Macro int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is greater than or equal to @var{y}. It is equivalent to @code{(@var{x}) >= (@var{y})}, but no exception is raised if @var{x} or @var{y} are NaN. @@ -1682,6 +1766,7 @@ @comment math.h @comment ISO @deftypefn Macro int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is less than @var{y}. It is equivalent to @code{(@var{x}) < (@var{y})}, but no exception is raised if @var{x} or @var{y} are NaN. @@ -1690,6 +1775,7 @@ @comment math.h @comment ISO @deftypefn Macro int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is less than or equal to @var{y}. It is equivalent to @code{(@var{x}) <= (@var{y})}, but no exception is raised if @var{x} or @var{y} are NaN. @@ -1698,6 +1784,7 @@ @comment math.h @comment ISO @deftypefn Macro int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether the argument @var{x} is less or greater than @var{y}. It is equivalent to @code{(@var{x}) < (@var{y}) || (@var{x}) > (@var{y})} (although it only evaluates @var{x} and @var{y} @@ -1710,6 +1797,7 @@ @comment math.h @comment ISO @deftypefn Macro int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro determines whether its arguments are unordered. In other words, it is true if @var{x} or @var{y} are NaN, and false otherwise. @end deftypefn @@ -1743,6 +1831,7 @@ @comment math.h @comment ISO @deftypefunx {long double} fminl (long double @var{x}, long double @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fmin} function returns the lesser of the two values @var{x} and @var{y}. It is similar to the expression @smallexample @@ -1763,6 +1852,7 @@ @comment math.h @comment ISO @deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fmax} function returns the greater of the two values @var{x} and @var{y}. @@ -1779,6 +1869,7 @@ @comment math.h @comment ISO @deftypefunx {long double} fdiml (long double @var{x}, long double @var{y}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fdim} function returns the positive difference between @var{x} and @var{y}. The positive difference is @math{@var{x} - @var{y}} if @var{x} is greater than @var{y}, and @math{0} otherwise. @@ -1796,6 +1887,7 @@ @comment ISO @deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z}) @cindex butterfly +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fma} function performs floating-point multiply-add. This is the operation @math{(@var{x} @mul{} @var{y}) + @var{z}}, but the intermediate result is not rounded to the destination type. This can @@ -1925,6 +2017,7 @@ @comment complex.h @comment ISO @deftypefunx {long double} creall (complex long double @var{z}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the real part of the complex number @var{z}. @end deftypefun @@ -1937,6 +2030,7 @@ @comment complex.h @comment ISO @deftypefunx {long double} cimagl (complex long double @var{z}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the imaginary part of the complex number @var{z}. @end deftypefun @@ -1949,6 +2043,7 @@ @comment complex.h @comment ISO @deftypefunx {complex long double} conjl (complex long double @var{z}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the conjugate value of the complex number @var{z}. The conjugate of a complex number has the same real part and a negated imaginary part. In other words, @samp{conj(a + bi) = a + -bi}. @@ -1963,6 +2058,7 @@ @comment complex.h @comment ISO @deftypefunx {long double} cargl (complex long double @var{z}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the argument of the complex number @var{z}. The argument of a complex number is the angle in the complex plane between the positive real axis and a line passing through zero and the @@ -1981,8 +2077,9 @@ @comment complex.h @comment ISO @deftypefunx {complex long double} cprojl (complex long double @var{z}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the projection of the complex value @var{z} onto -the Riemann sphere. Values with a infinite imaginary part are projected +the Riemann sphere. Values with an infinite imaginary part are projected to positive infinity on the real axis, even if the real part is NaN. If the real part is infinite, the result is equivalent to @@ -2026,6 +2123,15 @@ @comment stdlib.h @comment ISO @deftypefun {long int} strtol (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c strtol uses the thread-local pointer to the locale in effect, and +@c strtol_l loads the LC_NUMERIC locale data from it early on and once, +@c but if the locale is the global locale, and another thread calls +@c setlocale in a way that modifies the pointer to the LC_CTYPE locale +@c category, the behavior of e.g. IS*, TOUPPER will vary throughout the +@c execution of the function, because they re-read the locale data from +@c the given locale pointer. We solved this by documenting setlocale as +@c MT-Unsafe. The @code{strtol} (``string-to-long'') function converts the initial part of @var{string} to a signed integer, which is returned as a value of type @code{long int}. @@ -2089,6 +2195,7 @@ @comment wchar.h @comment ISO @deftypefun {long int} wcstol (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstol} function is equivalent to the @code{strtol} function in nearly all aspects but handles wide character strings. @@ -2098,6 +2205,7 @@ @comment stdlib.h @comment ISO @deftypefun {unsigned long int} strtoul (const char *retrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoul} (``string-to-unsigned-long'') function is like @code{strtol} except it converts to an @code{unsigned long int} value. The syntax is the same as described above for @code{strtol}. The value @@ -2116,6 +2224,7 @@ @comment wchar.h @comment ISO @deftypefun {unsigned long int} wcstoul (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoul} function is equivalent to the @code{strtoul} function in nearly all aspects but handles wide character strings. @@ -2125,6 +2234,7 @@ @comment stdlib.h @comment ISO @deftypefun {long long int} strtoll (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoll} function is like @code{strtol} except that it returns a @code{long long int} value, and accepts numbers with a correspondingly larger range. @@ -2141,6 +2251,7 @@ @comment wchar.h @comment ISO @deftypefun {long long int} wcstoll (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoll} function is equivalent to the @code{strtoll} function in nearly all aspects but handles wide character strings. @@ -2150,12 +2261,14 @@ @comment stdlib.h @comment BSD @deftypefun {long long int} strtoq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}. @end deftypefun @comment wchar.h @comment GNU @deftypefun {long long int} wcstoq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoq} function is equivalent to the @code{strtoq} function in nearly all aspects but handles wide character strings. @@ -2165,6 +2278,7 @@ @comment stdlib.h @comment ISO @deftypefun {unsigned long long int} strtoull (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoull} function is related to @code{strtoll} the same way @code{strtoul} is related to @code{strtol}. @@ -2174,6 +2288,7 @@ @comment wchar.h @comment ISO @deftypefun {unsigned long long int} wcstoull (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoull} function is equivalent to the @code{strtoull} function in nearly all aspects but handles wide character strings. @@ -2183,12 +2298,14 @@ @comment stdlib.h @comment BSD @deftypefun {unsigned long long int} strtouq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @code{strtouq} is the BSD name for @code{strtoull}. @end deftypefun @comment wchar.h @comment GNU @deftypefun {unsigned long long int} wcstouq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstouq} function is equivalent to the @code{strtouq} function in nearly all aspects but handles wide character strings. @@ -2198,6 +2315,7 @@ @comment inttypes.h @comment ISO @deftypefun intmax_t strtoimax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoimax} function is like @code{strtol} except that it returns a @code{intmax_t} value, and accepts numbers of a corresponding range. @@ -2214,6 +2332,7 @@ @comment wchar.h @comment ISO @deftypefun intmax_t wcstoimax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoimax} function is equivalent to the @code{strtoimax} function in nearly all aspects but handles wide character strings. @@ -2223,6 +2342,7 @@ @comment inttypes.h @comment ISO @deftypefun uintmax_t strtoumax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{strtoumax} function is related to @code{strtoimax} the same way that @code{strtoul} is related to @code{strtol}. @@ -2233,6 +2353,7 @@ @comment wchar.h @comment ISO @deftypefun uintmax_t wcstoumax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstoumax} function is equivalent to the @code{strtoumax} function in nearly all aspects but handles wide character strings. @@ -2242,6 +2363,7 @@ @comment stdlib.h @comment ISO @deftypefun {long int} atol (const char *@var{string}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is similar to the @code{strtol} function with a @var{base} argument of @code{10}, except that it need not detect overflow errors. The @code{atol} function is provided mostly for compatibility with @@ -2251,6 +2373,7 @@ @comment stdlib.h @comment ISO @deftypefun int atoi (const char *@var{string}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is like @code{atol}, except that it returns an @code{int}. The @code{atoi} function is also considered obsolete; use @code{strtol} instead. @@ -2259,6 +2382,7 @@ @comment stdlib.h @comment ISO @deftypefun {long long int} atoll (const char *@var{string}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is similar to @code{atol}, except it returns a @code{long long int}. @@ -2323,6 +2447,35 @@ @comment stdlib.h @comment ISO @deftypefun double strtod (const char *restrict @var{string}, char **restrict @var{tailptr}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c Besides the unsafe-but-ruled-safe locale uses, this uses a lot of +@c mpn, but it's all safe. +@c +@c round_and_return +@c get_rounding_mode ok +@c mpn_add_1 ok +@c mpn_rshift ok +@c MPN_ZERO ok +@c MPN2FLOAT -> mpn_construct_(float|double|long_double) ok +@c str_to_mpn +@c mpn_mul_1 -> umul_ppmm ok +@c mpn_add_1 ok +@c mpn_lshift_1 -> mpn_lshift ok +@c STRTOF_INTERNAL +@c MPN_VAR ok +@c SET_MANTISSA ok +@c STRNCASECMP ok, wide and narrow +@c round_and_return ok +@c mpn_mul ok +@c mpn_addmul_1 ok +@c ... mpn_sub +@c mpn_lshift ok +@c udiv_qrnnd ok +@c count_leading_zeros ok +@c add_ssaaaa ok +@c sub_ddmmss ok +@c umul_ppmm ok +@c mpn_submul_1 ok The @code{strtod} (``string-to-double'') function converts the initial part of @var{string} to a floating-point number, which is returned as a value of type @code{double}. @@ -2408,6 +2561,7 @@ @comment stdlib.h @comment ISO @deftypefunx {long double} strtold (const char *@var{string}, char **@var{tailptr}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} These functions are analogous to @code{strtod}, but return @code{float} and @code{long double} values respectively. They report errors in the same way as @code{strtod}. @code{strtof} can be substantially faster @@ -2427,6 +2581,7 @@ @comment stdlib.h @comment ISO @deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} The @code{wcstod}, @code{wcstof}, and @code{wcstol} functions are equivalent in nearly all aspect to the @code{strtod}, @code{strtof}, and @code{strtold} functions but it handles wide character string. @@ -2439,6 +2594,7 @@ @comment stdlib.h @comment ISO @deftypefun double atof (const char *@var{string}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is similar to the @code{strtod} function, except that it need not detect overflow and underflow errors. The @code{atof} function is provided mostly for compatibility with existing code; using @@ -2447,7 +2603,8 @@ @Theglibc{} also provides @samp{_l} versions of these functions, which take an additional argument, the locale to use in conversion. -@xref{Parsing of Integers}. + +See also @ref{Parsing of Integers}. @node System V Number Conversion @section Old-fashioned System V number-to-string functions @@ -2465,9 +2622,10 @@ @comment stdlib.h @comment SVID, Unix98 @deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) +@safety{@prelim{}@mtunsafe{@mtasurace{:ecvt}}@asunsafe{}@acsafe{}} The function @code{ecvt} converts the floating-point number @var{value} to a string with at most @var{ndigit} decimal digits. The -returned string contains no decimal point or sign. The first digit of +returned string contains no decimal point or sign. The first digit of the string is non-zero (unless @var{value} is actually zero) and the last digit is rounded to nearest. @code{*@var{decpt}} is set to the index in the string of the first digit after the decimal point. @@ -2490,6 +2648,7 @@ @comment stdlib.h @comment SVID, Unix98 @deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) +@safety{@prelim{}@mtunsafe{@mtasurace{:fcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The function @code{fcvt} is like @code{ecvt}, but @var{ndigit} specifies the number of digits after the decimal point. If @var{ndigit} is less than zero, @var{value} is rounded to the @math{@var{ndigit}+1}'th place to the @@ -2508,6 +2667,9 @@ @comment stdlib.h @comment SVID, Unix98 @deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c gcvt calls sprintf, that ultimately calls vfprintf, which malloc()s +@c args_value if it's too large, but gcvt never exercises this path. @code{gcvt} is functionally equivalent to @samp{sprintf(buf, "%*g", ndigit, value}. It is provided only for compatibility's sake. It returns @var{buf}. @@ -2522,6 +2684,7 @@ @comment stdlib.h @comment GNU @deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) +@safety{@prelim{}@mtunsafe{@mtasurace{:qecvt}}@asunsafe{}@acsafe{}} This function is equivalent to @code{ecvt} except that it takes a @code{long double} for the first parameter and that @var{ndigit} is restricted by the precision of a @code{long double}. @@ -2530,6 +2693,7 @@ @comment stdlib.h @comment GNU @deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) +@safety{@prelim{}@mtunsafe{@mtasurace{:qfcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function is equivalent to @code{fcvt} except that it takes a @code{long double} for the first parameter and that @var{ndigit} is restricted by the precision of a @code{long double}. @@ -2538,6 +2702,7 @@ @comment stdlib.h @comment GNU @deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is equivalent to @code{gcvt} except that it takes a @code{long double} for the first parameter and that @var{ndigit} is restricted by the precision of a @code{long double}. @@ -2558,6 +2723,7 @@ @comment stdlib.h @comment GNU @deftypefun int ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{ecvt_r} function is the same as @code{ecvt}, except that it places its result into the user-specified buffer pointed to by @var{buf}, with length @var{len}. The return value is @code{-1} in @@ -2569,6 +2735,7 @@ @comment stdlib.h @comment SVID, Unix98 @deftypefun int fcvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fcvt_r} function is the same as @code{fcvt}, except that it places its result into the user-specified buffer pointed to by @var{buf}, with length @var{len}. The return value is @code{-1} in @@ -2580,6 +2747,7 @@ @comment stdlib.h @comment GNU @deftypefun int qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{qecvt_r} function is the same as @code{qecvt}, except that it places its result into the user-specified buffer pointed to by @var{buf}, with length @var{len}. The return value is @code{-1} in @@ -2591,6 +2759,7 @@ @comment stdlib.h @comment GNU @deftypefun int qfcvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{qfcvt_r} function is the same as @code{qfcvt}, except that it places its result into the user-specified buffer pointed to by @var{buf}, with length @var{len}. The return value is @code{-1} in diff -urN glibc-2.17-c758a686/manual/charset.texi glibc-2.17-c758a686/manual/charset.texi --- glibc-2.17-c758a686/manual/charset.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/charset.texi 2014-09-12 16:10:06.045792717 -0400 @@ -504,6 +504,14 @@ @comment wchar.h @comment ISO @deftypefun int mbsinit (const mbstate_t *@var{ps}) +@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 +@c race here would be harmless. Other functions that take an optional +@c mbstate_t* argument named ps are marked with @mtasurace:/!ps, +@c to indicate that the function uses a static buffer if ps is NULL. +@c These could also have been marked with @mtsrace:ps, but we'll omit +@c that for brevity, for it's somewhat redundant with the @mtasurace. The @code{mbsinit} function determines whether the state object pointed to by @var{ps} is in the initial state. If @var{ps} is a null pointer or the object is in the initial state the return value is nonzero. Otherwise @@ -559,6 +567,14 @@ @comment wchar.h @comment ISO @deftypefun wint_t btowc (int @var{c}) +@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 +@c __wcsmbs_load_conv to initialize the ctype if it's null. +@c wcsmbs_load_conv takes a non-recursive wrlock before allocating +@c memory for the fcts structure, initializing it, and then storing it +@c in the locale object. The initialization involves dlopening and a +@c lot more. The @code{btowc} function (``byte to wide character'') converts a valid single byte character @var{c} in the initial shift state into the wide character equivalent using the conversion rules from the currently @@ -615,6 +631,7 @@ @comment wchar.h @comment ISO @deftypefun int wctob (wint_t @var{c}) +@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 this character in the initial state is exactly one byte long, the return @@ -634,6 +651,7 @@ @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}) +@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 character'') converts the next multibyte character in the string pointed @@ -728,6 +746,7 @@ @comment wchar.h @comment ISO @deftypefun size_t mbrlen (const char *restrict @var{s}, size_t @var{n}, mbstate_t *@var{ps}) +@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 next valid and complete multibyte character. @@ -786,7 +805,7 @@ This function simply calls @code{mbrlen} for each multibyte character in the string and counts the number of function calls. Please note that we here use @code{MB_LEN_MAX} as the size argument in the @code{mbrlen} -call. This is acceptable since a) this value is larger then the length of +call. This is acceptable since a) this value is larger than the length of the longest multibyte character sequence and b) we know that the string @var{s} ends with a NUL byte, which cannot be part of any other multibyte character sequence but the one representing the NUL wide character. @@ -811,6 +830,50 @@ @comment wchar.h @comment ISO @deftypefun size_t wcrtomb (char *restrict @var{s}, wchar_t @var{wc}, mbstate_t *restrict @var{ps}) +@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 +@c concurrently in other threads, this function behaves safely as long +@c as gconv modules don't bring MT safety issues of their own. +@c Attempting to load gconv modules or to build conversion chains in +@c signal handlers may encounter gconv databases or caches in a +@c partially-updated state, and asynchronous cancellation may leave them +@c in such states, besides leaking the lock that guards them. +@c get_gconv_fcts ok +@c wcsmbs_load_conv ok +@c norm_add_slashes ok +@c wcsmbs_getfct ok +@c gconv_find_transform ok +@c gconv_read_conf (libc_once) +@c gconv_lookup_cache ok +@c find_module_idx ok +@c find_module ok +@c gconv_find_shlib (ok) +@c ->init_fct (assumed ok) +@c gconv_get_builtin_trans ok +@c gconv_release_step ok +@c do_lookup_alias ok +@c find_derivation ok +@c derivation_lookup ok +@c increment_counter ok +@c gconv_find_shlib ok +@c step->init_fct (assumed ok) +@c gen_steps ok +@c gconv_find_shlib ok +@c dlopen (presumed ok) +@c dlsym (presumed ok) +@c step->init_fct (assumed ok) +@c step->end_fct (assumed ok) +@c gconv_get_builtin_trans ok +@c gconv_release_step ok +@c add_derivation ok +@c gconv_close_transform ok +@c gconv_release_step ok +@c step->end_fct (assumed ok) +@c gconv_release_shlib ok +@c dlclose (presumed ok) +@c gconv_release_cache ok +@c ->tomb->__fct (assumed ok) The @code{wcrtomb} function (``wide character restartable to multibyte'') converts a single wide character into a multibyte string corresponding to that wide character. @@ -955,8 +1018,9 @@ @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}) +@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 an NUL-terminated multibyte character +character string'') converts a NUL-terminated multibyte character string at @code{*@var{src}} into an equivalent wide character string, including the NUL wide character at the end. The conversion is started using the state information from the object pointed to by @var{ps} or @@ -1039,6 +1103,7 @@ @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}) +@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 @code{*@var{src}} into an equivalent multibyte character string and @@ -1084,6 +1149,7 @@ @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}) +@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 new. The return value is the same as for @code{mbsrtowcs}. @@ -1136,6 +1202,7 @@ @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}) +@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 @code{wcsrtombs} but, just like @code{mbsnrtowcs}, it takes an extra @@ -1280,6 +1347,7 @@ @comment stdlib.h @comment ISO @deftypefun int mbtowc (wchar_t *restrict @var{result}, const char *restrict @var{string}, size_t @var{size}) +@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 beginning at @var{string} to its corresponding wide character code. It @@ -1314,6 +1382,7 @@ @comment stdlib.h @comment ISO @deftypefun int wctomb (char *@var{string}, wchar_t @var{wchar}) +@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 character sequence, and stores the result in bytes starting at @@ -1353,6 +1422,7 @@ @comment stdlib.h @comment ISO @deftypefun int mblen (const char *@var{string}, size_t @var{size}) +@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 @var{string}, never examining more than @var{size} bytes. (The idea is @@ -1391,6 +1461,9 @@ @comment stdlib.h @comment ISO @deftypefun size_t mbstowcs (wchar_t *@var{wstring}, const char *@var{string}, size_t @var{size}) +@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. The @code{mbstowcs} (``multibyte string to wide character string'') function converts the null-terminated string of multibyte characters @var{string} to an array of wide character codes, storing not more than @@ -1431,6 +1504,7 @@ @comment stdlib.h @comment ISO @deftypefun size_t wcstombs (char *@var{string}, const wchar_t *@var{wstring}, size_t @var{size}) +@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} into a string containing multibyte characters, storing not more than @@ -1618,6 +1692,16 @@ @comment iconv.h @comment XPG2 @deftypefun iconv_t iconv_open (const char *@var{tocode}, const char *@var{fromcode}) +@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 +@c isalnum_l and toupper_l with the C locale. gconv_open may MT-safely +@c tokenize toset, replace unspecified codesets with the current locale +@c (possibly two different accesses), and finally it calls +@c gconv_find_transform and initializes the gconv_t result with all the +@c steps in the conversion sequence, running each one's initializer, +@c destructing and releasing them all if anything fails. + The @code{iconv_open} function has to be used before starting a conversion. The two parameters this function takes determine the source and destination character set for the conversion, and if the @@ -1625,7 +1709,7 @@ function returns a handle. If the wanted conversion is not available, the @code{iconv_open} function -returns @code{(iconv_t) -1}. In this case the global variable +returns @code{(iconv_t) -1}. In this case the global variable @code{errno} can have the following values: @table @code @@ -1682,6 +1766,12 @@ @comment iconv.h @comment XPG2 @deftypefun int iconv_close (iconv_t @var{cd}) +@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. +@c Access to the gconv_t object is not guarded, but calling iconv_close +@c concurrently with any other use is undefined. + The @code{iconv_close} function frees all resources associated with the handle @var{cd}, which must have been returned by a successful call to the @code{iconv_open} function. @@ -1708,6 +1798,10 @@ @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}) +@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 +@c conversion state. @cindex stateful The @code{iconv} function converts the text in the input buffer according to the rules associated with the descriptor @var{cd} and @@ -1744,7 +1838,7 @@ Therefore an @code{iconv} call to reset the state should always be performed if some protocol requires this for the output text. -The conversion stops for one of three reasons. The first is that all +The conversion stops for one of three reasons. The first is that all characters from the input buffer are converted. This actually can mean two things: either all bytes from the input buffer are consumed or there are some bytes at the end of the buffer that possibly can form a @@ -2039,7 +2133,7 @@ Unfortunately, the answer is: there is no general solution. On some systems guessing might help. On those systems most character sets can -convert to and from UTF-8 encoded @w{ISO 10646} or Unicode text. Beside +convert to and from UTF-8 encoded @w{ISO 10646} or Unicode text. Beside this only some very system-specific methods can help. Since the conversion functions come from loadable modules and these modules must be stored somewhere in the filesystem, one @emph{could} try to find them @@ -2239,7 +2333,7 @@ So far this section has described how modules are located and considered to be used. What remains to be described is the interface of the modules -so that one can write new ones. This section describes the interface as +so that one can write new ones. This section describes the interface as it is in use in January 1999. The interface will change a bit in the future but, with luck, only in an upwardly compatible way. @@ -2485,7 +2579,7 @@ same size, the minimum and maximum values are the same. @item __stateful -This element must be initialized to an nonzero value if the source +This element must be initialized to a nonzero value if the source character set is stateful. Otherwise it must be zero. @end table @@ -2824,7 +2918,7 @@ /* @r{Run the conversion loop. @code{status} is set} @r{appropriately afterwards.} */ - /* @r{If this is the last step, leave the loop. There is} + /* @r{If this is the last step, leave the loop. There is} @r{nothing we can do.} */ if (data->__is_last) @{ diff -urN glibc-2.17-c758a686/manual/check-safety.sh glibc-2.17-c758a686/manual/check-safety.sh --- glibc-2.17-c758a686/manual/check-safety.sh 1969-12-31 19:00:00.000000000 -0500 +++ glibc-2.17-c758a686/manual/check-safety.sh 2014-09-12 16:10:06.044792719 -0400 @@ -0,0 +1,119 @@ +#! /bin/sh + +# Copyright 2014 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 +# . + + +# Check that the @safety notes are self-consistent, i.e., that they're +# in proper order (mt then as then ac), that remarks appear within +# corresponding sections (mt within mt, etc), that unsafety always has +# an explicit reason and when there's a reason for unsafety it's not +# safe, and that there aren't duplicates remarks. + + +success=: + +# If no arguments are given, take all *.texi files in the current directory. +test $# != 0 || set *.texi + +# Check that all safety remarks have entries for all of MT, AS and AC, +# in this order, with an optional prelim note before them. +grep -n '^@safety' "$@" | +grep -v ':@safety{\(@prelim{}\)\?@mt\(un\)\?safe{.*}'\ +'@as\(un\)\?safe{.*}@ac\(un\)\?safe{.*}}' && +success=false + +# Check that @mt-started notes appear within @mtsafe or @mtunsafe, +# that @as-started notes appear within @assafe or @asunsafe, and that +# @ac-started notes appear within @acsafe or @acunsafe. Also check +# that @mt, @as and @ac are followed by an s (for safe) or u (for +# unsafe), but let @mt have as, ac or asc before [su], and let @as +# have a c (for cancel) before [su]. Also make sure blanks separate +# each of the annotations. +grep -n '^@safety' "$@" | +grep -v ':@safety{\(@prelim{}\)\?'\ +'@mt\(un\)\?safe{\(@mt\(asc\?\|ac\)\?[su][^ ]*}\)\?'\ +'\( @mt\(asc\?\|ac\)\?[su][^ ]*}\)*}'\ +'@as\(un\)\?safe{\(@asc\?[su][^ ]*}\)\?'\ +'\( @asc\?[su][^ ]*}\)*}'\ +'@ac\(un\)\?safe{\(@ac[su][^ ]*}\)\?'\ +'\( @ac[su][^ ]*}\)*}}' && +success=false + +# Make sure safety lines marked as @mtsafe do not contain any +# MT-Unsafe remark; that would be @mtu, but there could be as, ac or +# asc between mt and u. +grep -n '^@safety.*@mtsafe' "$@" | +grep '@mt\(asc\?\|ac\)?u' "$@" && +success=false + +# Make sure @mtunsafe lines contain at least one @mtu remark (with +# optional as, ac or asc between mt and u). +grep -n '^@safety.*@mtunsafe' "$@" | +grep -v '@mtunsafe{.*@mt\(asc\?\|ac\)\?u' && +success=false + +# Make sure safety lines marked as @assafe do not contain any AS-Unsafe +# remark, which could be @asu or @mtasu note (with an optional c +# between as and u in both cases). +grep -n '^@safety.*@assafe' "$@" | +grep '@\(mt\)\?asc\?u' && +success=false + +# Make sure @asunsafe lines contain at least one @asu remark (which +# could be @ascu, or @mtasu or even @mtascu). +grep -n '^@safety.*@asunsafe' "$@" | +grep -v '@mtasc\?u.*@asunsafe\|@asunsafe{.*@asc\?u' && +success=false + +# Make sure safety lines marked as @acsafe do not contain any +# AC-Unsafe remark, which could be @acu, @ascu or even @mtacu or +# @mtascu. +grep -n '^@safety.*@acsafe' "$@" | +grep '@\(mt\)\?as\?cu' && +success=false + +# Make sure @acunsafe lines contain at least one @acu remark (possibly +# implied by @ascu, @mtacu or @mtascu). +grep -n '^@safety.*@acunsafe' "$@" | +grep -v '@\(mtas\?\|as\)cu.*@acunsafe\|@acunsafe{.*@acu' && +success=false + +# Make sure there aren't duplicate remarks in the same safety note. +grep -n '^@safety' "$@" | +grep '[^:]\(@\(mt\|a[sc]\)[^ {]*{[^ ]*}\).*[^:]\1' && +success=false + +# Check that comments containing safety remarks do not contain {}s, +# that all @mt remarks appear before @as remarks, that in turn appear +# before @ac remarks, all properly blank-separated, and that an +# optional comment about exclusions is between []s at the end of the +# line. +grep -n '^@c \+[^@ ]\+\( dup\)\?'\ +'\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" | +grep -v ':@c *[^@{}]*\( @mt[^ {}]*\)*'\ +'\( @as[^ {}]*\)*\( @ac[^ {}]*\)*\( \[.*\]\)\?$' && +success=false + +# Check that comments containing safety remarks do not contain +# duplicate remarks. +grep -n '^@c \+[^@ ]\+\( dup\)\?'\ +'\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" | +grep '[^:]\(@\(mt\|a[sc]\)[^ ]*\) \(.*[^:]\)\?\1\($\| \)' && +success=false + +$success diff -urN glibc-2.17-c758a686/manual/conf.texi glibc-2.17-c758a686/manual/conf.texi --- glibc-2.17-c758a686/manual/conf.texi 2014-09-12 16:08:17.965070383 -0400 +++ glibc-2.17-c758a686/manual/conf.texi 2014-09-12 16:10:06.047792712 -0400 @@ -114,7 +114,7 @@ @comment limits.h @comment POSIX.1 -@deftypevr Macro int SSIZE_MAX +@deftypevr Macro ssize_t SSIZE_MAX The largest value that can fit in an object of type @code{ssize_t}. Effectively, this is the limit on the number of bytes that can be read or written in a single operation. @@ -288,6 +288,17 @@ @comment unistd.h @comment POSIX.1 @deftypefun {long int} sysconf (int @var{parameter}) +@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c Some parts of the implementation open /proc and /sys files and dirs +@c to collect system details, using fd and stream I/O depending on the +@c case. _SC_TZNAME_MAX calls __tzname_max, that (while holding a lock) +@c calls tzset_internal, that calls getenv if it's called the first +@c time; there are free and strdup calls in there too. The returned max +@c value may change over time for TZNAME_MAX, depending on selected +@c timezones; NPROCS, NPROCS_CONF, PHYS_PAGES, AVPHYS_PAGES, +@c NGROUPS_MAX, SIGQUEUE_MAX, depending on variable values read from +@c /proc at each call, and from rlimit-obtained values CHILD_MAX, +@c OPEN_MAX, ARG_MAX, SIGQUEUE_MAX. This function is used to inquire about runtime system parameters. The @var{parameter} argument should be one of the @samp{_SC_} symbols listed below. @@ -1121,7 +1132,7 @@ have on @emph{any} POSIX system. @xref{File Minimums}. @cindex limits, link count of files -@comment limits.h +@comment limits.h (optional) @comment POSIX.1 @deftypevr Macro int LINK_MAX The uniform system limit (if any) for the number of names for a given @@ -1348,6 +1359,11 @@ @comment unistd.h @comment POSIX.1 @deftypefun {long int} pathconf (const char *@var{filename}, int @var{parameter}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} +@c When __statfs_link_max finds an ext* filesystem, it may read +@c /proc/mounts or similar as a mntent stream. +@c __statfs_chown_restricted may read from +@c /proc/sys/fs/xfs/restrict_chown as a file descriptor. This function is used to inquire about the limits that apply to the file named @var{filename}. @@ -1375,6 +1391,8 @@ @comment unistd.h @comment POSIX.1 @deftypefun {long int} fpathconf (int @var{filedes}, int @var{parameter}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} +@c Same caveats as pathconf. This is just like @code{pathconf} except that an open file descriptor is used to specify the file for which information is requested, instead of a file name. @@ -1624,6 +1642,7 @@ @comment unistd.h @comment POSIX.2 @deftypefun size_t confstr (int @var{parameter}, char *@var{buf}, size_t @var{len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function reads the value of a string-valued system parameter, storing the string into @var{len} bytes of memory space starting at @var{buf}. The @var{parameter} argument should be one of the diff -urN glibc-2.17-c758a686/manual/crypt.texi glibc-2.17-c758a686/manual/crypt.texi --- glibc-2.17-c758a686/manual/crypt.texi 2014-09-12 16:08:18.169069859 -0400 +++ glibc-2.17-c758a686/manual/crypt.texi 2014-09-12 16:10:06.042792724 -0400 @@ -30,15 +30,15 @@ and the other based on the Data Encryption Standard (DES) that is compatible with Unix systems. -@cindex AUTH_DES +@vindex AUTH_DES @cindex FIPS 140-2 It also provides support for Secure RPC, and some library functions that -can be used to perform normal DES encryption. The use of DES when -using @code{AUTH_DES} in Secure RPC for authentication as provided by -@theglibc{} is not FIPS 140-2 compliant nor is any other use of DES -within @theglibc{}. It is recommended that Secure RPC should not be used -for systems that need to be FIPS 140-2 compliant since all forms of -supported authentication use normal DES. +can be used to perform normal DES encryption. The @code{AUTH_DES} +authentication flavor in Secure RPC, as provided by @theglibc{}, +uses DES and does not comply with FIPS 140-2 nor does any other use of DES +within @theglibc{}. It is recommended that Secure RPC should not be used +for systems that need to comply with FIPS 140-2 since all flavors of +encrypted authentication use normal DES. @menu * Legal Problems:: This software can get you locked up, or worse. @@ -99,6 +99,13 @@ @comment unistd.h @comment BSD @deftypefun {char *} getpass (const char *@var{prompt}) +@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 +@c mode in a thread-unsafe way, write out the prompt, read the password, +@c then restore the terminal mode. It has a cleanup to close the stream +@c in case of (synchronous) cancellation, but not to restore the +@c terminal mode. @code{getpass} outputs @var{prompt}, then reads a string in from the terminal without echoing it. It tries to connect to the real terminal, @@ -134,6 +141,13 @@ @comment crypt.h @comment BSD, SVID @deftypefun {char *} crypt (const char *@var{key}, const char *@var{salt}) +@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 +@c set of problems for AS- and AC-Safety. The FIPS mode checker and the +@c NSS implementations of may leak file descriptors if canceled. The +@c The MD5, SHA256 and SHA512 implementations will malloc on long keys, +@c and NSS relies on dlopening, which brings about another can of worms. The @code{crypt} function takes a password, @var{key}, as a string, and a @var{salt} character array which is described below, and returns a @@ -195,6 +209,9 @@ @comment crypt.h @comment GNU @deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data}) +@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. The @code{crypt_r} function does the same thing as @code{crypt}, but takes an extra parameter which includes space for its result (among @@ -241,6 +258,11 @@ @comment crypt.h @comment BSD, SVID @deftypefun void setkey (const char *@var{key}) +@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 +@c path; cancelling the initialization will leave the lock held, it +@c would otherwise repeat the initialization on the next call. The @code{setkey} function sets an internal data structure to be an expanded form of @var{key}. @var{key} is specified as an array of 64 @@ -252,6 +274,8 @@ @comment crypt.h @comment BSD, SVID @deftypefun void encrypt (char *@var{block}, int @var{edflag}) +@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} +@c Same issues as setkey. The @code{encrypt} function encrypts @var{block} if @var{edflag} is 0, otherwise it decrypts @var{block}, using a key @@ -265,9 +289,11 @@ @comment crypt.h @comment GNU @deftypefun void setkey_r (const char *@var{key}, {struct crypt_data *} @var{data}) +@c @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} @comment crypt.h @comment GNU @deftypefunx void encrypt_r (char *@var{block}, int @var{edflag}, {struct crypt_data *} @var{data}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}} These are reentrant versions of @code{setkey} and @code{encrypt}. The only difference is the extra parameter, which stores the expanded @@ -282,6 +308,7 @@ @comment rpc/des_crypt.h @comment SUNRPC @deftypefun int ecb_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{ecb_crypt} encrypts or decrypts one or more blocks using DES. Each block is encrypted independently. @@ -356,6 +383,7 @@ @comment rpc/des_crypt.h @comment SUNRPC @deftypefun int DES_FAILED (int @var{err}) +@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 @@ -363,6 +391,7 @@ @comment rpc/des_crypt.h @comment SUNRPC @deftypefun int cbc_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode}, char *@var{ivec}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{cbc_crypt} encrypts or decrypts one or more blocks using DES in Cipher Block Chaining mode. @@ -389,6 +418,7 @@ @comment rpc/des_crypt.h @comment SUNRPC @deftypefun void des_setparity (char *@var{key}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{des_setparity} changes the 64-bit @var{key}, stored packed in 8-bit bytes, to have odd parity by altering the low bits of diff -urN glibc-2.17-c758a686/manual/ctype.texi glibc-2.17-c758a686/manual/ctype.texi --- glibc-2.17-c758a686/manual/ctype.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/ctype.texi 2014-09-12 16:10:06.042792724 -0400 @@ -66,6 +66,16 @@ @comment ctype.h @comment ISO @deftypefun int islower (int @var{c}) +@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 +@c thread-local memory the (indirect) pointer to the ctype array, which +@c may involve one word access to the global locale object, if that's +@c the active locale for the thread, and the array, being part of the +@c locale data, is undeletable, so there's no thread-safety issue. We +@c might want to mark these with @mtslocale to flag to callers that +@c changing locales might affect them, even if not these simpler +@c functions. Returns true if @var{c} is a lower-case letter. The letter need not be from the Latin alphabet, any alphabet representable is valid. @end deftypefun @@ -74,6 +84,7 @@ @comment ctype.h @comment ISO @deftypefun int isupper (int @var{c}) +@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 @@ -82,6 +93,7 @@ @comment ctype.h @comment ISO @deftypefun int isalpha (int @var{c}) +@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 @code{isalpha} is also true. @@ -97,6 +109,7 @@ @comment ctype.h @comment ISO @deftypefun int isdigit (int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}). @end deftypefun @@ -104,6 +117,7 @@ @comment ctype.h @comment ISO @deftypefun int isalnum (int @var{c}) +@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 true of a character, then @code{isalnum} is also true. @@ -113,6 +127,7 @@ @comment ctype.h @comment ISO @deftypefun int isxdigit (int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns true if @var{c} is a hexadecimal digit. Hexadecimal digits include the normal decimal digits @samp{0} through @samp{9} and the letters @samp{A} through @samp{F} and @@ -123,6 +138,7 @@ @comment ctype.h @comment ISO @deftypefun int ispunct (int @var{c}) +@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 character. @@ -132,6 +148,7 @@ @comment ctype.h @comment ISO @deftypefun int isspace (int @var{c}) +@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 whitespace characters: @@ -161,6 +178,7 @@ @comment ctype.h @comment ISO @deftypefun int isblank (int @var{c}) +@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 @@ -169,6 +187,7 @@ @comment ctype.h @comment ISO @deftypefun int isgraph (int @var{c}) +@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 considered graphic. @@ -178,6 +197,7 @@ @comment ctype.h @comment ISO @deftypefun int isprint (int @var{c}) +@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 @@ -186,6 +206,7 @@ @comment ctype.h @comment ISO @deftypefun int iscntrl (int @var{c}) +@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 @@ -194,6 +215,7 @@ @comment ctype.h @comment SVID, BSD @deftypefun int isascii (int @var{c}) +@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 and is also an SVID extension. @@ -227,6 +249,10 @@ @comment ctype.h @comment ISO @deftypefun int tolower (int @var{c}) +@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 +@c thus safety guarantees are the same. If @var{c} is an upper-case letter, @code{tolower} returns the corresponding lower-case letter. If @var{c} is not an upper-case letter, @var{c} is returned unchanged. @@ -235,6 +261,7 @@ @comment ctype.h @comment ISO @deftypefun int toupper (int @var{c}) +@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 @@ -242,6 +269,7 @@ @comment ctype.h @comment SVID, BSD @deftypefun int toascii (int @var{c}) +@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. @@ -250,6 +278,7 @@ @comment ctype.h @comment SVID @deftypefun int _tolower (int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is identical to @code{tolower}, and is provided for compatibility with the SVID. @xref{SVID}.@refill @end deftypefun @@ -257,6 +286,7 @@ @comment ctype.h @comment SVID @deftypefun int _toupper (int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is identical to @code{toupper}, and is provided for compatibility with the SVID. @end deftypefun @@ -303,6 +333,18 @@ @comment wctype.h @comment ISO @deftypefun wctype_t wctype (const char *@var{property}) +@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 +@c should the global locale object change while active, the compiler can +@c and does combine them all into a single dereference that resolves +@c once to the LCTYPE locale object used throughout the function, so it +@c is safe in (optimized) practice, if not in theory, even when the +@c locale changes. Ideally we'd explicitly save the resolved +@c locale_data object to make it visibly safe instead of safe only under +@c compiler optimizations, but given the decision that setlocale is +@c MT-Unsafe, all this would afford us would be the ability to not mark +@c this function with @mtslocale. The @code{wctype} returns a value representing a class of wide characters which is identified by the string @var{property}. Beside some standard properties each locale can define its own ones. In case @@ -331,6 +373,8 @@ @comment wctype.h @comment ISO @deftypefun int iswctype (wint_t @var{wc}, wctype_t @var{desc}) +@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 class specified by @var{desc}. @var{desc} must previously be returned by a successful call to @code{wctype}. @@ -350,6 +394,16 @@ @comment wctype.h @comment ISO @deftypefun int iswalnum (wint_t @var{wc}) +@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 +@c wctype is equally safe when optimized, unsafe with changing locales +@c if not optimized (thus @mtslocale). Since it's not a macro, we +@c always optimize, and the locale can't change in any MT-Safe way, it's +@c fine. The test whether wc is ASCII to use the non-wide is* +@c macro/function doesn't bring any other safety issues: the test does +@c not depend on the locale, and each path after the decision resolves +@c the locale object only once. This function returns a nonzero value if @var{wc} is an alphanumeric character (a letter or number); in other words, if either @code{iswalpha} or @code{iswdigit} is true of a character, then @code{iswalnum} is also @@ -370,6 +424,7 @@ @comment wctype.h @comment ISO @deftypefun int iswalpha (wint_t @var{wc}) +@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 @code{iswalpha} is also true. @@ -394,6 +449,7 @@ @comment wctype.h @comment ISO @deftypefun int iswcntrl (wint_t @var{wc}) +@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). @@ -412,6 +468,7 @@ @comment wctype.h @comment ISO @deftypefun int iswdigit (wint_t @var{wc}) +@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 @emph{decimal} digits, but for all kinds of digits. A consequence is @@ -442,6 +499,7 @@ @comment wctype.h @comment ISO @deftypefun int iswgraph (wint_t @var{wc}) +@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 considered graphic. @@ -461,6 +519,7 @@ @comment ctype.h @comment ISO @deftypefun int iswlower (wint_t @var{wc}) +@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. @@ -479,6 +538,7 @@ @comment wctype.h @comment ISO @deftypefun int iswprint (wint_t @var{wc}) +@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. @@ -497,6 +557,7 @@ @comment wctype.h @comment ISO @deftypefun int iswpunct (wint_t @var{wc}) +@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 character. @@ -516,6 +577,7 @@ @comment wctype.h @comment ISO @deftypefun int iswspace (wint_t @var{wc}) +@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 whitespace characters: @@ -555,6 +617,7 @@ @comment wctype.h @comment ISO @deftypefun int iswupper (wint_t @var{wc}) +@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. @@ -573,6 +636,7 @@ @comment wctype.h @comment ISO @deftypefun int iswxdigit (wint_t @var{wc}) +@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 @samp{9} and the letters @samp{A} through @samp{F} and @@ -597,6 +661,7 @@ @comment wctype.h @comment ISO @deftypefun int iswblank (wint_t @var{wc}) +@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}. It is declared in @file{wchar.h}. @@ -691,6 +756,8 @@ @comment wctype.h @comment ISO @deftypefun wctrans_t wctrans (const char *@var{property}) +@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 mapping is defined in the current locale selected for the @code{LC_CTYPE} category. If the returned value is non-zero, you can use @@ -713,6 +780,8 @@ @comment wctype.h @comment ISO @deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Same caveats as iswctype. @code{towctrans} maps the input character @var{wc} according to the rules of the mapping for which @var{desc} is a descriptor, and returns the value it finds. @var{desc} must be @@ -730,6 +799,9 @@ @comment wctype.h @comment ISO @deftypefun wint_t towlower (wint_t @var{wc}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c Same caveats as iswalnum, just using a wctrans rather than a wctype +@c table. If @var{wc} is an upper-case letter, @code{towlower} returns the corresponding lower-case letter. If @var{wc} is not an upper-case letter, @var{wc} is returned unchanged. @@ -749,6 +821,7 @@ @comment wctype.h @comment ISO @deftypefun wint_t towupper (wint_t @var{wc}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} If @var{wc} is a lower-case letter, @code{towupper} returns the corresponding upper-case letter. Otherwise @var{wc} is returned unchanged. diff -urN glibc-2.17-c758a686/manual/debug.texi glibc-2.17-c758a686/manual/debug.texi --- glibc-2.17-c758a686/manual/debug.texi 2014-09-12 16:08:17.824070745 -0400 +++ glibc-2.17-c758a686/manual/debug.texi 2014-09-12 16:10:06.045792717 -0400 @@ -1,5 +1,5 @@ @node Debugging Support -@c @node Debugging Support, Internal Probes, Cryptographic Functions, Top +@c @node Debugging Support, POSIX Threads, Cryptographic Functions, Top @c %MENU% Functions to help debugging applications @chapter Debugging support @@ -36,6 +36,16 @@ @comment execinfo.h @comment GNU @deftypefun int backtrace (void **@var{buffer}, int @var{size}) +@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 +@c correctly, so it's AS-Unsafe to begin with. However, most (all?) +@c arches defer to libgcc_s's _Unwind_* implementation, dlopening +@c libgcc_s.so to that end except in a static version of libc. +@c libgcc_s's implementation may in turn defer to libunwind. We can't +@c assume those implementations are AS- or AC-safe, but even if we +@c could, our own initialization path isn't, and libgcc's implementation +@c calls malloc and performs internal locking, so... The @code{backtrace} function obtains a backtrace for the current thread, as a list of pointers, and places the information into @var{buffer}. The argument @var{size} should be the number of @@ -56,6 +66,17 @@ @comment execinfo.h @comment GNU @deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size}) +@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 +@c pointers to the strings into the array entries in the buffer. +@c _dl_addr takes the recursive dl_load_lock then calls +@c _dl_find_dso_for_object and determine_info. +@c _dl_find_dso_for_object calls _dl-addr_inside_object. +@c All of them are safe as long as the lock is held. +@c @asucorrupt? It doesn't look like the dynamic loader's data +@c structures could be in an inconsistent state that would cause +@c malfunction here. The @code{backtrace_symbols} function translates the information obtained from the @code{backtrace} function into an array of strings. The argument @var{buffer} should be a pointer to an array of addresses @@ -88,6 +109,11 @@ @comment execinfo.h @comment GNU @deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd}) +@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 +@c are converted to hex in auto buffers, so the only potential issue +@c here is leaking the dl lock in case of cancellation. The @code{backtrace_symbols_fd} function performs the same translation as the function @code{backtrace_symbols} function. Instead of returning the strings to the caller, it writes the strings to the file descriptor diff -urN glibc-2.17-c758a686/manual/errno.texi glibc-2.17-c758a686/manual/errno.texi --- glibc-2.17-c758a686/manual/errno.texi 2014-09-12 16:08:17.752070930 -0400 +++ glibc-2.17-c758a686/manual/errno.texi 2014-09-12 16:10:06.045792717 -0400 @@ -1293,6 +1293,9 @@ @comment string.h @comment ISO @deftypefun {char *} strerror (int @var{errnum}) +@safety{@prelim{}@mtunsafe{@mtasurace{:strerror}}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{}}} +@c Calls strerror_r with a static buffer allocated with malloc on the +@c first use. The @code{strerror} function maps the error code (@pxref{Checking for Errors}) specified by the @var{errnum} argument to a descriptive error message string. The return value is a pointer to this string. @@ -1310,10 +1313,11 @@ @comment string.h @comment GNU @deftypefun {char *} strerror_r (int @var{errnum}, char *@var{buf}, size_t @var{n}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuintl{}}@acunsafe{}} The @code{strerror_r} function works like @code{strerror} but instead of returning the error message in a statically allocated buffer shared by all threads in the process, it returns a private copy for the -thread. This might be either some permanent global data or a message +thread. This might be either some permanent global data or a message string in the user supplied buffer starting at @var{buf} with the length of @var{n} bytes. @@ -1331,6 +1335,10 @@ @comment stdio.h @comment ISO @deftypefun void perror (const char *@var{message}) +@safety{@prelim{}@mtsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} +@c Besides strerror_r's and some of fprintf's issues, if stderr is not +@c oriented yet, create a new stream with a dup of stderr's fd and write +@c to that instead of stderr, to avoid orienting it. This function prints an error message to the stream @code{stderr}; see @ref{Standard Streams}. The orientation of @code{stderr} is not changed. @@ -1442,6 +1450,13 @@ @comment error.h @comment GNU @deftypefun void error (int @var{status}, int @var{errnum}, const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acsafe{}} +@c Cancellation is disabled throughout the execution. It flushes stdout +@c and then holds a lock on stderr while printing the program name and +@c then running error_tail. The non-wide case just runs vfprintf; the +@c wide case converts the message to an alloca/malloc-allocated buffer +@c with mbsrtowcs, then prints it with vfwprintf. Afterwards, +@c print_errno_message calls strerror_r and fxprintf. The @code{error} function can be used to report general problems during program execution. The @var{format} argument is a format string just like those given to the @code{printf} family of functions. The @@ -1477,6 +1492,15 @@ @comment error.h @comment GNU @deftypefun void error_at_line (int @var{status}, int @var{errnum}, const char *@var{fname}, unsigned int @var{lineno}, const char *@var{format}, @dots{}) +@safety{@prelim{}@mtunsafe{@mtasurace{:error_at_line/error_one_per_line} @mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acunsafe{@acucorrupt{/error_one_per_line}}} +@c The error_one_per_line variable is accessed (without any form of +@c synchronization, but since it's an int used once, it should be safe +@c enough) and, if this mode is enabled, static variables used to hold +@c the last printed file name and line number are accessed and modified +@c without synchronization; the update is not atomic and it occurs +@c before disabling cancellation, so it can be interrupted after only +@c one of the two variables is modified. After that, it's very much +@c like error. The @code{error_at_line} function is very similar to the @code{error} function. The only difference are the additional parameters @var{fname} @@ -1508,7 +1532,7 @@ @comment error.h @comment GNU -@deftypevar {void (*) error_print_progname } (void) +@deftypevar {void (*error_print_progname)} (void) If the @code{error_print_progname} variable is defined to a non-zero value the function pointed to is called by @code{error} or @code{error_at_line}. It is expected to print the program name or do @@ -1582,6 +1606,8 @@ @comment err.h @comment BSD @deftypefun void warn (const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Just calls vwarn with the va_list. The @code{warn} function is roughly equivalent to a call like @smallexample error (0, errno, format, @r{the parameters}) @@ -1594,14 +1620,21 @@ @comment err.h @comment BSD @deftypefun void vwarn (const char *@var{format}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c While holding stderr's recursive lock, it prints the programname, the +@c given message, and the error string with fw?printf's %m. When the +@c stream is wide, convert_and_print converts the format string to an +@c alloca/malloc-created buffer using mbsrtowcs and then calls fwprintf. The @code{vwarn} function is just like @code{warn} except that the parameters for the handling of the format string @var{format} are passed -in as an value of type @code{va_list}. +in as a value of type @code{va_list}. @end deftypefun @comment err.h @comment BSD @deftypefun void warnx (const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as warn, but without the strerror translation issues. The @code{warnx} function is roughly equivalent to a call like @smallexample error (0, 0, format, @r{the parameters}) @@ -1615,14 +1648,18 @@ @comment err.h @comment BSD @deftypefun void vwarnx (const char *@var{format}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as vwarn, but without the strerror translation issues. The @code{vwarnx} function is just like @code{warnx} except that the parameters for the handling of the format string @var{format} are passed -in as an value of type @code{va_list}. +in as a value of type @code{va_list}. @end deftypefun @comment err.h @comment BSD @deftypefun void err (int @var{status}, const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as warn followed by exit. The @code{err} function is roughly equivalent to a call like @smallexample error (status, errno, format, @r{the parameters}) @@ -1635,14 +1672,18 @@ @comment err.h @comment BSD @deftypefun void verr (int @var{status}, const char *@var{format}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as vwarn followed by exit. The @code{verr} function is just like @code{err} except that the parameters for the handling of the format string @var{format} are passed -in as an value of type @code{va_list}. +in as a value of type @code{va_list}. @end deftypefun @comment err.h @comment BSD @deftypefun void errx (int @var{status}, const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as warnx followed by exit. The @code{errx} function is roughly equivalent to a call like @smallexample error (status, 0, format, @r{the parameters}) @@ -1657,7 +1698,9 @@ @comment err.h @comment BSD @deftypefun void verrx (int @var{status}, const char *@var{format}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as vwarnx followed by exit. The @code{verrx} function is just like @code{errx} except that the parameters for the handling of the format string @var{format} are passed -in as an value of type @code{va_list}. +in as a value of type @code{va_list}. @end deftypefun diff -urN glibc-2.17-c758a686/manual/examples/add.c glibc-2.17-c758a686/manual/examples/add.c --- glibc-2.17-c758a686/manual/examples/add.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/add.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Example of a Variadic Function - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/argp-ex1.c glibc-2.17-c758a686/manual/examples/argp-ex1.c --- glibc-2.17-c758a686/manual/examples/argp-ex1.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/argp-ex1.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Argp example #1 -- a minimal program using argp - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/argp-ex2.c glibc-2.17-c758a686/manual/examples/argp-ex2.c --- glibc-2.17-c758a686/manual/examples/argp-ex2.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/argp-ex2.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Argp example #2 -- a pretty minimal program using argp - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/argp-ex3.c glibc-2.17-c758a686/manual/examples/argp-ex3.c --- glibc-2.17-c758a686/manual/examples/argp-ex3.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/argp-ex3.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Argp example #3 -- a program with options and arguments using argp - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/argp-ex4.c glibc-2.17-c758a686/manual/examples/argp-ex4.c --- glibc-2.17-c758a686/manual/examples/argp-ex4.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/argp-ex4.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Argp example #4 -- a program with somewhat more complicated options - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/atexit.c glibc-2.17-c758a686/manual/examples/atexit.c --- glibc-2.17-c758a686/manual/examples/atexit.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/atexit.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Cleanups on Exit - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/db.c glibc-2.17-c758a686/manual/examples/db.c --- glibc-2.17-c758a686/manual/examples/db.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/db.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* User and Group Database Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/dir2.c glibc-2.17-c758a686/manual/examples/dir2.c --- glibc-2.17-c758a686/manual/examples/dir2.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/dir2.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Simple Program to List a Directory, Mark II - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/dir.c glibc-2.17-c758a686/manual/examples/dir.c --- glibc-2.17-c758a686/manual/examples/dir.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/dir.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Simple Program to List a Directory - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/execinfo.c glibc-2.17-c758a686/manual/examples/execinfo.c --- glibc-2.17-c758a686/manual/examples/execinfo.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/execinfo.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Obtain a backtrace and print it. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/filecli.c glibc-2.17-c758a686/manual/examples/filecli.c --- glibc-2.17-c758a686/manual/examples/filecli.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/filecli.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Example of Reading Datagrams - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/filesrv.c glibc-2.17-c758a686/manual/examples/filesrv.c --- glibc-2.17-c758a686/manual/examples/filesrv.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/filesrv.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Datagram Socket Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/fmtmsgexpl.c glibc-2.17-c758a686/manual/examples/fmtmsgexpl.c --- glibc-2.17-c758a686/manual/examples/fmtmsgexpl.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/fmtmsgexpl.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* How to use fmtmsg and addseverity. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/genpass.c glibc-2.17-c758a686/manual/examples/genpass.c --- glibc-2.17-c758a686/manual/examples/genpass.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/genpass.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Encrypting Passwords - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/inetcli.c glibc-2.17-c758a686/manual/examples/inetcli.c --- glibc-2.17-c758a686/manual/examples/inetcli.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/inetcli.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Byte Stream Socket Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/inetsrv.c glibc-2.17-c758a686/manual/examples/inetsrv.c --- glibc-2.17-c758a686/manual/examples/inetsrv.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/inetsrv.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Byte Stream Connection Server Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/isockad.c glibc-2.17-c758a686/manual/examples/isockad.c --- glibc-2.17-c758a686/manual/examples/isockad.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/isockad.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Internet Socket Example using sockaddr_in. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/longopt.c glibc-2.17-c758a686/manual/examples/longopt.c --- glibc-2.17-c758a686/manual/examples/longopt.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/longopt.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Example of Parsing Long Options with getopt_long. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/memopen.c glibc-2.17-c758a686/manual/examples/memopen.c --- glibc-2.17-c758a686/manual/examples/memopen.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/memopen.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* String Streams - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/memstrm.c glibc-2.17-c758a686/manual/examples/memstrm.c --- glibc-2.17-c758a686/manual/examples/memstrm.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/memstrm.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* open_memstream example. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/mkfsock.c glibc-2.17-c758a686/manual/examples/mkfsock.c --- glibc-2.17-c758a686/manual/examples/mkfsock.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/mkfsock.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Example of Local-Namespace Sockets - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License @@ -45,13 +45,12 @@ /* The size of the address is the offset of the start of the filename, - plus its length, - plus one for the terminating null byte. + plus its length (not including the terminating null byte). Alternatively you can just do: size = SUN_LEN (&name); */ size = (offsetof (struct sockaddr_un, sun_path) - + strlen (name.sun_path) + 1); + + strlen (name.sun_path)); if (bind (sock, (struct sockaddr *) &name, size) < 0) { diff -urN glibc-2.17-c758a686/manual/examples/mkisock.c glibc-2.17-c758a686/manual/examples/mkisock.c --- glibc-2.17-c758a686/manual/examples/mkisock.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/mkisock.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Internet Socket Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/mygetpass.c glibc-2.17-c758a686/manual/examples/mygetpass.c --- glibc-2.17-c758a686/manual/examples/mygetpass.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/mygetpass.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Reading Passwords - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/pipe.c glibc-2.17-c758a686/manual/examples/pipe.c --- glibc-2.17-c758a686/manual/examples/pipe.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/pipe.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Creating a Pipe - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/popen.c glibc-2.17-c758a686/manual/examples/popen.c --- glibc-2.17-c758a686/manual/examples/popen.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/popen.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Pipe to a Subprocess - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/rprintf.c glibc-2.17-c758a686/manual/examples/rprintf.c --- glibc-2.17-c758a686/manual/examples/rprintf.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/rprintf.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Printf Extension Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/search.c glibc-2.17-c758a686/manual/examples/search.c --- glibc-2.17-c758a686/manual/examples/search.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/search.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Searching and Sorting Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/select.c glibc-2.17-c758a686/manual/examples/select.c --- glibc-2.17-c758a686/manual/examples/select.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/select.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Waiting for Input or Output - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/setjmp.c glibc-2.17-c758a686/manual/examples/setjmp.c --- glibc-2.17-c758a686/manual/examples/setjmp.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/setjmp.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Introduction to Non-Local Exits - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/sigh1.c glibc-2.17-c758a686/manual/examples/sigh1.c --- glibc-2.17-c758a686/manual/examples/sigh1.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/sigh1.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Signal Handlers that Return - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/sigusr.c glibc-2.17-c758a686/manual/examples/sigusr.c --- glibc-2.17-c758a686/manual/examples/sigusr.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/sigusr.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Using kill for Communication - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/stpcpy.c glibc-2.17-c758a686/manual/examples/stpcpy.c --- glibc-2.17-c758a686/manual/examples/stpcpy.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/stpcpy.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* stpcpy example. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/strdupa.c glibc-2.17-c758a686/manual/examples/strdupa.c --- glibc-2.17-c758a686/manual/examples/strdupa.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/strdupa.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* strdupa example. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/strftim.c glibc-2.17-c758a686/manual/examples/strftim.c --- glibc-2.17-c758a686/manual/examples/strftim.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/strftim.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Time Functions Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/strncat.c glibc-2.17-c758a686/manual/examples/strncat.c --- glibc-2.17-c758a686/manual/examples/strncat.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/strncat.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* strncat example. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/subopt.c glibc-2.17-c758a686/manual/examples/subopt.c --- glibc-2.17-c758a686/manual/examples/subopt.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/subopt.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Parsing of Suboptions Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/swapcontext.c glibc-2.17-c758a686/manual/examples/swapcontext.c --- glibc-2.17-c758a686/manual/examples/swapcontext.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/swapcontext.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Complete Context Control - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/termios.c glibc-2.17-c758a686/manual/examples/termios.c --- glibc-2.17-c758a686/manual/examples/termios.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/termios.c 2014-09-12 16:10:06.046792714 -0400 @@ -1,5 +1,5 @@ /* Noncanonical Mode Example - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/testopt.c glibc-2.17-c758a686/manual/examples/testopt.c --- glibc-2.17-c758a686/manual/examples/testopt.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/testopt.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Example of Parsing Arguments with getopt. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/testpass.c glibc-2.17-c758a686/manual/examples/testpass.c --- glibc-2.17-c758a686/manual/examples/testpass.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/testpass.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* Verify a password. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/examples/timeval_subtract.c glibc-2.17-c758a686/manual/examples/timeval_subtract.c --- glibc-2.17-c758a686/manual/examples/timeval_subtract.c 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/examples/timeval_subtract.c 2014-09-12 16:10:06.047792712 -0400 @@ -1,5 +1,5 @@ /* struct timeval subtraction. - Copyright (C) 1991-2012 Free Software Foundation, Inc. + Copyright (C) 1991-2014 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff -urN glibc-2.17-c758a686/manual/filesys.texi glibc-2.17-c758a686/manual/filesys.texi --- glibc-2.17-c758a686/manual/filesys.texi 2014-09-12 16:08:17.966070381 -0400 +++ glibc-2.17-c758a686/manual/filesys.texi 2014-09-12 16:10:06.044792719 -0400 @@ -58,6 +58,25 @@ @comment unistd.h @comment POSIX.1 @deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c If buffer is NULL, this function calls malloc and realloc, and, in +@c case of error, free. Linux offers a getcwd syscall that we use on +@c GNU/Linux systems, but it may fail if the pathname is too long. As a +@c fallback, and on other systems, the generic implementation opens each +@c parent directory with opendir, which allocates memory for the +@c directory stream with malloc. If a fstatat64 syscall is not +@c available, very deep directory trees may also have to malloc to build +@c longer sequences of ../../../... than those supported by a global +@c const read-only string. + +@c linux/__getcwd +@c posix/__getcwd +@c malloc/realloc/free if buffer is NULL, or if dir is too deep +@c lstat64 -> see its own entry +@c fstatat64 +@c direct syscall if possible, alloca+snprintf+*stat64 otherwise +@c openat64_not_cancel_3, close_not_cancel_no_status +@c __fdopendir, __opendir, __readdir, rewinddir The @code{getcwd} function returns an absolute file name representing the current working directory, storing it in the character array @var{buffer} that you provide. The @var{size} argument is how you tell @@ -116,6 +135,9 @@ @comment unistd.h @comment BSD @deftypefn {Deprecated Function} {char *} getwd (char *@var{buffer}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{} @acsfd{}}} +@c Besides the getcwd safety issues, it calls strerror_r on error, which +@c brings in all of the i18n issues. This is similar to @code{getcwd}, but has no way to specify the size of the buffer. @Theglibc{} provides @code{getwd} only for backwards compatibility with BSD. @@ -130,6 +152,9 @@ @comment unistd.h @comment GNU @deftypefun {char *} get_current_dir_name (void) +@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c Besides getcwd, which this function calls as a fallback, it calls +@c getenv, with the potential thread-safety issues that brings about. @vindex PWD This @code{get_current_dir_name} function is basically equivalent to @w{@code{getcwd (NULL, 0)}}. The only difference is that the value of @@ -145,6 +170,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int chdir (const char *@var{filename}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is used to set the process's working directory to @var{filename}. @@ -158,6 +184,7 @@ @comment unistd.h @comment XPG @deftypefun int fchdir (int @var{filedes}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is used to set the process's working directory to directory associated with the file descriptor @var{filedes}. @@ -294,12 +321,14 @@ @comment dirent.h @comment BSD @deftypefun int IFTODT (mode_t @var{mode}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This returns the @code{d_type} value corresponding to @var{mode}. @end deftypefun @comment dirent.h @comment BSD @deftypefun mode_t DTTOIF (int @var{dtype}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This returns the @code{st_mode} value corresponding to @var{dtype}. @end deftypefun @end table @@ -342,6 +371,9 @@ @comment dirent.h @comment POSIX.1 @deftypefun {DIR *} opendir (const char *@var{dirname}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c Besides the safe syscall, we have to allocate the DIR object with +@c __alloc_dir, that calls malloc. The @code{opendir} function opens and returns a directory stream for reading the directory whose file name is @var{dirname}. The stream has type @code{DIR *}. @@ -381,6 +413,8 @@ @comment dirent.h @comment GNU @deftypefun {DIR *} fdopendir (int @var{fd}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c The DIR object is allocated with __alloc_dir, that calls malloc. The @code{fdopendir} function works just like @code{opendir} but instead of taking a file name and opening a file descriptor for the directory the caller is required to provide a file descriptor. This @@ -425,6 +459,7 @@ @comment dirent.h @comment GNU @deftypefun int dirfd (DIR *@var{dirstream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{dirfd} returns the file descriptor associated with the directory stream @var{dirstream}. This descriptor can be used until the directory is closed with @code{closedir}. If the directory stream @@ -443,6 +478,12 @@ @comment dirent.h @comment POSIX.1 @deftypefun {struct dirent *} readdir (DIR *@var{dirstream}) +@safety{@prelim{}@mtunsafe{@mtasurace{:dirstream}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c This function holds dirstream's non-recursive lock, which brings +@c about the usual issues with locks and async signals and cancellation, +@c but the lock taking is not enough to make the returned value safe to +@c use, since it points to a stream's internal buffer that can be +@c overwritten by subsequent calls or even released by closedir. This function reads the next entry from the directory. It normally returns a pointer to a structure containing information about the file. This structure is associated with the @var{dirstream} handle @@ -478,6 +519,7 @@ @comment dirent.h @comment GNU @deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} This function is a version of @code{readdir} which performs internal locking. Like @code{readdir} it returns the next entry from the directory. To prevent conflicts between simultaneously running @@ -549,6 +591,7 @@ @comment dirent.h @comment LFS @deftypefun {struct dirent64 *} readdir64 (DIR *@var{dirstream}) +@safety{@prelim{}@mtunsafe{@mtasurace{:dirstream}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} The @code{readdir64} function is just like the @code{readdir} function except that it returns a pointer to a record of type @code{struct dirent64}. Some of the members of this data type (notably @code{d_ino}) @@ -560,6 +603,7 @@ @comment dirent.h @comment LFS @deftypefun int readdir64_r (DIR *@var{dirstream}, struct dirent64 *@var{entry}, struct dirent64 **@var{result}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} The @code{readdir64_r} function is equivalent to the @code{readdir_r} function except that it takes parameters of base type @code{struct dirent64} instead of @code{struct dirent} in the second and third @@ -570,6 +614,10 @@ @comment dirent.h @comment POSIX.1 @deftypefun int closedir (DIR *@var{dirstream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@acsmem{} @acsfd{} @aculock{/hurd}}} +@c No synchronization in the posix implementation, only in the hurd +@c one. This is regarded as safe because it is undefined behavior if +@c other threads could still be using the dir stream while it's closed. This function closes the directory stream @var{dirstream}. It returns @code{0} on success and @code{-1} on failure. @@ -609,6 +657,7 @@ @comment dirent.h @comment POSIX.1 @deftypefun void rewinddir (DIR *@var{dirstream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} The @code{rewinddir} function is used to reinitialize the directory stream @var{dirstream}, so that if you call @code{readdir} it returns information about the first entry in the directory again. This @@ -622,6 +671,10 @@ @comment dirent.h @comment BSD @deftypefun {long int} telldir (DIR *@var{dirstream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}} +@c The implementation is safe on most platforms, but on BSD it uses +@c cookies, buckets and records, and the global array of pointers to +@c dynamically allocated records is guarded by a non-recursive lock. The @code{telldir} function returns the file position of the directory stream @var{dirstream}. You can use this value with @code{seekdir} to restore the directory stream to that position. @@ -630,6 +683,10 @@ @comment dirent.h @comment BSD @deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}} +@c The implementation is safe on most platforms, but on BSD it uses +@c cookies, buckets and records, and the global array of pointers to +@c dynamically allocated records is guarded by a non-recursive lock. The @code{seekdir} function sets the file position of the directory stream @var{dirstream} to @var{pos}. The value @var{pos} must be the result of a previous call to @code{telldir} on this particular stream; @@ -648,7 +705,20 @@ @comment dirent.h @comment BSD/SVID -@deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const void *, const void *)) +@deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const struct dirent **, const struct dirent **)) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c The scandir function calls __opendirat, __readdir, and __closedir to +@c go over the named dir; malloc and realloc to allocate the namelist +@c and copies of each selected dirent, besides the selector, if given, +@c and qsort and the cmp functions if the latter is given. In spite of +@c the cleanup handler that releases memory and the file descriptor in +@c case of synchronous cancellation, an asynchronous cancellation may +@c still leak memory and a file descriptor. Although readdir is unsafe +@c in general, the use of an internal dir stream for sequential scanning +@c of the directory with copying of dirents before subsequent calls +@c makes the use safe, and the fact that the dir stream is private to +@c each scandir call does away with the lock issues in readdir and +@c closedir. The @code{scandir} function scans the contents of the directory selected by @var{dir}. The result in *@var{namelist} is an array of pointers to @@ -678,7 +748,9 @@ @comment dirent.h @comment BSD/SVID -@deftypefun int alphasort (const void *@var{a}, const void *@var{b}) +@deftypefun int alphasort (const struct dirent **@var{a}, const struct dirent **@var{b}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c Calls strcoll. The @code{alphasort} function behaves like the @code{strcoll} function (@pxref{String/Array Comparison}). The difference is that the arguments are not string pointers but instead they are of type @@ -690,7 +762,10 @@ @comment dirent.h @comment GNU -@deftypefun int versionsort (const void *@var{a}, const void *@var{b}) +@deftypefun int versionsort (const struct dirent **@var{a}, const struct dirent **@var{b}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c Calls strverscmp, which will accesses the locale object multiple +@c times. The @code{versionsort} function is like @code{alphasort} except that it uses the @code{strverscmp} function internally. @end deftypefun @@ -702,7 +777,9 @@ @comment dirent.h @comment GNU -@deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const void *, const void *)) +@deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const struct dirent64 **, const struct dirent64 **)) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c See scandir. The @code{scandir64} function works like the @code{scandir} function except that the directory entries it returns are described by elements of type @w{@code{struct dirent64}}. The function pointed to by @@ -720,7 +797,9 @@ @comment dirent.h @comment GNU -@deftypefun int alphasort64 (const void *@var{a}, const void *@var{b}) +@deftypefun int alphasort64 (const struct dirent64 **@var{a}, const struct dirent **@var{b}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c See alphasort. The @code{alphasort64} function behaves like the @code{strcoll} function (@pxref{String/Array Comparison}). The difference is that the arguments are not string pointers but instead they are of type @@ -732,7 +811,9 @@ @comment dirent.h @comment GNU -@deftypefun int versionsort64 (const void *@var{a}, const void *@var{b}) +@deftypefun int versionsort64 (const struct dirent64 **@var{a}, const struct dirent64 **@var{b}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c See versionsort. The @code{versionsort64} function is like @code{alphasort64}, excepted that it uses the @code{strverscmp} function internally. @end deftypefun @@ -812,7 +893,7 @@ file does not exist. The situation for @code{nftw} is different. This value is only available if the program is compiled with -@code{_BSD_SOURCE} or @code{_XOPEN_EXTENDED} defined before including +@code{_XOPEN_EXTENDED} defined before including the first header. The original SVID systems do not have symbolic links. @end vtable @@ -913,6 +994,8 @@ @comment ftw.h @comment SVID @deftypefun int ftw (const char *@var{filename}, __ftw_func_t @var{func}, int @var{descriptors}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c see nftw for safety details The @code{ftw} function calls the callback function given in the parameter @var{func} for every item which is found in the directory specified by @var{filename} and all directories below. The function @@ -963,6 +1046,7 @@ @comment ftw.h @comment Unix98 @deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} This function is similar to @code{ftw} but it can work on filesystems with large files. File information is reported using a variable of type @code{struct stat64} which is passed by reference to the callback @@ -976,6 +1060,17 @@ @comment ftw.h @comment XPG4.2 @deftypefun int nftw (const char *@var{filename}, __nftw_func_t @var{func}, int @var{descriptors}, int @var{flag}) +@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}} +@c ftw_startup calls alloca, malloc, free, xstat/lxstat, tdestroy, and ftw_dir +@c if FTW_CHDIR, call open, and fchdir, or chdir and getcwd +@c ftw_dir calls open_dir_stream, readdir64, process_entry, closedir +@c if FTW_CHDIR, also calls fchdir +@c open_dir_stream calls malloc, realloc, readdir64, free, closedir, +@c then openat64_not_cancel_3 and fdopendir or opendir, then dirfd. +@c process_entry may cal realloc, fxstatat/lxstat/xstat, ftw_dir, and +@c find_object (tsearch) and add_object (tfind). +@c Since each invocation of *ftw uses its own private search tree, none +@c of the search tree concurrency issues apply. The @code{nftw} function works like the @code{ftw} functions. They call the callback function @var{func} for all items found in the directory @var{filename} and below. At most @var{descriptors} file descriptors @@ -1036,6 +1131,7 @@ @comment ftw.h @comment Unix98 @deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag}) +@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}} This function is similar to @code{nftw} but it can work on filesystems with large files. File information is reported using a variable of type @code{struct stat64} which is passed by reference to the callback @@ -1079,6 +1175,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int link (const char *@var{oldname}, const char *@var{newname}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{link} function makes a new link to the existing file named by @var{oldname}, under the new name @var{newname}. @@ -1186,6 +1283,7 @@ @comment unistd.h @comment BSD @deftypefun int symlink (const char *@var{oldname}, const char *@var{newname}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{symlink} function makes a symbolic link to @var{oldname} named @var{newname}. @@ -1222,7 +1320,8 @@ @comment unistd.h @comment BSD -@deftypefun int readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size}) +@deftypefun ssize_t readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{readlink} function gets the value of the symbolic link @var{filename}. The file name that the link points to is copied into @var{buffer}. This file name string is @emph{not} null-terminated; @@ -1282,6 +1381,8 @@ @comment stdlib.h @comment GNU @deftypefun {char *} canonicalize_file_name (const char *@var{name}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c Calls realpath. The @code{canonicalize_file_name} function returns the absolute name of the file named by @var{name} which contains no @code{.}, @code{..} @@ -1323,6 +1424,8 @@ @comment stdlib.h @comment XPG @deftypefun {char *} realpath (const char *restrict @var{name}, char *restrict @var{resolved}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c Calls malloc, realloc, getcwd, lxstat64, readlink, alloca. A call to @code{realpath} where the @var{resolved} parameter is @code{NULL} behaves exactly like @code{canonicalize_file_name}. The @@ -1362,6 +1465,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int unlink (const char *@var{filename}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{unlink} function deletes the file name @var{filename}. If this is a file's sole name, the file itself is also deleted. (Actually, if any process has the file open when this happens, deletion is @@ -1404,6 +1508,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int rmdir (const char *@var{filename}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @cindex directories, deleting @cindex deleting a directory The @code{rmdir} function deletes a directory. The directory must be @@ -1431,6 +1536,8 @@ @comment stdio.h @comment ISO @deftypefun int remove (const char *@var{filename}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Calls unlink and rmdir. This is the @w{ISO C} function to remove a file. It works like @code{unlink} for files and like @code{rmdir} for directories. @code{remove} is declared in @file{stdio.h}. @@ -1446,6 +1553,10 @@ @comment stdio.h @comment ISO @deftypefun int rename (const char *@var{oldname}, const char *@var{newname}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c In the absence of a rename syscall, there's an emulation with link +@c and unlink, but it's racy, even more so if newname exists and is +@c unlinked first. The @code{rename} function renames the file @var{oldname} to @var{newname}. The file formerly accessible under the name @var{oldname} is afterwards accessible as @var{newname} instead. (If @@ -1541,6 +1652,7 @@ @comment sys/stat.h @comment POSIX.1 @deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{mkdir} function creates a new, empty directory with name @var{filename}. @@ -1882,6 +1994,7 @@ @comment sys/stat.h @comment POSIX.1 @deftypefun int stat (const char *@var{filename}, struct stat *@var{buf}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{stat} function returns information about the attributes of the file named by @w{@var{filename}} in the structure pointed to by @var{buf}. @@ -1908,8 +2021,9 @@ @comment sys/stat.h @comment Unix98 @deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{stat} but it is also able to work on -files larger then @math{2^31} bytes on 32-bit systems. To be able to do +files larger than @math{2^31} bytes on 32-bit systems. To be able to do this the result is stored in a variable of type @code{struct stat64} to which @var{buf} must point. @@ -1921,6 +2035,7 @@ @comment sys/stat.h @comment POSIX.1 @deftypefun int fstat (int @var{filedes}, struct stat *@var{buf}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fstat} function is like @code{stat}, except that it takes an open file descriptor as an argument instead of a file name. @xref{Low-Level I/O}. @@ -1942,6 +2057,7 @@ @comment sys/stat.h @comment Unix98 @deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{fstat} but is able to work on large files on 32-bit platforms. For large files the file descriptor @var{filedes} should be obtained by @code{open64} or @code{creat64}. @@ -1953,9 +2069,16 @@ replaces the interface for small files on 32-bit machines. @end deftypefun +@c fstatat will call alloca and snprintf if the syscall is not +@c available. +@c @safety{@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} + @comment sys/stat.h @comment BSD @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct system call through lxstat, sometimes with an xstat conv call +@c afterwards. The @code{lstat} function is like @code{stat}, except that it does not follow symbolic links. If @var{filename} is the name of a symbolic link, @code{lstat} returns information about the link itself; otherwise @@ -1969,8 +2092,11 @@ @comment sys/stat.h @comment Unix98 @deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct system call through lxstat64, sometimes with an xstat conv +@c call afterwards. This function is similar to @code{lstat} but it is also able to work on -files larger then @math{2^31} bytes on 32-bit systems. To be able to do +files larger than @math{2^31} bytes on 32-bit systems. To be able to do this the result is stored in a variable of type @code{struct stat64} to which @var{buf} must point. @@ -2007,12 +2133,14 @@ @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISDIR (mode_t @var{m}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a directory. @end deftypefn @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISCHR (mode_t @var{m}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a character special file (a device like a terminal). @end deftypefn @@ -2020,6 +2148,7 @@ @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISBLK (mode_t @var{m}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a block special file (a device like a disk). @end deftypefn @@ -2027,12 +2156,14 @@ @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISREG (mode_t @var{m}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a regular file. @end deftypefn @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISFIFO (mode_t @var{m}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a FIFO special file, or a pipe. @xref{Pipes and FIFOs}. @end deftypefn @@ -2040,6 +2171,7 @@ @comment sys/stat.h @comment GNU @deftypefn Macro int S_ISLNK (mode_t @var{m}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a symbolic link. @xref{Symbolic Links}. @end deftypefn @@ -2047,6 +2179,7 @@ @comment sys/stat.h @comment GNU @deftypefn Macro int S_ISSOCK (mode_t @var{m}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns non-zero if the file is a socket. @xref{Sockets}. @end deftypefn @@ -2129,6 +2262,7 @@ @comment sys/stat.h @comment POSIX @deftypefn Macro int S_TYPEISMQ (struct stat *@var{s}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If the system implement POSIX message queues as distinct objects and the file is a message queue object, this macro returns a non-zero value. In all other cases the result is zero. @@ -2137,6 +2271,7 @@ @comment sys/stat.h @comment POSIX @deftypefn Macro int S_TYPEISSEM (struct stat *@var{s}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If the system implement POSIX semaphores as distinct objects and the file is a semaphore object, this macro returns a non-zero value. In all other cases the result is zero. @@ -2145,8 +2280,9 @@ @comment sys/stat.h @comment POSIX @deftypefn Macro int S_TYPEISSHM (struct stat *@var{s}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If the system implement POSIX shared memory objects as distinct objects -and the file is an shared memory object, this macro returns a non-zero +and the file is a shared memory object, this macro returns a non-zero value. In all other cases the result is zero. @end deftypefn @@ -2189,6 +2325,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{chown} function changes the owner of the file @var{filename} to @var{owner}, and its group owner to @var{group}. @@ -2222,7 +2359,8 @@ @comment unistd.h @comment BSD -@deftypefun int fchown (int @var{filedes}, int @var{owner}, int @var{group}) +@deftypefun int fchown (int @var{filedes}, uid_t @var{owner}, gid_t @var{group}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{chown}, except that it changes the owner of the open file with descriptor @var{filedes}. @@ -2502,6 +2641,7 @@ @comment sys/stat.h @comment POSIX.1 @deftypefun mode_t umask (mode_t @var{mask}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{umask} function sets the file creation mask of the current process to @var{mask}, and returns the previous value of the file creation mask. @@ -2527,6 +2667,7 @@ @comment sys/stat.h @comment GNU @deftypefun mode_t getumask (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Return the current value of the file creation mask for the current process. This function is a GNU extension and is only available on @gnuhurdsystems{}. @@ -2535,6 +2676,7 @@ @comment sys/stat.h @comment POSIX.1 @deftypefun int chmod (const char *@var{filename}, mode_t @var{mode}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{chmod} function sets the access permission bits for the file named by @var{filename} to @var{mode}. @@ -2574,7 +2716,8 @@ @comment sys/stat.h @comment BSD -@deftypefun int fchmod (int @var{filedes}, int @var{mode}) +@deftypefun int fchmod (int @var{filedes}, mode_t @var{mode}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{chmod}, except that it changes the permissions of the currently open file given by @var{filedes}. @@ -2645,6 +2788,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int access (const char *@var{filename}, int @var{how}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{access} function checks to see whether the file named by @var{filename} can be accessed in the way specified by the @var{how} argument. The @var{how} argument either can be the bitwise OR of the @@ -2746,7 +2890,7 @@ need to include the header file @file{utime.h} to use this facility. @pindex utime.h -@comment time.h +@comment utime.h @comment POSIX.1 @deftp {Data Type} {struct utimbuf} The @code{utimbuf} structure is used with the @code{utime} function to @@ -2762,9 +2906,12 @@ @end table @end deftp -@comment time.h +@comment utime.h @comment POSIX.1 @deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c In the absence of a utime syscall, it non-atomically converts times +@c to a struct timeval and calls utimes. This function is used to modify the file times associated with the file named @var{filename}. @@ -2815,7 +2962,11 @@ @comment sys/time.h @comment BSD -@deftypefun int utimes (const char *@var{filename}, struct timeval @var{tvp}@t{[2]}) +@deftypefun int utimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c In the absence of a utimes syscall, it non-atomically converts tvp +@c to struct timespec array and issues a utimensat syscall, or to +@c struct utimbuf and calls utime. This function sets the file access and modification times of the file @var{filename}. The new file access time is specified by @code{@var{tvp}[0]}, and the new modification time by @@ -2829,7 +2980,10 @@ @comment sys/time.h @comment BSD -@deftypefun int lutimes (const char *@var{filename}, struct timeval @var{tvp}@t{[2]}) +@deftypefun int lutimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Since there's no lutimes syscall, it non-atomically converts tvp +@c to struct timespec array and issues a utimensat syscall. This function is like @code{utimes}, except that it does not follow symbolic links. If @var{filename} is the name of a symbolic link, @code{lutimes} sets the file access and modification times of the @@ -2845,7 +2999,11 @@ @comment sys/time.h @comment BSD -@deftypefun int futimes (int @var{fd}, struct timeval @var{tvp}@t{[2]}) +@deftypefun int futimes (int @var{fd}, const struct timeval @var{tvp}@t{[2]}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Since there's no futimes syscall, it non-atomically converts tvp +@c to struct timespec array and issues a utimensat syscall, falling back +@c to utimes on a /proc/self/fd symlink. This function is like @code{utimes}, except that it takes an open file descriptor as an argument instead of a file name. @xref{Low-Level I/O}. This function comes from FreeBSD, and is not available on all @@ -2900,6 +3058,8 @@ @comment unistd.h @comment X/Open @deftypefun int truncate (const char *@var{filename}, off_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c In the absence of a truncate syscall, we use open and ftruncate. The @code{truncate} function changes the size of @var{filename} to @var{length}. If @var{length} is shorter than the previous length, data @@ -2944,6 +3104,8 @@ @comment unistd.h @comment Unix98 @deftypefun int truncate64 (const char *@var{name}, off64_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c In the absence of a syscall, try truncate if length fits. This function is similar to the @code{truncate} function. The difference is that the @var{length} argument is 64 bits wide even on 32 bits machines, which allows the handling of files with sizes up to @@ -2957,6 +3119,7 @@ @comment unistd.h @comment POSIX @deftypefun int ftruncate (int @var{fd}, off_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{truncate}, but it works on a file descriptor @var{fd} for an opened file instead of a file name to identify the object. The @@ -3021,6 +3184,8 @@ @comment unistd.h @comment Unix98 @deftypefun int ftruncate64 (int @var{id}, off64_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c In the absence of a syscall, try ftruncate if length fits. This function is similar to the @code{ftruncate} function. The difference is that the @var{length} argument is 64 bits wide even on 32 bits machines which allows the handling of files with sizes up to @@ -3082,7 +3247,11 @@ @comment sys/stat.h @comment BSD -@deftypefun int mknod (const char *@var{filename}, int @var{mode}, int @var{dev}) +@deftypefun int mknod (const char *@var{filename}, mode_t @var{mode}, dev_t @var{dev}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Instead of issuing the syscall directly, we go through xmknod. +@c Although the internal xmknod takes a dev_t*, that could lead to +@c @mtsrace races, it's passed a pointer to mknod's dev. The @code{mknod} function makes a special file with name @var{filename}. The @var{mode} specifies the mode of the file, and may include the various special file bits, such as @code{S_IFCHR} (for a character special file) @@ -3134,6 +3303,20 @@ @comment stdio.h @comment ISO @deftypefun {FILE *} tmpfile (void) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} +@c The unsafety issues are those of fdopen, plus @acsfd because of the +@c open. +@c __path_search (internal buf, !dir, const pfx, !try_tmpdir) ok +@c libc_secure_genenv only if try_tmpdir +@c xstat64, strlen, strcmp, sprintf +@c __gen_tempname (internal tmpl, __GT_FILE) ok +@c strlen, memcmp, getpid, open/mkdir/lxstat64 ok +@c HP_TIMING_NOW if available ok +@c gettimeofday (!tz) first time, or every time if no HP_TIMING_NOW ok +@c static value is used and modified without synchronization ok +@c but the use is as a source of non-cryptographic randomness +@c with retries in case of collision, so it should be safe +@c unlink, fdopen This function creates a temporary binary file for update mode, as if by calling @code{fopen} with mode @code{"wb+"}. The file is deleted automatically when it is closed or when the program terminates. (On @@ -3150,9 +3333,10 @@ @comment stdio.h @comment Unix98 @deftypefun {FILE *} tmpfile64 (void) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} This function is similar to @code{tmpfile}, but the stream it returns a pointer to was opened using @code{tmpfile64}. Therefore this stream can -be used for files larger then @math{2^31} bytes on 32-bit machines. +be used for files larger than @math{2^31} bytes on 32-bit machines. Please note that the return type is still @code{FILE *}. There is no special @code{FILE} type for the LFS interface. @@ -3165,6 +3349,11 @@ @comment stdio.h @comment ISO @deftypefun {char *} tmpnam (char *@var{result}) +@safety{@prelim{}@mtunsafe{@mtasurace{:tmpnam/!result}}@asunsafe{}@acsafe{}} +@c The passed-in buffer should not be modified concurrently with the +@c call. +@c __path_search (static or passed-in buf, !dir, !pfx, !try_tmpdir) ok +@c __gen_tempname (internal tmpl, __GT_NOCREATE) ok This function constructs and returns a valid file name that does not refer to any existing file. If the @var{result} argument is a null pointer, the return value is a pointer to an internal static string, @@ -3189,6 +3378,7 @@ @comment stdio.h @comment GNU @deftypefun {char *} tmpnam_r (char *@var{result}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is nearly identical to the @code{tmpnam} function, except that if @var{result} is a null pointer it returns a null pointer. @@ -3225,6 +3415,13 @@ @comment stdio.h @comment SVID @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix}) +@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c There's no way (short of being setuid) to avoid getenv("TMPDIR"), +@c even with a non-NULL dir. +@c +@c __path_search (internal buf, dir, pfx, try_tmpdir) unsafe getenv +@c __gen_tempname (internal tmpl, __GT_NOCREATE) ok +@c strdup This function generates a unique temporary file name. If @var{prefix} is not a null pointer, up to five characters of this string are used as a prefix for the file name. The return value is a string newly @@ -3288,6 +3485,8 @@ @comment stdlib.h @comment Unix @deftypefun {char *} mktemp (char *@var{template}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c __gen_tempname (caller tmpl, __GT_NOCREATE) ok The @code{mktemp} function generates a unique file name by modifying @var{template} as described above. If successful, it returns @var{template} as modified. If @code{mktemp} cannot find a unique file @@ -3306,6 +3505,8 @@ @comment stdlib.h @comment BSD @deftypefun int mkstemp (char *@var{template}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} +@c __gen_tempname (caller tmpl, __GT_FILE) ok The @code{mkstemp} function generates a unique file name just as @code{mktemp} does, but it also opens the file for you with @code{open} (@pxref{Opening and Closing Files}). If successful, it modifies @@ -3328,6 +3529,8 @@ @comment stdlib.h @comment BSD @deftypefun {char *} mkdtemp (char *@var{template}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c __gen_tempname (caller tmpl, __GT_DIR) ok The @code{mkdtemp} function creates a directory with a unique name. If it succeeds, it overwrites @var{template} with the name of the directory, and returns @var{template}. As with @code{mktemp} and @@ -3349,3 +3552,23 @@ @xref{Creating Directories}. The @code{mkdtemp} function comes from OpenBSD. + +@c FIXME these are undocumented: +@c faccessat +@c fchmodat +@c fchownat +@c futimesat +@c fstatat (there's a commented-out safety assessment for this one) +@c linkat +@c mkdirat +@c mkfifoat +@c name_to_handle_at +@c openat +@c open_by_handle_at +@c readlinkat +@c renameat +@c scandirat +@c symlinkat +@c unlinkat +@c utimensat +@c mknodat diff -urN glibc-2.17-c758a686/manual/freemanuals.texi glibc-2.17-c758a686/manual/freemanuals.texi --- glibc-2.17-c758a686/manual/freemanuals.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/freemanuals.texi 2014-09-12 16:10:06.044792719 -0400 @@ -1,4 +1,7 @@ -@appendix Free Software Needs Free Documentation +@c freemanuals.texi - blurb for free documentation. +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + @cindex free documentation The biggest deficiency in the free software community today is not in diff -urN glibc-2.17-c758a686/manual/getopt.texi glibc-2.17-c758a686/manual/getopt.texi --- glibc-2.17-c758a686/manual/getopt.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/getopt.texi 2014-09-12 16:10:06.044792719 -0400 @@ -59,7 +59,29 @@ @comment unistd.h @comment POSIX.2 -@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options}) +@deftypefun int getopt (int @var{argc}, char *const *@var{argv}, const char *@var{options}) +@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} +@c Swapping elements of passed-in argv may be partial in case of +@c cancellation. Gettext brings about a whole lot of AS and AC safety +@c issues. The getopt API involves returning values in the +@c non-thread-specific optarg variable, which adds another thread-safety +@c issue. Given print_errors, it may output errors to stderr, which may +@c self-deadlock, leak locks, or encounter (in a signal handler) or +@c leave (in case of cancellation) stderr in an inconsistent state. +@c Various implicit, indirect uses of malloc, in uses of memstream and +@c asprintf for error-printing, bring about the usual malloc issues. +@c (The explicit use of malloc in a conditional situation in +@c _getopt_initialize is never exercised in glibc.) +@c +@c _getopt_internal +@c _getopt_internal_r +@c gettext +@c _getopt_initialize +@c getenv +@c malloc if USE_NONOPTION_FLAGS, never defined in libc +@c open_memstream +@c lockfile, unlockfile, __fxprintf -> stderr +@c asprintf The @code{getopt} function gets the next option argument from the argument list specified by the @var{argv} and @var{argc} arguments. Normally these values come directly from the arguments received by @@ -225,6 +247,8 @@ @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}) +@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} +@c Same issues as getopt. Decode options from the vector @var{argv} (whose length is @var{argc}). The argument @var{shortopts} describes the short options to accept, just as it does in @code{getopt}. The argument @var{longopts} describes the long @@ -278,6 +302,8 @@ @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}) +@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} +@c Same issues as getopt. The @code{getopt_long_only} function is equivalent to the @code{getopt_long} function but it allows to specify the user of the diff -urN glibc-2.17-c758a686/manual/install-plain.texi glibc-2.17-c758a686/manual/install-plain.texi --- glibc-2.17-c758a686/manual/install-plain.texi 1969-12-31 19:00:00.000000000 -0500 +++ glibc-2.17-c758a686/manual/install-plain.texi 2014-09-12 16:10:06.046792714 -0400 @@ -0,0 +1,5 @@ +@c This is for making the `INSTALL' file for the distribution. +@c Makeinfo ignores it when processing the file from the include. +@setfilename INSTALL +@set plain +@include install.texi diff -urN glibc-2.17-c758a686/manual/install.texi glibc-2.17-c758a686/manual/install.texi --- glibc-2.17-c758a686/manual/install.texi 2014-09-12 16:08:17.783070851 -0400 +++ glibc-2.17-c758a686/manual/install.texi 2014-09-12 16:10:06.043792722 -0400 @@ -1,10 +1,10 @@ -@c This is for making the `INSTALL' file for the distribution. -@c Makeinfo ignores it when processing the file from the include. -@setfilename INSTALL @include macros.texi @include pkgvers.texi +@ifclear plain @node Installation, Maintenance, Library Summary, Top +@end ifclear + @c %MENU% How to install the GNU C Library @appendix Installing @theglibc{} @@ -21,6 +21,7 @@ You will need recent versions of several GNU tools: definitely GCC and GNU Make, and possibly others. @xref{Tools for Compilation}, below. +@ifclear plain @menu * Configuring and compiling:: How to compile and test GNU libc. * Running make install:: How to install it once you've got it @@ -29,6 +30,7 @@ * Linux:: Specific advice for GNU/Linux systems. * Reporting Bugs:: So they'll get fixed. @end menu +@end ifclear @node Configuring and compiling @appendixsec Configuring and compiling @theglibc{} @@ -138,11 +140,6 @@ Don't build libraries with profiling information. You may want to use this option if you don't plan to do profiling. -@item --disable-versioning -Don't compile the shared libraries with symbol version information. -Doing this will make the resulting library incompatible with old -binaries, so it's not recommended. - @item --enable-static-nss Compile static versions of the NSS (Name Service Switch) libraries. This is not recommended because it defeats the purpose of NSS; a program @@ -155,6 +152,14 @@ prevented though there generally is no reason since it creates compatibility problems. +@item --enable-hardcoded-path-in-tests +By default, dynamic tests are linked to run with the installed C library. +This option hardcodes the newly built C library path in dynamic tests +so that they can be invoked directly. + +@item --enable-lock-elision=yes +Enable lock elision for pthread mutexes by default. + @pindex pt_chown @findex grantpt @item --enable-pt_chown @@ -180,11 +185,11 @@ If you only specify @samp{--host}, @code{configure} will prepare for a native compile but use what you specify instead of guessing what your -system is. This is most useful to change the CPU submodel. For example, -if @code{configure} guesses your machine as @code{i586-pc-linux-gnu} but -you want to compile a library for 386es, give -@samp{--host=i386-pc-linux-gnu} or just @samp{--host=i386-linux} and add -the appropriate compiler flags (@samp{-mcpu=i386} will do the trick) to +system is. This is most useful to change the CPU submodel. For example, +if @code{configure} guesses your machine as @code{i686-pc-linux-gnu} but +you want to compile a library for 586es, give +@samp{--host=i586-pc-linux-gnu} or just @samp{--host=i586-linux} and add +the appropriate compiler flags (@samp{-mcpu=i586} will do the trick) to @var{CFLAGS}. If you specify just @samp{--build}, @code{configure} will get confused. @@ -230,6 +235,12 @@ system such as @file{/etc/passwd}, @file{/etc/nsswitch.conf} and others. These files must all contain correct and sensible content. +Normally, @code{make check} will run all the tests before reporting +all problems found and exiting with error status if any problems +occurred. You can specify @samp{stop-on-test-failure=y} when running +@code{make check} to make the test run stop and exit with an error +status immediately when a failure occurs. + To format the @cite{GNU C Library Reference Manual} for printing, type @w{@code{make dvi}}. You need a working @TeX{} installation to do this. The distribution builds the on-line formatted version of the @@ -264,13 +275,15 @@ In general, when testing @theglibc{}, @samp{test-wrapper} may be set to the name and arguments of any program to run newly built binaries. This program must preserve the arguments to the binary being run, its -working directory, all environment variables set as part of testing -and the standard input, output and error file descriptors. If +working directory and the standard input, output and error file +descriptors. If @samp{@var{test-wrapper} env} will not work to run a program with environment variables set, then @samp{test-wrapper-env} must be set to a program that runs a newly built program with environment variable assignments in effect, those assignments being specified as -@samp{@var{var}=@var{value}} before the name of the program to be run. +@samp{@var{var}=@var{value}} before the name of the program to be +run. If multiple assignments to the same variable are specified, +the last assignment specified must take precedence. @node Running make install @@ -278,7 +291,7 @@ @cindex installing To install the library and its header files, and the Info files of the -manual, type @code{env LANGUAGE=C LC_ALL=C make install}. This will +manual, type @code{make install}. This will build things, if necessary, before installing them; however, you should still compile everything first. If you are installing @theglibc{} as your primary C library, we recommend that you shut the system down to @@ -317,14 +330,11 @@ well. One auxiliary program, @file{/usr/libexec/pt_chown}, is installed setuid -@code{root}. This program is invoked by the @code{grantpt} function; it -sets the permissions on a pseudoterminal so it can be used by the -calling process. This means programs like @code{xterm} and -@code{screen} do not have to be setuid to get a pty. (There may be -other reasons why they need privileges.) If you are using a -Linux kernel with the @code{devptsfs} or @code{devfs} filesystems -providing pty slaves, you don't need this program; otherwise you do. -The source for @file{pt_chown} is in @file{login/programs/pt_chown.c}. +@code{root} if the @samp{--enable-pt_chown} configuration option is used. +This program is invoked by the @code{grantpt} function; it sets the +permissions on a pseudoterminal so it can be used by the calling process. +If you are using a Linux kernel with the @code{devpts} filesystem enabled +and mounted at @file{/dev/pts}, you don't need this program. After installation you might want to configure the timezone and locale installation of your system. @Theglibc{} comes with a locale @@ -362,9 +372,9 @@ bugs or lack features. @item -GCC 4.3 or newer, GCC 4.6 recommended +GCC 4.4 or newer, GCC 4.6 recommended -GCC 4.3 or higher is required; as of this writing, GCC 4.6 is the +GCC 4.4 or higher is required; as of this writing, GCC 4.6 is the compiler we advise to use to build @theglibc{}. You can use whatever compiler you like to compile programs that use @@ -388,10 +398,11 @@ mechanism for the info files is not present or works differently. @item -GNU @code{awk} 3.0, or higher +GNU @code{awk} 3.1.2, or higher -@code{Awk} is used in several places to generate files. -@code{gawk} 3.0 is known to work. +@code{awk} is used in several places to generate files. +Some @code{gawk} extensions are used, including the @code{asorti} +function, which was introduced in version 3.1.2 of @code{gawk}. @item Perl 5 @@ -412,7 +423,7 @@ @end itemize @noindent -If you change any of the @file{configure.in} files you will also need +If you change any of the @file{configure.ac} files you will also need @itemize @bullet @item @@ -436,7 +447,7 @@ @cindex kernel header files If you are installing @theglibc{} on @gnulinuxsystems{}, you need to have -the header files from a 2.6.19.1 or newer kernel around for reference. +the header files from a 2.6.32 or newer kernel around for reference. These headers must be installed using @samp{make headers_install}; the headers present in the kernel source directory are not suitable for direct use by @theglibc{}. You do not need to use that kernel, just have diff -urN glibc-2.17-c758a686/manual/intro.texi glibc-2.17-c758a686/manual/intro.texi --- glibc-2.17-c758a686/manual/intro.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/intro.texi 2014-09-12 16:10:06.044792719 -0400 @@ -159,6 +159,14 @@ These include utilities for dealing with regular expressions and other pattern matching facilities (@pxref{Pattern Matching}). +@menu +* POSIX Safety Concepts:: Safety concepts from POSIX. +* Unsafe Features:: Features that make functions unsafe. +* Conditionally Safe Features:: Features that make functions unsafe + in the absence of workarounds. +* Other Safety Remarks:: Additional safety features and remarks. +@end menu + @comment Roland sez: @comment The GNU C library as it stands conforms to 1003.2 draft 11, which @comment specifies: @@ -172,6 +180,725 @@ @comment (not yet implemented) @comment confstr +@node POSIX Safety Concepts, Unsafe Features, , POSIX +@subsubsection POSIX Safety Concepts +@cindex POSIX Safety Concepts + +This manual documents various safety properties of @glibcadj{} +functions, in lines that follow their prototypes and look like: + +@sampsafety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +The properties are assessed according to the criteria set forth in the +POSIX standard for such safety contexts as Thread-, Async-Signal- and +Async-Cancel- -Safety. Intuitive definitions of these properties, +attempting to capture the meaning of the standard definitions, follow. + +@itemize @bullet + +@item +@cindex MT-Safe +@cindex Thread-Safe +@code{MT-Safe} or Thread-Safe functions are safe to call in the presence +of other threads. MT, in MT-Safe, stands for Multi Thread. + +Being MT-Safe does not imply a function is atomic, nor that it uses any +of the memory synchronization mechanisms POSIX exposes to users. It is +even possible that calling MT-Safe functions in sequence does not yield +an MT-Safe combination. For example, having a thread call two MT-Safe +functions one right after the other does not guarantee behavior +equivalent to atomic execution of a combination of both functions, since +concurrent calls in other threads may interfere in a destructive way. + +Whole-program optimizations that could inline functions across library +interfaces may expose unsafe reordering, and so performing inlining +across the @glibcadj{} interface is not recommended. The documented +MT-Safety status is not guaranteed under whole-program optimization. +However, functions defined in user-visible headers are designed to be +safe for inlining. + + +@item +@cindex AS-Safe +@cindex Async-Signal-Safe +@code{AS-Safe} or Async-Signal-Safe functions are safe to call from +asynchronous signal handlers. AS, in AS-Safe, stands for Asynchronous +Signal. + +Many functions that are AS-Safe may set @code{errno}, or modify the +floating-point environment, because their doing so does not make them +unsuitable for use in signal handlers. However, programs could +misbehave should asynchronous signal handlers modify this thread-local +state, and the signal handling machinery cannot be counted on to +preserve it. Therefore, signal handlers that call functions that may +set @code{errno} or modify the floating-point environment @emph{must} +save their original values, and restore them before returning. + + +@item +@cindex AC-Safe +@cindex Async-Cancel-Safe +@code{AC-Safe} or Async-Cancel-Safe functions are safe to call when +asynchronous cancellation is enabled. AC in AC-Safe stands for +Asynchronous Cancellation. + +The POSIX standard defines only three functions to be AC-Safe, namely +@code{pthread_cancel}, @code{pthread_setcancelstate}, and +@code{pthread_setcanceltype}. At present @theglibc{} provides no +guarantees beyond these three functions, but does document which +functions are presently AC-Safe. This documentation is provided for use +by @theglibc{} developers. + +Just like signal handlers, cancellation cleanup routines must configure +the floating point environment they require. The routines cannot assume +a floating point environment, particularly when asynchronous +cancellation is enabled. If the configuration of the floating point +environment cannot be performed atomically then it is also possible that +the environment encountered is internally inconsistent. + + +@item +@cindex MT-Unsafe +@cindex Thread-Unsafe +@cindex AS-Unsafe +@cindex Async-Signal-Unsafe +@cindex AC-Unsafe +@cindex Async-Cancel-Unsafe +@code{MT-Unsafe}, @code{AS-Unsafe}, @code{AC-Unsafe} functions are not +safe to call within the safety contexts described above. Calling them +within such contexts invokes undefined behavior. + +Functions not explicitly documented as safe in a safety context should +be regarded as Unsafe. + + +@item +@cindex Preliminary +@code{Preliminary} safety properties are documented, indicating these +properties may @emph{not} be counted on in future releases of +@theglibc{}. + +Such preliminary properties are the result of an assessment of the +properties of our current implementation, rather than of what is +mandated and permitted by current and future standards. + +Although we strive to abide by the standards, in some cases our +implementation is safe even when the standard does not demand safety, +and in other cases our implementation does not meet the standard safety +requirements. The latter are most likely bugs; the former, when marked +as @code{Preliminary}, should not be counted on: future standards may +require changes that are not compatible with the additional safety +properties afforded by the current implementation. + +Furthermore, the POSIX standard does not offer a detailed definition of +safety. We assume that, by ``safe to call'', POSIX means that, as long +as the program does not invoke undefined behavior, the ``safe to call'' +function behaves as specified, and does not cause other functions to +deviate from their specified behavior. We have chosen to use its loose +definitions of safety, not because they are the best definitions to use, +but because choosing them harmonizes this manual with POSIX. + +Please keep in mind that these are preliminary definitions and +annotations, and certain aspects of the definitions are still under +discussion and might be subject to clarification or change. + +Over time, we envision evolving the preliminary safety notes into stable +commitments, as stable as those of our interfaces. As we do, we will +remove the @code{Preliminary} keyword from safety notes. As long as the +keyword remains, however, they are not to be regarded as a promise of +future behavior. + + +@end itemize + +Other keywords that appear in safety notes are defined in subsequent +sections. + + +@node Unsafe Features, Conditionally Safe Features, POSIX Safety Concepts, POSIX +@subsubsection Unsafe Features +@cindex Unsafe Features + +Functions that are unsafe to call in certain contexts are annotated with +keywords that document their features that make them unsafe to call. +AS-Unsafe features in this section indicate the functions are never safe +to call when asynchronous signals are enabled. AC-Unsafe features +indicate they are never safe to call when asynchronous cancellation is +enabled. There are no MT-Unsafe marks in this section. + +@itemize @bullet + +@item @code{lock} +@cindex lock + +Functions marked with @code{lock} as an AS-Unsafe feature may be +interrupted by a signal while holding a non-recursive lock. If the +signal handler calls another such function that takes the same lock, the +result is a deadlock. + +Functions annotated with @code{lock} as an AC-Unsafe feature may, if +cancelled asynchronously, fail to release a lock that would have been +released if their execution had not been interrupted by asynchronous +thread cancellation. Once a lock is left taken, attempts to take that +lock will block indefinitely. + + +@item @code{corrupt} +@cindex corrupt + +Functions marked with @code{corrupt} as an AS-Unsafe feature may corrupt +data structures and misbehave when they interrupt, or are interrupted +by, another such function. Unlike functions marked with @code{lock}, +these take recursive locks to avoid MT-Safety problems, but this is not +enough to stop a signal handler from observing a partially-updated data +structure. Further corruption may arise from the interrupted function's +failure to notice updates made by signal handlers. + +Functions marked with @code{corrupt} as an AC-Unsafe feature may leave +data structures in a corrupt, partially updated state. Subsequent uses +of the data structure may misbehave. + +@c A special case, probably not worth documenting separately, involves +@c reallocing, or even freeing pointers. Any case involving free could +@c be easily turned into an ac-safe leak by resetting the pointer before +@c releasing it; I don't think we have any case that calls for this sort +@c of fixing. Fixing the realloc cases would require a new interface: +@c instead of @code{ptr=realloc(ptr,size)} we'd have to introduce +@c @code{acsafe_realloc(&ptr,size)} that would modify ptr before +@c releasing the old memory. The ac-unsafe realloc could be implemented +@c in terms of an internal interface with this semantics (say +@c __acsafe_realloc), but since realloc can be overridden, the function +@c we call to implement realloc should not be this internal interface, +@c but another internal interface that calls __acsafe_realloc if realloc +@c was not overridden, and calls the overridden realloc with async +@c cancel disabled. --lxoliva + + +@item @code{heap} +@cindex heap + +Functions marked with @code{heap} may call heap memory management +functions from the @code{malloc}/@code{free} family of functions and are +only as safe as those functions. This note is thus equivalent to: + +@sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} + + +@c Check for cases that should have used plugin instead of or in +@c addition to this. Then, after rechecking gettext, adjust i18n if +@c needed. +@item @code{dlopen} +@cindex dlopen + +Functions marked with @code{dlopen} use the dynamic loader to load +shared libraries into the current execution image. This involves +opening files, mapping them into memory, allocating additional memory, +resolving symbols, applying relocations and more, all of this while +holding internal dynamic loader locks. + +The locks are enough for these functions to be AS- and AC-Unsafe, but +other issues may arise. At present this is a placeholder for all +potential safety issues raised by @code{dlopen}. + +@c dlopen runs init and fini sections of the module; does this mean +@c dlopen always implies plugin? + + +@item @code{plugin} +@cindex plugin + +Functions annotated with @code{plugin} may run code from plugins that +may be external to @theglibc{}. Such plugin functions are assumed to be +MT-Safe, AS-Unsafe and AC-Unsafe. Examples of such plugins are stack +@cindex NSS +unwinding libraries, name service switch (NSS) and character set +@cindex iconv +conversion (iconv) back-ends. + +Although the plugins mentioned as examples are all brought in by means +of dlopen, the @code{plugin} keyword does not imply any direct +involvement of the dynamic loader or the @code{libdl} interfaces, those +are covered by @code{dlopen}. For example, if one function loads a +module and finds the addresses of some of its functions, while another +just calls those already-resolved functions, the former will be marked +with @code{dlopen}, whereas the latter will get the @code{plugin}. When +a single function takes all of these actions, then it gets both marks. + + +@item @code{i18n} +@cindex i18n + +Functions marked with @code{i18n} may call internationalization +functions of the @code{gettext} family and will be only as safe as those +functions. This note is thus equivalent to: + +@sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}} + + +@item @code{timer} +@cindex timer + +Functions marked with @code{timer} use the @code{alarm} function or +similar to set a time-out for a system call or a long-running operation. +In a multi-threaded program, there is a risk that the time-out signal +will be delivered to a different thread, thus failing to interrupt the +intended thread. Besides being MT-Unsafe, such functions are always +AS-Unsafe, because calling them in signal handlers may interfere with +timers set in the interrupted code, and AC-Unsafe, because there is no +safe way to guarantee an earlier timer will be reset in case of +asynchronous cancellation. + +@end itemize + + +@node Conditionally Safe Features, Other Safety Remarks, Unsafe Features, POSIX +@subsubsection Conditionally Safe Features +@cindex Conditionally Safe Features + +For some features that make functions unsafe to call in certain +contexts, there are known ways to avoid the safety problem other than +refraining from calling the function altogether. The keywords that +follow refer to such features, and each of their definitions indicate +how the whole program needs to be constrained in order to remove the +safety problem indicated by the keyword. Only when all the reasons that +make a function unsafe are observed and addressed, by applying the +documented constraints, does the function become safe to call in a +context. + +@itemize @bullet + +@item @code{init} +@cindex init + +Functions marked with @code{init} as an MT-Unsafe feature perform +MT-Unsafe initialization when they are first called. + +Calling such a function at least once in single-threaded mode removes +this specific cause for the function to be regarded as MT-Unsafe. If no +other cause for that remains, the function can then be safely called +after other threads are started. + +Functions marked with @code{init} as an AS- or AC-Unsafe feature use the +internal @code{libc_once} machinery or similar to initialize internal +data structures. + +If a signal handler interrupts such an initializer, and calls any +function that also performs @code{libc_once} initialization, it will +deadlock if the thread library has been loaded. + +Furthermore, if an initializer is partially complete before it is +canceled or interrupted by a signal whose handler requires the same +initialization, some or all of the initialization may be performed more +than once, leaking resources or even resulting in corrupt internal data. + +Applications that need to call functions marked with @code{init} as an +AS- or AC-Unsafe feature should ensure the initialization is performed +before configuring signal handlers or enabling cancellation, so that the +AS- and AC-Safety issues related with @code{libc_once} do not arise. + +@c We may have to extend the annotations to cover conditions in which +@c initialization may or may not occur, since an initial call in a safe +@c context is no use if the initialization doesn't take place at that +@c time: it doesn't remove the risk for later calls. + + +@item @code{race} +@cindex race + +Functions annotated with @code{race} as an MT-Safety issue operate on +objects in ways that may cause data races or similar forms of +destructive interference out of concurrent execution. In some cases, +the objects are passed to the functions by users; in others, they are +used by the functions to return values to users; in others, they are not +even exposed to users. + +We consider access to objects passed as (indirect) arguments to +functions to be data race free. The assurance of data race free objects +is the caller's responsibility. We will not mark a function as +MT-Unsafe or AS-Unsafe if it misbehaves when users fail to take the +measures required by POSIX to avoid data races when dealing with such +objects. As a general rule, if a function is documented as reading from +an object passed (by reference) to it, or modifying it, users ought to +use memory synchronization primitives to avoid data races just as they +would should they perform the accesses themselves rather than by calling +the library function. @code{FILE} streams are the exception to the +general rule, in that POSIX mandates the library to guard against data +races in many functions that manipulate objects of this specific opaque +type. We regard this as a convenience provided to users, rather than as +a general requirement whose expectations should extend to other types. + +In order to remind users that guarding certain arguments is their +responsibility, we will annotate functions that take objects of certain +types as arguments. We draw the line for objects passed by users as +follows: objects whose types are exposed to users, and that users are +expected to access directly, such as memory buffers, strings, and +various user-visible @code{struct} types, do @emph{not} give reason for +functions to be annotated with @code{race}. It would be noisy and +redundant with the general requirement, and not many would be surprised +by the library's lack of internal guards when accessing objects that can +be accessed directly by users. + +As for objects that are opaque or opaque-like, in that they are to be +manipulated only by passing them to library functions (e.g., +@code{FILE}, @code{DIR}, @code{obstack}, @code{iconv_t}), there might be +additional expectations as to internal coordination of access by the +library. We will annotate, with @code{race} followed by a colon and the +argument name, functions that take such objects but that do not take +care of synchronizing access to them by default. For example, +@code{FILE} stream @code{unlocked} functions will be annotated, but +those that perform implicit locking on @code{FILE} streams by default +will not, even though the implicit locking may be disabled on a +per-stream basis. + +In either case, we will not regard as MT-Unsafe functions that may +access user-supplied objects in unsafe ways should users fail to ensure +the accesses are well defined. The notion prevails that users are +expected to safeguard against data races any user-supplied objects that +the library accesses on their behalf. + +@c The above describes @mtsrace; @mtasurace is described below. + +This user responsibility does not apply, however, to objects controlled +by the library itself, such as internal objects and static buffers used +to return values from certain calls. When the library doesn't guard +them against concurrent uses, these cases are regarded as MT-Unsafe and +AS-Unsafe (although the @code{race} mark under AS-Unsafe will be omitted +as redundant with the one under MT-Unsafe). As in the case of +user-exposed objects, the mark may be followed by a colon and an +identifier. The identifier groups all functions that operate on a +certain unguarded object; users may avoid the MT-Safety issues related +with unguarded concurrent access to such internal objects by creating a +non-recursive mutex related with the identifier, and always holding the +mutex when calling any function marked as racy on that identifier, as +they would have to should the identifier be an object under user +control. The non-recursive mutex avoids the MT-Safety issue, but it +trades one AS-Safety issue for another, so use in asynchronous signals +remains undefined. + +When the identifier relates to a static buffer used to hold return +values, the mutex must be held for as long as the buffer remains in use +by the caller. Many functions that return pointers to static buffers +offer reentrant variants that store return values in caller-supplied +buffers instead. In some cases, such as @code{tmpname}, the variant is +chosen not by calling an alternate entry point, but by passing a +non-@code{NULL} pointer to the buffer in which the returned values are +to be stored. These variants are generally preferable in multi-threaded +programs, although some of them are not MT-Safe because of other +internal buffers, also documented with @code{race} notes. + + +@item @code{const} +@cindex const + +Functions marked with @code{const} as an MT-Safety issue non-atomically +modify internal objects that are better regarded as constant, because a +substantial portion of @theglibc{} accesses them without +synchronization. Unlike @code{race}, that causes both readers and +writers of internal objects to be regarded as MT-Unsafe and AS-Unsafe, +this mark is applied to writers only. Writers remain equally MT- and +AS-Unsafe to call, but the then-mandatory constness of objects they +modify enables readers to be regarded as MT-Safe and AS-Safe (as long as +no other reasons for them to be unsafe remain), since the lack of +synchronization is not a problem when the objects are effectively +constant. + +The identifier that follows the @code{const} mark will appear by itself +as a safety note in readers. Programs that wish to work around this +safety issue, so as to call writers, may use a non-recursve +@code{rwlock} associated with the identifier, and guard @emph{all} calls +to functions marked with @code{const} followed by the identifier with a +write lock, and @emph{all} calls to functions marked with the identifier +by itself with a read lock. The non-recursive locking removes the +MT-Safety problem, but it trades one AS-Safety problem for another, so +use in asynchronous signals remains undefined. + +@c But what if, instead of marking modifiers with const:id and readers +@c with just id, we marked writers with race:id and readers with ro:id? +@c Instead of having to define each instance of “id”, we'd have a +@c general pattern governing all such “id”s, wherein race:id would +@c suggest the need for an exclusive/write lock to make the function +@c safe, whereas ro:id would indicate “id” is expected to be read-only, +@c but if any modifiers are called (while holding an exclusive lock), +@c then ro:id-marked functions ought to be guarded with a read lock for +@c safe operation. ro:env or ro:locale, for example, seems to convey +@c more clearly the expectations and the meaning, than just env or +@c locale. + + +@item @code{sig} +@cindex sig + +Functions marked with @code{sig} as a MT-Safety issue (that implies an +identical AS-Safety issue, omitted for brevity) may temporarily install +a signal handler for internal purposes, which may interfere with other +uses of the signal, identified after a colon. + +This safety problem can be worked around by ensuring that no other uses +of the signal will take place for the duration of the call. Holding a +non-recursive mutex while calling all functions that use the same +temporary signal; blocking that signal before the call and resetting its +handler afterwards is recommended. + +There is no safe way to guarantee the original signal handler is +restored in case of asynchronous cancellation, therefore so-marked +functions are also AC-Unsafe. + +@c fixme: at least deferred cancellation should get it right, and would +@c obviate the restoring bit below, and the qualifier above. + +Besides the measures recommended to work around the MT- and AS-Safety +problem, in order to avert the cancellation problem, disabling +asynchronous cancellation @emph{and} installing a cleanup handler to +restore the signal to the desired state and to release the mutex are +recommended. + + +@item @code{term} +@cindex term + +Functions marked with @code{term} as an MT-Safety issue may change the +terminal settings in the recommended way, namely: call @code{tcgetattr}, +modify some flags, and then call @code{tcsetattr}; this creates a window +in which changes made by other threads are lost. Thus, functions marked +with @code{term} are MT-Unsafe. The same window enables changes made by +asynchronous signals to be lost. These functions are also AS-Unsafe, +but the corresponding mark is omitted as redundant. + +It is thus advisable for applications using the terminal to avoid +concurrent and reentrant interactions with it, by not using it in signal +handlers or blocking signals that might use it, and holding a lock while +calling these functions and interacting with the terminal. This lock +should also be used for mutual exclusion with functions marked with +@code{@mtasurace{:tcattr(fd)}}, where @var{fd} is a file descriptor for +the controlling terminal. The caller may use a single mutex for +simplicity, or use one mutex per terminal, even if referenced by +different file descriptors. + +Functions marked with @code{term} as an AC-Safety issue are supposed to +restore terminal settings to their original state, after temporarily +changing them, but they may fail to do so if cancelled. + +@c fixme: at least deferred cancellation should get it right, and would +@c obviate the restoring bit below, and the qualifier above. + +Besides the measures recommended to work around the MT- and AS-Safety +problem, in order to avert the cancellation problem, disabling +asynchronous cancellation @emph{and} installing a cleanup handler to +restore the terminal settings to the original state and to release the +mutex are recommended. + + +@end itemize + + +@node Other Safety Remarks, , Conditionally Safe Features, POSIX +@subsubsection Other Safety Remarks +@cindex Other Safety Remarks + +Additional keywords may be attached to functions, indicating features +that do not make a function unsafe to call, but that may need to be +taken into account in certain classes of programs: + +@itemize @bullet + +@item @code{locale} +@cindex locale + +Functions annotated with @code{locale} as an MT-Safety issue read from +the locale object without any form of synchronization. Functions +annotated with @code{locale} called concurrently with locale changes may +behave in ways that do not correspond to any of the locales active +during their execution, but an unpredictable mix thereof. + +We do not mark these functions as MT- or AS-Unsafe, however, because +functions that modify the locale object are marked with +@code{const:locale} and regarded as unsafe. Being unsafe, the latter +are not to be called when multiple threads are running or asynchronous +signals are enabled, and so the locale can be considered effectively +constant in these contexts, which makes the former safe. + +@c Should the locking strategy suggested under @code{const} be used, +@c failure to guard locale uses is not as fatal as data races in +@c general: unguarded uses will @emph{not} follow dangling pointers or +@c access uninitialized, unmapped or recycled memory. Each access will +@c read from a consistent locale object that is or was active at some +@c point during its execution. Without synchronization, however, it +@c cannot even be assumed that, after a change in locale, earlier +@c locales will no longer be used, even after the newly-chosen one is +@c used in the thread. Nevertheless, even though unguarded reads from +@c the locale will not violate type safety, functions that access the +@c locale multiple times may invoke all sorts of undefined behavior +@c because of the unexpected locale changes. + + +@item @code{env} +@cindex env + +Functions marked with @code{env} as an MT-Safety issue access the +environment with @code{getenv} or similar, without any guards to ensure +safety in the presence of concurrent modifications. + +We do not mark these functions as MT- or AS-Unsafe, however, because +functions that modify the environment are all marked with +@code{const:env} and regarded as unsafe. Being unsafe, the latter are +not to be called when multiple threads are running or asynchronous +signals are enabled, and so the environment can be considered +effectively constant in these contexts, which makes the former safe. + + +@item @code{hostid} +@cindex hostid + +The function marked with @code{hostid} as an MT-Safety issue reads from +the system-wide data structures that hold the ``host ID'' of the +machine. These data structures cannot generally be modified atomically. +Since it is expected that the ``host ID'' will not normally change, the +function that reads from it (@code{gethostid}) is regarded as safe, +whereas the function that modifies it (@code{sethostid}) is marked with +@code{@mtasuconst{:@mtshostid{}}}, indicating it may require special +care if it is to be called. In this specific case, the special care +amounts to system-wide (not merely intra-process) coordination. + + +@item @code{sigintr} +@cindex sigintr + +Functions marked with @code{sigintr} as an MT-Safety issue access the +@code{_sigintr} internal data structure without any guards to ensure +safety in the presence of concurrent modifications. + +We do not mark these functions as MT- or AS-Unsafe, however, because +functions that modify the this data structure are all marked with +@code{const:sigintr} and regarded as unsafe. Being unsafe, the latter +are not to be called when multiple threads are running or asynchronous +signals are enabled, and so the data structure can be considered +effectively constant in these contexts, which makes the former safe. + + +@item @code{fd} +@cindex fd + +Functions annotated with @code{fd} as an AC-Safety issue may leak file +descriptors if asynchronous thread cancellation interrupts their +execution. + +Functions that allocate or deallocate file descriptors will generally be +marked as such. Even if they attempted to protect the file descriptor +allocation and deallocation with cleanup regions, allocating a new +descriptor and storing its number where the cleanup region could release +it cannot be performed as a single atomic operation. Similarly, +releasing the descriptor and taking it out of the data structure +normally responsible for releasing it cannot be performed atomically. +There will always be a window in which the descriptor cannot be released +because it was not stored in the cleanup handler argument yet, or it was +already taken out before releasing it. It cannot be taken out after +release: an open descriptor could mean either that the descriptor still +has to be closed, or that it already did so but the descriptor was +reallocated by another thread or signal handler. + +Such leaks could be internally avoided, with some performance penalty, +by temporarily disabling asynchronous thread cancellation. However, +since callers of allocation or deallocation functions would have to do +this themselves, to avoid the same sort of leak in their own layer, it +makes more sense for the library to assume they are taking care of it +than to impose a performance penalty that is redundant when the problem +is solved in upper layers, and insufficient when it is not. + +This remark by itself does not cause a function to be regarded as +AC-Unsafe. However, cumulative effects of such leaks may pose a +problem for some programs. If this is the case, suspending asynchronous +cancellation for the duration of calls to such functions is recommended. + + +@item @code{mem} +@cindex mem + +Functions annotated with @code{mem} as an AC-Safety issue may leak +memory if asynchronous thread cancellation interrupts their execution. + +The problem is similar to that of file descriptors: there is no atomic +interface to allocate memory and store its address in the argument to a +cleanup handler, or to release it and remove its address from that +argument, without at least temporarily disabling asynchronous +cancellation, which these functions do not do. + +This remark does not by itself cause a function to be regarded as +generally AC-Unsafe. However, cumulative effects of such leaks may be +severe enough for some programs that disabling asynchronous cancellation +for the duration of calls to such functions may be required. + + +@item @code{cwd} +@cindex cwd + +Functions marked with @code{cwd} as an MT-Safety issue may temporarily +change the current working directory during their execution, which may +cause relative pathnames to be resolved in unexpected ways in other +threads or within asynchronous signal or cancellation handlers. + +This is not enough of a reason to mark so-marked functions as MT- or +AS-Unsafe, but when this behavior is optional (e.g., @code{nftw} with +@code{FTW_CHDIR}), avoiding the option may be a good alternative to +using full pathnames or file descriptor-relative (e.g. @code{openat}) +system calls. + + +@item @code{!posix} +@cindex !posix + +This remark, as an MT-, AS- or AC-Safety note to a function, indicates +the safety status of the function is known to differ from the specified +status in the POSIX standard. For example, POSIX does not require a +function to be Safe, but our implementation is, or vice-versa. + +For the time being, the absence of this remark does not imply the safety +properties we documented are identical to those mandated by POSIX for +the corresponding functions. + + +@item @code{:identifier} +@cindex :identifier + +Annotations may sometimes be followed by identifiers, intended to group +several functions that e.g. access the data structures in an unsafe way, +as in @code{race} and @code{const}, or to provide more specific +information, such as naming a signal in a function marked with +@code{sig}. It is envisioned that it may be applied to @code{lock} and +@code{corrupt} as well in the future. + +In most cases, the identifier will name a set of functions, but it may +name global objects or function arguments, or identifiable properties or +logical components associated with them, with a notation such as +e.g. @code{:buf(arg)} to denote a buffer associated with the argument +@var{arg}, or @code{:tcattr(fd)} to denote the terminal attributes of a +file descriptor @var{fd}. + +The most common use for identifiers is to provide logical groups of +functions and arguments that need to be protected by the same +synchronization primitive in order to ensure safe operation in a given +context. + + +@item @code{/condition} +@cindex /condition + +Some safety annotations may be conditional, in that they only apply if a +boolean expression involving arguments, global variables or even the +underlying kernel evaluates evaluates to true. Such conditions as +@code{/hurd} or @code{/!linux!bsd} indicate the preceding marker only +applies when the underlying kernel is the HURD, or when it is neither +Linux nor a BSD kernel, respectively. @code{/!ps} and +@code{/one_per_line} indicate the preceding marker only applies when +argument @var{ps} is NULL, or global variable @var{one_per_line} is +nonzero. + +When all marks that render a function unsafe are adorned with such +conditions, and none of the named conditions hold, then the function can +be regarded as safe. + + +@end itemize + @node Berkeley Unix, SVID, POSIX, Standards and Portability @subsection Berkeley Unix @@ -556,19 +1283,59 @@ Here is an overview of the contents of the remaining chapters of this manual. +@c The chapter overview ordering is: +@c Error Reporting (2) +@c Virtual Memory Allocation and Paging (3) +@c Character Handling (4) +@c Strings and Array Utilities (5) +@c Character Set Handling (6) +@c Locales and Internationalization (7) +@c Searching and Sorting (9) +@c Pattern Matching (10) +@c Input/Output Overview (11) +@c Input/Output on Streams (12) +@c Low-level Input/Ooutput (13) +@c File System Interface (14) +@c Pipes and FIFOs (15) +@c Sockets (16) +@c Low-Level Terminal Interface (17) +@c Syslog (18) +@c Mathematics (19) +@c Aritmetic Functions (20) +@c Date and Time (21) +@c Non-Local Exist (23) +@c Signal Handling (24) +@c The Basic Program/System Interface (25) +@c Processes (26) +@c Job Control (28) +@c System Databases and Name Service Switch (29) +@c Users and Groups (30) -- References `User Database' and `Group Database' +@c System Management (31) +@c System Configuration Parameters (32) +@c C Language Facilities in the Library (AA) +@c Summary of Library Facilities (AB) +@c Installing (AC) +@c Library Maintenance (AD) + +@c The following chapters need overview text to be added: +@c Message Translation (8) +@c Resource Usage And Limitations (22) +@c Inter-Process Communication (27) +@c DES Encryption and Password Handling (33) +@c Debugging support (34) +@c POSIX Threads (35) +@c Internal Probes (36) +@c Platform-specific facilities (AE) +@c Contributors to (AF) +@c Free Software Needs Free Documentation (AG) +@c GNU Lesser General Public License (AH) +@c GNU Free Documentation License (AI) + @itemize @bullet @item @ref{Error Reporting}, describes how errors detected by the library are reported. -@item -@ref{Language Features}, contains information about library support for -standard parts of the C language, including things like the @code{sizeof} -operator and the symbolic constant @code{NULL}, how to write functions -accepting variable numbers of arguments, and constants describing the -ranges and other properties of the numerical types. There is also a simple -debugging mechanism which allows you to put assertions in your code, and -have diagnostic messages printed if the tests fail. @item @ref{Memory}, describes @theglibc{}'s facilities for managing and @@ -588,6 +1355,26 @@ byte arrays, including operations such as copying and comparison. @item +@ref{Character Set Handling}, contains information about manipulating +characters and strings using character sets larger than will fit in +the usual @code{char} data type. + +@item +@ref{Locales}, describes how selecting a particular country +or language affects the behavior of the library. For example, the locale +affects collation sequences for strings and how monetary values are +formatted. + +@item +@ref{Searching and Sorting}, contains information about functions +for searching and sorting arrays. You can use these functions on any +kind of array by providing an appropriate comparison function. + +@item +@ref{Pattern Matching}, presents functions for matching regular expressions +and shell file name patterns, and for expanding words as the shell does. + +@item @ref{I/O Overview}, gives an overall look at the input and output facilities in the library, and contains information about basic concepts such as file names. @@ -639,30 +1426,10 @@ numbers from strings. @item -@ref{Searching and Sorting}, contains information about functions -for searching and sorting arrays. You can use these functions on any -kind of array by providing an appropriate comparison function. - -@item -@ref{Pattern Matching}, presents functions for matching regular expressions -and shell file name patterns, and for expanding words as the shell does. - -@item @ref{Date and Time}, describes functions for measuring both calendar time and CPU time, as well as functions for setting alarms and timers. @item -@ref{Character Set Handling}, contains information about manipulating -characters and strings using character sets larger than will fit in -the usual @code{char} data type. - -@item -@ref{Locales}, describes how selecting a particular country -or language affects the behavior of the library. For example, the locale -affects collation sequences for strings and how monetary values are -formatted. - -@item @ref{Non-Local Exits}, contains descriptions of the @code{setjmp} and @code{longjmp} functions. These functions provide a facility for @code{goto}-like jumps which can jump from one function to another. @@ -708,6 +1475,15 @@ compatibility with POSIX. @item +@ref{Language Features}, contains information about library support for +standard parts of the C language, including things like the @code{sizeof} +operator and the symbolic constant @code{NULL}, how to write functions +accepting variable numbers of arguments, and constants describing the +ranges and other properties of the numerical types. There is also a simple +debugging mechanism which allows you to put assertions in your code, and +have diagnostic messages printed if the tests fail. + +@item @ref{Library Summary}, gives a summary of all the functions, variables, and macros in the library, with complete data types and function prototypes, and says what standard or system each is derived from. diff -urN glibc-2.17-c758a686/manual/ipc.texi glibc-2.17-c758a686/manual/ipc.texi --- glibc-2.17-c758a686/manual/ipc.texi 1969-12-31 19:00:00.000000000 -0500 +++ glibc-2.17-c758a686/manual/ipc.texi 2014-09-12 16:10:06.047792712 -0400 @@ -0,0 +1,116 @@ +@node Inter-Process Communication, Job Control, Processes, Top +@c %MENU% All about inter-process communication +@chapter Inter-Process Communication +@cindex ipc + +This chapter describes the @glibcadj{} inter-process communication primitives. + +@menu +* Semaphores:: Support for creating and managing semaphores +@end menu + +@node Semaphores +@section Semaphores + +@Theglibc{} implements the semaphore APIs as defined in POSIX and +System V. Semaphores can be used by multiple processes to coordinate shared +resources. The following is a complete list of the semaphore functions provided +by @theglibc{}. + +@c Need descriptions for all of these functions. + +@subsection System V Semaphores +@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}} +@c syscall(ipc) ok +@c +@c AC-unsafe because we need to translate the new kernel +@c semid_ds buf into the userspace layout. Cancellation +@c at that point results in an inconsistent userspace +@c semid_ds. +@end deftypefun + +@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c syscall(ipc) ok +@end deftypefun + +@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c syscall(ipc) ok +@end deftypefun + +@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c syscall(ipc) ok +@end deftypefun + +@subsection POSIX Semaphores + +@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@c Does not atomically update sem_t therefore AC-unsafe +@c because it can leave sem_t partially initialized. +@end deftypefun + +@deftypefun int sem_destroy (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Function does nothing and is therefore always safe. +@end deftypefun + +@deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...); +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}} +@c pthread_once asuinit +@c +@c We are AC-Unsafe becuase we use pthread_once to initialize +@c a global variable that holds the location of the mounted +@c shmfs on Linux. +@end deftypefun + +@deftypefun int sem_close (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c lll_lock asulock aculock +@c twalk mtsrace{:root} +@c +@c We are AS-unsafe because we take a non-recursive lock. +@c We are AC-unsafe because several internal data structures +@c are not updated atomically. +@end deftypefun + +@deftypefun int sem_unlink (const char *@var{name}); +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}} +@c pthread_once asuinit acucorrupt aculock +@c mempcpy acucorrupt +@end deftypefun + +@deftypefun int sem_wait (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@c atomic_increment (nwaiters) acucorrupt +@c +@c Given the use atomic operations this function seems +@c to be AS-safe. It is AC-unsafe because there is still +@c a window between atomic_decrement and the pthread_push +@c of the handler that undoes that operation. A cancellation +@c at that point would fail to remove the process from the +@c waiters count. +@end deftypefun + +@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@c Same safety issues as sem_wait. +@end deftypefun + +@deftypefun int sem_trywait (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c All atomic operations are safe in all contexts. +@end deftypefun + +@deftypefun int sem_post (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Same safety as sem_trywait. +@end deftypefun + +@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Atomic write of a value is safe in all contexts. +@end deftypefun diff -urN glibc-2.17-c758a686/manual/job.texi glibc-2.17-c758a686/manual/job.texi --- glibc-2.17-c758a686/manual/job.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/job.texi 2014-09-12 16:10:06.048792709 -0400 @@ -1,4 +1,4 @@ -@node Job Control, Name Service Switch, Processes, Top +@node Job Control, Name Service Switch, Inter-Process Communication, Top @c %MENU% All about process groups and sessions @chapter Job Control @@ -1039,6 +1039,10 @@ @comment stdio.h @comment POSIX.1 @deftypefun {char *} ctermid (char *@var{string}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This function is a stub by default; the actual implementation, for +@c posix systems, returns an internal buffer if passed a NULL string, +@c but the internal buffer is always set to /dev/tty. The @code{ctermid} function returns a string containing the file name of the controlling terminal for the current process. If @var{string} is not a null pointer, it should be an array that can hold at least @@ -1075,6 +1079,12 @@ @comment unistd.h @comment POSIX.1 @deftypefun pid_t setsid (void) +@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 +@c uses a mutex and a hurd critical section, and the latter issues a few +@c syscalls, so both seem safe, the locking on Hurd is safe because of +@c the critical section. The @code{setsid} function creates a new session. The calling process becomes the session leader, and is put in a new process group whose process group ID is the same as the process ID of that process. There @@ -1098,6 +1108,8 @@ @comment unistd.h @comment SVID @deftypefun pid_t getsid (pid_t @var{pid}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Stub or direct syscall, except on hurd, where it is equally safe. The @code{getsid} function returns the process group ID of the session leader of the specified process. If a @var{pid} is @code{0}, the @@ -1118,39 +1130,21 @@ @end table @end deftypefun -The @code{getpgrp} function has two definitions: one derived from BSD -Unix, and one from the POSIX.1 standard. The feature test macros you -have selected (@pxref{Feature Test Macros}) determine which definition -you get. Specifically, you get the BSD version if you define -@code{_BSD_SOURCE}; otherwise, you get the POSIX version if you define -@code{_POSIX_SOURCE} or @code{_GNU_SOURCE}. Programs written for old -BSD systems will not include @file{unistd.h}, which defines -@code{getpgrp} specially under @code{_BSD_SOURCE}. You must link such -programs with the @code{-lbsd-compat} option to get the BSD definition.@refill -@pindex -lbsd-compat -@pindex bsd-compat -@cindex BSD compatibility library - @comment unistd.h @comment POSIX.1 -@deftypefn {POSIX.1 Function} pid_t getpgrp (void) -The POSIX.1 definition of @code{getpgrp} returns the process group ID of +@deftypefun pid_t getpgrp (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +The @code{getpgrp} function returns the process group ID of the calling process. -@end deftypefn - -@comment unistd.h -@comment BSD -@deftypefn {BSD Function} pid_t getpgrp (pid_t @var{pid}) -The BSD definition of @code{getpgrp} returns the process group ID of the -process @var{pid}. You can supply a value of @code{0} for the @var{pid} -argument to get information about the calling process. -@end deftypefn +@end deftypefun @comment unistd.h -@comment SVID -@deftypefn {System V Function} int getpgid (pid_t @var{pid}) +@comment POSIX.1 +@deftypefun int getpgid (pid_t @var{pid}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Stub or direct syscall, except on hurd, where it is equally safe. -@code{getpgid} is the same as the BSD function @code{getpgrp}. It +The @code{getpgid} function returns the process group ID of the process @var{pid}. You can supply a value of @code{0} for the @var{pid} argument to get information about the calling process. @@ -1166,11 +1160,13 @@ process group ID of the process with ID @var{pid} from the calling process. @end table -@end deftypefn +@end deftypefun @comment unistd.h @comment POSIX.1 @deftypefun int setpgid (pid_t @var{pid}, pid_t @var{pgid}) +@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 group @var{pgid}. As a special case, either @var{pid} or @var{pgid} can be zero to indicate the process ID of the calling process. @@ -1208,6 +1204,8 @@ @comment unistd.h @comment BSD @deftypefun int setpgrp (pid_t @var{pid}, pid_t @var{pgid}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall or setpgid wrapper. This is the BSD Unix name for @code{setpgid}. Both functions do exactly the same thing. @end deftypefun @@ -1230,6 +1228,8 @@ @comment unistd.h @comment POSIX.1 @deftypefun pid_t tcgetpgrp (int @var{filedes}) +@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 group associated with the terminal open on descriptor @var{filedes}. @@ -1258,6 +1258,8 @@ @comment unistd.h @comment POSIX.1 @deftypefun int tcsetpgrp (int @var{filedes}, pid_t @var{pgid}) +@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. The argument @var{filedes} is a descriptor which specifies the terminal; @var{pgid} specifies the process group. The calling process must be a @@ -1297,6 +1299,8 @@ @comment termios.h @comment Unix98 @deftypefun pid_t tcgetsid (int @var{fildes}) +@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 for which the terminal specified by @var{fildes} is the controlling terminal. If the call is successful the group ID is returned. Otherwise the diff -urN glibc-2.17-c758a686/manual/lang.texi glibc-2.17-c758a686/manual/lang.texi --- glibc-2.17-c758a686/manual/lang.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/lang.texi 2014-09-12 16:10:06.045792717 -0400 @@ -51,6 +51,8 @@ @comment assert.h @comment ISO @deftypefn Macro void assert (int @var{expression}) +@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 this point in the program. @@ -91,6 +93,8 @@ @comment assert.h @comment GNU @deftypefn Macro void assert_perror (int @var{errnum}) +@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. If @code{NDEBUG} is not defined, @code{assert_perror} tests the value of @@ -423,6 +427,8 @@ @comment stdarg.h @comment ISO @deftypefn {Macro} void va_start (va_list @var{ap}, @var{last-required}) +@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 to the first of the optional arguments of the current function; @var{last-required} must be the last required argument to the function. @@ -431,6 +437,11 @@ @comment stdarg.h @comment ISO @deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type}) +@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 +@c the va_list object or don't modify it, this one modifies ap, and it +@c may leave it in a partially updated state. The @code{va_arg} macro returns the value of the next optional argument, and modifies the value of @var{ap} to point to the subsequent argument. Thus, successive uses of @code{va_arg} return successive optional @@ -445,6 +456,8 @@ @comment stdarg.h @comment ISO @deftypefn {Macro} void va_end (va_list @var{ap}) +@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 @code{va_arg} calls with the same @var{ap} may not work. You should invoke @code{va_end} before returning from the function in which @code{va_start} @@ -466,6 +479,8 @@ @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}) +@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 @code{va_list} even if this is not an integral type. The argument pointer in @var{dest} is initialized to point to the same argument as the @@ -1212,7 +1227,9 @@ @comment stddef.h @comment ISO @deftypefn {Macro} size_t offsetof (@var{type}, @var{member}) -This expands to a integer constant expression that is the offset of the +@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 structure member named @var{member} in the structure type @var{type}. For example, @code{offsetof (struct s, elem)} is the offset, in bytes, of the member @code{elem} in a @code{struct s}. diff -urN glibc-2.17-c758a686/manual/libc.texinfo glibc-2.17-c758a686/manual/libc.texinfo --- glibc-2.17-c758a686/manual/libc.texinfo 2014-09-12 16:08:17.677071123 -0400 +++ glibc-2.17-c758a686/manual/libc.texinfo 2014-09-12 16:10:25.996741462 -0400 @@ -7,7 +7,7 @@ @include macros.texi @comment Tell install-info what to do. -@dircategory Libraries +@dircategory Software libraries @direntry * Libc: (libc). C library. @end direntry @@ -46,7 +46,7 @@ @value{VERSION} @value{PKGVERSION}. @end ifclear -Copyright @copyright{} 1993--2012 Free Software Foundation, Inc. +Copyright @copyright{} 1993--2014 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version @@ -118,6 +118,7 @@ @include chapters.texi @node Free Manuals, Copying, Contributors, Top +@appendix Free Software Needs Free Documentation @include freemanuals.texi @node Copying, Documentation License, Free Manuals, Top diff -urN glibc-2.17-c758a686/manual/libc-texinfo.sh glibc-2.17-c758a686/manual/libc-texinfo.sh --- glibc-2.17-c758a686/manual/libc-texinfo.sh 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/libc-texinfo.sh 2014-09-12 16:10:06.042792724 -0400 @@ -91,9 +91,11 @@ * Variable Index:: Index of variables and variable-like macros. * File Index:: Index of programs and files. + @detailmenu --- The Detailed Node Listing --- EOF cat ${OUTDIR}lmenu.$$ + echo '@end detailmenu' echo '@end menu'; } >${OUTDIR}top-menu.texi.$$ mv -f ${OUTDIR}top-menu.texi.$$ ${OUTDIR}top-menu.texi diff -urN glibc-2.17-c758a686/manual/libdl.texi glibc-2.17-c758a686/manual/libdl.texi --- glibc-2.17-c758a686/manual/libdl.texi 1969-12-31 19:00:00.000000000 -0500 +++ glibc-2.17-c758a686/manual/libdl.texi 2014-09-12 16:10:06.045792717 -0400 @@ -0,0 +1,10 @@ +@c FIXME these are undocumented: +@c dladdr +@c dladdr1 +@c dlclose +@c dlerror +@c dlinfo +@c dlmopen +@c dlopen +@c dlsym +@c dlvsym diff -urN glibc-2.17-c758a686/manual/llio.texi glibc-2.17-c758a686/manual/llio.texi --- glibc-2.17-c758a686/manual/llio.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/llio.texi 2014-09-12 16:10:06.047792712 -0400 @@ -78,6 +82,7 @@ @comment fcntl.h @comment POSIX.1 @deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}]) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} The @code{open} function creates and returns a new file descriptor for the file named by @var{filename}. Initially, the file position indicator for the file is at the beginning of the file. The argument @@ -164,6 +169,7 @@ @comment fcntl.h @comment Unix98 @deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}]) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function is similar to @code{open}. It returns a file descriptor which can be used to access the file named by @var{filename}. The only difference is that on 32 bit systems the file is opened in the @@ -178,6 +184,7 @@ @comment fcntl.h @comment POSIX.1 @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function is obsolete. The call: @smallexample @@ -202,6 +209,7 @@ @comment fcntl.h @comment Unix98 @deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function is similar to @code{creat}. It returns a file descriptor which can be used to access the file named by @var{filename}. The only the difference is that on 32 bit systems the file is opened in the @@ -219,6 +227,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int close (int @var{filedes}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} The function @code{close} closes the file descriptor @var{filedes}. Closing a file has the following consequences: @@ -300,6 +309,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{read} function reads up to @var{size} bytes from the file with descriptor @var{filedes}, storing the results in the @var{buffer}. (This is not necessarily a character string, and no terminating null @@ -395,6 +405,10 @@ @comment unistd.h @comment Unix98 @deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is usually a safe syscall. The sysdeps/posix fallback emulation +@c is not MT-Safe because it uses lseek, read and lseek back, but is it +@c used anywhere? The @code{pread} function is similar to the @code{read} function. The first three arguments are identical, and the return values and error codes also correspond. @@ -430,6 +444,10 @@ @comment unistd.h @comment Unix98 @deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is usually a safe syscall. The sysdeps/posix fallback emulation +@c is not MT-Safe because it uses lseek64, read and lseek64 back, but is +@c it used anywhere? This function is similar to the @code{pread} function. The difference is that the @var{offset} parameter is of type @code{off64_t} instead of @code{off_t} which makes it possible on 32 bit machines to address @@ -447,6 +465,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{write} function writes up to @var{size} bytes from @var{buffer} to the file with descriptor @var{filedes}. The data in @var{buffer} is not necessarily a character string and a null character is @@ -557,6 +576,10 @@ @comment unistd.h @comment Unix98 @deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is usually a safe syscall. The sysdeps/posix fallback emulation +@c is not MT-Safe because it uses lseek, write and lseek back, but is it +@c used anywhere? The @code{pwrite} function is similar to the @code{write} function. The first three arguments are identical, and the return values and error codes also correspond. @@ -592,6 +615,10 @@ @comment unistd.h @comment Unix98 @deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is usually a safe syscall. The sysdeps/posix fallback emulation +@c is not MT-Safe because it uses lseek64, write and lseek64 back, but +@c is it used anywhere? This function is similar to the @code{pwrite} function. The difference is that the @var{offset} parameter is of type @code{off64_t} instead of @code{off_t} which makes it possible on 32 bit machines to address @@ -624,6 +651,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{lseek} function is used to change the file position of the file with descriptor @var{filedes}. @@ -713,6 +741,7 @@ @comment unistd.h @comment Unix98 @deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to the @code{lseek} function. The difference is that the @var{offset} parameter is of type @code{off64_t} instead of @code{off_t} which makes it possible on 32 bit machines to address @@ -825,6 +854,7 @@ @comment stdio.h @comment POSIX.1 @deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} The @code{fdopen} function returns a new stream for the file descriptor @var{filedes}. @@ -853,6 +883,7 @@ @comment stdio.h @comment POSIX.1 @deftypefun int fileno (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns the file descriptor associated with the stream @var{stream}. If an error is detected (for example, if the @var{stream} is not valid) or if @var{stream} does not do I/O to a file, @@ -862,6 +893,7 @@ @comment stdio.h @comment GNU @deftypefun int fileno_unlocked (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fileno_unlocked} function is equivalent to the @code{fileno} function except that it does not implicitly lock the stream if the state is @code{FSETLOCKING_INTERNAL}. @@ -1055,7 +1087,7 @@ @comment BSD @deftp {Data Type} {struct iovec} -The @code{iovec} structure describes a buffer. It contains two fields: +The @code{iovec} structure describes a buffer. It contains two fields: @table @code @@ -1071,6 +1103,11 @@ @comment sys/uio.h @comment BSD @deftypefun ssize_t readv (int @var{filedes}, const struct iovec *@var{vector}, int @var{count}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c The fallback sysdeps/posix implementation, used even on GNU/Linux +@c with old kernels that lack a full readv/writev implementation, may +@c malloc the buffer into which data is read, if the total read size is +@c too large for alloca. The @code{readv} function reads data from @var{filedes} and scatters it into the buffers described in @var{vector}, which is taken to be @@ -1089,6 +1126,11 @@ @comment sys/uio.h @comment BSD @deftypefun ssize_t writev (int @var{filedes}, const struct iovec *@var{vector}, int @var{count}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c The fallback sysdeps/posix implementation, used even on GNU/Linux +@c with old kernels that lack a full readv/writev implementation, may +@c malloc the buffer from which data is written, if the total write size +@c is too large for alloca. The @code{writev} function gathers data from the buffers described in @var{vector}, which is taken to be @var{count} structures long, and writes @@ -1103,8 +1145,8 @@ @end deftypefun -@c Note - I haven't read this anywhere. I surmised it from my knowledge -@c of computer science. Thus, there could be subtleties I'm missing. +@c Note - I haven't read this anywhere. I surmised it from my knowledge +@c of computer science. Thus, there could be subtleties I'm missing. Note that if the buffers are small (under about 1kB), high-level streams may be easier to use than these functions. However, @code{readv} and @@ -1149,6 +1191,7 @@ @comment sys/mman.h @comment POSIX @deftypefun {void *} mmap (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{mmap} function creates a new mapping, connected to bytes (@var{offset}) to (@var{offset} + @var{length} - 1) in the file open on @@ -1156,8 +1199,8 @@ is created, which is not removed by closing the file. @var{address} gives a preferred starting address for the mapping. -@code{NULL} expresses no preference. Any previous mapping at that -address is automatically removed. The address you give may still be +@code{NULL} expresses no preference. Any previous mapping at that +address is automatically removed. The address you give may still be changed, unless you use the @code{MAP_FIXED} flag. @vindex PROT_READ @@ -1221,13 +1264,13 @@ @c Linux has some other MAP_ options, which I have not discussed here. @c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to -@c user programs (and I don't understand the last two). MAP_LOCKED does +@c user programs (and I don't understand the last two). MAP_LOCKED does @c not appear to be implemented. @end vtable -@code{mmap} returns the address of the new mapping, or @math{-1} for an -error. +@code{mmap} returns the address of the new mapping, or +@code{MAP_FAILED} for an error. Possible errors include: @@ -1268,6 +1311,9 @@ @comment sys/mman.h @comment LFS @deftypefun {void *} mmap64 (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off64_t @var{offset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c The page_shift auto detection when MMAP2_PAGE_SHIFT is -1 (it never +@c is) would be thread-unsafe. The @code{mmap64} function is equivalent to the @code{mmap} function but the @var{offset} parameter is of type @code{off64_t}. On 32-bit systems this allows the file associated with the @var{filedes} descriptor to be @@ -1284,6 +1330,7 @@ @comment sys/mman.h @comment POSIX @deftypefun int munmap (void *@var{addr}, size_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} + @var{length}). @var{length} should be the length of the mapping. @@ -1310,6 +1357,7 @@ @comment sys/mman.h @comment POSIX @deftypefun int msync (void *@var{address}, size_t @var{length}, int @var{flags}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} When using shared mappings, the kernel can write the file at any time before the mapping is removed. To be certain data has actually been @@ -1357,17 +1405,18 @@ @comment sys/mman.h @comment GNU @deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function can be used to change the size of an existing memory area. @var{address} and @var{length} must cover a region entirely mapped -in the same @code{mmap} statement. A new mapping with the same +in the same @code{mmap} statement. A new mapping with the same characteristics will be returned with the length @var{new_length}. -One option is possible, @code{MREMAP_MAYMOVE}. If it is given in +One option is possible, @code{MREMAP_MAYMOVE}. If it is given in @var{flags}, the system may remove the existing mapping and create a new one of the desired length in another location. -The address of the resulting mapping is returned, or @math{-1}. Possible +The address of the resulting mapping is returned, or @math{-1}. Possible error codes include: @table @code @@ -1405,6 +1454,7 @@ @comment sys/mman.h @comment POSIX @deftypefun int madvise (void *@var{addr}, size_t @var{length}, int @var{advice}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function can be used to provide the system with @var{advice} about the intended usage patterns of the memory region starting at @var{addr} @@ -1418,11 +1468,11 @@ The region should receive no further special treatment. @item MADV_RANDOM -The region will be accessed via random page references. The kernel +The region will be accessed via random page references. The kernel should page-in the minimal number of pages for each page fault. @item MADV_SEQUENTIAL -The region will be accessed via sequential page references. This +The region will be accessed via sequential page references. This may cause the kernel to aggressively read-ahead, expecting further sequential references after any page fault within this region. @@ -1471,6 +1521,58 @@ @end table @end deftypefun +@comment sys/mman.h +@comment POSIX +@deftypefn Function int shm_open (const char *@var{name}, int @var{oflag}, mode_t @var{mode}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c shm_open @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_once(where_is_shmfs) @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd +@c where_is_shmfs @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c statfs dup ok +@c setmntent dup @ascuheap @asulock @acsmem @acsfd @aculock +@c getmntent_r dup @mtslocale @ascuheap @aculock @acsmem [no @asucorrupt @acucorrupt; exclusive stream] +@c strcmp dup ok +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c mempcpy dup ok +@c endmntent dup @ascuheap @asulock @aculock @acsmem @acsfd +@c strlen dup ok +@c strchr dup ok +@c mempcpy dup ok +@c open dup @acsfd +@c fcntl dup ok +@c close dup @acsfd + +This function returns a file descriptor that can be used to allocate shared +memory via mmap. Unrelated processes can use same @var{name} to create or +open existing shared memory objects. + +A @var{name} argument specifies the shared memory object to be opened. +In @theglibc{} it must be a string smaller than @code{NAME_MAX} bytes starting +with an optional slash but containing no other slashes. + +The semantics of @var{oflag} and @var{mode} arguments is same as in @code{open}. + +@code{shm_open} returns the file descriptor on success or @math{-1} on error. +On failure @code{errno} is set. +@end deftypefn + +@deftypefn Function int shm_unlink (const char *@var{name}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c shm_unlink @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_once(where_is_shmfs) dup @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd +@c strlen dup ok +@c strchr dup ok +@c mempcpy dup ok +@c unlink dup ok + +This function is inverse of @code{shm_open} and removes the object with +the given @var{name} previously created by @code{shm_open}. + +@code{shm_unlink} returns @math{0} on success or @math{-1} on error. +On failure @code{errno} is set. +@end deftypefn + @node Waiting for I/O @section Waiting for Input or Output @cindex waiting for input or output @@ -1531,6 +1633,7 @@ @comment sys/types.h @comment BSD @deftypefn Macro void FD_ZERO (fd_set *@var{set}) +@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} This macro initializes the file descriptor set @var{set} to be the empty set. @end deftypefn @@ -1538,6 +1641,9 @@ @comment sys/types.h @comment BSD @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set}) +@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} +@c Setting a bit isn't necessarily atomic, so there's a potential race +@c here if set is not used exclusively. This macro adds @var{filedes} to the file descriptor set @var{set}. The @var{filedes} parameter must not have side effects since it is @@ -1547,6 +1653,9 @@ @comment sys/types.h @comment BSD @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set}) +@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} +@c Setting a bit isn't necessarily atomic, so there's a potential race +@c here if set is not used exclusively. This macro removes @var{filedes} from the file descriptor set @var{set}. The @var{filedes} parameter must not have side effects since it is @@ -1556,6 +1665,7 @@ @comment sys/types.h @comment BSD @deftypefn Macro int FD_ISSET (int @var{filedes}, const fd_set *@var{set}) +@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}} This macro returns a nonzero value (true) if @var{filedes} is a member of the file descriptor set @var{set}, and zero (false) otherwise. @@ -1568,6 +1678,10 @@ @comment sys/types.h @comment BSD @deftypefun int select (int @var{nfds}, fd_set *@var{read-fds}, fd_set *@var{write-fds}, fd_set *@var{except-fds}, struct timeval *@var{timeout}) +@safety{@prelim{}@mtsafe{@mtsrace{:read-fds} @mtsrace{:write-fds} @mtsrace{:except-fds}}@assafe{}@acsafe{}} +@c The select syscall is preferred, but pselect6 may be used instead, +@c which requires converting timeout to a timespec and back. The +@c conversions are not atomic. The @code{select} function blocks the calling process until there is activity on any of the specified sets of file descriptors, or until the timeout period has expired. @@ -1669,15 +1783,14 @@ @comment unistd.h @comment X/Open -@deftypefun int sync (void) +@deftypefun void sync (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} A call to this function will not return as long as there is data which has not been written to the device. All dirty buffers in the kernel will be written and so an overall consistent system can be achieved (if no other process in parallel writes data). A prototype for @code{sync} can be found in @file{unistd.h}. - -The return value is zero to indicate no error. @end deftypefun Programs more often want to ensure that data written to a given file is @@ -1687,6 +1800,7 @@ @comment unistd.h @comment POSIX @deftypefun int fsync (int @var{fildes}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fsync} function can be used to make sure all data associated with the open file @var{fildes} is written to the device associated with the descriptor. The function call does not return unless all actions have @@ -1724,6 +1838,7 @@ @comment unistd.h @comment POSIX @deftypefun int fdatasync (int @var{fildes}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} When a call to the @code{fdatasync} function returns, it is ensured that all of the file data is written to the device. For all pending I/O operations, the parts guaranteeing data integrity finished. @@ -1925,6 +2040,158 @@ @comment aio.h @comment POSIX.1b @deftypefun int aio_read (struct aiocb *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} +@c Calls aio_enqueue_request. +@c aio_enqueue_request @asulock @ascuheap @aculock @acsmem +@c pthread_self ok +@c pthread_getschedparam @asulock @aculock +@c lll_lock (pthread descriptor's lock) @asulock @aculock +@c sched_getparam ok +@c sched_getscheduler ok +@c lll_unlock @aculock +@c pthread_mutex_lock (aio_requests_mutex) @asulock @aculock +@c get_elem @ascuheap @acsmem [@asucorrupt @acucorrupt] +@c realloc @ascuheap @acsmem +@c calloc @ascuheap @acsmem +@c aio_create_helper_thread @asulock @ascuheap @aculock @acsmem +@c pthread_attr_init ok +@c pthread_attr_setdetachstate ok +@c pthread_get_minstack ok +@c pthread_attr_setstacksize ok +@c sigfillset ok +@c memset ok +@c sigdelset ok +@c SYSCALL rt_sigprocmask ok +@c pthread_create @asulock @ascuheap @aculock @acsmem +@c lll_lock (default_pthread_attr_lock) @asulock @aculock +@c alloca/malloc @ascuheap @acsmem +@c lll_unlock @aculock +@c allocate_stack @asulock @ascuheap @aculock @acsmem +@c getpagesize dup +@c lll_lock (default_pthread_attr_lock) @asulock @aculock +@c lll_unlock @aculock +@c _dl_allocate_tls @ascuheap @acsmem +@c _dl_allocate_tls_storage @ascuheap @acsmem +@c memalign @ascuheap @acsmem +@c memset ok +@c allocate_dtv dup +@c free @ascuheap @acsmem +@c allocate_dtv @ascuheap @acsmem +@c calloc @ascuheap @acsmem +@c INSTALL_DTV ok +@c list_add dup +@c get_cached_stack +@c lll_lock (stack_cache_lock) @asulock @aculock +@c list_for_each ok +@c list_entry dup +@c FREE_P dup +@c stack_list_del dup +@c stack_list_add dup +@c lll_unlock @aculock +@c _dl_allocate_tls_init ok +@c GET_DTV ok +@c mmap ok +@c atomic_increment_val ok +@c munmap ok +@c change_stack_perm ok +@c mprotect ok +@c mprotect ok +@c stack_list_del dup +@c _dl_deallocate_tls dup +@c munmap ok +@c THREAD_COPY_STACK_GUARD ok +@c THREAD_COPY_POINTER_GUARD ok +@c atomic_exchange_acq ok +@c lll_futex_wake ok +@c deallocate_stack @asulock @ascuheap @aculock @acsmem +@c lll_lock (state_cache_lock) @asulock @aculock +@c stack_list_del ok +@c atomic_write_barrier ok +@c list_del ok +@c atomic_write_barrier ok +@c queue_stack @ascuheap @acsmem +@c stack_list_add ok +@c atomic_write_barrier ok +@c list_add ok +@c atomic_write_barrier ok +@c free_stacks @ascuheap @acsmem +@c list_for_each_prev_safe ok +@c list_entry ok +@c FREE_P ok +@c stack_list_del dup +@c _dl_deallocate_tls dup +@c munmap ok +@c _dl_deallocate_tls @ascuheap @acsmem +@c free @ascuheap @acsmem +@c lll_unlock @aculock +@c create_thread @asulock @ascuheap @aculock @acsmem +@c td_eventword +@c td_eventmask +@c do_clone @asulock @ascuheap @aculock @acsmem +@c PREPARE_CREATE ok +@c lll_lock (pd->lock) @asulock @aculock +@c atomic_increment ok +@c clone ok +@c atomic_decrement ok +@c atomic_exchange_acq ok +@c lll_futex_wake ok +@c deallocate_stack dup +@c sched_setaffinity ok +@c tgkill ok +@c sched_setscheduler ok +@c atomic_compare_and_exchange_bool_acq ok +@c nptl_create_event ok +@c lll_unlock (pd->lock) @aculock +@c free @ascuheap @acsmem +@c pthread_attr_destroy ok (cpuset won't be set, so free isn't called) +@c add_request_to_runlist ok +@c pthread_cond_signal ok +@c aio_free_request ok +@c pthread_mutex_unlock @aculock + +@c (in the new thread, initiated with clone) +@c start_thread ok +@c HP_TIMING_NOW ok +@c ctype_init @mtslocale +@c atomic_exchange_acq ok +@c lll_futex_wake ok +@c sigemptyset ok +@c sigaddset ok +@c setjmp ok +@c CANCEL_ASYNC -> pthread_enable_asynccancel ok +@c do_cancel ok +@c pthread_unwind ok +@c Unwind_ForcedUnwind or longjmp ok [@ascuheap @acsmem?] +@c lll_lock @asulock @aculock +@c lll_unlock @asulock @aculock +@c CANCEL_RESET -> pthread_disable_asynccancel ok +@c lll_futex_wait ok +@c ->start_routine ok ----- +@c call_tls_dtors @asulock @ascuheap @aculock @acsmem +@c user-supplied dtor +@c rtld_lock_lock_recursive (dl_load_lock) @asulock @aculock +@c rtld_lock_unlock_recursive @aculock +@c free @ascuheap @acsmem +@c nptl_deallocate_tsd @ascuheap @acsmem +@c tsd user-supplied dtors ok +@c free @ascuheap @acsmem +@c libc_thread_freeres +@c libc_thread_subfreeres ok +@c atomic_decrement_and_test ok +@c td_eventword ok +@c td_eventmask ok +@c atomic_compare_exchange_bool_acq ok +@c nptl_death_event ok +@c lll_robust_dead ok +@c getpagesize ok +@c madvise ok +@c free_tcb @asulock @ascuheap @aculock @acsmem +@c free @ascuheap @acsmem +@c deallocate_stack @asulock @ascuheap @aculock @acsmem +@c lll_futex_wait ok +@c exit_thread_inline ok +@c syscall(exit) ok + This function initiates an asynchronous read operation. It immediately returns after the operation was enqueued or when an error was encountered. @@ -1989,7 +2256,8 @@ @comment aio.h @comment Unix98 -@deftypefun int aio_read64 (struct aiocb *@var{aiocbp}) +@deftypefun int aio_read64 (struct aiocb64 *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to the @code{aio_read} function. The only difference is that on @w{32 bit} machines, the file descriptor should be opened in the large file mode. Internally, @code{aio_read64} uses @@ -2008,13 +2276,14 @@ @comment aio.h @comment POSIX.1b @deftypefun int aio_write (struct aiocb *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function initiates an asynchronous write operation. The function call immediately returns after the operation was enqueued or if before this happens an error was encountered. The first @code{aiocbp->aio_nbytes} bytes from the buffer starting at @code{aiocbp->aio_buf} are written to the file for which -@code{aiocbp->aio_fildes} is an descriptor, starting at the absolute +@code{aiocbp->aio_fildes} is a descriptor, starting at the absolute position @code{aiocbp->aio_offset} in the file. If prioritized I/O is supported by the platform, the @@ -2073,7 +2342,8 @@ @comment aio.h @comment Unix98 -@deftypefun int aio_write64 (struct aiocb *@var{aiocbp}) +@deftypefun int aio_write64 (struct aiocb64 *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to the @code{aio_write} function. The only difference is that on @w{32 bit} machines the file descriptor should be opened in the large file mode. Internally @code{aio_write64} uses @@ -2095,6 +2365,12 @@ @comment aio.h @comment POSIX.1b @deftypefun int lio_listio (int @var{mode}, struct aiocb *const @var{list}[], int @var{nent}, struct sigevent *@var{sig}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} +@c Call lio_listio_internal, that takes the aio_requests_mutex lock and +@c enqueues each request. Then, it waits for notification or prepares +@c for it before releasing the lock. Even though it performs memory +@c allocation and locking of its own, it doesn't add any classes of +@c safety issues that aren't already covered by aio_enqueue_request. The @code{lio_listio} function can be used to enqueue an arbitrary number of read and write requests at one time. The requests can all be meant for the same file, all for different files or every solution in @@ -2177,7 +2453,8 @@ @comment aio.h @comment Unix98 -@deftypefun int lio_listio64 (int @var{mode}, struct aiocb *const @var{list}, int @var{nent}, struct sigevent *@var{sig}) +@deftypefun int lio_listio64 (int @var{mode}, struct aiocb64 *const @var{list}[], int @var{nent}, struct sigevent *@var{sig}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to the @code{lio_listio} function. The only difference is that on @w{32 bit} machines, the file descriptor should be opened in the large file mode. Internally, @code{lio_listio64} uses @@ -2206,6 +2483,7 @@ @comment aio.h @comment POSIX.1b @deftypefun int aio_error (const struct aiocb *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function determines the error state of the request described by the @code{struct aiocb} variable pointed to by @var{aiocbp}. If the request has not yet terminated the value returned is always @@ -2227,6 +2505,7 @@ @comment aio.h @comment Unix98 @deftypefun int aio_error64 (const struct aiocb64 *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{aio_error} with the only difference that the argument is a reference to a variable of type @code{struct aiocb64}. @@ -2239,7 +2518,8 @@ @comment aio.h @comment POSIX.1b -@deftypefun ssize_t aio_return (const struct aiocb *@var{aiocbp}) +@deftypefun ssize_t aio_return (struct aiocb *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function can be used to retrieve the return status of the operation carried out by the request described in the variable pointed to by @var{aiocbp}. As long as the error status of this request as returned @@ -2262,7 +2542,8 @@ @comment aio.h @comment Unix98 -@deftypefun int aio_return64 (const struct aiocb64 *@var{aiocbp}) +@deftypefun ssize_t aio_return64 (struct aiocb64 *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{aio_return} with the only difference that the argument is a reference to a variable of type @code{struct aiocb64}. @@ -2291,6 +2572,9 @@ @comment aio.h @comment POSIX.1b @deftypefun int aio_fsync (int @var{op}, struct aiocb *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} +@c After fcntl to check that the FD is open, it calls +@c aio_enqueue_request. Calling this function forces all I/O operations operating queued at the time of the function call operating on the file descriptor @code{aiocbp->aio_fildes} into the synchronized I/O completion state @@ -2322,8 +2606,7 @@ @item EAGAIN The request could not be enqueued due to temporary lack of resources. @item EBADF -The file descriptor @code{aiocbp->aio_fildes} is not valid or not open -for writing. +The file descriptor @code{@var{aiocbp}->aio_fildes} is not valid. @item EINVAL The implementation does not support I/O synchronization or the @var{op} parameter is other than @code{O_DSYNC} and @code{O_SYNC}. @@ -2339,6 +2622,7 @@ @comment aio.h @comment Unix98 @deftypefun int aio_fsync64 (int @var{op}, struct aiocb64 *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to @code{aio_fsync} with the only difference that the argument is a reference to a variable of type @code{struct aiocb64}. @@ -2365,6 +2649,9 @@ @comment aio.h @comment POSIX.1b @deftypefun int aio_suspend (const struct aiocb *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c Take aio_requests_mutex, set up waitlist and requestlist, wait +@c for completion or timeout, and release the mutex. When calling this function, the calling thread is suspended until at least one of the requests pointed to by the @var{nent} elements of the array @var{list} has completed. If any of the requests has already @@ -2403,6 +2690,7 @@ @comment aio.h @comment Unix98 @deftypefun int aio_suspend64 (const struct aiocb64 *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} This function is similar to @code{aio_suspend} with the only difference that the argument is a reference to a variable of type @code{struct aiocb64}. @@ -2430,6 +2718,16 @@ @comment aio.h @comment POSIX.1b @deftypefun int aio_cancel (int @var{fildes}, struct aiocb *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} +@c After fcntl to check the fd is open, hold aio_requests_mutex, call +@c aio_find_req_fd, aio_remove_request, then aio_notify and +@c aio_free_request each request before releasing the lock. +@c aio_notify calls aio_notify_only and free, besides cond signal or +@c similar. aio_notify_only calls pthread_attr_init, +@c pthread_attr_setdetachstate, malloc, pthread_create, +@c notify_func_wrapper, aio_sigqueue, getpid, raise. +@c notify_func_wraper calls aio_start_notify_thread, free and then the +@c notifier function. The @code{aio_cancel} function can be used to cancel one or more outstanding requests. If the @var{aiocbp} parameter is @code{NULL}, the function tries to cancel all of the outstanding requests which would process @@ -2477,6 +2775,7 @@ @comment aio.h @comment Unix98 @deftypefun int aio_cancel64 (int @var{fildes}, struct aiocb64 *@var{aiocbp}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} This function is similar to @code{aio_cancel} with the only difference that the argument is a reference to a variable of type @code{struct aiocb64}. @@ -2532,6 +2831,8 @@ @comment aio.h @comment GNU @deftypefun void aio_init (const struct aioinit *@var{init}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c All changes to global objects are guarded by aio_requests_mutex. This function must be called before any other AIO function. Calling it is completely voluntary, as it is only meant to help the AIO implementation perform better. @@ -2566,6 +2867,7 @@ @comment fcntl.h @comment POSIX.1 @deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{fcntl} function performs the operation specified by @var{command} on the file descriptor @var{filedes}. Some commands require additional arguments to be supplied. These additional arguments @@ -2592,7 +2894,7 @@ Set flags associated with the open file. @xref{File Status Flags}. @item F_GETLK -Get a file lock. @xref{File Locks}. +Test a file lock. @xref{File Locks}. @item F_SETLK Set or clear a file lock. @xref{File Locks}. @@ -2648,6 +2962,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int dup (int @var{old}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies descriptor @var{old} to the first available descriptor number (the first number not currently open). It is equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}. @@ -2656,6 +2971,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int dup2 (int @var{old}, int @var{new}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies the descriptor @var{old} to descriptor number @var{new}. @@ -2929,19 +3245,19 @@ But most programs will want to be portable to other POSIX.1 systems and should use the POSIX.1 names above instead. -@comment fcntl.h +@comment fcntl.h (optional) @comment GNU @deftypevr Macro int O_READ Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU. @end deftypevr -@comment fcntl.h +@comment fcntl.h (optional) @comment GNU @deftypevr Macro int O_WRITE Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU. @end deftypevr -@comment fcntl.h +@comment fcntl.h (optional) @comment GNU @deftypevr Macro int O_EXEC Open the file for executing. Only defined on GNU. @@ -3045,7 +3361,7 @@ The following three file name translation flags exist only on @gnuhurdsystems{}. -@comment fcntl.h +@comment fcntl.h (optional) @comment GNU @deftypevr Macro int O_IGNORE_CTTY Do not recognize the named file as the controlling terminal, even if it @@ -3054,7 +3370,7 @@ @xref{Job Control}. @end deftypevr -@comment fcntl.h +@comment fcntl.h (optional) @comment GNU @deftypevr Macro int O_NOLINK If the named file is a symbolic link, open the link itself instead of @@ -3063,7 +3379,7 @@ @cindex symbolic link, opening @end deftypevr -@comment fcntl.h +@comment fcntl.h (optional) @comment GNU @deftypevr Macro int O_NOTRANS If the named file is specially translated, do not invoke the translator. @@ -3095,7 +3411,7 @@ The remaining operating modes are BSD extensions. They exist only on some systems. On other systems, these macros are not defined. -@comment fcntl.h +@comment fcntl.h (optional) @comment BSD @deftypevr Macro int O_SHLOCK Acquire a shared lock on the file, as with @code{flock}. @@ -3106,7 +3422,7 @@ the lock on the new file first. @end deftypevr -@comment fcntl.h +@comment fcntl.h (optional) @comment BSD @deftypevr Macro int O_EXLOCK Acquire an exclusive lock on the file, as with @code{flock}. @@ -3599,7 +4134,7 @@ @gnusystems{} can handle most input/output operations on many different devices and objects in terms of a few file primitives - @code{read}, @code{write} and @code{lseek}. However, most devices also have a few -peculiar operations which do not fit into this model. Such as: +peculiar operations which do not fit into this model. Such as: @itemize @bullet @@ -3634,6 +4169,7 @@ @comment sys/ioctl.h @comment BSD @deftypefun int ioctl (int @var{filedes}, int @var{command}, @dots{}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{ioctl} function performs the generic I/O operation @var{command} on @var{filedes}. @@ -3653,3 +4189,6 @@ Most IOCTLs are OS-specific and/or only used in special system utilities, and are thus beyond the scope of this document. For an example of the use of an IOCTL, see @ref{Out-of-Band Data}. + +@c FIXME this is undocumented: +@c dup3 diff -urN glibc-2.17-c758a686/manual/locale.texi glibc-2.17-c758a686/manual/locale.texi --- glibc-2.17-c758a686/manual/locale.texi 2014-09-12 16:08:18.266069610 -0400 +++ glibc-2.17-c758a686/manual/locale.texi 2014-09-12 16:10:06.044792719 -0400 @@ -231,6 +231,136 @@ @comment locale.h @comment ISO @deftypefun {char *} setlocale (int @var{category}, const char *@var{locale}) +@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 +@c once threads are started. It takes a write lock itself, but it may +@c return a pointer loaded from the global locale object after releasing +@c the lock, or before taking it. +@c setlocale @mtasuconst:@mtslocale @mtsenv @asuinit @ascuheap @asulock @asucorrupt @acucorrupt @acsmem @acsfd @aculock +@c libc_rwlock_wrlock @asulock @aculock +@c libc_rwlock_unlock @aculock +@c getenv LOCPATH @mtsenv +@c malloc @ascuheap @acsmem +@c free @ascuheap @acsmem +@c new_composite_name ok +@c setdata ok +@c setname ok +@c _nl_find_locale @mtsenv @asuinit @ascuheap @asulock @asucorrupt @acucorrupt @acsmem @acsfd @aculock +@c getenv LC_ALL and LANG @mtsenv +@c _nl_load_locale_from_archive @ascuheap @acucorrupt @acsmem @acsfd +@c sysconf _SC_PAGE_SIZE ok +@c _nl_normalize_codeset @ascuheap @acsmem +@c isalnum_l ok (C locale) +@c isdigit_l ok (C locale) +@c malloc @ascuheap @acsmem +@c tolower_l ok (C locale) +@c open_not_cancel_2 @acsfd +@c fxstat64 ok +@c close_not_cancel_no_status ok +@c __mmap64 @acsmem +@c calculate_head_size ok +@c __munmap ok +@c compute_hashval ok +@c qsort dup @acucorrupt +@c rangecmp ok +@c malloc @ascuheap @acsmem +@c strdup @ascuheap @acsmem +@c _nl_intern_locale_data @ascuheap @acsmem +@c malloc @ascuheap @acsmem +@c free @ascuheap @acsmem +@c _nl_expand_alias @ascuheap @asulock @acsmem @acsfd @aculock +@c libc_lock_lock @asulock @aculock +@c bsearch ok +@c alias_compare ok +@c strcasecmp ok +@c read_alias_file @ascuheap @asulock @acsmem @acsfd @aculock +@c fopen @ascuheap @asulock @acsmem @acsfd @aculock +@c fsetlocking ok +@c feof_unlocked ok +@c fgets_unlocked ok +@c isspace ok (locale mutex is locked) +@c extend_alias_table @ascuheap @acsmem +@c realloc @ascuheap @acsmem +@c realloc @ascuheap @acsmem +@c fclose @ascuheap @asulock @acsmem @acsfd @aculock +@c qsort @ascuheap @acsmem +@c alias_compare dup +@c libc_lock_unlock @aculock +@c _nl_explode_name @ascuheap @acsmem +@c _nl_find_language ok +@c _nl_normalize_codeset dup @ascuheap @acsmem +@c _nl_make_l10nflist @ascuheap @acsmem +@c malloc @ascuheap @acsmem +@c free @ascuheap @acsmem +@c __argz_stringify ok +@c __argz_count ok +@c __argz_next ok +@c _nl_load_locale @ascuheap @acsmem @acsfd +@c open_not_cancel_2 @acsfd +@c __fxstat64 ok +@c close_not_cancel_no_status ok +@c mmap @acsmem +@c malloc @ascuheap @acsmem +@c read_not_cancel ok +@c free @ascuheap @acsmem +@c _nl_intern_locale_data dup @ascuheap @acsmem +@c munmap ok +@c __gconv_compare_alias @asuinit @ascuheap @asucorrupt @asulock @acsmem@acucorrupt @acsfd @aculock +@c __gconv_read_conf @asuinit @ascuheap @asucorrupt @asulock @acsmem@acucorrupt @acsfd @aculock +@c (libc_once-initializes gconv_cache and gconv_path_envvar; they're +@c never modified afterwards) +@c __gconv_load_cache @ascuheap @acsmem @acsfd +@c getenv GCONV_PATH @mtsenv +@c open_not_cancel @acsfd +@c __fxstat64 ok +@c close_not_cancel_no_status ok +@c mmap @acsmem +@c malloc @ascuheap @acsmem +@c __read ok +@c free @ascuheap @acsmem +@c munmap ok +@c __gconv_get_path @asulock @ascuheap @aculock @acsmem @acsfd +@c getcwd @ascuheap @acsmem @acsfd +@c libc_lock_lock @asulock @aculock +@c malloc @ascuheap @acsmem +@c strtok_r ok +@c libc_lock_unlock @aculock +@c read_conf_file @ascuheap @asucorrupt @asulock @acsmem @acucorrupt @acsfd @aculock +@c fopen @ascuheap @asulock @acsmem @acsfd @aculock +@c fsetlocking ok +@c feof_unlocked ok +@c getdelim @ascuheap @asucorrupt @acsmem @acucorrupt +@c isspace_l ok (C locale) +@c add_alias +@c isspace_l ok (C locale) +@c toupper_l ok (C locale) +@c add_alias2 dup @ascuheap @acucorrupt @acsmem +@c add_module @ascuheap @acsmem +@c isspace_l ok (C locale) +@c toupper_l ok (C locale) +@c strtol ok (@mtslocale but we hold the locale lock) +@c tfind __gconv_alias_db ok +@c __gconv_alias_compare dup ok +@c calloc @ascuheap @acsmem +@c insert_module dup @ascuheap +@c __tfind ok (because the tree is read only by then) +@c __gconv_alias_compare dup ok +@c insert_module @ascuheap +@c free @ascuheap +@c add_alias2 @ascuheap @acucorrupt @acsmem +@c detect_conflict ok, reads __gconv_modules_db +@c malloc @ascuheap @acsmem +@c tsearch __gconv_alias_db @ascuheap @acucorrupt @acsmem [exclusive tree, no @mtsrace] +@c __gconv_alias_compare ok +@c free @ascuheap +@c __gconv_compare_alias_cache ok +@c find_module_idx ok +@c do_lookup_alias ok +@c __tfind ok (because the tree is read only by then) +@c __gconv_alias_compare ok +@c strndup @ascuheap @acsmem +@c strcasecmp_l ok (C locale) The function @code{setlocale} sets the current locale for category @var{category} to @var{locale}. @@ -496,6 +626,10 @@ @comment locale.h @comment ISO @deftypefun {struct lconv *} localeconv (void) +@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 +@c as the return value. The @code{localeconv} function returns a pointer to a structure whose components contain information about how numeric and monetary values should be formatted in the current locale. @@ -762,6 +896,9 @@ @comment langinfo.h @comment XOPEN @deftypefun {char *} nl_langinfo (nl_item @var{item}) +@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. The @code{nl_langinfo} function can be used to access individual elements of the locale categories. Unlike the @code{localeconv} function, which returns all the information, @code{nl_langinfo} @@ -1056,6 +1193,11 @@ numbers according to these rules. @deftypefun ssize_t strfmon (char *@var{s}, size_t @var{maxsize}, const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c It (and strfmon_l) both call vstrfmon_l, which, besides accessing the +@c locale object passed to it, accesses the active locale through +@c isdigit (but to_digit assumes ASCII digits only). It may call +@c __printf_fp (@mtslocale @ascuheap @acsmem) and guess_grouping (safe). The @code{strfmon} function is similar to the @code{strftime} function in that it takes a buffer, its size, a format string, and values to write into the buffer as text in a form specified @@ -1267,6 +1409,10 @@ @comment GNU @comment stdlib.h @deftypefun int rpmatch (const char *@var{response}) +@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. +@c regfree is also called, but it doesn't introduce any further issues. The function @code{rpmatch} checks the string in @var{response} whether or not it is a correct yes-or-no answer and if yes, which one. The check uses the @code{YESEXPR} and @code{NOEXPR} data in the @@ -1318,5 +1464,5 @@ free (line); @end smallexample -Note that the loop continues until an read error is detected or until a +Note that the loop continues until a read error is detected or until a definitive (positive or negative) answer is read. diff -urN glibc-2.17-c758a686/manual/macros.texi glibc-2.17-c758a686/manual/macros.texi --- glibc-2.17-c758a686/manual/macros.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/macros.texi 2014-09-12 16:10:06.045792717 -0400 @@ -35,16 +35,225 @@ GNU/Linux and GNU/Hurd systems @end macro -@c Descrption applying to GNU/Hurd systems; that is, systems using the +@c Description applying to GNU/Hurd systems; that is, systems using the @c GNU Hurd with the GNU C Library. @macro gnuhurdsystems GNU/Hurd systems @end macro -@c Descrption applying to GNU/Linux systems; that is, systems using +@c Description applying to GNU/Linux systems; that is, systems using @c the Linux kernel with the GNU C Library. @macro gnulinuxsystems GNU/Linux systems @end macro +@c Document the safety functions as preliminary. It does NOT expand its +@c comments. +@macro prelim {comments} +Preliminary: + +@end macro +@c Document a function as thread safe. +@macro mtsafe {comments} +| MT-Safe \comments\ + +@end macro +@c Document a function as thread unsafe. +@macro mtunsafe {comments} +| MT-Unsafe \comments\ + +@end macro +@c Document a function as safe for use in asynchronous signal handlers. +@macro assafe {comments} +| AS-Safe \comments\ + +@end macro +@c Document a function as unsafe for use in asynchronous signal +@c handlers. This distinguishes unmarked functions, for which this +@c property has not been assessed, from those that have been analyzed. +@macro asunsafe {comments} +| AS-Unsafe \comments\ + +@end macro +@c Document a function as safe for use when asynchronous cancellation is +@c enabled. +@macro acsafe {comments} +| AC-Safe \comments\ + +@end macro +@c Document a function as unsafe for use when asynchronous cancellation +@c is enabled. This distinguishes unmarked functions, for which this +@c property has not been assessed, from those that have been analyzed. +@macro acunsafe {comments} +| AC-Unsafe \comments\ + +@end macro +@c Format safety properties without referencing the section of the +@c definitions. To be used in the definitions of the properties +@c themselves. +@macro sampsafety {notes} +@noindent +\notes\| + + +@end macro +@c Format the safety properties of a function. +@macro safety {notes} +\notes\| @xref{POSIX Safety Concepts}. + + +@end macro +@c Function is MT- and AS-Unsafe due to an internal race. +@macro mtasurace {comments} +race\comments\ +@end macro +@c Function is AS-Unsafe due to an internal race. +@macro asurace {comments} +race\comments\ +@end macro +@c Function is MT-Safe, but with potential race on user-supplied object +@c of opaque type. +@macro mtsrace {comments} +race\comments\ +@end macro +@c Function is MT- and AS-Unsafe for modifying an object that is decreed +@c MT-constant due to MT-Unsafe accesses elsewhere. +@macro mtasuconst {comments} +const\comments\ +@end macro +@c Function accesses the assumed-constant locale object. +@macro mtslocale {comments} +locale\comments\ +@end macro +@c Function accesses the assumed-constant environment. +@macro mtsenv {comments} +env\comments\ +@end macro +@c Function accesses the assumed-constant hostid. +@macro mtshostid {comments} +hostid\comments\ +@end macro +@c Function accesses the assumed-constant _sigintr variable. +@macro mtssigintr {comments} +sigintr\comments\ +@end macro +@c Function performs MT-Unsafe initialization at the first call. +@macro mtuinit {comments} +init\comments\ +@end macro +@c Function performs libc_once AS-Unsafe initialization. +@macro asuinit {comments} +init\comments\ +@end macro +@c Function performs libc_once AC-Unsafe initialization. +@macro acuinit {comments} +init\comments\ +@end macro +@c Function is AS-Unsafe because it takes a non-recursive mutex that may +@c already be held by the function interrupted by the signal. +@macro asulock {comments} +lock\comments\ +@end macro +@c Function is AC-Unsafe because it may fail to release a mutex. +@macro aculock {comments} +lock\comments\ +@end macro +@c Function is AS-Unsafe because some data structure may be inconsistent +@c due to an ongoing updated interrupted by a signal. +@macro asucorrupt {comments} +corrupt\comments\ +@end macro +@c Function is AC-Unsafe because some data structure may be left +@c inconsistent when cancelled. +@macro acucorrupt {comments} +corrupt\comments\ +@end macro +@c Function is AS- and AC-Unsafe because of malloc/free. +@macro ascuheap {comments} +heap\comments\ +@end macro +@c Function is AS-Unsafe because of malloc/free. +@macro asuheap {comments} +heap\comments\ +@end macro +@c Function is AS- and AC-Unsafe because of dlopen/dlclose. +@macro ascudlopen {comments} +dlopen\comments\ +@end macro +@c Function is AS- and AC-Unsafe because of unknown plugins. +@macro ascuplugin {comments} +plugin\comments\ +@end macro +@c Function is AS- and AC-Unsafe because of i18n. +@macro ascuintl {comments} +i18n\comments\ +@end macro +@c Function is AS--Unsafe because of i18n. +@macro asuintl {comments} +i18n\comments\ +@end macro +@c Function may leak file descriptors if async-cancelled. +@macro acsfd {comments} +fd\comments\ +@end macro +@c Function may leak memory if async-cancelled. +@macro acsmem {comments} +mem\comments\ +@end macro +@c Function is unsafe due to temporary overriding a signal handler. +@macro mtascusig {comments} +sig\comments\ +@end macro +@c Function is MT- and AS-Unsafe due to temporarily changing attributes +@c of the controlling terminal. +@macro mtasuterm {comments} +term\comments\ +@end macro +@c Function is AC-Unsafe for failing to restore attributes of the +@c controlling terminal. +@macro acuterm {comments} +term\comments\ +@end macro +@c Function sets timers atomically. +@macro mtstimer {comments} +timer\comments\ +@end macro +@c Function sets and restores timers. +@macro mtascutimer {comments} +timer\comments\ +@end macro +@c Function temporarily changes the current working directory. +@macro mtasscwd {comments} +cwd\comments\ +@end macro +@c Function may fail to restore to the original current working +@c directory after temporarily changing it. +@macro acscwd {comments} +cwd\comments\ +@end macro +@c Function is MT-Safe while POSIX says it needn't be MT-Safe. +@macro mtsposix {comments} +!posix\comments\ +@end macro +@c Function is MT-Unsafe while POSIX says it should be MT-Safe. +@macro mtuposix {comments} +!posix\comments\ +@end macro +@c Function is AS-Safe while POSIX says it needn't be AS-Safe. +@macro assposix {comments} +!posix\comments\ +@end macro +@c Function is AS-Unsafe while POSIX says it should be AS-Safe. +@macro asuposix {comments} +!posix\comments\ +@end macro +@c Function is AC-Safe while POSIX says it needn't be AC-Safe. +@macro acsposix {comments} +!posix\comments\ +@end macro +@c Function is AC-Unsafe while POSIX says it should be AC-Safe. +@macro acuposix {comments} +!posix\comments\ +@end macro + @end ifclear diff -urN glibc-2.17-c758a686/manual/maint.texi glibc-2.17-c758a686/manual/maint.texi --- glibc-2.17-c758a686/manual/maint.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/maint.texi 2014-09-12 16:10:06.045792717 -0400 @@ -316,7 +316,7 @@ The top-level @file{configure} script uses the shell @code{.} command to read the @file{configure} file in each system-dependent directory chosen, in order. The @file{configure} files are often generated from -@file{configure.in} files using Autoconf. +@file{configure.ac} files using Autoconf. A system-dependent @file{configure} script will usually add things to the shell variables @samp{DEFS} and @samp{config_vars}; see the @@ -329,14 +329,14 @@ just @w{@samp{--with-@var{package}}} (no argument), then it sets @w{@samp{with_@var{package}}} to @samp{yes}. -@item configure.in +@item configure.ac This file is an Autoconf input fragment to be processed into the file @file{configure} in this subdirectory. @xref{Introduction,,, autoconf.info, Autoconf: Generating Automatic Configuration Scripts}, for a description of Autoconf. You should write either @file{configure} -or @file{configure.in}, but not both. The first line of -@file{configure.in} should invoke the @code{m4} macro +or @file{configure.ac}, but not both. The first line of +@file{configure.ac} should invoke the @code{m4} macro @samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls for Autoconf macros which are used by the top-level @file{configure} script; without this, those macros might be invoked again unnecessarily @@ -424,7 +424,7 @@ files specific to those machine architectures, but not specific to any particular operating system. There might be subdirectories for specializations of those architectures, such as -@w{@file{sysdeps/m68k/68020}}. Code which is specific to the +@w{@file{sysdeps/m68k/68020}}. Code which is specific to the floating-point coprocessor used with a particular machine should go in @w{@file{sysdeps/@var{machine}/fpu}}. diff -urN glibc-2.17-c758a686/manual/Makefile glibc-2.17-c758a686/manual/Makefile --- glibc-2.17-c758a686/manual/Makefile 2014-09-12 16:08:17.823070748 -0400 +++ glibc-2.17-c758a686/manual/Makefile 2014-09-12 16:10:06.045792717 -0400 @@ -1,5 +1,4 @@ -# Copyright (C) 1992-2012 -# Free Software Foundation, Inc. +# Copyright (C) 1992-2014 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 @@ -20,14 +19,10 @@ subdir := manual -# Allow override -INSTALL_INFO = install-info +include ../Makeconfig .PHONY: dvi pdf info html -# Get glibc's configuration info. -include ../Makeconfig - dvi: $(objpfx)libc.dvi pdf: $(objpfx)libc.pdf @@ -42,8 +37,8 @@ intro errno memory ctype string charset locale \ message search pattern io stdio llio filesys \ pipe socket terminal syslog math arith time \ - resource setjmp signal startup process job nss \ - users sysinfo conf crypt debug probes) + resource setjmp signal startup process ipc job \ + nss users sysinfo conf crypt debug threads probes) add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi)) appendices = lang.texi header.texi install.texi maint.texi platform.texi \ contrib.texi @@ -89,6 +84,7 @@ $(objpfx)summary.texi: $(objpfx)stamp-summary ; $(objpfx)stamp-summary: summary.awk $(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 $(move-if-change) $(objpfx)summary-tmp $(objpfx)summary.texi @@ -145,8 +141,7 @@ mv -f $@.new $@ $(objpfx)%.info: %.texinfo - LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=`basename $@` $< - mv `basename $@`* $(objpfx) + LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $< $(objpfx)%.dvi: %.texinfo cd $(objpfx);$(TEXI2DVI) -I $(shell cd $(mutex) @asulock @aculock +@c malloc_consolidate dup ok +@c set_max_fast ok +@c mutex_unlock dup @aculock + When calling @code{mallopt}, the @var{param} argument specifies the parameter to be set, and @var{value} the new value to be set. Possible choices for @var{param}, as defined in @file{malloc.h}, are: @table @code -@item M_TRIM_THRESHOLD -This is the minimum size (in bytes) of the top-most, releasable chunk -that will cause @code{sbrk} to be called with a negative argument in -order to return memory to the system. -@item M_TOP_PAD -This parameter determines the amount of extra memory to obtain from the -system when a call to @code{sbrk} is required. It also specifies the -number of bytes to retain when shrinking the heap by calling @code{sbrk} -with a negative argument. This provides the necessary hysteresis in -heap size such that excessive amounts of system calls can be avoided. +@comment TODO: @item M_ARENA_MAX +@comment - Document ARENA_MAX env var. +@comment TODO: @item M_ARENA_TEST +@comment - Document ARENA_TEST env var. +@comment TODO: @item M_CHECK_ACTION +@item M_MMAP_MAX +The maximum number of chunks to allocate with @code{mmap}. Setting this +to zero disables all use of @code{mmap}. @item M_MMAP_THRESHOLD All chunks larger than this value are allocated outside the normal heap, using the @code{mmap} system call. This way it is guaranteed that the memory for these chunks can be returned to the system on @code{free}. Note that requests smaller than this threshold might still be allocated via @code{mmap}. -@item M_MMAP_MAX -The maximum number of chunks to allocate with @code{mmap}. Setting this -to zero disables all use of @code{mmap}. +@comment TODO: @item M_MXFAST @item M_PERTURB If non-zero, memory blocks are filled with values depending on some low order bits of this parameter when they are allocated (except when @@ -710,6 +1140,16 @@ guarantee that the freed block will have any specific values. It only guarantees that the content the block had before it was freed will be overwritten. +@item M_TOP_PAD +This parameter determines the amount of extra memory to obtain from the +system when a call to @code{sbrk} is required. It also specifies the +number of bytes to retain when shrinking the heap by calling @code{sbrk} +with a negative argument. This provides the necessary hysteresis in +heap size such that excessive amounts of system calls can be avoided. +@item M_TRIM_THRESHOLD +This is the minimum size (in bytes) of the top-most, releasable chunk +that will cause @code{sbrk} to be called with a negative argument in +order to return memory to the system. @end table @end deftypefun @@ -728,6 +1168,17 @@ @comment mcheck.h @comment GNU @deftypefun int mcheck (void (*@var{abortfn}) (enum mcheck_status @var{status})) +@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 +@c was already used, that doesn't pose any safety issues. The actual +@c problem is with the hooks, designed for single-threaded +@c fully-synchronous operation: they manage an unguarded linked list of +@c allocated blocks, and get temporarily overwritten before calling the +@c allocation functions recursively while holding the old hooks. There +@c are no guards for thread safety, and inconsistent hooks may be found +@c within signal handlers or left behind in case of cancellation. + Calling @code{mcheck} tells @code{malloc} to perform occasional consistency checks. These will catch things such as writing past the end of a block that was allocated with @code{malloc}. @@ -770,6 +1221,18 @@ @end deftypefun @deftypefun {enum mcheck_status} mprobe (void *@var{pointer}) +@safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +@c The linked list of headers may be modified concurrently by other +@c threads, and it may find a partial update if called from a signal +@c handler. It's mostly read only, so cancelling it might be safe, but +@c it will modify global state that, if cancellation hits at just the +@c right spot, may be left behind inconsistent. This path is only taken +@c if checkhdr finds an inconsistency. If the inconsistency could only +@c occur because of earlier undefined behavior, that wouldn't be an +@c additional safety issue problem, but because of the other concurrency +@c issues in the mcheck hooks, the apparent inconsistency could be the +@c result of mcheck's own internal data race. So, AC-Unsafe it is. + The @code{mprobe} function lets you explicitly check for inconsistencies in a particular allocated block. You must have already called @code{mcheck} at the beginning of the program, to do its occasional @@ -896,16 +1359,18 @@ @comment malloc.h @comment GNU @defvar __memalign_hook -The value of this variable is a pointer to function that @code{memalign} -uses whenever it is called. You should define this function to look -like @code{memalign}; that is, like: +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}; +that is, like: @smallexample void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller}) @end smallexample The value of @var{caller} is the return address found on the stack when -the @code{memalign} function was called. This value allows you to trace the +the @code{aligned_alloc}, @code{memalign}, @code{posix_memalign} or +@code{valloc} functions are called. This value allows you to trace the memory consumption of the program. @end defvar @@ -1082,6 +1547,24 @@ @comment malloc.h @comment SVID @deftypefun {struct mallinfo} mallinfo (void) +@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 +@c mark the statistics as unsafe, rather than the fast-path functions +@c that collect the possibly inconsistent data. + +@c __libc_mallinfo @mtuinit @mtasuconst:mallopt @asuinit @asulock @aculock +@c ptmalloc_init (once) dup @mtsenv @asulock @aculock @acsfd @acsmem +@c mutex_lock dup @asulock @aculock +@c int_mallinfo @mtasuconst:mallopt [mp_ access on main_arena] +@c malloc_consolidate dup ok +@c check_malloc_state dup ok/disabled +@c chunksize dup ok +@c fastbin dupo ok +@c bin_at dup ok +@c last dup ok +@c mutex_unlock @aculock + This function returns information about the current dynamic memory usage in a structure of type @code{struct mallinfo}. @end deftypefun @@ -1112,6 +1595,14 @@ Allocate a block of @var{size} bytes, starting on a page boundary. @xref{Aligned Memory Blocks}. +@item void *aligned_alloc (size_t @var{size}, size_t @var{alignment}) +Allocate a block of @var{size} bytes, starting on an address that is a +multiple of @var{alignment}. @xref{Aligned Memory Blocks}. + +@item int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size}) +Allocate a block of @var{size} bytes, starting on an address that is a +multiple of @var{alignment}. @xref{Aligned Memory Blocks}. + @item void *memalign (size_t @var{size}, size_t @var{boundary}) Allocate a block of @var{size} bytes, starting on an address that is a multiple of @var{boundary}. @xref{Aligned Memory Blocks}. @@ -1134,7 +1625,8 @@ A pointer to a function that @code{free} uses whenever it is called. @item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller}) -A pointer to a function that @code{memalign} uses whenever it is called. +A pointer to a function that @code{aligned_alloc}, @code{memalign}, +@code{posix_memalign} and @code{valloc} use whenever they are called. @item struct mallinfo mallinfo (void) Return information about the current dynamic memory usage. @@ -1171,6 +1663,20 @@ @comment mcheck.h @comment GNU @deftypefun void mtrace (void) +@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 +@c regard to other threads, signals or cancellation. + +@c mtrace @mtuinit @mtasurace:mtrace @mtsenv @asuinit @ascuheap @asucorrupt @acuinit @acucorrupt @aculock @acsfd @acsmem +@c __libc_secure_getenv dup @mtsenv +@c malloc dup @ascuheap @acsmem +@c fopen dup @ascuheap @asulock @aculock @acsmem @acsfd +@c fcntl dup ok +@c setvbuf dup @aculock +@c fprintf dup (on newly-created stream) @aculock +@c __cxa_atexit (once) dup @asulock @aculock @acsmem +@c free dup @ascuheap @acsmem When the @code{mtrace} function is called it looks for an environment variable named @code{MALLOC_TRACE}. This variable is supposed to contain a valid file name. The user must have write access. If the @@ -1194,6 +1700,11 @@ @comment mcheck.h @comment GNU @deftypefun void muntrace (void) +@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 +@c fprintf (fputs) dup @mtslocale @asucorrupt @ascuheap @acsmem @aculock @acucorrupt +@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd The @code{muntrace} function can be called after @code{mtrace} was used to enable tracing the @code{malloc} calls. If no (successful) call of @code{mtrace} was made @code{muntrace} does nothing. @@ -1505,6 +2016,20 @@ @comment obstack.h @comment GNU @deftypefun int obstack_init (struct obstack *@var{obstack-ptr}) +@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{@acsmem{}}} +@c obstack_init @mtsrace:obstack-ptr @acsmem +@c _obstack_begin @acsmem +@c chunkfun = obstack_chunk_alloc (suggested malloc) +@c freefun = obstack_chunk_free (suggested free) +@c *chunkfun @acsmem +@c obstack_chunk_alloc user-supplied +@c *obstack_alloc_failed_handler user-supplied +@c -> print_and_abort (default) +@c +@c print_and_abort +@c _ dup @ascuintl +@c fxprintf dup @asucorrupt @aculock @acucorrupt +@c exit @acucorrupt? Initialize obstack @var{obstack-ptr} for allocation of objects. This function calls the obstack's @code{obstack_chunk_alloc} function. If allocation of memory fails, the function pointed to by @@ -1560,6 +2085,10 @@ @comment obstack.h @comment GNU @deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size}) +@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 +@c obstack_finish dup @mtsrace:obstack-ptr @acucorrupt This allocates an uninitialized block of @var{size} bytes in an obstack and returns its address. Here @var{obstack-ptr} specifies which obstack to allocate the block in; it is the address of the @code{struct obstack} @@ -1594,6 +2123,10 @@ @comment obstack.h @comment GNU @deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) +@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 +@c obstack_finish dup @mtsrace:obstack-ptr @acucorrupt This allocates a block and initializes it by copying @var{size} bytes of data starting at @var{address}. It calls @code{obstack_alloc_failed_handler} if allocation of memory by @@ -1603,6 +2136,10 @@ @comment obstack.h @comment GNU @deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size}) +@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 +@c obstack_finish dup @mtsrace:obstack-ptr @acucorrupt Like @code{obstack_copy}, but appends an extra byte containing a null character. This extra byte is not counted in the argument @var{size}. @end deftypefun @@ -1635,6 +2172,10 @@ @comment obstack.h @comment GNU @deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) +@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}} +@c obstack_free @mtsrace:obstack-ptr @acucorrupt +@c (obstack_free) @mtsrace:obstack-ptr @acucorrupt +@c *freefun dup user-supplied If @var{object} is a null pointer, everything allocated in the obstack is freed. Otherwise, @var{object} must be the address of an object allocated in the obstack. Then @var{object} is freed, along with @@ -1739,6 +2280,13 @@ @comment obstack.h @comment GNU @deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size}) +@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 +@c *chunkfun dup @acsmem +@c *obstack_alloc_failed_handler dup user-supplied +@c *freefun +@c obstack_blank_fast dup @mtsrace:obstack-ptr The most basic function for adding to a growing object is @code{obstack_blank}, which adds space without initializing it. @end deftypefun @@ -1746,6 +2294,10 @@ @comment obstack.h @comment GNU @deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size}) +@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 +@c memcpy ok To add a block of initialized space, use @code{obstack_grow}, which is the growing-object analogue of @code{obstack_copy}. It adds @var{size} bytes of data to the growing object, copying the contents from @@ -1755,6 +2307,12 @@ @comment obstack.h @comment GNU @deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size}) +@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) +@c (multiple changes to next_free => @acucorrupt) +@c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem +@c memcpy ok This is the growing-object analogue of @code{obstack_copy0}. It adds @var{size} bytes copied from @var{data}, followed by an additional null character. @@ -1763,6 +2321,10 @@ @comment obstack.h @comment GNU @deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c}) +@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 +@c obstack_1grow_fast dup @mtsrace:obstack-ptr @acucorrupt @acsmem 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 @@ -1770,6 +2332,10 @@ @comment obstack.h @comment GNU @deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data}) +@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 +@c obstack_ptr_grow_fast dup @mtsrace:obstack-ptr Adding the value of a pointer one can use the function @code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes containing the value of @var{data}. @@ -1778,6 +2344,10 @@ @comment obstack.h @comment GNU @deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data}) +@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 +@c obstack_int_grow_fast dup @mtsrace:obstack-ptr A single value of type @code{int} can be added by using the @code{obstack_int_grow} function. It adds @code{sizeof (int)} bytes to the growing object and initializes them with the value of @var{data}. @@ -1786,6 +2356,8 @@ @comment obstack.h @comment GNU @deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr}) +@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 @code{obstack_finish} to close it off and return its final address. @@ -1805,6 +2377,7 @@ @comment obstack.h @comment GNU @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr}) +@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. After it is finished, @code{obstack_object_size} will return zero. @@ -1848,6 +2421,7 @@ @comment obstack.h @comment GNU @deftypefun int obstack_room (struct obstack *@var{obstack-ptr}) +@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 @var{obstack} using the fast growth functions. @@ -1859,6 +2433,9 @@ @comment obstack.h @comment GNU @deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c}) +@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) 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 @@ -1866,6 +2443,8 @@ @comment obstack.h @comment GNU @deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data}) +@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 *)} bytes containing the value of @var{data} to the growing object in obstack @var{obstack-ptr}. @@ -1874,6 +2453,8 @@ @comment obstack.h @comment GNU @deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data}) +@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 containing the value of @var{data} to the growing object in obstack @var{obstack-ptr}. @@ -1882,6 +2463,8 @@ @comment obstack.h @comment GNU @deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size}) +@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 growing object in obstack @var{obstack-ptr} without initializing them. @end deftypefun @@ -1909,7 +2492,7 @@ int room = obstack_room (obstack); if (room == 0) @{ - /* @r{Not enough room. Add one character slowly,} + /* @r{Not enough room. Add one character slowly,} @r{which may copy to a new chunk and make room.} */ obstack_1grow (obstack, *ptr++); len--; @@ -1940,6 +2523,7 @@ @comment obstack.h @comment GNU @deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr}) +@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 immediately, it will have that address. If you make it larger first, it @@ -1953,6 +2537,7 @@ @comment obstack.h @comment GNU @deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr}) +@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 growing object. If no object is growing, @code{obstack_next_free} @@ -1962,6 +2547,8 @@ @comment obstack.h @comment GNU @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr}) +@c dup +@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}} This function returns the size in bytes of the currently growing object. This is equivalent to @@ -1986,6 +2573,7 @@ @comment obstack.h @comment GNU @deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr}) +@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 less than a power of 2; the effect is that all object addresses are @@ -2053,6 +2641,7 @@ @comment obstack.h @comment GNU @deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This returns the chunk size of the given obstack. @end deftypefn @@ -2172,6 +2761,7 @@ @comment stdlib.h @comment GNU, BSD @deftypefun {void *} alloca (size_t @var{size}) +@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. @end deftypefun @@ -2354,6 +2944,7 @@ @comment unistd.h @comment BSD @deftypefun int brk (void *@var{addr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{brk} sets the high end of the calling process' data segment to @var{addr}. @@ -2396,6 +2987,8 @@ @comment unistd.h @comment BSD @deftypefun void *sbrk (ptrdiff_t @var{delta}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + This function is the same as @code{brk} except that you specify the new end of the data segment as an offset @var{delta} from the current end and on success the return value is the address of the resulting end of @@ -2535,6 +3128,7 @@ @comment sys/mman.h @comment POSIX.1b @deftypefun int mlock (const void *@var{addr}, size_t @var{len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{mlock} locks a range of the calling process' virtual pages. @@ -2588,6 +3182,7 @@ @comment sys/mman.h @comment POSIX.1b @deftypefun int munlock (const void *@var{addr}, size_t @var{len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{munlock} unlocks a range of the calling process' virtual pages. @@ -2600,6 +3195,7 @@ @comment sys/mman.h @comment POSIX.1b @deftypefun int mlockall (int @var{flags}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{mlockall} locks all the pages in a process' virtual memory address space, and/or any that are added to it in the future. This includes the @@ -2676,6 +3272,7 @@ @comment sys/mman.h @comment POSIX.1b @deftypefun int munlockall (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{munlockall} unlocks every page in the calling process' virtual address space and turn off @code{MCL_FUTURE} future locking mode. diff -urN glibc-2.17-c758a686/manual/message.texi glibc-2.17-c758a686/manual/message.texi --- glibc-2.17-c758a686/manual/message.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/message.texi 2014-09-12 16:10:06.043792722 -0400 @@ -2,9 +2,9 @@ @c %MENU% How to make the program speak the user's language @chapter Message Translation -The program's interface with the human should be designed in a way to -ease the human the task. One of the possibilities is to use messages in -whatever language the user prefers. +The program's interface with the user should be designed to ease the user's +task. One way to ease the user's task is to use messages in whatever +language the user prefers. Printing messages in different languages can be implemented in different ways. One could add all the different languages in the source code and @@ -40,7 +40,7 @@ @end itemize The two approaches mainly differ in the implementation of this last -step. The design decisions made for this influences the whole rest. +step. Decisions made in the last step influence the rest of the design. @menu * Message catalogs a la X/Open:: The @code{catgets} family of functions. @@ -86,7 +86,32 @@ @comment nl_types.h @comment X/Open @deftypefun nl_catd catopen (const char *@var{cat_name}, int @var{flag}) -The @code{catgets} function tries to locate the message data file names +@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c catopen @mtsenv @ascuheap @acsmem +@c strchr ok +@c setlocale(,NULL) ok +@c getenv @mtsenv +@c strlen ok +@c alloca ok +@c stpcpy ok +@c malloc @ascuheap @acsmem +@c __open_catalog @ascuheap @acsmem +@c strchr ok +@c open_not_cancel_2 @acsfd +@c strlen ok +@c ENOUGH ok +@c alloca ok +@c memcpy ok +@c fxstat64 ok +@c __set_errno ok +@c mmap @acsmem +@c malloc dup @ascuheap @acsmem +@c read_not_cancel ok +@c free dup @ascuheap @acsmem +@c munmap ok +@c close_not_cancel_no_status ok +@c free @ascuheap @acsmem +The @code{catopen} function tries to locate the message data file names @var{cat_name} and loads it when found. The return value is of an opaque type and can be used in calls to the other functions to refer to this loaded catalog. @@ -243,6 +268,7 @@ @deftypefun {char *} catgets (nl_catd @var{catalog_desc}, int @var{set}, int @var{message}, const char *@var{string}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{catgets} has to be used to access the massage catalog previously opened using the @code{catopen} function. The @var{catalog_desc} parameter must be a value previously returned by @@ -281,6 +307,11 @@ Usage}). @deftypefun int catclose (nl_catd @var{catalog_desc}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} +@c catclose @ascuheap @acucorrupt @acsmem +@c __set_errno ok +@c munmap ok +@c free @ascuheap @acsmem The @code{catclose} function can be used to free the resources associated with a message catalog which previously was opened by a call to @code{catopen}. If the resources can be successfully freed the @@ -803,12 +834,14 @@ @comment libintl.h @comment GNU @deftypefun {char *} gettext (const char *@var{msgid}) +@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 catalogs for a string which is equal to @var{msgid}. If there is such a string available it is returned. Otherwise the argument string @var{msgid} is returned. -Please note that all though the return value is @code{char *} the +Please note that although the return value is @code{char *} the returned string must not be changed. This broken type results from the history of the function and does not reflect the way the function should be used. @@ -850,6 +883,8 @@ @comment libintl.h @comment GNU @deftypefun {char *} dgettext (const char *@var{domainname}, const char *@var{msgid}) +@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c Wrapper for dcgettext. The @code{dgettext} functions acts just like the @code{gettext} function. It only takes an additional first argument @var{domainname} which guides the selection of the message catalogs which are searched @@ -864,6 +899,102 @@ @comment libintl.h @comment GNU @deftypefun {char *} dcgettext (const char *@var{domainname}, const char *@var{msgid}, int @var{category}) +@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 +@c libc_rwlock_rdlock @asulock @aculock +@c current_locale_name ok [protected from @mtslocale] +@c tfind ok +@c libc_rwlock_unlock ok +@c plural_lookup ok +@c plural_eval ok +@c rawmemchr ok +@c DETERMINE_SECURE ok, nothing +@c strcmp ok +@c strlen ok +@c getcwd @ascuheap @acsmem @acsfd +@c strchr ok +@c stpcpy ok +@c category_to_name ok +@c guess_category_value @mtsenv +@c getenv @mtsenv +@c current_locale_name dup ok [protected from @mtslocale by dcigettext] +@c strcmp ok +@c ENABLE_SECURE ok +@c _nl_find_domain @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem +@c libc_rwlock_rdlock dup @asulock @aculock +@c _nl_make_l10nflist dup @ascuheap @acsmem +@c libc_rwlock_unlock dup ok +@c _nl_load_domain @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock_recursive @aculock +@c libc_lock_unlock_recursive @aculock +@c open->open_not_cancel_2 @acsfd +@c fstat ok +@c mmap dup @acsmem +@c close->close_not_cancel_no_status @acsfd +@c malloc dup @ascuheap @acsmem +@c read->read_not_cancel ok +@c munmap dup @acsmem +@c W dup ok +@c strlen dup ok +@c get_sysdep_segment_value ok +@c memcpy dup ok +@c hash_string dup ok +@c free dup @ascuheap @acsmem +@c libc_rwlock_init ok +@c _nl_find_msg dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem +@c libc_rwlock_fini ok +@c EXTRACT_PLURAL_EXPRESSION @ascuheap @acsmem +@c strstr dup ok +@c isspace ok +@c strtoul ok +@c PLURAL_PARSE @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c INIT_GERMANIC_PLURAL ok, nothing +@c the pre-C99 variant is @acucorrupt [protected from @mtuinit by dcigettext] +@c _nl_expand_alias dup @ascuheap @asulock @acsmem @acsfd @aculock +@c _nl_explode_name dup @ascuheap @acsmem +@c libc_rwlock_wrlock dup @asulock @aculock +@c free dup @asulock @aculock @acsfd @acsmem +@c _nl_find_msg @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem +@c _nl_load_domain dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem +@c strlen ok +@c hash_string ok +@c W ok +@c SWAP ok +@c bswap_32 ok +@c strcmp ok +@c get_output_charset @mtsenv @ascuheap @acsmem +@c getenv dup @mtsenv +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c memcpy dup ok +@c libc_rwlock_rdlock dup @asulock @aculock +@c libc_rwlock_unlock dup ok +@c libc_rwlock_wrlock dup @asulock @aculock +@c realloc @ascuheap @acsmem +@c strdup @ascuheap @acsmem +@c strstr ok +@c strcspn ok +@c mempcpy dup ok +@c norm_add_slashes dup ok +@c gconv_open @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c [protected from @mtslocale by dcigettext locale lock] +@c free dup @ascuheap @acsmem +@c libc_lock_lock @asulock @aculock +@c calloc @ascuheap @acsmem +@c gconv dup @acucorrupt [protected from @mtsrace and @asucorrupt by lock] +@c libc_lock_unlock ok +@c malloc @ascuheap @acsmem +@c mempcpy ok +@c memcpy ok +@c strcpy ok +@c libc_rwlock_wrlock @asulock @aculock +@c tsearch @ascuheap @acucorrupt @acsmem [protected from @mtsrace and @asucorrupt] +@c transcmp ok +@c strmp dup ok +@c free @ascuheap @acsmem The @code{dcgettext} adds another argument to those which @code{dgettext} takes. This argument @var{category} specifies the last piece of information needed to localize the message catalog. I.e., the @@ -967,7 +1098,7 @@ second best choice to fall back on the language of the developer and simply not translate any message. Instead a user might be better able to read the messages in another language and so the user of the program -should be able to define an precedence order of languages. +should be able to define a precedence order of languages. @end itemize We can divide the configuration actions in two parts: the one is @@ -988,6 +1119,13 @@ @comment libintl.h @comment GNU @deftypefun {char *} textdomain (const char *@var{domainname}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}} +@c textdomain @asulock @ascuheap @aculock @acsmem +@c libc_rwlock_wrlock @asulock @aculock +@c strcmp ok +@c strdup @ascuheap @acsmem +@c free @ascuheap @acsmem +@c libc_rwlock_unlock ok The @code{textdomain} function sets the default domain, which is used in all future @code{gettext} calls, to @var{domainname}. Please note that @code{dgettext} and @code{dcgettext} calls are not influenced if the @@ -1019,6 +1157,14 @@ @comment libintl.h @comment GNU @deftypefun {char *} bindtextdomain (const char *@var{domainname}, const char *@var{dirname}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c bindtextdomain @ascuheap @acsmem +@c set_binding_values @ascuheap @acsmem +@c libc_rwlock_wrlock dup @asulock @aculock +@c strcmp dup ok +@c strdup dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem The @code{bindtextdomain} function can be used to specify the directory which contains the message catalogs for domain @var{domainname} for the different languages. To be correct, this is the directory where the @@ -1114,7 +1260,7 @@ extended @code{gettext} interface should be used. These extra functions are taking instead of the one key string two -strings and an numerical argument. The idea behind this is that using +strings and a numerical argument. The idea behind this is that using the numerical argument and the first string as a key, the implementation can select using rules specified by the translator the right plural form. The two string arguments then will be used to provide a return @@ -1134,6 +1280,8 @@ @comment libintl.h @comment GNU @deftypefun {char *} ngettext (const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}) +@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 as it finds the message catalogs in the same way. But it takes two extra arguments. The @var{msgid1} parameter must contain the singular @@ -1157,6 +1305,8 @@ @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}) +@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 way the message catalog is selected. The difference is that it takes two extra parameter to provide the correct plural form. These two @@ -1166,6 +1316,8 @@ @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}) +@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 way the message catalog is selected. The difference is that it takes two extra parameter to provide the correct plural form. These two @@ -1422,6 +1574,9 @@ @comment libintl.h @comment GNU @deftypefun {char *} bind_textdomain_codeset (const char *@var{domainname}, const char *@var{codeset}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c bind_textdomain_codeset @ascuheap @acsmem +@c set_binding_values dup @ascuheap @acsmem The @code{bind_textdomain_codeset} function can be used to specify the output character set for message catalogs for domain @var{domainname}. The @var{codeset} argument must be a valid codeset name which can be used @@ -1429,7 +1584,7 @@ If the @var{codeset} parameter is the null pointer, @code{bind_textdomain_codeset} returns the currently selected codeset -for the domain with the name @var{domainname}. It returns @code{NULL} if +for the domain with the name @var{domainname}. It returns @code{NULL} if no codeset has yet been selected. The @code{bind_textdomain_codeset} function can be used several times. @@ -1441,7 +1596,8 @@ allocated internally in the function and must not be changed by the user. If the system went out of core during the execution of @code{bind_textdomain_codeset}, the return value is @code{NULL} and the -global variable @var{errno} is set accordingly. @end deftypefun +global variable @var{errno} is set accordingly. +@end deftypefun @node GUI program problems diff -urN glibc-2.17-c758a686/manual/nss.texi glibc-2.17-c758a686/manual/nss.texi --- glibc-2.17-c758a686/manual/nss.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/nss.texi 2014-09-12 16:10:25.996741462 -0400 @@ -10,7 +10,7 @@ using files (e.g., @file{/etc/passwd}), but other nameservices (like the Network Information Service (NIS) and the Domain Name Service (DNS)) became popular, and were hacked into the C library, usually with a fixed -search order (@pxref{frobnicate, , ,jargon, The Jargon File}). +search order. @Theglibc{} contains a cleaner solution of this problem. It is designed after a method used by Sun Microsystems in the C library of diff -urN glibc-2.17-c758a686/manual/pattern.texi glibc-2.17-c758a686/manual/pattern.texi --- glibc-2.17-c758a686/manual/pattern.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/pattern.texi 2014-09-12 16:10:06.045792717 -0400 @@ -28,6 +28,38 @@ @comment fnmatch.h @comment POSIX.2 @deftypefun int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c fnmatch @mtsenv @mtslocale @ascuheap @acsmem +@c strnlen dup ok +@c mbsrtowcs +@c memset dup ok +@c malloc dup @ascuheap @acsmem +@c mbsinit dup ok +@c free dup @ascuheap @acsmem +@c FCT = internal_fnwmatch @mtsenv @mtslocale @ascuheap @acsmem +@c FOLD @mtslocale +@c towlower @mtslocale +@c EXT @mtsenv @mtslocale @ascuheap @acsmem +@c STRLEN = wcslen dup ok +@c getenv @mtsenv +@c malloc dup @ascuheap @acsmem +@c MEMPCPY = wmempcpy dup ok +@c FCT dup @mtsenv @mtslocale @ascuheap @acsmem +@c STRCAT = wcscat dup ok +@c free dup @ascuheap @acsmem +@c END @mtsenv +@c getenv @mtsenv +@c MEMCHR = wmemchr dup ok +@c getenv @mtsenv +@c IS_CHAR_CLASS = is_char_class @mtslocale +@c wctype @mtslocale +@c BTOWC ok +@c ISWCTYPE ok +@c auto findidx dup ok +@c elem_hash dup ok +@c memcmp dup ok +@c collseq_table_lookup dup ok +@c NO_LEADING_PERIOD ok This function tests whether the string @var{string} matches the pattern @var{pattern}. It returns @code{0} if they do match; otherwise, it returns the nonzero value @code{FNM_NOMATCH}. The arguments @@ -36,11 +68,8 @@ The argument @var{flags} is a combination of flag bits that alter the details of matching. See below for a list of the defined flags. -In @theglibc{}, @code{fnmatch} cannot experience an ``error''---it -always returns an answer for whether the match succeeds. However, other -implementations of @code{fnmatch} might sometimes report ``errors''. -They would do so by returning nonzero values that are not equal to -@code{FNM_NOMATCH}. +In @theglibc{}, @code{fnmatch} might sometimes report ``errors'' by +returning nonzero values that are not equal to @code{FNM_NOMATCH}. @end deftypefun These are the available flags for the @var{flags} argument: @@ -234,6 +263,12 @@ (*) (const char *,} @w{struct stat *)}}. This is a GNU extension. + +@item gl_flags +The flags used when @code{glob} was called. In addition, @code{GLOB_MAGCHAR} +might be set. See @ref{Flags for Globbing} for more details. + +This is a GNU extension. @end table @end deftp @@ -312,12 +347,75 @@ (*) (const char *,} @w{struct stat64 *)}}. This is a GNU extension. + +@item gl_flags +The flags used when @code{glob} was called. In addition, @code{GLOB_MAGCHAR} +might be set. See @ref{Flags for Globbing} for more details. + +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}) +@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 +@c strchr dup ok +@c malloc dup @ascuheap @acsmem +@c mempcpy dup ok +@c next_brace_sub ok +@c free dup @ascuheap @acsmem +@c globfree dup @asucorrupt @ascuheap @acucorrupt @acsmem +@c glob_pattern_p ok +@c glob_pattern_type dup ok +@c getenv dup @mtsenv +@c GET_LOGIN_NAME_MAX ok +@c getlogin_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c GETPW_R_SIZE_MAX ok +@c getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c memcpy dup ok +@c memchr dup ok +@c *pglob->gl_stat user-supplied +@c stat64 dup ok +@c S_ISDIR dup ok +@c strdup dup @ascuheap @acsmem +@c glob_pattern_type ok +@c glob_in_dir @mtsenv @mtslocale @asucorrupt @ascuheap @acucorrupt @acsfd @acsmem +@c strlen dup ok +@c glob_pattern_type dup ok +@c malloc dup @ascuheap @acsmem +@c mempcpy dup ok +@c *pglob->gl_stat user-supplied +@c stat64 dup ok +@c free dup @ascuheap @acsmem +@c *pglob->gl_opendir user-supplied +@c opendir dup @ascuheap @acsmem @acsfd +@c dirfd dup ok +@c *pglob->gl_readdir user-supplied +@c CONVERT_DIRENT_DIRENT64 ok +@c readdir64 ok [protected by exclusive use of the stream] +@c REAL_DIR_ENTRY ok +@c DIRENT_MIGHT_BE_DIR ok +@c fnmatch dup @mtsenv @mtslocale @ascuheap @acsmem +@c DIRENT_MIGHT_BE_SYMLINK ok +@c link_exists_p ok +@c link_exists2_p ok +@c strlen dup ok +@c mempcpy dup ok +@c *pglob->gl_stat user-supplied +@c fxstatat64 dup ok +@c realloc dup @ascuheap @acsmem +@c pglob->gl_closedir user-supplied +@c closedir @ascuheap @acsmem @acsfd +@c prefix_array dup @asucorrupt @ascuheap @acucorrupt @acsmem +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c mempcpy dup ok +@c strcpy dup ok The function @code{glob} does globbing using the pattern @var{pattern} in the current directory. It puts the result in a newly allocated vector, and stores the size and address of this vector into @@ -389,6 +487,8 @@ @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}) +@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 extensions but is not part of the original LFS proposal. The reason for this is simple: it is not necessary. The necessity for a @code{glob64} @@ -408,10 +508,12 @@ @node Flags for Globbing @subsection Flags for Globbing -This section describes the flags that you can specify in the +This section describes the standard flags that you can specify in the @var{flags} argument to @code{glob}. Choose the flags you want, 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 @@ -481,13 +583,6 @@ @comment glob.h @comment POSIX.2 -@item GLOB_NOSORT -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. - -@comment glob.h -@comment POSIX.2 @item GLOB_NOESCAPE Don't treat the @samp{\} character specially in patterns. Normally, @samp{\} quotes the following character, turning off its special meaning @@ -500,6 +595,13 @@ @code{glob} does its work by calling the function @code{fnmatch} 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 +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. @end vtable @node More Flags for Globbing @@ -651,6 +753,9 @@ @comment glob.h @comment POSIX.2 @deftypefun void globfree (glob_t *@var{pglob}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} +@c globfree dup @asucorrupt @ascuheap @acucorrupt @acsmem +@c free dup @ascuheap @acsmem The @code{globfree} function frees all resources allocated by previous calls to @code{glob} associated with the object pointed to by @var{pglob}. This function should be called whenever the currently used @@ -660,6 +765,7 @@ @comment glob.h @comment GNU @deftypefun void globfree64 (glob64_t *@var{pglob}) +@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}. @end deftypefun @@ -722,6 +828,250 @@ @comment regex.h @comment POSIX.2 @deftypefun int regcomp (regex_t *restrict @var{compiled}, const char *restrict @var{pattern}, int @var{cflags}) +@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 +@c or inverted character classes. +@c (re_)malloc @ascuheap @acsmem +@c re_compile_internal @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c (re_)realloc @ascuheap @acsmem [no @asucorrupt @acucorrupt for we zero the buffer] +@c init_dfa @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c (re_)malloc @ascuheap @acsmem +@c calloc @ascuheap @acsmem +@c _NL_CURRENT ok +@c _NL_CURRENT_WORD ok +@c btowc @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c libc_lock_init ok +@c re_string_construct @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_construct_common ok +@c re_string_realloc_buffers @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c build_wcs_upper_buffer @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c isascii ok +@c mbsinit ok +@c toupper ok +@c mbrtowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c iswlower @mtslocale +@c towupper @mtslocale +@c wcrtomb dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c (re_)malloc dup @ascuheap @acsmem +@c build_upper_buffer ok (@mtslocale but optimized) +@c islower ok +@c toupper ok +@c build_wcs_buffer @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c mbrtowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_translate_buffer ok +@c parse @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c fetch_token @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c peek_token @mtslocale +@c re_string_eoi ok +@c re_string_peek_byte ok +@c re_string_cur_idx ok +@c re_string_length ok +@c re_string_peek_byte_case @mtslocale +@c re_string_peek_byte dup ok +@c re_string_is_single_byte_char ok +@c isascii ok +@c re_string_peek_byte dup ok +@c re_string_wchar_at ok +@c re_string_skip_bytes ok +@c re_string_skip_bytes dup ok +@c parse_reg_exp @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c parse_branch @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c parse_expression @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c create_token_tree dup @ascuheap @acsmem +@c re_string_eoi dup ok +@c re_string_first_byte ok +@c fetch_token dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c create_tree dup @ascuheap @acsmem +@c parse_sub_exp @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c fetch_token dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c parse_reg_exp dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c postorder() @ascuheap @acsmem +@c free_tree @ascuheap @acsmem +@c free_token dup @ascuheap @acsmem +@c create_tree dup @ascuheap @acsmem +@c parse_bracket_exp @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c _NL_CURRENT dup ok +@c _NL_CURRENT_WORD dup ok +@c calloc dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c peek_token_bracket ok +@c re_string_eoi dup ok +@c re_string_peek_byte dup ok +@c re_string_first_byte dup ok +@c re_string_cur_idx dup ok +@c re_string_length dup ok +@c re_string_skip_bytes dup ok +@c bitset_set ok +@c re_string_skip_bytes ok +@c parse_bracket_element @mtslocale +@c re_string_char_size_at ok +@c re_string_wchar_at dup ok +@c re_string_skip_bytes dup ok +@c parse_bracket_symbol @mtslocale +@c re_string_eoi dup ok +@c re_string_fetch_byte_case @mtslocale +@c re_string_fetch_byte ok +@c re_string_first_byte dup ok +@c isascii ok +@c re_string_char_size_at dup ok +@c re_string_skip_bytes dup ok +@c re_string_fetch_byte dup ok +@c re_string_peek_byte dup ok +@c re_string_skip_bytes dup ok +@c peek_token_bracket dup ok +@c auto build_range_exp @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c auto lookup_collation_sequence_value @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c btowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c collseq_table_lookup ok +@c auto seek_collating_symbol_entry dup ok +@c (re_)realloc dup @ascuheap @acsmem +@c collseq_table_lookup dup ok +@c bitset_set dup ok +@c (re_)realloc dup @ascuheap @acsmem +@c build_equiv_class @mtslocale @ascuheap @acsmem +@c _NL_CURRENT ok +@c auto findidx ok +@c bitset_set dup ok +@c (re_)realloc dup @ascuheap @acsmem +@c auto build_collating_symbol @ascuheap @acsmem +@c auto seek_collating_symbol_entry ok +@c bitset_set dup ok +@c (re_)realloc dup @ascuheap @acsmem +@c build_charclass @mtslocale @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c bitset_set dup ok +@c isalnum ok +@c iscntrl ok +@c isspace ok +@c isalpha ok +@c isdigit ok +@c isprint ok +@c isupper ok +@c isblank ok +@c isgraph ok +@c ispunct ok +@c isxdigit ok +@c bitset_not ok +@c bitset_mask ok +@c create_token_tree dup @ascuheap @acsmem +@c create_tree dup @ascuheap @acsmem +@c free_charset dup @ascuheap @acsmem +@c init_word_char @mtslocale +@c isalnum ok +@c build_charclass_op @mtslocale @ascuheap @acsmem +@c calloc dup @ascuheap @acsmem +@c build_charclass dup @mtslocale @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c free_charset dup @ascuheap @acsmem +@c bitset_set dup ok +@c bitset_not dup ok +@c bitset_mask dup ok +@c create_token_tree dup @ascuheap @acsmem +@c create_tree dup @ascuheap @acsmem +@c parse_dup_op @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_cur_idx dup ok +@c fetch_number @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c fetch_token dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_set_index ok +@c postorder() @ascuheap @acsmem +@c free_tree dup @ascuheap @acsmem +@c mark_opt_subexp ok +@c duplicate_tree @ascuheap @acsmem +@c create_token_tree dup @ascuheap @acsmem +@c create_tree dup @ascuheap @acsmem +@c postorder() @ascuheap @acsmem +@c free_tree dup @ascuheap @acsmem +@c fetch_token dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c parse_branch dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c create_tree dup @ascuheap @acsmem +@c create_tree @ascuheap @acsmem +@c create_token_tree @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c analyze @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c preorder() @ascuheap @acsmem +@c optimize_subexps ok +@c calc_next ok +@c link_nfa_nodes @ascuheap @acsmem +@c re_node_set_init_1 @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c re_node_set_init_2 @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c postorder() @ascuheap @acsmem +@c lower_subexps @ascuheap @acsmem +@c lower_subexp @ascuheap @acsmem +@c create_tree dup @ascuheap @acsmem +@c calc_first @ascuheap @acsmem +@c re_dfa_add_node @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c re_node_set_init_empty ok +@c calc_eclosure @ascuheap @acsmem +@c calc_eclosure_iter @ascuheap @acsmem +@c re_node_set_alloc @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c duplicate_node_closure @ascuheap @acsmem +@c re_node_set_empty ok +@c duplicate_node @ascuheap @acsmem +@c re_dfa_add_node dup @ascuheap @acsmem +@c re_node_set_insert @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c search_duplicated_node ok +@c re_node_set_merge @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c re_node_set_free @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c re_node_set_insert dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c calc_inveclosure @ascuheap @acsmem +@c re_node_set_init_empty dup ok +@c re_node_set_insert_last @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c optimize_utf8 ok +@c create_initial_state @ascuheap @acsmem +@c re_node_set_init_copy @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c re_node_set_init_empty dup ok +@c re_node_set_contains ok +@c re_node_set_merge dup @ascuheap @acsmem +@c re_acquire_state_context @ascuheap @acsmem +@c calc_state_hash ok +@c re_node_set_compare ok +@c create_cd_newstate @ascuheap @acsmem +@c calloc dup @ascuheap @acsmem +@c re_node_set_init_copy dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c free_state @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c NOT_SATISFY_PREV_CONSTRAINT ok +@c re_node_set_remove_at ok +@c register_state @ascuheap @acsmem +@c re_node_set_alloc dup @ascuheap @acsmem +@c re_node_set_insert_last dup @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c free_workarea_compile @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c re_string_destruct @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c free_dfa_content @ascuheap @acsmem +@c free_token @ascuheap @acsmem +@c free_charset @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c re_compile_fastmap @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_compile_fastmap_iter @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_set_fastmap ok +@c tolower ok +@c mbrtowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c wcrtomb dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c towlower @mtslocale +@c _NL_CURRENT ok +@c (re_)free @ascuheap @acsmem The function @code{regcomp} ``compiles'' a regular expression into a data structure that you can use with @code{regexec} to match against a string. The compiled regular expression format is designed for @@ -871,6 +1221,247 @@ @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}) +@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 +@c re_string_allocate @ascuheap @acsmem +@c re_string_construct_common dup ok +@c re_string_realloc_buffers dup @ascuheap @acsmem +@c match_ctx_init @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c re_string_byte_at ok +@c re_string_first_byte dup ok +@c check_matching @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_cur_idx dup ok +@c acquire_init_state_context dup @ascuheap @acsmem +@c re_string_context_at ok +@c re_string_byte_at dup ok +@c bitset_contain ok +@c re_acquire_state_context dup @ascuheap @acsmem +@c check_subexp_matching_top @ascuheap @acsmem +@c match_ctx_add_subtop @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c calloc dup @ascuheap @acsmem +@c transit_state_bkref @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_cur_idx dup ok +@c re_string_context_at dup ok +@c NOT_SATISFY_NEXT_CONSTRAINT ok +@c get_subexp @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_get_buffer ok +@c search_cur_bkref_entry ok +@c clean_state_log_if_needed @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c extend_buffers @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_realloc_buffers dup @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c build_wcs_upper_buffer dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c build_upper_buffer dup ok (@mtslocale but optimized) +@c build_wcs_buffer dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_translate_buffer dup ok +@c get_subexp_sub @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c check_arrival @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c (re_)realloc dup @ascuheap @acsmem +@c re_string_context_at dup ok +@c re_node_set_init_1 dup @ascuheap @acsmem +@c check_arrival_expand_ecl @ascuheap @acsmem +@c re_node_set_alloc dup @ascuheap @acsmem +@c find_subexp_node ok +@c re_node_set_merge dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c check_arrival_expand_ecl_sub @ascuheap @acsmem +@c re_node_set_contains dup ok +@c re_node_set_insert dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c re_node_set_init_copy dup @ascuheap @acsmem +@c re_node_set_init_empty dup ok +@c expand_bkref_cache @ascuheap @acsmem +@c search_cur_bkref_entry dup ok +@c re_node_set_contains dup ok +@c re_node_set_init_1 dup @ascuheap @acsmem +@c check_arrival_expand_ecl dup @ascuheap @acsmem +@c re_node_set_merge dup @ascuheap @acsmem +@c re_node_set_init_copy dup @ascuheap @acsmem +@c re_node_set_insert dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c re_acquire_state @ascuheap @acsmem +@c calc_state_hash dup ok +@c re_node_set_compare dup ok +@c create_ci_newstate @ascuheap @acsmem +@c calloc dup @ascuheap @acsmem +@c re_node_set_init_copy dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c register_state dup @ascuheap @acsmem +@c free_state dup @ascuheap @acsmem +@c re_acquire_state_context dup @ascuheap @acsmem +@c re_node_set_merge dup @ascuheap @acsmem +@c check_arrival_add_next_nodes @mtslocale @ascuheap @acsmem +@c re_node_set_init_empty dup ok +@c check_node_accept_bytes @mtslocale @ascuheap @acsmem +@c re_string_byte_at dup ok +@c re_string_char_size_at dup ok +@c re_string_elem_size_at @mtslocale +@c _NL_CURRENT_WORD dup ok +@c _NL_CURRENT dup ok +@c auto findidx dup ok +@c _NL_CURRENT_WORD dup ok +@c _NL_CURRENT dup ok +@c collseq_table_lookup dup ok +@c find_collation_sequence_value @mtslocale +@c _NL_CURRENT_WORD dup ok +@c _NL_CURRENT dup ok +@c auto findidx dup ok +@c wcscoll @mtslocale @ascuheap @acsmem +@c re_node_set_empty dup ok +@c re_node_set_merge dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c re_node_set_insert dup @ascuheap @acsmem +@c re_acquire_state dup @ascuheap @acsmem +@c check_node_accept ok +@c re_string_byte_at dup ok +@c bitset_contain dup ok +@c re_string_context_at dup ok +@c NOT_SATISFY_NEXT_CONSTRAINT dup ok +@c match_ctx_add_entry @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c clean_state_log_if_needed dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c extend_buffers dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c find_subexp_node dup ok +@c calloc dup @ascuheap @acsmem +@c check_arrival dup *** +@c match_ctx_add_sublast @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c re_acquire_state_context dup @ascuheap @acsmem +@c re_node_set_init_union @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c re_node_set_init_copy dup @ascuheap @acsmem +@c re_node_set_init_empty dup ok +@c re_node_set_free dup @ascuheap @acsmem +@c check_subexp_matching_top dup @ascuheap @acsmem +@c check_halt_state_context ok +@c re_string_context_at dup ok +@c check_halt_node_context ok +@c NOT_SATISFY_NEXT_CONSTRAINT dup ok +@c re_string_eoi dup ok +@c extend_buffers dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c transit_state @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c transit_state_mb @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_context_at dup ok +@c NOT_SATISFY_NEXT_CONSTRAINT dup ok +@c check_node_accept_bytes dup @mtslocale @ascuheap @acsmem +@c re_string_cur_idx dup ok +@c clean_state_log_if_needed @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_node_set_init_union dup @ascuheap @acsmem +@c re_acquire_state_context dup @ascuheap @acsmem +@c re_string_fetch_byte dup ok +@c re_string_context_at dup ok +@c build_trtable @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c group_nodes_into_DFAstates @ascuheap @acsmem +@c bitset_empty dup ok +@c bitset_set dup ok +@c bitset_merge dup ok +@c bitset_set_all ok +@c bitset_clear ok +@c bitset_contain dup ok +@c bitset_copy ok +@c re_node_set_init_copy dup @ascuheap @acsmem +@c re_node_set_insert dup @ascuheap @acsmem +@c re_node_set_init_1 dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c re_node_set_alloc dup @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c bitset_empty ok +@c re_node_set_empty dup ok +@c re_node_set_merge dup @ascuheap @acsmem +@c re_acquire_state_context dup @ascuheap @acsmem +@c bitset_merge ok +@c calloc dup @ascuheap @acsmem +@c bitset_contain dup ok +@c merge_state_with_log @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c re_string_cur_idx dup ok +@c re_node_set_init_union dup @ascuheap @acsmem +@c re_string_context_at dup ok +@c re_node_set_free dup @ascuheap @acsmem +@c check_subexp_matching_top @ascuheap @acsmem +@c match_ctx_add_subtop dup @ascuheap @acsmem +@c transit_state_bkref dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c find_recover_state +@c re_string_cur_idx dup ok +@c re_string_skip_bytes dup ok +@c merge_state_with_log dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c check_halt_state_context dup ok +@c prune_impossible_nodes @mtslocale @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c sift_ctx_init ok +@c re_node_set_init_empty dup ok +@c sift_states_backward @mtslocale @ascuheap @acsmem +@c re_node_set_init_1 dup @ascuheap @acsmem +@c update_cur_sifted_state @mtslocale @ascuheap @acsmem +@c add_epsilon_src_nodes @ascuheap @acsmem +@c re_acquire_state dup @ascuheap @acsmem +@c re_node_set_alloc dup @ascuheap @acsmem +@c re_node_set_merge dup @ascuheap @acsmem +@c re_node_set_add_intersect @ascuheap @acsmem +@c (re_)realloc dup @ascuheap @acsmem +@c check_subexp_limits @ascuheap @acsmem +@c sub_epsilon_src_nodes @ascuheap @acsmem +@c re_node_set_init_empty dup ok +@c re_node_set_contains dup ok +@c re_node_set_add_intersect dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c re_node_set_remove_at dup ok +@c re_node_set_contains dup ok +@c re_acquire_state dup @ascuheap @acsmem +@c sift_states_bkref @mtslocale @ascuheap @acsmem +@c search_cur_bkref_entry dup ok +@c check_dst_limits ok +@c search_cur_bkref_entry dup ok +@c check_dst_limits_calc_pos ok +@c check_dst_limits_calc_pos_1 ok +@c re_node_set_init_copy dup @ascuheap @acsmem +@c re_node_set_insert dup @ascuheap @acsmem +@c sift_states_backward dup @mtslocale @ascuheap @acsmem +@c merge_state_array dup @ascuheap @acsmem +@c re_node_set_remove ok +@c re_node_set_contains dup ok +@c re_node_set_remove_at dup ok +@c re_node_set_free dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c re_node_set_empty dup ok +@c build_sifted_states @mtslocale @ascuheap @acsmem +@c sift_states_iter_mb @mtslocale @ascuheap @acsmem +@c check_node_accept_bytes dup @mtslocale @ascuheap @acsmem +@c check_node_accept dup ok +@c check_dst_limits dup ok +@c re_node_set_insert dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c check_halt_state_context dup ok +@c merge_state_array @ascuheap @acsmem +@c re_node_set_init_union dup @ascuheap @acsmem +@c re_acquire_state dup @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c set_regs @ascuheap @acsmem +@c (re_)malloc dup @ascuheap @acsmem +@c re_node_set_init_empty dup ok +@c free_fail_stack_return @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c update_regs ok +@c re_node_set_free dup @ascuheap @acsmem +@c pop_fail_stack @ascuheap @acsmem +@c re_node_set_free dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c match_ctx_free @ascuheap @acsmem +@c match_ctx_clean @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c (re_)free dup @ascuheap @acsmem +@c re_string_destruct dup @ascuheap @acsmem +@c libc_lock_unlock @aculock This function tries to match the compiled regular expression @code{*@var{compiled}} against @var{string}. @@ -1033,6 +1624,9 @@ @comment regex.h @comment POSIX.2 @deftypefun void regfree (regex_t *@var{compiled}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c (re_)free dup @ascuheap @acsmem +@c free_dfa_content dup @ascuheap @acsmem Calling @code{regfree} frees all the storage that @code{*@var{compiled}} points to. This includes various internal fields of the @code{regex_t} structure that aren't documented in this manual. @@ -1050,6 +1644,8 @@ @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}) +@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 @var{errcode}, and stores the string in @var{length} bytes of memory starting at @var{buffer}. For the @var{compiled} argument, supply the @@ -1215,6 +1811,145 @@ @comment wordexp.h @comment POSIX.2 @deftypefun int wordexp (const char *@var{words}, wordexp_t *@var{word-vector-ptr}, int @var{flags}) +@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 +@c wordfree dup @asucorrupt @ascuheap @acucorrupt @acsmem +@c calloc dup @ascuheap @acsmem +@c getenv dup @mtsenv +@c strcpy dup ok +@c parse_backslash @ascuheap @acsmem +@c w_addchar dup @ascuheap @acsmem +@c parse_dollars @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c w_addchar dup @ascuheap @acsmem +@c parse_arith @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c w_newword dup ok +@c parse_dollars dup @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c parse_backtick dup @ascuplugin @ascuheap @aculock @acsfd @acsmem +@c parse_qtd_backslash dup @ascuheap @acsmem +@c eval_expr @mtslocale +@c eval_expr_multidiv @mtslocale +@c eval_expr_val @mtslocale +@c isspace dup @mtslocale +@c eval_expr dup @mtslocale +@c isspace dup @mtslocale +@c isspace dup @mtslocale +@c free dup @ascuheap @acsmem +@c w_addchar dup @ascuheap @acsmem +@c w_addstr dup @ascuheap @acsmem +@c itoa_word dup ok +@c parse_comm @ascuplugin @ascuheap @aculock @acsfd @acsmem +@c w_newword dup ok +@c pthread_setcancelstate @ascuplugin @ascuheap @acsmem +@c (disable cancellation around exec_comm; it may do_cancel the +@c second time, if async cancel is enabled) +@c THREAD_ATOMIC_CMPXCHG_VAL dup ok +@c CANCEL_ENABLED_AND_CANCELED_AND_ASYNCHRONOUS dup ok +@c do_cancel @ascuplugin @ascuheap @acsmem +@c THREAD_ATOMIC_BIT_SET dup ok +@c pthread_unwind @ascuplugin @ascuheap @acsmem +@c Unwind_ForcedUnwind if available @ascuplugin @ascuheap @acsmem +@c libc_unwind_longjmp otherwise +@c cleanups +@c exec_comm @ascuplugin @ascuheap @aculock @acsfd @acsmem +@c pipe2 dup ok +@c pipe dup ok +@c fork dup @ascuplugin @aculock +@c close dup @acsfd +@c on child: exec_comm_child -> exec or abort +@c waitpid dup ok +@c read dup ok +@c w_addmem dup @ascuheap @acsmem +@c strchr dup ok +@c w_addword dup @ascuheap @acsmem +@c w_newword dup ok +@c w_addchar dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c kill dup ok +@c free dup @ascuheap @acsmem +@c parse_param @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c reads from __libc_argc and __libc_argv without guards +@c w_newword dup ok +@c isalpha dup @mtslocale^^ +@c w_addchar dup @ascuheap @acsmem +@c isalnum dup @mtslocale^^ +@c isdigit dup @mtslocale^^ +@c strchr dup ok +@c itoa_word dup ok +@c atoi dup @mtslocale +@c getpid dup ok +@c w_addstr dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c stpcpy dup ok +@c w_addword dup @ascuheap @acsmem +@c strdup dup @ascuheap @acsmem +@c getenv dup @mtsenv +@c parse_dollars dup @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c parse_tilde dup @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c fnmatch dup @mtsenv @mtslocale @ascuheap @acsmem +@c mempcpy dup ok +@c _ dup @ascuintl +@c fxprintf dup @aculock +@c setenv dup @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem +@c strspn dup ok +@c strcspn dup ok +@c parse_backtick @ascuplugin @ascuheap @aculock @acsfd @acsmem +@c w_newword dup ok +@c exec_comm dup @ascuplugin @ascuheap @aculock @acsfd @acsmem +@c free dup @ascuheap @acsmem +@c parse_qtd_backslash dup @ascuheap @acsmem +@c parse_backslash dup @ascuheap @acsmem +@c w_addchar dup @ascuheap @acsmem +@c parse_dquote @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c parse_dollars dup @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c parse_backtick dup @ascuplugin @ascuheap @aculock @acsfd @acsmem +@c parse_qtd_backslash dup @ascuheap @acsmem +@c w_addchar dup @ascuheap @acsmem +@c w_addword dup @ascuheap @acsmem +@c strdup dup @ascuheap @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c parse_squote dup @ascuheap @acsmem +@c w_addchar dup @ascuheap @acsmem +@c parse_tilde @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c strchr dup ok +@c w_addchar dup @ascuheap @acsmem +@c getenv dup @mtsenv +@c w_addstr dup @ascuheap @acsmem +@c strlen dup ok +@c w_addmem dup @ascuheap @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c mempcpy dup ok +@c getuid dup ok +@c getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c parse_glob @mtasurace:utent @mtasuconst:@mtsenv @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c strchr dup ok +@c parse_dollars dup @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c parse_qtd_backslash @ascuheap @acsmem +@c w_addchar dup @ascuheap @acsmem +@c parse_backslash dup @ascuheap @acsmem +@c w_addchar dup @ascuheap @acsmem +@c w_addword dup @ascuheap @acsmem +@c w_newword dup ok +@c do_parse_glob @mtasurace:utent @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @aculock @acsfd @acsmem +@c glob dup @mtasurace:utent @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @aculock @acsfd @acsmem [auto glob_t avoids @asucorrupt @acucorrupt] +@c w_addstr dup @ascuheap @acsmem +@c w_addchar dup @ascuheap @acsmem +@c globfree dup @ascuheap @acsmem [auto glob_t avoids @asucorrupt @acucorrupt] +@c free dup @ascuheap @acsmem +@c w_newword dup ok +@c strdup dup @ascuheap @acsmem +@c w_addword dup @ascuheap @acsmem +@c wordfree dup @asucorrupt @ascuheap @acucorrupt @acsmem +@c strchr dup ok +@c w_addchar dup @ascuheap @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem Perform word expansion on the string @var{words}, putting the result in a newly allocated vector, and store the size and address of this vector into @code{*@var{word-vector-ptr}}. The argument @var{flags} is a @@ -1278,6 +2013,9 @@ @comment wordexp.h @comment POSIX.2 @deftypefun void wordfree (wordexp_t *@var{word-vector-ptr}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} +@c wordfree dup @asucorrupt @ascuheap @acucorrupt @acsmem +@c free dup @ascuheap @acsmem Free the storage used for the word-strings and vector that @code{*@var{word-vector-ptr}} points to. This does not free the structure @code{*@var{word-vector-ptr}} itself---only the other diff -urN glibc-2.17-c758a686/manual/pipe.texi glibc-2.17-c758a686/manual/pipe.texi --- glibc-2.17-c758a686/manual/pipe.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/pipe.texi 2014-09-12 16:10:06.048792709 -0400 @@ -56,6 +56,8 @@ @comment unistd.h @comment POSIX.1 @deftypefun int pipe (int @var{filedes}@t{[2]}) +@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 for the reading and writing ends of the pipe (respectively) into @code{@var{filedes}[0]} and @code{@var{filedes}[1]}. @@ -108,6 +110,41 @@ @comment stdio.h @comment POSIX.2, SVID, BSD @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c popen @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem +@c malloc dup @ascuheap @acsmem +@c _IO_init ok +@c _IO_no_init ok +@c _IO_old_init ok +@c _IO_lock_init ok +@c _IO_new_file_init @asucorrupt @acucorrupt @aculock @acsfd +@c _IO_link_in @asucorrupt @acucorrupt @aculock @acsfd +@c the linked list is guarded by a recursive lock; +@c it may get corrupted with async signals and cancellation +@c _IO_lock_lock dup @aculock +@c _IO_flockfile dup @aculock +@c _IO_funlockfile dup @aculock +@c _IO_lock_unlock dup @aculock +@c _IO_new_proc_open @asucorrupt @acucorrupt @aculock @acsfd +@c the linked list is guarded by a recursive lock; + @c it may get corrupted with async signals and cancellation +@c _IO_file_is_open ok +@c pipe2 dup @acsfd +@c pipe dup @acsfd +@c _IO_fork=fork @aculock +@c _IO_close=close_not_cancel dup @acsfd +@c fcntl dup ok +@c _IO_lock_lock @aculock +@c _IO_lock_unlock @aculock +@c _IO_mask_flags ok [no @mtasurace:stream, nearly but sufficiently exclusive access] +@c _IO_un_link @asucorrupt @acucorrupt @aculock @acsfd +@c the linked list is guarded by a recursive lock; +@c it may get corrupted with async signals and cancellation +@c _IO_lock_lock dup @aculock +@c _IO_flockfile dup @aculock +@c _IO_funlockfile dup @aculock +@c _IO_lock_unlock dup @aculock +@c free dup @ascuheap @acsmem The @code{popen} function is closely related to the @code{system} function; see @ref{Running a Command}. It executes the shell command @var{command} as a subprocess. However, instead of waiting for the @@ -131,6 +168,77 @@ @comment stdio.h @comment POSIX.2, SVID, BSD @deftypefun int pclose (FILE *@var{stream}) +@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 +@c is called, other stdio linked lists and their locks may be left in +@c corrupt states; that's where the corrupt and lock annotations come +@c from. +@c +@c pclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem +@c _IO_new_fclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem +@c _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd +@c _IO_acquire_lock dup @aculock +@c _IO_flockfile dup @aculock +@c _IO_file_close_it @ascuheap @ascuplugin @asucorrupt @aculock @acucorrupt @acsfd @acsmem +@c _IO_file_is_open dup ok +@c _IO_do_flush @asucorrupt @ascuplugin @acucorrupt +@c _IO_do_write @asucorrupt @acucorrupt +@c new_do_write @asucorrupt @acucorrupt +@c _IO_SYSSEEK ok +@c lseek64 dup ok +@c _IO_SYSWRITE ok +@c write_not_cancel dup ok +@c write dup ok +@c _IO_adjust_column ok +@c _IO_setg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked] +@c _IO_wdo_write @asucorrupt @ascuplugin @acucorrupt +@c _IO_new_do_write=_IO_do_write dup @asucorrupt @acucorrupt +@c *cc->__codecvt_do_out @ascuplugin +@c _IO_wsetg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked] +@c _IO_unsave_markers @ascuheap @asucorrupt @acucorrupt @acsmem +@c _IO_have_backup dup ok +@c _IO_free_backup_area dup @ascuheap @asucorrupt @acucorrupt @acsmem +@c _IO_SYSCLOSE @aculock @acucorrupt @acsfd +@c _IO_lock_lock dup @aculock +@c _IO_close=close_not_cancel dup @acsfd +@c _IO_lock_unlock dup @aculock +@c _IO_waitpid=waitpid_not_cancel dup ok +@c _IO_have_wbackup ok +@c _IO_free_wbackup_area @ascuheap @asucorrupt @acucorrupt @acsmem +@c _IO_in_backup dup ok +@c _IO_switch_to_main_wget_area @asucorrupt @acucorrupt +@c free dup @ascuheap @acsmem +@c _IO_wsetb @asucorrupt @acucorrupt [no @mtasurace:stream, locked] +@c _IO_wsetg @asucorrupt @acucorrupt [no @mtasurace:stream, locked] +@c _IO_wsetp @asucorrupt @acucorrupt [no @mtasurace:stream, locked] +@c _IO_setb @asucorrupt @acucorrupt [no @mtasurace:stream, locked] +@c _IO_setg @asucorrupt @acucorrupt [no @mtasurace:stream, locked] +@c _IO_setp @asucorrupt @acucorrupt [no @mtasurace:stream, locked] +@c _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd +@c _IO_release_lock dup @aculock +@c _IO_funlockfile dup @aculock +@c _IO_FINISH @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem +@c _IO_new_file_finish @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem +@c _IO_file_is_open dup ok +@c _IO_do_flush dup @ascuplugin @asucorrupt @acucorrupt +@c _IO_SYSCLOSE dup @aculock @acucorrupt @acsfd +@c _IO_default_finish @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem +@c FREE_BUF @acsmem +@c munmap dup @acsmem +@c free dup @ascuheap @acsmem +@c _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd +@c _IO_lock_fini ok +@c libc_lock_fini_recursive ok +@c libc_lock_lock dup @asulock @aculock +@c gconv_release_step ok +@c libc_lock_unlock dup @asulock @aculock +@c _IO_have_backup ok +@c _IO_free_backup_area @ascuheap @asucorrupt @acucorrupt @acsmem +@c _IO_in_backup ok +@c _IO_switch_to_main_get_area @asucorrupt @acucorrupt +@c free dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem The @code{pclose} function is used to close a stream created by @code{popen}. It waits for the child process to terminate and returns its status value, as for the @code{system} function. @@ -168,6 +276,8 @@ @comment sys/stat.h @comment POSIX.1 @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c On generic Posix, calls xmknod. The @code{mkfifo} function makes a FIFO special file with name @var{filename}. The @var{mode} argument is used to set the file's permissions; see @ref{Setting Permissions}. diff -urN glibc-2.17-c758a686/manual/platform.texi glibc-2.17-c758a686/manual/platform.texi --- glibc-2.17-c758a686/manual/platform.texi 2014-09-12 16:08:17.865070640 -0400 +++ glibc-2.17-c758a686/manual/platform.texi 2014-09-12 16:10:06.046792714 -0400 @@ -15,6 +15,7 @@ operating system are declared in @file{sys/platform/ppc.h}. @deftypefun {uint64_t} __ppc_get_timebase (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Read the current value of the Time Base Register. The @dfn{Time Base Register} is a 64-bit register that stores a monotonically @@ -28,6 +29,17 @@ @end deftypefun @deftypefun {uint64_t} __ppc_get_timebase_freq (void) +@safety{@prelim{}@mtunsafe{@mtuinit{}}@asunsafe{@asucorrupt{:init}}@acunsafe{@acucorrupt{:init}}} +@c __ppc_get_timebase_freq=__get_timebase_freq @mtuinit @acsfd +@c __get_clockfreq @mtuinit @asucorrupt:init @acucorrupt:init @acsfd +@c the initialization of the static timebase_freq is not exactly +@c safe, because hp_timing_t cannot be atomically set up. +@c syscall:get_tbfreq ok +@c open dup @acsfd +@c read dup ok +@c memcpy dup ok +@c memmem dup ok +@c close dup @acsfd Read the current frequency at which the Time Base Register is updated. This frequency is not related to the processor clock or the bus clock. @@ -42,17 +54,20 @@ Section 3.2}. @deftypefun {void} __ppc_yield (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Provide a hint that performance will probably be improved if shared resources dedicated to the executing processor are released for use by other processors. @end deftypefun @deftypefun {void} __ppc_mdoio (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Provide a hint that performance will probably be improved if shared resources dedicated to the executing processor are released until all outstanding storage accesses to caching-inhibited storage have been completed. @end deftypefun @deftypefun {void} __ppc_mdoom (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Provide a hint that performance will probably be improved if shared resources dedicated to the executing processor are released until all outstanding storage accesses to cacheable storage for which the data is not in the cache have been @@ -60,6 +75,7 @@ @end deftypefun @deftypefun {void} __ppc_set_ppr_med (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Set the Program Priority Register to medium value (default). The @dfn{Program Priority Register} (PPR) is a 64-bit register that controls @@ -73,9 +89,11 @@ @end deftypefun @deftypefun {void} __ppc_set_ppr_low (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Set the Program Priority Register to low value. @end deftypefun @deftypefun {void} __ppc_set_ppr_med_low (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Set the Program Priority Register to medium low value. @end deftypefun diff -urN glibc-2.17-c758a686/manual/process.texi glibc-2.17-c758a686/manual/process.texi --- glibc-2.17-c758a686/manual/process.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/process.texi 2014-09-12 16:10:06.044792719 -0400 @@ -1,4 +1,4 @@ -@node Processes, Job Control, Program Basics, Top +@node Processes, Inter-Process Communication, Program Basics, Top @c %MENU% How to create processes and run other programs @chapter Processes @@ -55,6 +55,43 @@ @comment ISO @deftypefun int system (const char *@var{command}) @pindex sh +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} +@c system @ascuplugin @ascuheap @asulock @aculock @acsmem +@c do_system @ascuplugin @ascuheap @asulock @aculock @acsmem +@c sigemptyset dup ok +@c libc_lock_lock @asulock @aculock +@c ADD_REF ok +@c sigaction dup ok +@c SUB_REF ok +@c libc_lock_unlock @aculock +@c sigaddset dup ok +@c sigprocmask dup ok +@c CLEANUP_HANDLER @ascuplugin @ascuheap @acsmem +@c libc_cleanup_region_start @ascuplugin @ascuheap @acsmem +@c pthread_cleanup_push_defer @ascuplugin @ascuheap @acsmem +@c CANCELLATION_P @ascuplugin @ascuheap @acsmem +@c CANCEL_ENABLED_AND_CANCELED ok +@c do_cancel @ascuplugin @ascuheap @acsmem +@c cancel_handler ok +@c kill syscall ok +@c waitpid dup ok +@c libc_lock_lock ok +@c sigaction dup ok +@c libc_lock_unlock ok +@c FORK ok +@c clone syscall ok +@c waitpid dup ok +@c CLEANUP_RESET ok +@c libc_cleanup_region_end ok +@c pthread_cleanup_pop_restore ok +@c SINGLE_THREAD_P ok +@c LIBC_CANCEL_ASYNC @ascuplugin @ascuheap @acsmem +@c libc_enable_asynccancel @ascuplugin @ascuheap @acsmem +@c CANCEL_ENABLED_AND_CANCELED_AND_ASYNCHRONOUS dup ok +@c do_cancel dup @ascuplugin @ascuheap @acsmem +@c LIBC_CANCEL_RESET ok +@c libc_disable_asynccancel ok +@c lll_futex_wait dup ok This function executes @var{command} as a shell command. In @theglibc{}, it always uses the default shell @code{sh} to run the command. In particular, it searches the directories in @code{PATH} to find @@ -157,12 +194,14 @@ @comment unistd.h @comment POSIX.1 @deftypefun pid_t getpid (void) +@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) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getppid} function returns the process ID of the parent of the current process. @end deftypefun @@ -177,6 +216,19 @@ @comment unistd.h @comment POSIX.1 @deftypefun pid_t fork (void) +@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 +@c ops and retries, avoiding locking altogether. It then takes the +@c IO_list lock, resets the thread-local pid, and runs fork. The parent +@c restores the thread-local pid, releases the lock, and runs parent +@c handlers, decrementing the ref count and signaling futex wait if +@c requested by unregister_atfork. The child bumps the fork generation, +@c sets the thread-local pid, resets cpu clocks, initializes the robust +@c mutex list, the stream locks, the IO_list lock, the dynamic loader +@c lock, runs the child handlers, reseting ref counters to 1, and +@c initializes the fork lock. These are all safe, unless atfork +@c handlers themselves are unsafe. The @code{fork} function creates a new process. If the operation is successful, there are then both parent and child @@ -242,6 +294,9 @@ @comment unistd.h @comment BSD @deftypefun pid_t vfork (void) +@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. The @code{vfork} function is similar to @code{fork} but on some systems it is more efficient; however, there are restrictions you must follow to use it safely. @@ -287,6 +342,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{execv} function executes the file named by @var{filename} as a new process image. @@ -305,6 +361,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{}) +@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. @@ -313,6 +370,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]}) +@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 be an array of strings in the same format as for the @code{environ} @@ -322,6 +380,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, @dots{}, char *const @var{env}@t{[]}) +@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 passed following the null pointer that marks the last @var{argv} @@ -332,6 +391,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]}) +@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 (@pxref{Standard Environment}) to find the full file name of a @@ -345,6 +405,7 @@ @comment unistd.h @comment POSIX.1 @deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{}) +@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. @end deftypefun @@ -462,6 +523,7 @@ @comment sys/wait.h @comment POSIX.1 @deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status-ptr}, int @var{options}) +@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 process is suspended until the child process makes status information @@ -565,6 +627,7 @@ @comment sys/wait.h @comment POSIX.1 @deftypefun pid_t wait (int *@var{status-ptr}) +@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: @@ -591,6 +654,7 @@ @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}) +@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})}. @@ -643,6 +707,7 @@ @comment sys/wait.h @comment POSIX.1 @deftypefn Macro int WIFEXITED (int @var{status}) +@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 @@ -650,6 +715,7 @@ @comment sys/wait.h @comment POSIX.1 @deftypefn Macro int WEXITSTATUS (int @var{status}) +@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}. @@ -658,6 +724,7 @@ @comment sys/wait.h @comment POSIX.1 @deftypefn Macro int WIFSIGNALED (int @var{status}) +@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}. @@ -666,6 +733,7 @@ @comment sys/wait.h @comment POSIX.1 @deftypefn Macro int WTERMSIG (int @var{status}) +@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 @@ -673,6 +741,7 @@ @comment sys/wait.h @comment BSD @deftypefn Macro int WCOREDUMP (int @var{status}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro returns a nonzero value if the child process terminated and produced a core dump. @end deftypefn @@ -680,12 +749,14 @@ @comment sys/wait.h @comment POSIX.1 @deftypefn Macro int WIFSTOPPED (int @var{status}) +@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}) +@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. @end deftypefn @@ -739,6 +810,7 @@ @comment sys/wait.h @comment BSD @deftypefun pid_t wait3 (union wait *@var{status-ptr}, int @var{options}, struct rusage *@var{usage}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} If @var{usage} is a null pointer, @code{wait3} is equivalent to @code{waitpid (-1, @var{status-ptr}, @var{options})}. diff -urN glibc-2.17-c758a686/manual/resource.texi glibc-2.17-c758a686/manual/resource.texi --- glibc-2.17-c758a686/manual/resource.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/resource.texi 2014-09-12 16:10:06.044792719 -0400 @@ -25,6 +25,8 @@ @comment sys/resource.h @comment BSD @deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage}) +@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 @var{processes}, storing the information in @code{*@var{rusage}}. @@ -129,9 +131,11 @@ @code{vtimes} and its @code{vtimes} data structure are declared in @file{sys/vtimes.h}. @pindex sys/vtimes.h -@comment vtimes.h -@deftypefun int vtimes (struct vtimes @var{current}, struct vtimes @var{child}) +@comment sys/vtimes.h +@deftypefun int vtimes (struct vtimes *@var{current}, struct vtimes *@var{child}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Calls getrusage twice. @code{vtimes} reports resource usage totals for a process. @@ -223,6 +227,8 @@ @comment sys/resource.h @comment BSD @deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall on most systems. Read the current and maximum limits for the resource @var{resource} and store them in @code{*@var{rlp}}. @@ -237,6 +243,8 @@ @comment sys/resource.h @comment Unix98 @deftypefun int getrlimit64 (int @var{resource}, struct rlimit64 *@var{rlp}) +@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 a pointer to a variable of type @code{struct rlimit64}, which allows it to read values which wouldn't fit in the member of a @code{struct @@ -250,6 +258,8 @@ @comment sys/resource.h @comment BSD @deftypefun int setrlimit (int @var{resource}, const struct rlimit *@var{rlp}) +@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} in @code{*@var{rlp}}. @@ -275,6 +285,8 @@ @comment sys/resource.h @comment Unix98 @deftypefun int setrlimit64 (int @var{resource}, const struct rlimit64 *@var{rlp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Wrapper for setrlimit or direct syscall. This function is similar to @code{setrlimit} but its second parameter is a pointer to a variable of type @code{struct rlimit64} which allows it to set values which wouldn't fit in the member of a @code{struct @@ -419,7 +431,7 @@ @comment sys/resource.h @comment BSD -@deftypevr Constant int RLIM_INFINITY +@deftypevr Constant rlim_t RLIM_INFINITY This constant stands for a value of ``infinity'' when supplied as the limit value in @code{setrlimit}. @end deftypevr @@ -433,7 +445,10 @@ @comment ulimit.h @comment BSD -@deftypefun int ulimit (int @var{cmd}, @dots{}) +@deftypefun {long int} ulimit (int @var{cmd}, @dots{}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Wrapper for getrlimit, setrlimit or +@c sysconf(_SC_OPEN_MAX)->getdtablesize->getrlimit. @code{ulimit} gets the current limit or sets the current and maximum limit for a particular resource for the calling process according to the @@ -480,6 +495,10 @@ @comment sys/vlimit.h @comment BSD @deftypefun int vlimit (int @var{resource}, int @var{limit}) +@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 +@c modifies e.g. rlim_max, which will be lost if running as super-user. @code{vlimit} sets the current limit for a resource for a process. @@ -778,6 +797,8 @@ @comment sched.h @comment POSIX @deftypefun int sched_setscheduler (pid_t @var{pid}, int @var{policy}, const struct sched_param *@var{param}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall, Linux only. This function sets both the absolute priority and the scheduling policy for a process. @@ -848,6 +869,8 @@ @comment sched.h @comment POSIX @deftypefun int sched_getscheduler (pid_t @var{pid}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall, Linux only. This function returns the scheduling policy assigned to the process with Process ID (pid) @var{pid}, or the calling process if @var{pid} is zero. @@ -881,6 +904,8 @@ @comment sched.h @comment POSIX @deftypefun int sched_setparam (pid_t @var{pid}, const struct sched_param *@var{param}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall, Linux only. This function sets a process' absolute priority. @@ -893,7 +918,9 @@ @comment sched.h @comment POSIX -@deftypefun int sched_getparam (pid_t @var{pid}, const struct sched_param *@var{param}) +@deftypefun int sched_getparam (pid_t @var{pid}, struct sched_param *@var{param}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall, Linux only. This function returns a process' absolute priority. @@ -922,7 +949,9 @@ @comment sched.h @comment POSIX -@deftypefun int sched_get_priority_min (int *@var{policy}) +@deftypefun int sched_get_priority_min (int @var{policy}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall, Linux only. This function returns the lowest absolute priority value that is allowable for a process with scheduling policy @var{policy}. @@ -942,7 +971,9 @@ @comment sched.h @comment POSIX -@deftypefun int sched_get_priority_max (int *@var{policy}) +@deftypefun int sched_get_priority_max (int @var{policy}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall, Linux only. This function returns the highest absolute priority value that is allowable for a process that with scheduling policy @var{policy}. @@ -963,6 +994,8 @@ @comment sched.h @comment POSIX @deftypefun int sched_rr_get_interval (pid_t @var{pid}, struct timespec *@var{interval}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall, Linux only. This function returns the length of the quantum (time slice) used with the Round Robin scheduling policy, if it is used, for the process with @@ -987,6 +1020,8 @@ @comment sched.h @comment POSIX @deftypefun int sched_yield (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall on Linux; alias to swtch on HURD. This function voluntarily gives up the process' claim on the CPU. @@ -1045,7 +1080,7 @@ about. But just to be clear about the scope of this scheduling: Any time a -process with a absolute priority of 0 and a process with an absolute +process with an absolute priority of 0 and a process with an absolute priority higher than 0 are ready to run at the same time, the one with absolute priority 0 does not run. If it's already running when the higher priority ready-to-run process comes into existence, it stops @@ -1138,6 +1173,8 @@ @comment sys/resource.h @comment BSD,POSIX @deftypefun int getpriority (int @var{class}, int @var{id}) +@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} specify which ones (see below). If the processes specified do not all have the same nice value, this returns the lowest value that any of them @@ -1165,6 +1202,8 @@ @comment sys/resource.h @comment BSD,POSIX @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{niceval}) +@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} and @var{id} specify which ones (see below). @@ -1222,6 +1261,11 @@ @comment unistd.h @comment BSD @deftypefun int nice (int @var{increment}) +@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 +@c a window for a concurrent setpriority (or nice) call to be lost or +@c exhibit surprising behavior. Increment the nice value of the calling process by @var{increment}. The return value is the new nice value on success, and @code{-1} on failure. In the case of failure, @code{errno} will be set to the @@ -1319,6 +1363,10 @@ @comment sched.h @comment GNU @deftypefn Macro void CPU_ZERO (cpu_set_t *@var{set}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_ZERO ok +@c __CPU_ZERO_S ok +@c memset dup ok 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}. @@ -1327,6 +1375,11 @@ @comment sched.h @comment GNU @deftypefn Macro void CPU_SET (int @var{cpu}, cpu_set_t *@var{set}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_SET ok +@c __CPU_SET_S ok +@c __CPUELT ok +@c __CPUMASK ok This macro adds @var{cpu} to the CPU set @var{set}. The @var{cpu} parameter must not have side effects since it is @@ -1338,6 +1391,11 @@ @comment sched.h @comment GNU @deftypefn Macro void CPU_CLR (int @var{cpu}, cpu_set_t *@var{set}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_CLR ok +@c __CPU_CLR_S ok +@c __CPUELT dup ok +@c __CPUMASK dup ok This macro removes @var{cpu} from the CPU set @var{set}. The @var{cpu} parameter must not have side effects since it is @@ -1349,6 +1407,11 @@ @comment sched.h @comment GNU @deftypefn Macro int CPU_ISSET (int @var{cpu}, const cpu_set_t *@var{set}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c CPU_ISSET ok +@c __CPU_ISSET_S ok +@c __CPUELT dup ok +@c __CPUMASK dup ok This macro returns a nonzero value (true) if @var{cpu} is a member of the CPU set @var{set}, and zero (false) otherwise. @@ -1365,6 +1428,9 @@ @comment sched.h @comment GNU @deftypefun int sched_getaffinity (pid_t @var{pid}, size_t @var{cpusetsize}, cpu_set_t *@var{cpuset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Wrapped syscall to zero out past the kernel cpu set size; Linux +@c only. This functions stores the CPU affinity mask for the process or thread with the ID @var{pid} in the @var{cpusetsize} bytes long bitmap @@ -1393,6 +1459,9 @@ @comment sched.h @comment GNU @deftypefun int sched_setaffinity (pid_t @var{pid}, size_t @var{cpusetsize}, const cpu_set_t *@var{cpuset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Wrapped syscall to detect attempts to set bits past the kernel cpu +@c set size; Linux only. This function installs the @var{cpusetsize} bytes long affinity mask pointed to by @var{cpuset} for the process or thread with the ID @var{pid}. @@ -1516,6 +1585,9 @@ @comment unistd.h @comment BSD @deftypefun int getpagesize (void) +@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. The @code{getpagesize} function returns the page size of the process. This value is fixed for the runtime of the process but can vary in different runs of the application. @@ -1559,6 +1631,8 @@ @comment sys/sysinfo.h @comment GNU @deftypefun {long int} get_phys_pages (void) +@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 physical the system has. To get the amount of memory this number has to be multiplied by the page size. @@ -1569,7 +1643,8 @@ @comment sys/sysinfo.h @comment GNU @deftypefun {long int} get_avphys_pages (void) -The @code{get_phys_pages} function returns the number of available pages of +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} +The @code{get_avphys_pages} function returns the number of available pages of physical the system has. To get the amount of memory this number has to be multiplied by the page size. @@ -1614,6 +1689,9 @@ @comment sys/sysinfo.h @comment GNU @deftypefun int get_nprocs_conf (void) +@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. The @code{get_nprocs_conf} function returns the number of processors the operating system configured. @@ -1623,6 +1701,8 @@ @comment sys/sysinfo.h @comment GNU @deftypefun int get_nprocs (void) +@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. This function is a GNU extension. @@ -1638,8 +1718,12 @@ @comment stdlib.h @comment BSD @deftypefun int getloadavg (double @var{loadavg}[], int @var{nelem}) +@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 +@c the C locale to convert the strings to doubles. This function gets the 1, 5 and 15 minute load averages of the -system. The values are placed in @var{loadavg}. @code{getloadavg} will +system. The values are placed in @var{loadavg}. @code{getloadavg} will place at most @var{nelem} elements into the array but never more than three elements. The return value is the number of elements written to @var{loadavg}, or -1 on error. diff -urN glibc-2.17-c758a686/manual/search.texi glibc-2.17-c758a686/manual/search.texi --- glibc-2.17-c758a686/manual/search.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/search.texi 2014-09-12 16:10:06.043792722 -0400 @@ -71,7 +71,8 @@ @comment search.h @comment SVID -@deftypefun {void *} lfind (const void *@var{key}, void *@var{base}, size_t *@var{nmemb}, size_t @var{size}, comparison_fn_t @var{compar}) +@deftypefun {void *} lfind (const void *@var{key}, const void *@var{base}, size_t *@var{nmemb}, size_t @var{size}, comparison_fn_t @var{compar}) +@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 which matches the one pointed to by @var{key}. The function pointed to @@ -90,6 +91,21 @@ @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}) +@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 +@c new element initialized twice, with parts of both initializations +@c prevailing, and another uninitialized element), but this is just a +@c special case of races on user-controlled objects, that have to be +@c avoided by users. + +@c In case of cancellation, we know the array won't be left in a corrupt +@c state; the new element is initialized before the element count is +@c incremented, and the compiler can't reorder these operations because +@c it can't know that they don't alias. So, we'll either cancel after +@c the increment and the initialization are both complete, or the +@c increment won't have taken place, and so how far the initialization +@c got doesn't matter. The @code{lsearch} function is similar to the @code{lfind} function. It searches the given array for an element and returns it if found. The difference is that if no matching element is found the @code{lsearch} @@ -113,6 +129,7 @@ @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}) +@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, each of which is of size @var{size} bytes. @@ -146,6 +163,7 @@ @comment stdlib.h @comment ISO @deftypefun void qsort (void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare}) +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} The @var{qsort} function sorts the array @var{array}. The array contains @var{count} elements, each of which is of size @var{size}. @@ -256,6 +274,9 @@ @comment search.h @comment SVID @deftypefun int hcreate (size_t @var{nel}) +@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 The @code{hcreate} function creates a hashing table which can contain at least @var{nel} elements. There is no possibility to grow this table so it is necessary to choose the value for @var{nel} wisely. The method @@ -270,7 +291,7 @@ The weakest aspect of this function is that there can be at most one hashing table used through the whole program. The table is allocated in local memory out of control of the programmer. As an extension @theglibc{} -provides an additional set of functions with an reentrant +provides an additional set of functions with a reentrant interface which provide a similar interface but which allow to keep arbitrarily many hashing tables. @@ -285,6 +306,9 @@ @comment search.h @comment SVID @deftypefun void hdestroy (void) +@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 The @code{hdestroy} function can be used to free all the resources allocated in a previous call of @code{hcreate}. After a call to this function it is again possible to call @code{hcreate} and allocate a new @@ -328,6 +352,9 @@ @comment search.h @comment SVID @deftypefun {ENTRY *} hsearch (ENTRY @var{item}, ACTION @var{action}) +@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 To search in a hashing table created using @code{hcreate} the @code{hsearch} function must be used. This function can perform simple search for an element (if @var{action} has the @code{FIND}) or it can @@ -358,6 +385,24 @@ @comment search.h @comment GNU @deftypefun int hcreate_r (size_t @var{nel}, struct hsearch_data *@var{htab}) +@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 +@c caller responsibility. + +@c Cancellation is unlikely to leave the htab in a corrupt state: the +@c last field to be initialized is the one that tells whether the entire +@c data structure was initialized, and there's a function call (calloc) +@c in between that will often ensure all other fields are written before +@c the table. However, should this call be inlined (say with LTO), this +@c assumption may not hold. The calloc call doesn't cross our library +@c interface barrier, so let's consider this could happen and mark this +@c with @acucorrupt. It's no safety loss, since we already have +@c @ascuheap anyway... + +@c hcreate_r @mtsrace:htab @ascuheap @acucorrupt @acsmem +@c isprime ok +@c calloc dup @ascuheap @acsmem The @code{hcreate_r} function initializes the object pointed to by @var{htab} to contain a hashing table with at least @var{nel} elements. So this function is equivalent to the @code{hcreate} function except @@ -376,6 +421,16 @@ @comment search.h @comment GNU @deftypefun void hdestroy_r (struct hsearch_data *@var{htab}) +@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 +@c free(). Using the table in a handler while it's being released would +@c also be dangerous, but calling free() already makes it unsafe, and +@c the requirement on the caller to ensure exclusive access already +@c guarantees this doesn't happen, so we don't get @asucorrupt. + +@c hdestroy_r @mtsrace:htab @ascuheap @acucorrupt @acsmem +@c free dup @ascuheap @acsmem The @code{hdestroy_r} function frees all resources allocated by the @code{hcreate_r} function for this very same object @var{htab}. As for @code{hdestroy} it is the programs responsibility to free the strings @@ -385,6 +440,13 @@ @comment search.h @comment GNU @deftypefun int hsearch_r (ENTRY @var{item}, ACTION @var{action}, ENTRY **@var{retval}, struct hsearch_data *@var{htab}) +@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. + +@c hsearch_r @mtsrace:htab @acucorrupt/action==ENTER +@c strlen dup ok +@c strcmp dup ok The @code{hsearch_r} function is equivalent to @code{hsearch}. The meaning of the first two arguments is identical. But instead of operating on a single global hashing table the function works on the @@ -401,7 +463,7 @@ @table @code @item ENOMEM -The table is filled and @code{hsearch_r} was called with an so far +The table is filled and @code{hsearch_r} was called with a so far unknown key and @var{action} set to @code{ENTER}. @item ESRCH The @var{action} parameter is @code{FIND} and no corresponding element @@ -436,6 +498,12 @@ @comment search.h @comment SVID @deftypefun {void *} tsearch (const void *@var{key}, void **@var{rootp}, comparison_fn_t @var{compar}) +@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 +@c asynchronous signal handler (except for the caller-synchronization +@c requirement) or after asynchronous cancellation of the thread +@c performing the rotation or the insertion. The @code{tsearch} function searches in the tree pointed to by @code{*@var{rootp}} for an element matching @var{key}. The function pointed to by @var{compar} is used to determine whether two elements @@ -465,6 +533,7 @@ @comment search.h @comment SVID @deftypefun {void *} tfind (const void *@var{key}, void *const *@var{rootp}, comparison_fn_t @var{compar}) +@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 a pointer to this element. But if no matching element is available no @@ -479,6 +548,7 @@ @comment search.h @comment SVID @deftypefun {void *} tdelete (const void *@var{key}, void **@var{rootp}, comparison_fn_t @var{compar}) +@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 same method as @code{tfind}. The corresponding element is then removed @@ -492,6 +562,7 @@ @comment search.h @comment GNU @deftypefun void tdestroy (void *@var{vroot}, __free_fn_t @var{freefct}) +@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} function to generate the tree pointed to by @var{vroot}. @@ -546,6 +617,7 @@ @comment search.h @comment SVID @deftypefun void twalk (const void *@var{root}, __action_fn_t @var{action}) +@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 @var{action}. For leaf nodes the function is called exactly once with diff -urN glibc-2.17-c758a686/manual/setjmp.texi glibc-2.17-c758a686/manual/setjmp.texi --- glibc-2.17-c758a686/manual/setjmp.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/setjmp.texi 2014-09-12 16:10:06.043792722 -0400 @@ -107,6 +107,10 @@ @comment setjmp.h @comment ISO @deftypefn Macro int setjmp (jmp_buf @var{state}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c _setjmp ok +@c __sigsetjmp(!savemask) ok +@c __sigjmp_save(!savemask) ok, does not call sigprocmask When called normally, @code{setjmp} stores information about the execution state of the program in @var{state} and returns zero. If @code{longjmp} is later used to perform a non-local exit to this @@ -116,6 +120,20 @@ @comment setjmp.h @comment ISO @deftypefun void longjmp (jmp_buf @var{state}, int @var{value}) +@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 +@c __pthread_cleanup_upto @ascuplugin @asucorrupt @acucorrupt +@c plugins may be unsafe themselves, but even if they weren't, this +@c function isn't robust WRT async signals and cancellation: +@c cleanups aren't taken off the stack right away, only after all +@c cleanups have been run. This means that async-cancelling +@c longjmp, or interrupting longjmp with an async signal handler +@c that calls longjmp may run the same cleanups multiple times. +@c _JMPBUF_UNWINDS_ADJ ok +@c *cleanup_buf->__routine @ascuplugin +@c sigprocmask(SIG_SETMASK) dup @asulock/hurd @aculock/hurd +@c __longjmp ok This function restores current execution to the state saved in @var{state}, and continues execution from the call to @code{setjmp} that established that return point. Returning from @code{setjmp} by means of @@ -141,7 +159,7 @@ statement (such as @samp{if}, @samp{switch}, or @samp{while}). @item -As one operand of a equality or comparison operator that appears as the +As one operand of an equality or comparison operator that appears as the test expression of a selection or iteration statement. The other operand must be an integer constant expression. @@ -199,6 +217,11 @@ @comment setjmp.h @comment POSIX.1 @deftypefun int sigsetjmp (sigjmp_buf @var{state}, int @var{savesigs}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} +@c sigsetjmp @asulock/hurd @aculock/hurd +@c __sigsetjmp(savemask) @asulock/hurd @aculock/hurd +@c __sigjmp_save(savemask) @asulock/hurd @aculock/hurd +@c sigprocmask(SIG_BLOCK probe) dup @asulock/hurd @aculock/hurd This is similar to @code{setjmp}. If @var{savesigs} is nonzero, the set of blocked signals is saved in @var{state} and will be restored if a @code{siglongjmp} is later performed with this @var{state}. @@ -207,6 +230,8 @@ @comment setjmp.h @comment POSIX.1 @deftypefun void siglongjmp (sigjmp_buf @var{state}, int @var{value}) +@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} argument. If the @code{sigsetjmp} call that set this @var{state} used a nonzero @var{savesigs} flag, @code{siglongjmp} also restores the set of @@ -237,7 +262,7 @@ @comment SVID @deftp {Data Type} ucontext_t -The @code{ucontext_t} type is defined as a structure with as least the +The @code{ucontext_t} type is defined as a structure with at least the following elements: @table @code @@ -267,6 +292,10 @@ @comment ucontext.h @comment SVID @deftypefun int getcontext (ucontext_t *@var{ucp}) +@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 +@c too. The ppc case is implemented in terms of a swapcontext syscall. The @code{getcontext} function initializes the variable pointed to by @var{ucp} with the context of the calling thread. The context contains the content of the registers, the signal mask, and the current stack. @@ -278,25 +307,26 @@ @end deftypefun The @code{getcontext} function is similar to @code{setjmp} but it does -not provide an indication of whether the function returns for the first -time or whether the initialized context was used and the execution is -resumed at just that point. If this is necessary the user has to take -determine this herself. This must be done carefully since the context -contains registers which might contain register variables. This is a -good situation to define variables with @code{volatile}. +not provide an indication of whether @code{getcontext} is returning for +the first time or whether an initialized context has just been restored. +If this is necessary the user has to determine this herself. This must +be done carefully since the context contains registers which might contain +register variables. This is a good situation to define variables with +@code{volatile}. Once the context variable is initialized it can be used as is or it can -be modified. The latter is normally done to implement co-routines or -similar constructs. The @code{makecontext} function is what has to be -used to do that. +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{}) +@safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@assafe{}@acsafe{}} +@c Linux-only implementations mostly in assembly, nothing unsafe. -The @var{ucp} parameter passed to the @code{makecontext} shall be +The @var{ucp} parameter passed to @code{makecontext} shall be initialized by a call to @code{getcontext}. The context will be -modified to in a way so that if the context is resumed it will start by +modified in a way such that if the context is resumed it will start by calling the function @code{func} which gets @var{argc} integer arguments passed. The integer arguments which are to be passed should follow the @var{argc} parameter in the call to @code{makecontext}. @@ -316,7 +346,7 @@ While allocating the memory for the stack one has to be careful. Most modern processors keep track of whether a certain memory region is allowed to contain code which is executed or not. Data segments and -heap memory is normally not tagged to allow this. The result is that +heap memory are normally not tagged to allow this. The result is that programs would fail. Examples for such code include the calling sequences the GNU C compiler generates for calls to nested functions. Safe ways to allocate stacks correctly include using memory on the @@ -332,13 +362,22 @@ allocated for the stack and the size of the memory region is stored in @code{ss_size}. There are implements out there which require @code{ss_sp} to be set to the value the stack pointer will have (which -can depending on the direction the stack grows be different). This +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}) +@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 +@c first and then proceed restore other registers in userland, which +@c leaves a window for cancellation or async signals with misaligned or +@c otherwise corrupt stack. ??? Switching to a different stack, or even +@c to an earlier state on the same stack, may conflict with pthread +@c cleanups. This is not quite MT-Unsafe, it's a different kind of +@c safety issue. The @code{setcontext} function restores the context described by @var{ucp}. The context is not modified and can be reused as often as @@ -357,6 +396,9 @@ terminates normally with an exit status value of @code{EXIT_SUCCESS} (@pxref{Program Termination}). +If the context was created by a call to a signal handler or from any +other source then the behaviour of @code{setcontext} is unspecified. + Since the context contains information about the stack no two threads should use the same context at the same time. The result in most cases would be disastrous. @@ -372,6 +414,10 @@ @comment ucontext.h @comment SVID @deftypefun int swapcontext (ucontext_t *restrict @var{oucp}, const ucontext_t *restrict @var{ucp}) +@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 +@c between, so we inherit the potential issues of both. The @code{swapcontext} function is similar to @code{setcontext} but instead of just replacing the current context the latter is first saved @@ -385,15 +431,15 @@ If @code{swapcontext} succeeds the function does not return unless the context @var{oucp} is used without prior modification by @code{makecontext}. The return value in this case is @code{0}. If the -function fails it returns @code{-1} and set @var{errno} accordingly. +function fails it returns @code{-1} and sets @var{errno} accordingly. @end deftypefun @heading Example for SVID Context Handling The easiest way to use the context handling functions is as a replacement for @code{setjmp} and @code{longjmp}. The context contains -on most platforms more information which might lead to less surprises -but this also means using these functions is more expensive (beside +on most platforms more information which may lead to fewer surprises +but this also means using these functions is more expensive (besides being less portable). @smallexample @@ -440,11 +486,11 @@ This an example how the context functions can be used to implement co-routines or cooperative multi-threading. All that has to be done is to call every once in a while @code{swapcontext} to continue running a -different context. It is not allowed to do the context switching from -the signal handler directly since neither @code{setcontext} nor -@code{swapcontext} are functions which can be called from a signal -handler. But setting a variable in the signal handler and checking it -in the body of the functions which are executed. Since -@code{swapcontext} is saving the current context it is possible to have -multiple different scheduling points in the code. Execution will always -resume where it was left. +different context. It is not recommended to do the context switching from +the signal handler directly since leaving the signal handler via +@code{setcontext} if the signal was delivered during code that was not +asynchronous signal safe could lead to problems. Setting a variable in +the signal handler and checking it in the body of the functions which +are executed is a safer approach. Since @code{swapcontext} is saving the +current context it is possible to have multiple different scheduling points +in the code. Execution will always resume where it was left. diff -urN glibc-2.17-c758a686/manual/signal.texi glibc-2.17-c758a686/manual/signal.texi --- glibc-2.17-c758a686/manual/signal.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/signal.texi 2014-09-12 16:10:06.045792717 -0400 @@ -889,6 +889,20 @@ @comment string.h @comment GNU @deftypefun {char *} strsignal (int @var{signum}) +@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 +@c [once] init +@c libc_key_create ok +@c pthread_key_create dup ok +@c getbuffer @asucorrupt @ascuheap @acsmem +@c libc_getspecific ok +@c pthread_getspecific dup ok +@c malloc dup @ascuheap @acsmem +@c libc_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem +@c pthread_setspecific dup @asucorrupt @ascuheap @acucorrupt @acsmem +@c snprintf dup @mtslocale @ascuheap @acsmem +@c _ @ascuintl This function returns a pointer to a statically-allocated string containing a message describing the signal @var{signum}. You should not modify the contents of this string; and, since it can be @@ -903,6 +917,12 @@ @comment signal.h @comment BSD @deftypefun void psignal (int @var{signum}, const char *@var{message}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} +@c psignal @mtslocale @asucorrupt @ascuintl @ascuheap @aculock @acucorrupt @acsmem +@c _ @ascuintl +@c fxprintf @asucorrupt @aculock @acucorrupt +@c asprintf @mtslocale @ascuheap @acsmem +@c free dup @ascuheap @acsmem This function prints a message describing the signal @var{signum} to the standard error output stream @code{stderr}; see @ref{Standard Streams}. @@ -972,6 +992,12 @@ @comment signal.h @comment ISO @deftypefun sighandler_t signal (int @var{signum}, sighandler_t @var{action}) +@safety{@prelim{}@mtsafe{@mtssigintr{}}@assafe{}@acsafe{}} +@c signal ok +@c sigemptyset dup ok +@c sigaddset dup ok +@c sigismember dup ok +@c sigaction dup ok The @code{signal} function establishes @var{action} as the action for the signal @var{signum}. @@ -1094,6 +1120,10 @@ @comment signal.h @comment GNU @deftypefun sighandler_t sysv_signal (int @var{signum}, sighandler_t @var{action}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c sysv_signal ok +@c sigemptyset dup ok +@c sigaction dup ok The @code{sysv_signal} implements the behavior of the standard @code{signal} function as found on SVID systems. The difference to BSD systems is that the handler is deinstalled after a delivery of a signal. @@ -1106,6 +1136,8 @@ @comment signal.h @comment SVID @deftypefun sighandler_t ssignal (int @var{signum}, sighandler_t @var{action}) +@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 @@ -1172,6 +1204,7 @@ @comment signal.h @comment POSIX.1 @deftypefun int sigaction (int @var{signum}, const struct sigaction *restrict @var{action}, struct sigaction *restrict @var{old-action}) +@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 information about the action previously associated with this symbol. @@ -2168,6 +2194,14 @@ @comment signal.h @comment ISO @deftypefun int raise (int @var{signum}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c raise ok +@c [posix] +@c getpid dup ok +@c kill dup ok +@c [linux] +@c syscall(gettid) ok +@c syscall(tgkill) ok The @code{raise} function sends the signal @var{signum} to the calling process. It returns zero if successful and a nonzero value if it fails. About the only reason for failure would be if the value of @var{signum} @@ -2177,6 +2211,8 @@ @comment signal.h @comment SVID @deftypefun int gsignal (int @var{signum}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Aliases raise. The @code{gsignal} function does the same thing as @code{raise}; it is provided only for compatibility with SVID. @end deftypefun @@ -2269,6 +2305,11 @@ @comment signal.h @comment POSIX.1 @deftypefun int kill (pid_t @var{pid}, int @var{signum}) +@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 +@c ports or the memory allocated by proc_getpgrppids when pid <= 0. +@c Since none of these make it AC-Unsafe, I'm leaving them out. The @code{kill} function sends the signal @var{signum} to the process or process group specified by @var{pid}. Besides the signals listed in @ref{Standard Signals}, @var{signum} can also have a value of zero to @@ -2325,6 +2366,8 @@ @comment signal.h @comment BSD @deftypefun int killpg (int @var{pgid}, int @var{signum}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Calls kill with -pgid. This is similar to @code{kill}, but sends signal @var{signum} to the process group @var{pgid}. This function is provided for compatibility with BSD; using @code{kill} to do this is more portable. @@ -2497,6 +2540,8 @@ @comment signal.h @comment POSIX.1 @deftypefun int sigemptyset (sigset_t *@var{set}) +@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 @@ -2504,6 +2549,7 @@ @comment signal.h @comment POSIX.1 @deftypefun int sigfillset (sigset_t *@var{set}) +@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 @@ -2511,6 +2557,7 @@ @comment signal.h @comment POSIX.1 @deftypefun int sigaddset (sigset_t *@var{set}, int @var{signum}) +@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 unblock any signals. @@ -2527,6 +2574,7 @@ @comment signal.h @comment POSIX.1 @deftypefun int sigdelset (sigset_t *@var{set}, int @var{signum}) +@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 block or unblock any signals. The return value and error conditions are @@ -2538,6 +2586,7 @@ @comment signal.h @comment POSIX.1 @deftypefun int sigismember (const sigset_t *@var{set}, int @var{signum}) +@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 is in the set, @code{0} if not, and @code{-1} if there is an error. @@ -2566,7 +2615,7 @@ Note that you must not use @code{sigprocmask} in multi-threaded processes, because each thread has its own signal mask and there is no single process -signal mask. According to POSIX, the behavior of @code{sigprocmask} in a +signal mask. According to POSIX, the behavior of @code{sigprocmask} in a multi-threaded process is ``unspecified''. Instead, use @code{pthread_sigmask}. @ifset linuxthreads @@ -2576,6 +2625,10 @@ @comment signal.h @comment POSIX.1 @deftypefun int sigprocmask (int @var{how}, const sigset_t *restrict @var{set}, sigset_t *restrict @var{oldset}) +@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 +@c introduces a race window. The @code{sigprocmask} function is used to examine or change the calling process's signal mask. The @var{how} argument determines how the signal mask is changed, and must be one of the following values: @@ -2759,6 +2812,10 @@ @comment signal.h @comment POSIX.1 @deftypefun int sigpending (sigset_t *@var{set}) +@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 +@c its lock. The @code{sigpending} function stores information about pending signals in @var{set}. If there is a pending signal that is blocked from delivery, then that signal is a member of the returned set. (You can @@ -2921,7 +2978,18 @@ @comment unistd.h @comment POSIX.1 -@deftypefun int pause () +@deftypefun int pause (void) +@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 +@c safety issue? Probably not. +@c pause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd +@c [ports/linux/generic] +@c syscall_pause ok +@c [posix] +@c sigemptyset dup ok +@c sigprocmask(SIG_BLOCK) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)] +@c sigsuspend dup @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd The @code{pause} function suspends program execution until a signal arrives whose action is either to execute a handler function, or to terminate the process. @@ -3017,6 +3085,18 @@ @comment signal.h @comment POSIX.1 @deftypefun int sigsuspend (const sigset_t *@var{set}) +@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 +@c saving and restoring the procmask is racy +@c sigprocmask(SIG_SETMASK) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)] +@c pause @asulock/hurd @aculock/hurd +@c [bsd] +@c sigismember dup ok +@c sigmask dup ok +@c sigpause dup ok [no @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd] +@c [linux] +@c do_sigsuspend ok This function replaces the process's signal mask with @var{set} and then suspends the process until a signal is delivered whose action is either to terminate the process or invoke a signal handling function. In other @@ -3150,6 +3230,9 @@ @comment signal.h @comment XPG @deftypefun int sigaltstack (const stack_t *restrict @var{stack}, stack_t *restrict @var{oldstack}) +@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. The @code{sigaltstack} function specifies an alternate stack for use during signal handling. When a signal is received by the process and its action indicates that the signal stack is used, the system arranges @@ -3195,7 +3278,9 @@ @comment signal.h @comment BSD -@deftypefun int sigstack (const struct sigstack *@var{stack}, struct sigstack *@var{oldstack}) +@deftypefun int sigstack (struct sigstack *@var{stack}, struct sigstack *@var{oldstack}) +@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 signal handling. When a signal is received by the process and its action indicates that the signal stack is used, the system arranges a @@ -3301,6 +3386,13 @@ @comment signal.h @comment BSD @deftypefun int sigvec (int @var{signum}, const struct sigvec *@var{action}, struct sigvec *@var{old-action}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is mostly a safe wrapper for sigaction. The exception are +@c systems that lack SA_RESETHAND, in which a signal handler wrapper is +@c used that calls sigaction to reset the handler before calling the +@c user-supplied handler; it's unlikely that this emulation is used +@c anywhere, for user-supplied flags and mask don't seem to be used +@c the way one would expect. This function is the equivalent of @code{sigaction} (@pxref{Advanced Signal Handling}); it installs the action @var{action} for the signal @var{signum}, returning information about the previous action in effect for that signal @@ -3310,6 +3402,14 @@ @comment signal.h @comment BSD @deftypefun int siginterrupt (int @var{signum}, int @var{failflag}) +@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 +@c override the effects of a concurrent sigaction call. It also +@c modifies without any guards the global _sigintr variable, that +@c bsd_signal reads from, and it may leave _sigintr modified without +@c overriding the active handler if cancelled between the two +@c operations. This function specifies which approach to use when certain primitives are interrupted by handling signal @var{signum}. If @var{failflag} is false, signal @var{signum} restarts primitives. If @var{failflag} is @@ -3323,6 +3423,8 @@ @comment signal.h @comment BSD @deftypefn Macro int sigmask (int @var{signum}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This just shifts signum. This macro returns a signal mask that has the bit for signal @var{signum} set. You can bitwise-OR the results of several calls to @code{sigmask} together to specify more than one signal. For example, @@ -3339,6 +3441,11 @@ @comment signal.h @comment BSD @deftypefun int sigblock (int @var{mask}) +@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. +@c sigblock @asulock/hurd @aculock/hurd +@c sigprocmask(SIG_BLOCK) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)] This function is equivalent to @code{sigprocmask} (@pxref{Process Signal Mask}) with a @var{how} argument of @code{SIG_BLOCK}: it adds the signals specified by @var{mask} to the calling process's set of blocked @@ -3348,6 +3455,11 @@ @comment signal.h @comment BSD @deftypefun int sigsetmask (int @var{mask}) +@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. +@c sigsetmask @asulock/hurd @aculock/hurd +@c sigprocmask(SIG_SETMASK) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)] This function equivalent to @code{sigprocmask} (@pxref{Process Signal Mask}) with a @var{how} argument of @code{SIG_SETMASK}: it sets the calling process's signal mask to @var{mask}. The return value is @@ -3357,6 +3469,15 @@ @comment signal.h @comment BSD @deftypefun int sigpause (int @var{mask}) +@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] +@c __sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd +@c do_sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd +@c sigprocmask(0) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)] +@c sigdelset dup ok +@c sigset_set_old_mask dup ok +@c sigsuspend dup @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd This function is the equivalent of @code{sigsuspend} (@pxref{Waiting for a Signal}): it sets the calling process's signal mask to @var{mask}, and waits for a signal to arrive. On return the previous set of blocked diff -urN glibc-2.17-c758a686/manual/socket.texi glibc-2.17-c758a686/manual/socket.texi --- glibc-2.17-c758a686/manual/socket.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/socket.texi 2014-09-12 16:10:06.046792714 -0400 @@ -394,6 +394,8 @@ @comment sys/socket.h @comment BSD @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall, except on Hurd. The @code{bind} function assigns an address to the socket @var{socket}. The @var{addr} and @var{length} arguments specify the address; the detailed format of the address depends on the namespace. @@ -442,6 +444,9 @@ @comment sys/socket.h @comment BSD @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsmem{/hurd}}} +@c Direct syscall, except on Hurd, where it seems like it might leak +@c VM if cancelled. The @code{getsockname} function returns information about the address of the socket @var{socket} in the locations specified by the @var{addr} and @var{length-ptr} arguments. Note that the @@ -501,6 +506,14 @@ @comment net/if.h @comment IPv6 basic API @deftypefun {unsigned int} if_nametoindex (const char *@var{ifname}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} +@c It opens a socket to use ioctl on the fd to get the index. +@c opensock may call socket and access multiple times until it finds a +@c socket family that works. The Linux implementation has a potential +@c concurrency issue WRT last_type and last_family not being updated +@c atomically, but it is harmless; the generic implementation, OTOH, +@c takes a lock, which makes all callers AS- and AC-Unsafe. +@c opensock @asulock @aculock @acsfd This function yields the interface index corresponding to a particular name. If no interface exists with the name given, it returns 0. @end deftypefun @@ -508,6 +521,9 @@ @comment net/if.h @comment IPv6 basic API @deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} +@c It opens a socket with opensock to use ioctl on the fd to get the +@c name from the index. This function maps an interface index to its corresponding name. The returned name is placed in the buffer pointed to by @code{ifname}, which must be at least @code{IFNAMSIZ} bytes in length. If the index was @@ -534,6 +550,39 @@ @comment net/if.h @comment IPv6 basic API @deftypefun {struct if_nameindex *} if_nameindex (void) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@aculock{/hurd} @acsfd{} @acsmem{}}} +@c if_nameindex @ascuheap @asulock/hurd @aculock/hurd @acsfd @acsmem +@c [linux] +@c netlink_open @acsfd @acsmem/hurd +@c socket dup @acsfd +@c memset dup ok +@c bind dup ok +@c netlink_close dup @acsfd +@c getsockname dup @acsmem/hurd +@c netlink_request @ascuheap @acsmem +@c getpagesize dup ok +@c malloc dup @ascuheap @acsmem +@c netlink_sendreq ok +@c memset dup ok +@c sendto dup ok +@c recvmsg dup ok +@c memcpy dup ok +@c free dup @ascuheap @acsmem +@c netlink_free_handle @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c netlink_close @acsfd +@c close dup @acsfd +@c malloc dup @asuheap @acsmem +@c strndup @ascuheap @acsmem +@c if_freenameindex @ascuheap @acsmem +@c [hurd] +@c opensock dup @asulock @aculock @acsfd +@c hurd_socket_server ok +@c pfinet_siocgifconf ok +@c malloc @ascuheap @acsmem +@c strdup @ascuheap @acsmem +@c ioctl dup ok +@c free @ascuheap @acsmem This function returns an array of @code{if_nameindex} structures, one for every interface that is present. The end of the list is indicated by a structure with an interface of 0 and a null name pointer. If an @@ -546,6 +595,9 @@ @comment net/if.h @comment IPv6 basic API @deftypefun void if_freenameindex (struct if_nameindex *@var{ptr}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c if_freenameindex @ascuheap @acsmem +@c free dup @ascuheap @acsmem This function frees the structure returned by an earlier call to @code{if_nameindex}. @end deftypefun @@ -660,6 +712,7 @@ @comment sys/un.h @comment BSD @deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The macro computes the length of socket address in the local namespace. @end deftypefn @@ -689,7 +742,7 @@ To create a socket in the IPv4 Internet namespace, use the symbolic name @code{PF_INET} of this namespace as the @var{namespace} argument to @code{socket} or @code{socketpair}. For IPv6 addresses you need the -macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}. +macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}. @pindex sys/socket.h @comment sys/socket.h @@ -726,12 +779,12 @@ * Internet Address Formats:: How socket addresses are specified in the Internet namespace. * Host Addresses:: All about host addresses of Internet host. -* Protocols Database:: Referring to protocols by name. * Ports:: Internet port numbers. * Services Database:: Ports may have symbolic names. * Byte Order:: Different hosts may use different byte ordering conventions; you need to canonicalize host address and port number. +* Protocols Database:: Referring to protocols by name. * Inet Example:: Putting it all together. @end menu @@ -1035,6 +1088,13 @@ @comment arpa/inet.h @comment BSD @deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c inet_aton @mtslocale +@c isdigit dup @mtslocale +@c strtoul dup @mtslocale +@c isascii dup @mtslocale +@c isspace dup @mtslocale +@c htonl dup ok This function converts the IPv4 Internet host address @var{name} from the standard numbers-and-dots notation into binary data and stores it in the @code{struct in_addr} that @var{addr} points to. @@ -1044,10 +1104,13 @@ @comment arpa/inet.h @comment BSD @deftypefun {uint32_t} inet_addr (const char *@var{name}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c inet_addr @mtslocale +@c inet_aton dup @mtslocale This function converts the IPv4 Internet host address @var{name} from the standard numbers-and-dots notation into binary data. If the input is not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an -obsolete interface to @code{inet_aton}, described immediately above. It +obsolete interface to @code{inet_aton}, described immediately above. It is obsolete because @code{INADDR_NONE} is a valid address (255.255.255.255), and @code{inet_aton} provides a cleaner way to indicate error return. @@ -1056,9 +1119,15 @@ @comment arpa/inet.h @comment BSD @deftypefun {uint32_t} inet_network (const char *@var{name}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c inet_network @mtslocale +@c isdigit dup @mtslocale +@c isxdigit dup @mtslocale +@c tolower dup @mtslocale +@c isspace dup @mtslocale This function extracts the network number from the address @var{name}, -given in the standard numbers-and-dots notation. The returned address is -in host order. If the input is not valid, @code{inet_network} returns +given in the standard numbers-and-dots notation. The returned address is +in host order. If the input is not valid, @code{inet_network} returns @code{-1}. The function works only with traditional IPv4 class A, B and C network @@ -1069,6 +1138,10 @@ @comment arpa/inet.h @comment BSD @deftypefun {char *} inet_ntoa (struct in_addr @var{addr}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asurace{}}@acsafe{}} +@c inet_ntoa @mtslocale @asurace +@c writes to a thread-local static buffer +@c snprintf @mtslocale [no @ascuheap or @acsmem] This function converts the IPv4 Internet host address @var{addr} to a string in the standard numbers-and-dots notation. The return value is a pointer into a statically-allocated buffer. Subsequent calls will @@ -1087,6 +1160,9 @@ @comment arpa/inet.h @comment BSD @deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c inet_makeaddr ok +@c htonl dup ok This function makes an IPv4 Internet host address by combining the network number @var{net} with the local-address-within-network number @var{local}. @@ -1095,6 +1171,11 @@ @comment arpa/inet.h @comment BSD @deftypefun uint32_t inet_lnaof (struct in_addr @var{addr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c inet_lnaof ok +@c ntohl dup ok +@c IN_CLASSA ok +@c IN_CLASSB ok This function returns the local-address-within-network part of the Internet host address @var{addr}. @@ -1106,6 +1187,11 @@ @comment arpa/inet.h @comment BSD @deftypefun uint32_t inet_netof (struct in_addr @var{addr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c inet_netof ok +@c ntohl dup ok +@c IN_CLASSA ok +@c IN_CLASSB ok This function returns the network number part of the Internet host address @var{addr}. @@ -1117,6 +1203,16 @@ @comment arpa/inet.h @comment IPv6 basic API @deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c inet_pton @mtslocale +@c inet_pton4 ok +@c memcpy dup ok +@c inet_pton6 @mtslocale +@c memset dup ok +@c tolower dup @mtslocale +@c strchr dup ok +@c inet_pton4 dup ok +@c memcpy dup ok This function converts an Internet address (either IPv4 or IPv6) from presentation (textual) to network (binary) format. @var{af} should be either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of @@ -1127,7 +1223,17 @@ @comment arpa/inet.h @comment IPv6 basic API -@deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, size_t @var{len}) +@deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c inet_ntop @mtslocale +@c inet_ntop4 @mtslocale +@c sprintf dup @mtslocale [no @ascuheap or @acsmem] +@c strcpy dup ok +@c inet_ntop6 @mtslocale +@c memset dup ok +@c inet_ntop4 dup @mtslocale +@c sprintf dup @mtslocale [no @ascuheap or @acsmem] +@c strcpy dup ok This function converts an Internet address (either IPv4 or IPv6) from network (binary) to presentation (textual) form. @var{af} should be either @code{AF_INET} or @code{AF_INET6}, as appropriate. @var{cp} is a @@ -1211,6 +1317,71 @@ @comment netdb.h @comment BSD @deftypefun {struct hostent *} gethostbyname (const char *@var{name}) +@safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} +@c gethostbyname @mtasurace:hostbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c nss_hostname_digits_dots @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c res_maybe_init(!preinit) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c res_iclose @acsuheap @acsmem @acsfd +@c close_not_cancel_no_status dup @acsfd +@c free dup @acsuheap @acsmem +@c res_vinit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c res_randomid ok +@c getpid dup ok +@c getenv dup @mtsenv +@c strncpy dup ok +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fsetlocking dup ok [no concurrent uses] +@c fgets_unlocked dup ok [no concurrent uses] +@c MATCH ok +@c strncmp dup ok +@c strpbrk dup ok +@c strchr dup ok +@c inet_aton dup @mtslocale +@c htons dup +@c inet_pton dup @mtslocale +@c malloc dup @ascuheap @acsmem +@c IN6_IS_ADDR_LINKLOCAL ok +@c htonl dup ok +@c IN6_IS_ADDR_MC_LINKLOCAL ok +@c if_nametoindex dup @asulock @aculock @acsfd +@c strtoul dup @mtslocale +@c ISSORTMASK ok +@c strchr dup ok +@c isascii dup @mtslocale +@c isspace dup @mtslocale +@c net_mask ok +@c ntohl dup ok +@c IN_CLASSA dup ok +@c htonl dup ok +@c IN_CLASSB dup ok +@c res_setoptions @mtslocale +@c strncmp dup ok +@c atoi dup @mtslocale +@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd +@c inet_makeaddr dup ok +@c gethostname dup ok +@c strcpy dup ok +@c rawmemchr dup ok +@c res_ninit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c res_vinit dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c isdigit dup @mtslocale +@c isxdigit dup @mtslocale +@c strlen dup ok +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c memset dup ok +@c inet_aton dup @mtslocale +@c inet_pton dup @mtslocale +@c strcpy dup ok +@c memcpy dup ok +@c strchr dup ok +@c gethostbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c set_h_errno ok The @code{gethostbyname} function returns information about the host named @var{name}. If the lookup fails, it returns a null pointer. @end deftypefun @@ -1218,6 +1389,16 @@ @comment netdb.h @comment IPv6 Basic API @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af}) +@safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname2} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} +@c gethostbyname2 @mtasurace:hostbyname2 @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c gethostbyname2_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c set_h_errno dup ok The @code{gethostbyname2} function is like @code{gethostbyname}, but allows the caller to specify the desired address family (e.g.@: @code{AF_INET} or @code{AF_INET6}) of the result. @@ -1225,11 +1406,20 @@ @comment netdb.h @comment BSD -@deftypefun {struct hostent *} gethostbyaddr (const char *@var{addr}, size_t @var{length}, int @var{format}) +@deftypefun {struct hostent *} gethostbyaddr (const void *@var{addr}, socklen_t @var{length}, int @var{format}) +@safety{@prelim{}@mtunsafe{@mtasurace{:hostbyaddr} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} +@c gethostbyaddr @mtasurace:hostbyaddr @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c gethostbyaddr_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c set_h_errno dup ok The @code{gethostbyaddr} function returns information about the host with Internet address @var{addr}. The parameter @var{addr} is not really a pointer to char - it can be a pointer to an IPv4 or an IPv6 -address. The @var{length} argument is the size (in bytes) of the address +address. The @var{length} argument is the size (in bytes) of the address at @var{addr}. @var{format} specifies the address format; for an IPv4 Internet address, specify a value of @code{AF_INET}; for an IPv6 Internet address, use @code{AF_INET6}. @@ -1282,6 +1472,76 @@ @comment netdb.h @comment GNU @deftypefun int gethostbyname_r (const char *restrict @var{name}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} +@c gethostbyname_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd +@c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c nscd_gethostbyname_r @mtsenv @ascuheap @acsfd @acsmem +@c nscd_gethst_r @mtsenv @ascuheap @acsfd @acsmem +@c getenv dup @mtsenv +@c nscd_get_map_ref dup @ascuheap @acsfd @acsmem +@c nscd_cache_search dup ok +@c memcpy dup ok +@c nscd_open_socket dup @acsfd +@c readvall dup ok +@c readall dup ok +@c close_not_cancel_no_status dup @acsfd +@c nscd_drop_map_ref dup @ascuheap @acsmem +@c nscd_unmap dup @ascuheap @acsmem +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c res_hconf_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called] +@c res_hconf.c:do_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem +@c memset dup ok +@c getenv dup @mtsenv +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fsetlocking dup ok [no concurrent uses] +@c fgets_unlocked dup ok [no concurrent uses] +@c strchrnul dup ok +@c res_hconf.c:parse_line @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem +@c skip_ws dup @mtslocale +@c skip_string dup @mtslocale +@c strncasecmp dup @mtslocale +@c strlen dup ok +@c asprintf dup @mtslocale @ascuheap @acsmem +@c fxprintf dup @asucorrupt @aculock @acucorrupt +@c free dup @ascuheap @acsmem +@c arg_trimdomain_list dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem +@c arg_spoof dup @mtslocale +@c arg_bool dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem +@c isspace dup @mtslocale +@c fclose dup @ascuheap @asulock @acsmem @acsfd @aculock +@c arg_spoof @mtslocale +@c skip_string @mtslocale +@c isspace dup @mtslocale +@c strncasecmp dup @mtslocale +@c arg_bool @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem +@c strncasecmp dup @mtslocale +@c asprintf dup @mtslocale @ascuheap @acsmem +@c fxprintf dup @asucorrupt @aculock @acucorrupt +@c free dup @ascuheap @acsmem +@c arg_trimdomain_list @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem +@c skip_string dup @mtslocale +@c asprintf dup @mtslocale @ascuheap @acsmem +@c fxprintf dup @asucorrupt @aculock @acucorrupt +@c free dup @ascuheap @acsmem +@c strndup dup @ascuheap @acsmem +@c skip_ws @mtslocale +@c isspace dup @mtslocale +@c nss_hosts_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_database_lookup dup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_gethostbyname_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c res_hconf_reorder_addrs @asulock @ascuheap @aculock @acsmem @acsfd +@c socket dup @acsfd +@c libc_lock_lock dup @asulock @aculock +@c ifreq @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c if_nextreq dup ok +@c ioctl dup ok +@c realloc dup @ascuheap @acsmem +@c if_freereq dup @acsmem +@c libc_lock_unlock dup @aculock +@c close dup @acsfd The @code{gethostbyname_r} function returns information about the host named @var{name}. The caller must pass a pointer to an object of type @code{struct hostent} in the @var{result_buf} parameter. In addition @@ -1290,37 +1550,42 @@ parameters. A pointer to the buffer, in which the result is stored, is available in -@code{*@var{result}} after the function call successfully returned. If -an error occurs or if no entry is found, the pointer @code{*@var{result}} -is a null pointer. Success is signalled by a zero return value. If the -function failed the return value is an error number. In addition to the -errors defined for @code{gethostbyname} it can also be @code{ERANGE}. -In this case the call should be repeated with a larger buffer. -Additional error information is not stored in the global variable -@code{h_errno} but instead in the object pointed to by @var{h_errnop}. +@code{*@var{result}} after the function call successfully returned. The +buffer passed as the @var{buf} parameter can be freed only once the caller +has finished with the result hostent struct, or has copied it including all +the other memory that it points to. If an error occurs or if no entry is +found, the pointer @code{*@var{result}} is a null pointer. Success is +signalled by a zero return value. If the function failed the return value +is an error number. In addition to the errors defined for +@code{gethostbyname} it can also be @code{ERANGE}. In this case the call +should be repeated with a larger buffer. Additional error information is +not stored in the global variable @code{h_errno} but instead in the object +pointed to by @var{h_errnop}. Here's a small example: @smallexample struct hostent * gethostname (char *host) @{ - struct hostent hostbuf, *hp; + struct hostent *hostbuf, *hp; size_t hstbuflen; char *tmphstbuf; int res; int herr; + hostbuf = malloc (sizeof (struct hostent)); hstbuflen = 1024; - /* Allocate buffer, remember to free it to avoid memory leakage. */ tmphstbuf = malloc (hstbuflen); - while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen, + while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen, &hp, &herr)) == ERANGE) @{ /* Enlarge the buffer. */ hstbuflen *= 2; tmphstbuf = realloc (tmphstbuf, hstbuflen); @} + + free (tmphstbuf); /* Check for errors. */ if (res || hp == NULL) return NULL; @@ -1332,6 +1597,17 @@ @comment netdb.h @comment GNU @deftypefun int gethostbyname2_r (const char *@var{name}, int @var{af}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} +@c gethostbyname2_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd +@c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c nscd_gethostbyname2_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem +@c nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called] +@c nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_gethostbyname2_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd The @code{gethostbyname2_r} function is like @code{gethostbyname_r}, but allows the caller to specify the desired address family (e.g.@: @code{AF_INET} or @code{AF_INET6}) for the result. @@ -1339,11 +1615,26 @@ @comment netdb.h @comment GNU -@deftypefun int gethostbyaddr_r (const char *@var{addr}, size_t @var{length}, int @var{format}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) +@deftypefun int gethostbyaddr_r (const void *@var{addr}, socklen_t @var{length}, int @var{format}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} +@c gethostbyaddr_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd +@c memcmp dup ok +@c nscd_gethostbyaddr_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem +@c nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called] +@c nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_gethostbyaddr_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd +@c res_hconf_trim_domains @mtslocale +@c res_hconf_trim_domain @mtslocale +@c strlen dup ok +@c strcasecmp dup @mtslocale The @code{gethostbyaddr_r} function returns information about the host with Internet address @var{addr}. The parameter @var{addr} is not really a pointer to char - it can be a pointer to an IPv4 or an IPv6 -address. The @var{length} argument is the size (in bytes) of the address +address. The @var{length} argument is the size (in bytes) of the address at @var{addr}. @var{format} specifies the address format; for an IPv4 Internet address, specify a value of @code{AF_INET}; for an IPv6 Internet address, use @code{AF_INET6}. @@ -1362,6 +1653,18 @@ @comment netdb.h @comment BSD @deftypefun void sethostent (int @var{stayopen}) +@safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c sethostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_setent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c set_h_errno dup ok +@c setup(nss_hosts_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *lookup_fct = nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:hostent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock dup @aculock This function opens the hosts database to begin scanning it. You can then call @code{gethostent} to read the entries. @@ -1377,6 +1680,27 @@ @comment netdb.h @comment BSD @deftypefun {struct hostent *} gethostent (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtasurace{:hostentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c gethostent @mtasurace:hostent @mtasurace:hostentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_getent(gethostent_r) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c malloc dup @ascuheap @acsmem +@c *func = gethostent_r dup @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c gethostent_r @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_getent_r(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c setup(nss_hosts_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:hostent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *sfct.f @mtasurace:hostent @ascuplugin +@c libc_lock_unlock dup @aculock + This function returns the next entry in the hosts database. It returns a null pointer if there are no more entries. @end deftypefun @@ -1384,6 +1708,15 @@ @comment netdb.h @comment BSD @deftypefun void endhostent (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c endhostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock @asulock @aculock +@c nss_endent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:hostent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock @aculock This function closes the hosts database. @end deftypefun @@ -1483,6 +1816,34 @@ @comment netdb.h @comment BSD @deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto}) +@safety{@prelim{}@mtunsafe{@mtasurace{:servbyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c getservbyname =~ getpwuid @mtasurace:servbyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c getservbyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c getservbyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nscd_getservbyname_r @ascuheap @acsfd @acsmem +@c nscd_getserv_r @ascuheap @acsfd @acsmem +@c nscd_get_map_ref dup @ascuheap @acsfd @acsmem +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c mempcpy dup ok +@c memcpy dup ok +@c nscd_cache_search dup ok +@c nscd_open_socket dup @acsfd +@c readvall dup ok +@c readall dup ok +@c close_not_cancel_no_status dup @acsfd +@c nscd_drop_map_ref dup @ascuheap @acsmem +@c nscd_unmap dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_getservbyname_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem The @code{getservbyname} function returns information about the service named @var{name} using protocol @var{proto}. If it can't find such a service, it returns a null pointer. @@ -1494,6 +1855,21 @@ @comment netdb.h @comment BSD @deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto}) +@safety{@prelim{}@mtunsafe{@mtasurace{:servbyport} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c getservbyport =~ getservbyname @mtasurace:servbyport @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c getservbyport_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c getservbyport_r =~ getservbyname_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nscd_getservbyport_r @ascuheap @acsfd @acsmem +@c nscd_getserv_r dup @ascuheap @acsfd @acsmem +@c nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_getservbyport_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem The @code{getservbyport} function returns information about the service at port @var{port} using protocol @var{proto}. If it can't find such a service, it returns a null pointer. @@ -1507,6 +1883,16 @@ @comment netdb.h @comment BSD @deftypefun void setservent (int @var{stayopen}) +@safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c setservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_setent(nss_services_lookup2) @mtasurace:servenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c setup(nss_services_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *lookup_fct = nss_services_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:servent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock dup @aculock This function opens the services database to begin scanning it. If the @var{stayopen} argument is nonzero, this sets a flag so that @@ -1519,6 +1905,25 @@ @comment netdb.h @comment BSD @deftypefun {struct servent *} getservent (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtasurace{:serventbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c getservent @mtasurace:servent @mtasurace:serventbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_getent(getservent_r) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c malloc dup @ascuheap @acsmem +@c *func = getservent_r dup @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c getservent_r @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_getent_r(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:servent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *sfct.f @mtasurace:servent @ascuplugin +@c libc_lock_unlock dup @aculock This function returns the next entry in the services database. If there are no more entries, it returns a null pointer. @end deftypefun @@ -1526,6 +1931,14 @@ @comment netdb.h @comment BSD @deftypefun void endservent (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c endservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock @asulock @aculock +@c nss_endent(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:servent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock @aculock This function closes the services database. @end deftypefun @@ -1571,6 +1984,11 @@ @comment netinet/in.h @comment BSD @deftypefun {uint16_t} htons (uint16_t @var{hostshort}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c htons ok +@c bswap_16 ok +@c bswap_constant_16 ok + This function converts the @code{uint16_t} integer @var{hostshort} from host byte order to network byte order. @end deftypefun @@ -1578,6 +1996,8 @@ @comment netinet/in.h @comment BSD @deftypefun {uint16_t} ntohs (uint16_t @var{netshort}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Alias to htons. This function converts the @code{uint16_t} integer @var{netshort} from network byte order to host byte order. @end deftypefun @@ -1585,6 +2005,9 @@ @comment netinet/in.h @comment BSD @deftypefun {uint32_t} htonl (uint32_t @var{hostlong}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c htonl ok +@c bswap_32 dup ok This function converts the @code{uint32_t} integer @var{hostlong} from host byte order to network byte order. @@ -1594,6 +2017,8 @@ @comment netinet/in.h @comment BSD @deftypefun {uint32_t} ntohl (uint32_t @var{netlong}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Alias to htonl. This function converts the @code{uint32_t} integer @var{netlong} from network byte order to host byte order. @@ -1658,6 +2083,20 @@ @comment netdb.h @comment BSD @deftypefun {struct protoent *} getprotobyname (const char *@var{name}) +@safety{@prelim{}@mtunsafe{@mtasurace{:protobyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c getprotobyname =~ getpwuid @mtasurace:protobyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c getprotobyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c getprotobyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c no nscd support +@c nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_getprotobyname_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem The @code{getprotobyname} function returns information about the network protocol named @var{name}. If there is no such protocol, it returns a null pointer. @@ -1666,6 +2105,20 @@ @comment netdb.h @comment BSD @deftypefun {struct protoent *} getprotobynumber (int @var{protocol}) +@safety{@prelim{}@mtunsafe{@mtasurace{:protobynumber} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c getprotobynumber =~ getpwuid @mtasurace:protobynumber @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c getprotobynumber_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c getprotobynumber_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c no nscd support +@c nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_getprotobynumber_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem The @code{getprotobynumber} function returns information about the network protocol with number @var{protocol}. If there is no such protocol, it returns a null pointer. @@ -1678,6 +2131,16 @@ @comment netdb.h @comment BSD @deftypefun void setprotoent (int @var{stayopen}) +@safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c setprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_setent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c setup(nss_protocols_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *lookup_fct = nss_protocols_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:protoent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock dup @aculock This function opens the protocols database to begin scanning it. If the @var{stayopen} argument is nonzero, this sets a flag so that @@ -1690,6 +2153,25 @@ @comment netdb.h @comment BSD @deftypefun {struct protoent *} getprotoent (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtasurace{:protoentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c getprotoent @mtasurace:protoent @mtasurace:protoentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_getent(getprotoent_r) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c malloc dup @ascuheap @acsmem +@c *func = getprotoent_r dup @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c getprotoent_r @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_getent_r(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:servent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *sfct.f @mtasurace:protoent @ascuplugin +@c libc_lock_unlock dup @aculock This function returns the next entry in the protocols database. It returns a null pointer if there are no more entries. @end deftypefun @@ -1697,6 +2179,14 @@ @comment netdb.h @comment BSD @deftypefun void endprotoent (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c endprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock @asulock @aculock +@c nss_endent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:protoent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock @aculock This function closes the protocols database. @end deftypefun @@ -1766,6 +2256,7 @@ @comment sys/socket.h @comment BSD @deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function creates a socket and specifies communication style @var{style}, which should be one of the socket styles listed in @ref{Communication Styles}. The @var{namespace} argument specifies @@ -1828,6 +2319,7 @@ @comment sys/socket.h @comment BSD @deftypefun int shutdown (int @var{socket}, int @var{how}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{shutdown} function shuts down the connection of socket @var{socket}. The argument @var{how} specifies what action to perform: @@ -1879,6 +2371,7 @@ @comment sys/socket.h @comment BSD @deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function creates a socket pair, returning the file descriptors in @code{@var{filedes}[0]} and @code{@var{filedes}[1]}. The socket pair is a full-duplex communications channel, so that both reading and writing @@ -1972,6 +2465,7 @@ @comment sys/socket.h @comment BSD @deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{connect} function initiates a connection from the socket with file descriptor @var{socket} to the socket whose address is specified by the @var{addr} and @var{length} arguments. (This socket @@ -2071,6 +2565,7 @@ @comment sys/socket.h @comment BSD @deftypefun int listen (int @var{socket}, int @var{n}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} The @code{listen} function enables the socket @var{socket} to accept connections, thus making it a server socket. @@ -2123,6 +2618,7 @@ @comment sys/socket.h @comment BSD @deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length_ptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} This function is used to accept a connection request on the server socket @var{socket}. @@ -2181,6 +2677,7 @@ @comment sys/socket.h @comment BSD @deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getpeername} function returns the address of the socket that @var{socket} is connected to; it stores the address in the memory space specified by @var{addr} and @var{length-ptr}. It stores the length of @@ -2248,7 +2745,8 @@ @comment sys/socket.h @comment BSD -@deftypefun int send (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}) +@deftypefun ssize_t send (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{send} function is like @code{write}, but with the additional flags @var{flags}. The possible values of @var{flags} are described in @ref{Socket Data Options}. @@ -2315,7 +2813,8 @@ @comment sys/socket.h @comment BSD -@deftypefun int recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}) +@deftypefun ssize_t recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{recv} function is like @code{read}, but with the additional flags @var{flags}. The possible values of @var{flags} are described in @ref{Socket Data Options}. @@ -2643,7 +3142,8 @@ @comment sys/socket.h @comment BSD -@deftypefun int sendto (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length}) +@deftypefun ssize_t sendto (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{sendto} function transmits the data in the @var{buffer} through the socket @var{socket} to the destination address specified by the @var{addr} and @var{length} arguments. The @var{size} argument @@ -2678,7 +3178,8 @@ @comment sys/socket.h @comment BSD -@deftypefun int recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) +@deftypefun ssize_t recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{recvfrom} function reads one packet from the socket @var{socket} into the buffer @var{buffer}. The @var{size} argument specifies the maximum number of bytes to be read. @@ -2725,7 +3226,8 @@ @comment sys/socket.h @comment BSD -@deftypefun int sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags}) +@deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is defined as a cancellation point in multi-threaded programs, so one has to be prepared for this and make sure that @@ -2736,7 +3238,8 @@ @comment sys/socket.h @comment BSD -@deftypefun int recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags}) +@deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is defined as a cancellation point in multi-threaded programs, so one has to be prepared for this and make sure that @@ -2924,6 +3427,7 @@ @comment sys/socket.h @comment BSD @deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{getsockopt} function gets information about the value of option @var{optname} at level @var{level} for socket @var{socket}. @@ -2953,7 +3457,8 @@ @comment sys/socket.h @comment BSD -@deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t @var{optlen}) +@deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, const void *@var{optval}, socklen_t @var{optlen}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is used to set the socket option @var{optname} at level @var{level} for socket @var{socket}. The value of the option is passed in the buffer @var{optval} of size @var{optlen}. @@ -3150,6 +3655,21 @@ @comment netdb.h @comment BSD @deftypefun {struct netent *} getnetbyname (const char *@var{name}) +@safety{@prelim{}@mtunsafe{@mtasurace{:netbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c getnetbyname =~ getpwuid @mtasurace:netbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c getnetbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c getnetbyname_r =~ getpwuid_r @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c no nscd support +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_getnetbyname_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem The @code{getnetbyname} function returns information about the network named @var{name}. It returns a null pointer if there is no such network. @@ -3157,7 +3677,21 @@ @comment netdb.h @comment BSD -@deftypefun {struct netent *} getnetbyaddr (unsigned long int @var{net}, int @var{type}) +@deftypefun {struct netent *} getnetbyaddr (uint32_t @var{net}, int @var{type}) +@safety{@prelim{}@mtunsafe{@mtasurace{:netbyaddr} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c getnetbyaddr =~ getpwuid @mtasurace:netbyaddr @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c getnetbyaddr_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c getnetbyaddr_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c no nscd support +@c nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_getnetbyaddr_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem The @code{getnetbyaddr} function returns information about the network of type @var{type} with number @var{net}. You should specify a value of @code{AF_INET} for the @var{type} argument for Internet networks. @@ -3173,6 +3707,17 @@ @comment netdb.h @comment BSD @deftypefun void setnetent (int @var{stayopen}) +@safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c setnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_setent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c setup(nss_networks_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *lookup_fct = nss_networks_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:netent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock dup @aculock This function opens and rewinds the networks database. If the @var{stayopen} argument is nonzero, this sets a flag so that @@ -3185,6 +3730,26 @@ @comment netdb.h @comment BSD @deftypefun {struct netent *} getnetent (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtasurace{:netentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c getnetent @mtasurace:netent @mtasurace:netentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_getent(getnetent_r) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c malloc dup @ascuheap @acsmem +@c *func = getnetent_r dup @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock +@c +@c getnetent_r @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_getent_r(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:servent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *sfct.f @mtasurace:netent @ascuplugin +@c libc_lock_unlock dup @aculock This function returns the next entry in the networks database. It returns a null pointer if there are no more entries. @end deftypefun @@ -3192,5 +3757,14 @@ @comment netdb.h @comment BSD @deftypefun void endnetent (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c endnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock @asulock @aculock +@c nss_endent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:netent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock @aculock This function closes the networks database. @end deftypefun diff -urN glibc-2.17-c758a686/manual/startup.texi glibc-2.17-c758a686/manual/startup.texi --- glibc-2.17-c758a686/manual/startup.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/startup.texi 2014-09-12 16:10:06.042792724 -0400 @@ -41,7 +41,7 @@ * Program Termination:: Telling the system you're done; return status @end menu -@node Program Arguments +@node Program Arguments, Environment Variables, , Program Basics @section Program Arguments @cindex program arguments @cindex command line arguments @@ -220,7 +220,12 @@ available. @comment stdlib.h -@deftypefun int getsubopt (char **@var{optionp}, const char* const *@var{tokens}, char **@var{valuep}) +@deftypefun int getsubopt (char **@var{optionp}, char *const *@var{tokens}, char **@var{valuep}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c getsubopt ok +@c strchrnul dup ok +@c memchr dup ok +@c strncmp dup ok The @var{optionp} parameter must be a pointer to a variable containing the address of the string to process. When the function returns the @@ -258,7 +263,7 @@ @end smallexample -@node Environment Variables +@node Environment Variables, Auxiliary Vector, Program Arguments, Program Basics @section Environment Variables @cindex environment variable @@ -322,6 +327,8 @@ @comment stdlib.h @comment ISO @deftypefun {char *} getenv (const char *@var{name}) +@safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}} +@c Unguarded access to __environ. This function returns a string that is the value of the environment variable @var{name}. You must not modify this string. In some non-Unix systems not using @theglibc{}, it might be overwritten by subsequent @@ -333,6 +340,8 @@ @comment stdlib.h @comment GNU @deftypefun {char *} secure_getenv (const char *@var{name}) +@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 pointer if the environment is untrusted. This happens when the program file has SUID or SGID bits set. General-purpose libraries @@ -346,6 +355,13 @@ @comment stdlib.h @comment SVID @deftypefun int putenv (char *@var{string}) +@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 +@c strndup dup @ascuheap @acsmem +@c add_to_environ dup @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem +@c free dup @ascuheap @acsmem +@c unsetenv dup @mtasuconst:@mtsenv @asulock @aculock The @code{putenv} function adds or removes definitions from the environment. If the @var{string} is of the form @samp{@var{name}=@var{value}}, the definition is added to the environment. Otherwise, the @var{string} is @@ -358,20 +374,37 @@ The difference to the @code{setenv} function is that the exact string given as the parameter @var{string} is put into the environment. If the user should change the string after the @code{putenv} call this will -reflect in automatically in the environment. This also requires that -@var{string} is no automatic variable which scope is left before the +reflect automatically in the environment. This also requires that +@var{string} not be an automatic variable whose scope is left before the variable is removed from the environment. The same applies of course to dynamically allocated variables which are freed later. -This function is part of the extended Unix interface. Since it was also -available in old SVID libraries you should define either -@var{_XOPEN_SOURCE} or @var{_SVID_SOURCE} before including any header. +This function is part of the extended Unix interface. You should define +@var{_XOPEN_SOURCE} before including any header. @end deftypefun @comment stdlib.h @comment BSD @deftypefun int setenv (const char *@var{name}, const char *@var{value}, int @var{replace}) +@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 +@c strlen dup ok +@c libc_lock_lock @asulock @aculock +@c strncmp dup ok +@c realloc dup @ascuheap @acsmem +@c libc_lock_unlock @aculock +@c malloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c mempcpy dup ok +@c memcpy dup ok +@c KNOWN_VALUE ok +@c tfind(strcmp) [no @mtsrace guarded access] +@c strcmp dup ok +@c STORE_VALUE @ascuheap @acucorrupt @acsmem +@c tsearch(strcmp) @ascuheap @acucorrupt @acsmem [no @mtsrace or @asucorrupt guarded access makes for mtsafe and @asulock] +@c strcmp dup ok The @code{setenv} function can be used to add a new definition to the environment. The entry with the name @var{name} is replaced by the value @samp{@var{name}=@var{value}}. Please note that this is also true @@ -395,6 +428,13 @@ @comment stdlib.h @comment BSD @deftypefun int unsetenv (const char *@var{name}) +@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c unsetenv @mtasuconst:@mtsenv @asulock @aculock +@c strchr dup ok +@c strlen dup ok +@c libc_lock_lock @asulock @aculock +@c strncmp dup ok +@c libc_lock_unlock @aculock Using this function one can remove an entry completely from the environment. If the environment contains an entry with the key @var{name} this whole entry is removed. A call to this function is @@ -418,6 +458,11 @@ @comment stdlib.h @comment GNU @deftypefun int clearenv (void) +@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 +@c free dup @ascuheap @acsmem +@c libc_lock_unlock @aculock The @code{clearenv} function removes all entries from the environment. Using @code{putenv} and @code{setenv} new entries can be added again later. @@ -622,10 +667,13 @@ @subsection Definition of @code{getauxval} @comment sys/auxv.h @deftypefun {unsigned long int} getauxval (unsigned long int @var{type}) +@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 vector. The @var{type} argument should be one of the @samp{AT_} symbols defined in @file{elf.h}. If a matching entry is found, the value is -returned; if the entry is not found, zero is returned. +returned; if the entry is not found, zero is returned and @code{errno} is +set to @code{ENOENT}. @end deftypefun For some platforms, the key @code{AT_HWCAP} is the easiest way to inquire @@ -677,6 +725,7 @@ @comment unistd.h @comment ??? @deftypefun {long int} syscall (long int @var{sysno}, @dots{}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{syscall} performs a generic system call. @@ -782,6 +831,10 @@ @comment stdlib.h @comment ISO @deftypefun void exit (int @var{status}) +@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 +@c AS and AC issues with streams. The @code{exit} function tells the system that the program is done, which causes it to terminate the process. @@ -898,6 +951,15 @@ @comment stdlib.h @comment ISO @deftypefun int atexit (void (*@var{function}) (void)) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} +@c atexit @ascuheap @asulock @aculock @acsmem +@c cxa_atexit @ascuheap @asulock @aculock @acsmem +@c __internal_atexit @ascuheap @asulock @aculock @acsmem +@c __new_exitfn @ascuheap @asulock @aculock @acsmem +@c __libc_lock_lock @asulock @aculock +@c calloc dup @ascuheap @acsmem +@c __libc_lock_unlock @aculock +@c atomic_write_barrier dup ok The @code{atexit} function registers the function @var{function} to be called at normal program termination. The @var{function} is called with no arguments. @@ -909,6 +971,10 @@ @comment stdlib.h @comment SunOS @deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} +@c on_exit @ascuheap @asulock @aculock @acsmem +@c new_exitfn dup @ascuheap @asulock @aculock @acsmem +@c atomic_write_barrier dup ok This function is a somewhat more powerful variant of @code{atexit}. It accepts two arguments, a function @var{function} and an arbitrary pointer @var{arg}. At normal program termination, the @var{function} is @@ -940,6 +1006,10 @@ @comment stdlib.h @comment ISO @deftypefun void abort (void) +@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 +@c using streams, we may encounter them in inconsistent states. The @code{abort} function causes abnormal program termination. This does not execute cleanup functions registered with @code{atexit} or @code{on_exit}. @@ -967,6 +1037,9 @@ @comment unistd.h @comment POSIX.1 @deftypefun void _exit (int @var{status}) +@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. The @code{_exit} function is the primitive for causing a process to terminate with status @var{status}. Calling this function does not execute cleanup functions registered with @code{atexit} or @@ -976,6 +1049,8 @@ @comment stdlib.h @comment ISO @deftypefun void _Exit (int @var{status}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Alias for _exit. The @code{_Exit} function is the @w{ISO C} equivalent to @code{_exit}. The @w{ISO C} committee members were not sure whether the definitions of @code{_exit} and @code{_Exit} were compatible so they have not used the diff -urN glibc-2.17-c758a686/manual/stdio.texi glibc-2.17-c758a686/manual/stdio.texi --- glibc-2.17-c758a686/manual/stdio.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/stdio.texi 2014-09-12 16:10:06.043792722 -0400 @@ -148,6 +148,8 @@ @comment stdio.h @comment ISO @deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} +@c fopen may leak the list lock if cancelled within _IO_link_in. The @code{fopen} function opens a stream for I/O to the file @var{filename}, and returns a pointer to the stream. @@ -265,9 +267,10 @@ @comment stdio.h @comment Unix98 @deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} This function is similar to @code{fopen} but the stream it returns a pointer for is opened using @code{open64}. Therefore this stream can be -used even on files larger then @math{2^31} bytes on 32 bit machines. +used even on files larger than @math{2^31} bytes on 32 bit machines. Please note that the return type is still @code{FILE *}. There is no special @code{FILE} type for the LFS interface. @@ -294,6 +297,16 @@ @comment stdio.h @comment ISO @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}} +@c Like most I/O operations, this one is guarded by a recursive lock, +@c released even upon cancellation, but cancellation may leak file +@c descriptors and leave the stream in an inconsistent state (e.g., +@c still bound to the closed descriptor). Also, if the stream is +@c part-way through a significant update (say running freopen) when a +@c signal handler calls freopen again on the same stream, the result is +@c likely to be an inconsistent stream, and the possibility of closing +@c twice file descriptor number that the stream used to use, the second +@c time when it might have already been reused by another thread. This function is like a combination of @code{fclose} and @code{fopen}. It first closes the stream referred to by @var{stream}, ignoring any errors that are detected in the process. (Because errors are ignored, @@ -320,6 +333,7 @@ @comment stdio.h @comment Unix98 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}} This function is similar to @code{freopen}. The only difference is that on 32 bit machine the stream returned is able to read beyond the @math{2^31} bytes limits imposed by the normal interface. It should be @@ -341,6 +355,7 @@ @comment stdio_ext.h @comment GNU @deftypefun int __freadable (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__freadable} function determines whether the stream @var{stream} was opened to allow reading. In this case the return value is nonzero. For write-only streams the function returns zero. @@ -351,6 +366,7 @@ @comment stdio_ext.h @comment GNU @deftypefun int __fwritable (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__fwritable} function determines whether the stream @var{stream} was opened to allow writing. In this case the return value is nonzero. For read-only streams the function returns zero. @@ -364,6 +380,7 @@ @comment stdio_ext.h @comment GNU @deftypefun int __freading (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__freading} function determines whether the stream @var{stream} was last read from or whether it is opened read-only. In this case the return value is nonzero, otherwise it is zero. @@ -377,6 +394,7 @@ @comment stdio_ext.h @comment GNU @deftypefun int __fwriting (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__fwriting} function determines whether the stream @var{stream} was last written to or whether it is opened write-only. In this case the return value is nonzero, otherwise it is zero. @@ -396,6 +414,21 @@ @comment stdio.h @comment ISO @deftypefun int fclose (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c After fclose, it is undefined behavior to use the stream it points +@c to. Therefore, one must only call fclose when the stream is +@c otherwise unused. Concurrent uses started before will complete +@c successfully because of the lock, which makes it MT-Safe. Calling it +@c from a signal handler is perfectly safe if the stream is known to be +@c no longer used, which is a precondition for fclose to be safe in the +@c first place; since this is no further requirement, fclose is safe for +@c use in async signals too. After calling fclose, you can no longer +@c use the stream, not even to fclose it again, so its memory and file +@c descriptor may leak if fclose is canceled before @c releasing them. +@c That the stream must be unused and it becomes unused after the call +@c is what would enable fclose to be AS- and AC-Safe while freopen +@c isn't. However, because of the possibility of leaving __gconv_lock +@c taken upon cancellation, AC-Safety is lost. This function causes @var{stream} to be closed and the connection to the corresponding file to be broken. Any buffered output is written and any buffered input is discarded. The @code{fclose} function returns @@ -418,6 +451,12 @@ @comment stdio.h @comment GNU @deftypefun int fcloseall (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:streams}}@asunsafe{}@acsafe{}} +@c Like fclose, using any previously-opened streams after fcloseall is +@c undefined. However, the implementation of fcloseall isn't equivalent +@c to calling fclose for all streams: it just flushes and unbuffers all +@c streams, without any locking. It's the flushing without locking that +@c makes it unsafe. This function causes all open streams of the process to be closed and the connection to corresponding files to be broken. All buffered data is written and any buffered input is discarded. The @code{fcloseall} @@ -474,6 +513,9 @@ @comment stdio.h @comment POSIX @deftypefun void flockfile (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} +@c There's no way to tell whether the lock was acquired before or after +@c cancellation so as to unlock only when appropriate. The @code{flockfile} function acquires the internal locking object associated with the stream @var{stream}. This ensures that no other thread can explicitly through @code{flockfile}/@code{ftrylockfile} or @@ -485,6 +527,7 @@ @comment stdio.h @comment POSIX @deftypefun int ftrylockfile (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} The @code{ftrylockfile} function tries to acquire the internal locking object associated with the stream @var{stream} just like @code{flockfile}. But unlike @code{flockfile} this function does not @@ -496,8 +539,9 @@ @comment stdio.h @comment POSIX @deftypefun void funlockfile (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} The @code{funlockfile} function releases the internal locking object of -the stream @var{stream}. The stream must have been locked before by a +the stream @var{stream}. The stream must have been locked before by a call to @code{flockfile} or a successful call of @code{ftrylockfile}. The implicit locking performed by the stream operations do not count. The @code{funlockfile} function does not return an error status and the @@ -621,6 +665,15 @@ @comment stdio_ext.h @comment GNU @deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asulock{}}@acsafe{}} +@c Changing the implicit-locking status of a stream while it's in use by +@c another thread may cause a lock to be implicitly acquired and not +@c released, or vice-versa. This function should probably hold the lock +@c while changing this setting, to make sure we don't change it while +@c there are any concurrent uses. Meanwhile, callers should acquire the +@c lock themselves to be safe, and even concurrent uses with external +@c locking will be fine, as long as functions that require external +@c locking are not called without holding locks. The @code{__fsetlocking} function can be used to select whether the stream operations will implicitly acquire the locking object of the @@ -725,6 +778,10 @@ @comment wchar.h @comment ISO @deftypefun int fwide (FILE *@var{stream}, int @var{mode}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{}}} +@c Querying is always safe, but changing the stream when it's in use +@c upthread may be problematic. Like most lock-acquiring functions, +@c this one may leak the lock if canceled. The @code{fwide} function can be used to set and query the state of the orientation of the stream @var{stream}. If the @var{mode} parameter has @@ -811,6 +868,16 @@ @comment stdio.h @comment ISO @deftypefun int fputc (int @var{c}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} +@c If the stream is in use when interrupted by a signal, the recursive +@c lock won't help ensure the stream is consistent; indeed, if fputc +@c gets a signal precisely before the post-incremented _IO_write_ptr +@c value is stored, we may overwrite the interrupted write. Conversely, +@c depending on compiler optimizations, the incremented _IO_write_ptr +@c may be stored before the character is stored in the buffer, +@c corrupting the stream if async cancel hits between the two stores. +@c There may be other reasons for AS- and AC-unsafety in the overflow +@c cases. The @code{fputc} function converts the character @var{c} to type @code{unsigned char}, and writes it to the stream @var{stream}. @code{EOF} is returned if a write error occurs; otherwise the @@ -820,6 +887,7 @@ @comment wchar.h @comment ISO @deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The @code{fputwc} function writes the wide character @var{wc} to the stream @var{stream}. @code{WEOF} is returned if a write error occurs; otherwise the character @var{wc} is returned. @@ -828,13 +896,18 @@ @comment stdio.h @comment POSIX @deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +@c The unlocked functions can't possibly satisfy the MT-Safety +@c requirements on their own, because they require external locking for +@c safety. The @code{fputc_unlocked} function is equivalent to the @code{fputc} function except that it does not implicitly lock the stream. @end deftypefun @comment wchar.h @comment POSIX -@deftypefun wint_t fputwc_unlocked (wint_t @var{wc}, FILE *@var{stream}) +@deftypefun wint_t fputwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fputwc_unlocked} function is equivalent to the @code{fputwc} function except that it does not implicitly lock the stream. @@ -844,6 +917,7 @@ @comment stdio.h @comment ISO @deftypefun int putc (int @var{c}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} This is just like @code{fputc}, except that most systems implement it as a macro, making it faster. One consequence is that it may evaluate the @var{stream} argument more than once, which is an exception to the @@ -854,6 +928,7 @@ @comment wchar.h @comment ISO @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} This is just like @code{fputwc}, except that it can be implement as a macro, making it faster. One consequence is that it may evaluate the @var{stream} argument more than once, which is an exception to the @@ -864,6 +939,7 @@ @comment stdio.h @comment POSIX @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putc_unlocked} function is equivalent to the @code{putc} function except that it does not implicitly lock the stream. @end deftypefun @@ -871,6 +947,7 @@ @comment wchar.h @comment GNU @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putwc_unlocked} function is equivalent to the @code{putwc} function except that it does not implicitly lock the stream. @@ -880,6 +957,7 @@ @comment stdio.h @comment ISO @deftypefun int putchar (int @var{c}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The @code{putchar} function is equivalent to @code{putc} with @code{stdout} as the value of the @var{stream} argument. @end deftypefun @@ -887,6 +965,7 @@ @comment wchar.h @comment ISO @deftypefun wint_t putwchar (wchar_t @var{wc}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The @code{putwchar} function is equivalent to @code{putwc} with @code{stdout} as the value of the @var{stream} argument. @end deftypefun @@ -894,6 +973,7 @@ @comment stdio.h @comment POSIX @deftypefun int putchar_unlocked (int @var{c}) +@safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putchar_unlocked} function is equivalent to the @code{putchar} function except that it does not implicitly lock the stream. @end deftypefun @@ -901,6 +981,7 @@ @comment wchar.h @comment GNU @deftypefun wint_t putwchar_unlocked (wchar_t @var{wc}) +@safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putwchar_unlocked} function is equivalent to the @code{putwchar} function except that it does not implicitly lock the stream. @@ -910,6 +991,7 @@ @comment stdio.h @comment ISO @deftypefun int fputs (const char *@var{s}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The function @code{fputs} writes the string @var{s} to the stream @var{stream}. The terminating null character is not written. This function does @emph{not} add a newline character, either. @@ -933,6 +1015,7 @@ @comment wchar.h @comment ISO @deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} The function @code{fputws} writes the wide character string @var{ws} to the stream @var{stream}. The terminating null character is not written. This function does @emph{not} add a newline character, either. It @@ -945,6 +1028,7 @@ @comment stdio.h @comment GNU @deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fputs_unlocked} function is equivalent to the @code{fputs} function except that it does not implicitly lock the stream. @@ -954,6 +1038,7 @@ @comment wchar.h @comment GNU @deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fputws_unlocked} function is equivalent to the @code{fputws} function except that it does not implicitly lock the stream. @@ -963,6 +1048,7 @@ @comment stdio.h @comment ISO @deftypefun int puts (const char *@var{s}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{puts} function writes the string @var{s} to the stream @code{stdout} followed by a newline. The terminating null character of the string is not written. (Note that @code{fputs} does @emph{not} @@ -982,6 +1068,7 @@ @comment stdio.h @comment SVID @deftypefun int putw (int @var{w}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function writes the word @var{w} (that is, an @code{int}) to @var{stream}. It is provided for compatibility with SVID, but we recommend you use @code{fwrite} instead (@pxref{Block Input/Output}). @@ -1014,6 +1101,11 @@ @comment stdio.h @comment ISO @deftypefun int fgetc (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} +@c Same caveats as fputc, but instead of losing a write in case of async +@c signals, we may read the same character more than once, and the +@c stream may be left in odd states due to cancellation in the underflow +@c cases. This function reads the next character as an @code{unsigned char} from the stream @var{stream} and returns its value, converted to an @code{int}. If an end-of-file condition or read error occurs, @@ -1023,6 +1115,7 @@ @comment wchar.h @comment ISO @deftypefun wint_t fgetwc (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function reads the next wide character from the stream @var{stream} and returns its value. If an end-of-file condition or read error occurs, @code{WEOF} is returned instead. @@ -1031,6 +1124,7 @@ @comment stdio.h @comment POSIX @deftypefun int fgetc_unlocked (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fgetc_unlocked} function is equivalent to the @code{fgetc} function except that it does not implicitly lock the stream. @end deftypefun @@ -1038,6 +1132,7 @@ @comment wchar.h @comment GNU @deftypefun wint_t fgetwc_unlocked (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc} function except that it does not implicitly lock the stream. @@ -1047,6 +1142,7 @@ @comment stdio.h @comment ISO @deftypefun int getc (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This is just like @code{fgetc}, except that it is permissible (and typical) for it to be implemented as a macro that evaluates the @var{stream} argument more than once. @code{getc} is often highly @@ -1057,6 +1153,7 @@ @comment wchar.h @comment ISO @deftypefun wint_t getwc (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This is just like @code{fgetwc}, except that it is permissible for it to be implemented as a macro that evaluates the @var{stream} argument more than once. @code{getwc} can be highly optimized, so it is usually the @@ -1066,6 +1163,7 @@ @comment stdio.h @comment POSIX @deftypefun int getc_unlocked (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getc_unlocked} function is equivalent to the @code{getc} function except that it does not implicitly lock the stream. @end deftypefun @@ -1073,6 +1171,7 @@ @comment wchar.h @comment GNU @deftypefun wint_t getwc_unlocked (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getwc_unlocked} function is equivalent to the @code{getwc} function except that it does not implicitly lock the stream. @@ -1082,6 +1181,7 @@ @comment stdio.h @comment ISO @deftypefun int getchar (void) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{getchar} function is equivalent to @code{getc} with @code{stdin} as the value of the @var{stream} argument. @end deftypefun @@ -1089,6 +1189,7 @@ @comment wchar.h @comment ISO @deftypefun wint_t getwchar (void) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin} as the value of the @var{stream} argument. @end deftypefun @@ -1096,6 +1197,7 @@ @comment stdio.h @comment POSIX @deftypefun int getchar_unlocked (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getchar_unlocked} function is equivalent to the @code{getchar} function except that it does not implicitly lock the stream. @end deftypefun @@ -1103,6 +1205,7 @@ @comment wchar.h @comment GNU @deftypefun wint_t getwchar_unlocked (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getwchar_unlocked} function is equivalent to the @code{getwchar} function except that it does not implicitly lock the stream. @@ -1145,6 +1248,7 @@ @comment stdio.h @comment SVID @deftypefun int getw (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function reads a word (that is, an @code{int}) from @var{stream}. It's provided for compatibility with SVID. We recommend you use @code{fread} instead (@pxref{Block Input/Output}). Unlike @code{getc}, @@ -1173,6 +1277,12 @@ @comment stdio.h @comment GNU @deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} +@c Besides the usual possibility of getting an inconsistent stream in a +@c signal handler or leaving it inconsistent in case of cancellation, +@c the possibility of leaving a dangling pointer upon cancellation +@c between reallocing the buffer at *lineptr and updating the pointer +@c brings about another case of @acucorrupt. This function reads an entire line from @var{stream}, storing the text (including the newline and a terminating null character) in a buffer and storing the buffer address in @code{*@var{lineptr}}. @@ -1188,7 +1298,8 @@ If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}} to zero, before the call, then @code{getline} allocates the initial -buffer for you by calling @code{malloc}. +buffer for you by calling @code{malloc}. This buffer remains allocated +even if @code{getline} encounters errors and is unable to read any bytes. In either case, when @code{getline} returns, @code{*@var{lineptr}} is a @code{char *} which points to the text of the line. @@ -1208,6 +1319,8 @@ @comment stdio.h @comment GNU @deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} +@c See the getline @acucorrupt note. This function is like @code{getline} except that the character which tells it to stop reading is not necessarily newline. The argument @var{delimiter} specifies the delimiter character; @code{getdelim} keeps @@ -1232,6 +1345,7 @@ @comment stdio.h @comment ISO @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{fgets} function reads characters from the stream @var{stream} up to and including a newline character and stores them in the string @var{s}, adding a null character to mark the end of the string. You @@ -1255,6 +1369,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{fgetws} function reads wide characters from the stream @var{stream} up to and including a newline character and stores them in the string @var{ws}, adding a null wide character to mark the end of the @@ -1280,6 +1395,7 @@ @comment stdio.h @comment GNU @deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fgets_unlocked} function is equivalent to the @code{fgets} function except that it does not implicitly lock the stream. @@ -1289,6 +1405,7 @@ @comment wchar.h @comment GNU @deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fgetws_unlocked} function is equivalent to the @code{fgetws} function except that it does not implicitly lock the stream. @@ -1298,6 +1415,7 @@ @comment stdio.h @comment ISO @deftypefn {Deprecated function} {char *} gets (char *@var{s}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The function @code{gets} reads characters from the stream @code{stdin} up to the next newline character, and stores them in the string @var{s}. The newline character is discarded (note that this differs from the @@ -1388,6 +1506,7 @@ @comment stdio.h @comment ISO @deftypefun int ungetc (int @var{c}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{ungetc} function pushes back the character @var{c} onto the input stream @var{stream}. So the next input from @var{stream} will read @var{c} before anything else. @@ -1425,6 +1544,7 @@ @comment wchar.h @comment ISO @deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{ungetwc} function behaves just like @code{ungetc} just that it pushes back a wide character. @end deftypefun @@ -1483,6 +1603,7 @@ @comment stdio.h @comment ISO @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function reads up to @var{count} objects of size @var{size} into the array @var{data}, from the stream @var{stream}. It returns the number of objects actually read, which might be less than @var{count} if @@ -1498,6 +1619,7 @@ @comment stdio.h @comment GNU @deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fread_unlocked} function is equivalent to the @code{fread} function except that it does not implicitly lock the stream. @@ -1507,6 +1629,7 @@ @comment stdio.h @comment ISO @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function writes up to @var{count} objects of size @var{size} from the array @var{data}, to the stream @var{stream}. The return value is normally @var{count}, if the call succeeds. Any other value indicates @@ -1516,6 +1639,7 @@ @comment stdio.h @comment GNU @deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fwrite_unlocked} function is equivalent to the @code{fwrite} function except that it does not implicitly lock the stream. @@ -1670,7 +1794,7 @@ @defvr Macro NL_ARGMAX The value of @code{NL_ARGMAX} is the maximum value allowed for the -specification of an positional parameter in a @code{printf} call. The +specification of a positional parameter in a @code{printf} call. The actual value in effect at runtime can be retrieved by using @code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf Definition}. @@ -2257,6 +2381,7 @@ @comment stdio.h @comment ISO @deftypefun int printf (const char *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} The @code{printf} function prints the optional arguments under the control of the template string @var{template} to the stream @code{stdout}. It returns the number of characters printed, or a @@ -2266,6 +2391,7 @@ @comment wchar.h @comment ISO @deftypefun int wprintf (const wchar_t *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} The @code{wprintf} function prints the optional arguments under the control of the wide template string @var{template} to the stream @code{stdout}. It returns the number of wide characters printed, or a @@ -2275,6 +2401,7 @@ @comment stdio.h @comment ISO @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is just like @code{printf}, except that the output is written to the stream @var{stream} instead of @code{stdout}. @end deftypefun @@ -2282,6 +2409,7 @@ @comment wchar.h @comment ISO @deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is just like @code{wprintf}, except that the output is written to the stream @var{stream} instead of @code{stdout}. @end deftypefun @@ -2289,6 +2417,7 @@ @comment stdio.h @comment ISO @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is like @code{printf}, except that the output is stored in the character array @var{s} instead of written to a stream. A null character is written to mark the end of the string. @@ -2313,6 +2442,7 @@ @comment wchar.h @comment GNU @deftypefun int swprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is like @code{wprintf}, except that the output is stored in the wide character array @var{ws} instead of written to a stream. A null wide character is written to mark the end of the string. The @var{size} @@ -2330,13 +2460,14 @@ parameters. @code{swprintf} in fact corresponds to the @code{snprintf} function. Since the @code{sprintf} function can be dangerous and should be avoided the @w{ISO C} committee refused to make the same mistake -again and decided to not define an function exactly corresponding to +again and decided to not define a function exactly corresponding to @code{sprintf}. @end deftypefun @comment stdio.h @comment GNU @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{snprintf} function is similar to @code{sprintf}, except that the @var{size} argument specifies the maximum number of characters to produce. The trailing null character is counted towards this limit, so @@ -2407,6 +2538,7 @@ @comment stdio.h @comment GNU @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function is similar to @code{sprintf}, except that it dynamically allocates a string (as with @code{malloc}; @pxref{Unconstrained Allocation}) to hold the output, instead of putting the output in a @@ -2416,7 +2548,7 @@ location. The return value is the number of characters allocated for the buffer, or -less than zero if an error occurred. Usually this means that the buffer +less than zero if an error occurred. Usually this means that the buffer could not be allocated. Here is how to use @code{asprintf} to get the same result as the @@ -2439,6 +2571,7 @@ @comment stdio.h @comment GNU @deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} This function is similar to @code{asprintf}, except that it uses the obstack @var{obstack} to allocate the space. @xref{Obstacks}. @@ -2509,6 +2642,7 @@ @comment stdio.h @comment ISO @deftypefun int vprintf (const char *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is similar to @code{printf} except that, instead of taking a variable number of arguments directly, it takes an argument list pointer @var{ap}. @@ -2517,6 +2651,7 @@ @comment wchar.h @comment ISO @deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is similar to @code{wprintf} except that, instead of taking a variable number of arguments directly, it takes an argument list pointer @var{ap}. @@ -2525,6 +2660,48 @@ @comment stdio.h @comment ISO @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} +@c Although vfprintf sets up a cleanup region to release the lock on the +@c output stream, it doesn't use it to release args_value or string in +@c case of cancellation. This doesn't make it unsafe, but cancelling it +@c may leak memory. The unguarded use of __printf_function_table is +@c also of concern for all callers. +@c _itoa ok +@c _udiv_qrnnd_preinv ok +@c group_number ok +@c _i18n_number_rewrite +@c __wctrans ok +@c __towctrans @mtslocale +@c __wcrtomb ok? dup below +@c outdigit_value ok +@c outdigitwc_value ok +@c outchar ok +@c outstring ok +@c PAD ok +@c __printf_fp @mtslocale @ascuheap @acsmem +@c __printf_fphex @mtslocale +@c __readonly_area +@c [GNU/Linux] fopen, strtoul, free +@c __strerror_r ok if no translation, check otherwise +@c __btowc ? gconv-modules +@c __wcrtomb ok (not using internal state) gconv-modules +@c ARGCHECK +@c UNBUFFERED_P (tested before taking the stream lock) +@c buffered_vfprintf ok +@c __find_spec(wc|mb) +@c read_int +@c __libc_use_alloca +@c process_arg +@c process_string_arg +@c extend_alloca +@c __parse_one_spec(wc|mb) +@c *__printf_arginfo_table unguarded +@c __printf_va_arg_table-> unguarded +@c *__printf_function_table unguarded +@c done_add +@c printf_unknown +@c outchar +@c _itoa_word This is the equivalent of @code{fprintf} with the variable argument list specified directly as for @code{vprintf}. @end deftypefun @@ -2532,6 +2709,7 @@ @comment wchar.h @comment ISO @deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This is the equivalent of @code{fwprintf} with the variable argument list specified directly as for @code{vwprintf}. @end deftypefun @@ -2539,6 +2717,7 @@ @comment stdio.h @comment ISO @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{sprintf} with the variable argument list specified directly as for @code{vprintf}. @end deftypefun @@ -2546,6 +2725,7 @@ @comment wchar.h @comment GNU @deftypefun int vswprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{swprintf} with the variable argument list specified directly as for @code{vwprintf}. @end deftypefun @@ -2553,6 +2733,7 @@ @comment stdio.h @comment GNU @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{snprintf} with the variable argument list specified directly as for @code{vprintf}. @end deftypefun @@ -2560,6 +2741,7 @@ @comment stdio.h @comment GNU @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{vasprintf} function is the equivalent of @code{asprintf} with the variable argument list specified directly as for @code{vprintf}. @end deftypefun @@ -2567,6 +2749,10 @@ @comment stdio.h @comment GNU @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} +@c The obstack is not guarded by mutexes, it might be at an inconsistent +@c state within a signal handler, and it could be left at an +@c inconsistent state in case of cancellation. The @code{obstack_vprintf} function is the equivalent of @code{obstack_printf} with the variable argument list specified directly as for @code{vprintf}.@refill @@ -2639,6 +2825,7 @@ @comment printf.h @comment GNU @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function returns information about the number and types of arguments expected by the @code{printf} template string @var{template}. The information is stored in the array @var{argtypes}; each element of @@ -2879,6 +3066,12 @@ @comment printf.h @comment GNU @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function}) +@safety{@prelim{}@mtunsafe{@mtasuconst{:printfext}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} +@c This function is guarded by the global non-recursive libc lock, but +@c users of the variables it sets aren't, and those should be MT-Safe, +@c so we're ruling out the use of this extension with threads. Calling +@c it from a signal handler may self-deadlock, and cancellation may +@c leave the lock held, besides leaking allocated memory. This function defines the conversion specifier character @var{spec}. Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}. You can redefine the built-in conversions like @samp{%s}, but flag @@ -3125,6 +3318,12 @@ @comment printf.h @comment GNU @deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args}) +@safety{@prelim{}@mtsafe{@mtsrace{:fp} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @acucorrupt{}}} +@c This is meant to be called by vfprintf, that should hold the lock on +@c the stream, but if this function is called directly, output will be +@c racy, besides the uses of the global locale object while other +@c threads may be changing it and the possbility of leaving the stream +@c object in an inconsistent state in case of cancellation. Print a given floating point number as for the format @code{%f} except that there is a postfix character indicating the divisor for the number to make this less than 1000. There are two possible divisors: @@ -3183,6 +3382,7 @@ @comment printf.h @comment GNU @deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function will return in @var{argtypes} the information about the used parameters in the way the @code{vfprintf} implementation expects it. The format always takes one argument. @@ -3672,7 +3872,7 @@ To read in characters that belong to an arbitrary set of your choice, use the @samp{%[} conversion. You specify the set between the @samp{[} character and a following @samp{]} character, using the same syntax used -in regular expressions. As special cases: +in regular expressions for explicit sets of characters. As special cases: @itemize @bullet @item @@ -3692,6 +3892,10 @@ The @samp{%[} conversion does not skip over initial whitespace characters. +Note that the @dfn{character class} syntax available in character sets +that appear inside regular expressions (such as @samp{[:alpha:]}) is +@emph{not} available in the @samp{%[} conversion. + Here are some examples of @samp{%[} conversions and what they mean: @table @samp @@ -3799,6 +4003,7 @@ @comment stdio.h @comment ISO @deftypefun int scanf (const char *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} The @code{scanf} function reads formatted input from the stream @code{stdin} under the control of the template string @var{template}. The optional arguments are pointers to the places which receive the @@ -3813,6 +4018,7 @@ @comment wchar.h @comment ISO @deftypefun int wscanf (const wchar_t *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} The @code{wscanf} function reads formatted input from the stream @code{stdin} under the control of the template string @var{template}. The optional arguments are pointers to the places which receive the @@ -3827,6 +4033,7 @@ @comment stdio.h @comment ISO @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is just like @code{scanf}, except that the input is read from the stream @var{stream} instead of @code{stdin}. @end deftypefun @@ -3834,6 +4041,7 @@ @comment wchar.h @comment ISO @deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is just like @code{wscanf}, except that the input is read from the stream @var{stream} instead of @code{stdin}. @end deftypefun @@ -3841,6 +4049,7 @@ @comment stdio.h @comment ISO @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is like @code{scanf}, except that the characters are taken from the null-terminated string @var{s} instead of from a stream. Reaching the end of the string is treated as an end-of-file condition. @@ -3853,7 +4062,8 @@ @comment wchar.h @comment ISO -@deftypefun int swscanf (const wchar_t *@var{ws}, const char *@var{template}, @dots{}) +@deftypefun int swscanf (const wchar_t *@var{ws}, const wchar_t *@var{template}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is like @code{wscanf}, except that the characters are taken from the null-terminated string @var{ws} instead of from a stream. Reaching the end of the string is treated as an end-of-file condition. @@ -3880,6 +4090,7 @@ @comment stdio.h @comment ISO @deftypefun int vscanf (const char *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is similar to @code{scanf}, but instead of taking a variable number of arguments directly, it takes an argument list pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}). @@ -3888,6 +4099,7 @@ @comment wchar.h @comment ISO @deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This function is similar to @code{wscanf}, but instead of taking a variable number of arguments directly, it takes an argument list pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}). @@ -3896,6 +4108,7 @@ @comment stdio.h @comment ISO @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This is the equivalent of @code{fscanf} with the variable argument list specified directly as for @code{vscanf}. @end deftypefun @@ -3903,6 +4116,7 @@ @comment wchar.h @comment ISO @deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} This is the equivalent of @code{fwscanf} with the variable argument list specified directly as for @code{vwscanf}. @end deftypefun @@ -3910,6 +4124,7 @@ @comment stdio.h @comment ISO @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{sscanf} with the variable argument list specified directly as for @code{vscanf}. @end deftypefun @@ -3917,6 +4132,7 @@ @comment wchar.h @comment ISO @deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This is the equivalent of @code{swscanf} with the variable argument list specified directly as for @code{vwscanf}. @end deftypefun @@ -3966,6 +4182,7 @@ @comment stdio.h @comment ISO @deftypefun int feof (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} The @code{feof} function returns nonzero if and only if the end-of-file indicator for the stream @var{stream} is set. @@ -3975,6 +4192,9 @@ @comment stdio.h @comment GNU @deftypefun int feof_unlocked (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c There isn't much of a thread unsafety risk in reading a flag word and +@c testing a bit in it. The @code{feof_unlocked} function is equivalent to the @code{feof} function except that it does not implicitly lock the stream. @@ -3986,6 +4206,7 @@ @comment stdio.h @comment ISO @deftypefun int ferror (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} The @code{ferror} function returns nonzero if and only if the error indicator for the stream @var{stream} is set, indicating that an error has occurred on a previous operation on the stream. @@ -3996,6 +4217,7 @@ @comment stdio.h @comment GNU @deftypefun int ferror_unlocked (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{ferror_unlocked} function is equivalent to the @code{ferror} function except that it does not implicitly lock the stream. @@ -4023,6 +4245,7 @@ @comment stdio.h @comment ISO @deftypefun void clearerr (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} This function clears the end-of-file and error indicators for the stream @var{stream}. @@ -4033,6 +4256,7 @@ @comment stdio.h @comment GNU @deftypefun void clearerr_unlocked (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@assafe{}@acsafe{}} The @code{clearerr_unlocked} function is equivalent to the @code{clearerr} function except that it does not implicitly lock the stream. @@ -4146,6 +4370,7 @@ @comment stdio.h @comment ISO @deftypefun {long int} ftell (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function returns the current file position of the stream @var{stream}. @@ -4158,6 +4383,7 @@ @comment stdio.h @comment Unix98 @deftypefun off_t ftello (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{ftello} function is similar to @code{ftell}, except that it returns a value of type @code{off_t}. Systems which support this type use it to describe all file positions, unlike the POSIX specification @@ -4181,6 +4407,7 @@ @comment stdio.h @comment Unix98 @deftypefun off64_t ftello64 (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{ftello} with the only difference that the return value is of type @code{off64_t}. This also requires that the stream @var{stream} was opened using either @code{fopen64}, @@ -4196,6 +4423,7 @@ @comment stdio.h @comment ISO @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{fseek} function is used to change the file position of the stream @var{stream}. The value of @var{whence} must be one of the constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to @@ -4215,6 +4443,7 @@ @comment stdio.h @comment Unix98 @deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{fseek} but it corrects a problem with @code{fseek} in a system with POSIX types. Using a value of type @code{long int} for the offset is not compatible with POSIX. @@ -4238,6 +4467,7 @@ @comment stdio.h @comment Unix98 @deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{fseeko} with the only difference that the @var{offset} parameter is of type @code{off64_t}. This also requires that the stream @var{stream} was opened using either @@ -4286,6 +4516,7 @@ @comment stdio.h @comment ISO @deftypefun void rewind (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{rewind} function positions the stream @var{stream} at the beginning of the file. It is equivalent to calling @code{fseek} or @code{fseeko} on the @var{stream} with an @var{offset} argument of @@ -4407,6 +4638,7 @@ @comment stdio.h @comment ISO @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function stores the value of the file position indicator for the stream @var{stream} in the @code{fpos_t} object pointed to by @var{position}. If successful, @code{fgetpos} returns zero; otherwise @@ -4421,6 +4653,7 @@ @comment stdio.h @comment Unix98 @deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{fgetpos} but the file position is returned in a variable of type @code{fpos64_t} to which @var{position} points. @@ -4433,6 +4666,7 @@ @comment stdio.h @comment ISO @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function sets the file position indicator for the stream @var{stream} to the position @var{position}, which must have been set by a previous call to @code{fgetpos} on the same stream. If successful, @code{fsetpos} @@ -4449,6 +4683,7 @@ @comment stdio.h @comment Unix98 @deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is similar to @code{fsetpos} but the file position used for positioning is provided in a variable of type @code{fpos64_t} to which @var{position} points. @@ -4560,6 +4795,7 @@ @comment stdio.h @comment ISO @deftypefun int fflush (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function causes any buffered output on @var{stream} to be delivered to the file. If @var{stream} is a null pointer, then @code{fflush} causes buffered output on @emph{all} open output streams @@ -4572,6 +4808,7 @@ @comment stdio.h @comment POSIX @deftypefun int fflush_unlocked (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{fflush_unlocked} function is equivalent to the @code{fflush} function except that it does not implicitly lock the stream. @end deftypefun @@ -4588,6 +4825,7 @@ @comment stdio_ext.h @comment GNU @deftypefun void _flushlbf (void) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} The @code{_flushlbf} function flushes all line buffered streams currently opened. @@ -4609,6 +4847,7 @@ @comment stdio_ext.h @comment GNU @deftypefun void __fpurge (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{__fpurge} function causes the buffer of the stream @var{stream} to be emptied. If the stream is currently in read mode all input in the buffer is lost. If the stream is in output mode the @@ -4633,6 +4872,7 @@ @comment stdio.h @comment ISO @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function is used to specify that the stream @var{stream} should have the buffering mode @var{mode}, which can be either @code{_IOFBF} (for full buffering), @code{_IOLBF} (for line buffering), or @@ -4710,6 +4950,7 @@ @comment stdio.h @comment ISO @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} If @var{buf} is a null pointer, the effect of this function is equivalent to calling @code{setvbuf} with a @var{mode} argument of @code{_IONBF}. Otherwise, it is equivalent to calling @code{setvbuf} @@ -4723,6 +4964,7 @@ @comment stdio.h @comment BSD @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} If @var{buf} is a null pointer, this function makes @var{stream} unbuffered. Otherwise, it makes @var{stream} fully buffered using @var{buf} as the buffer. The @var{size} argument specifies the length of @var{buf}. @@ -4734,6 +4976,7 @@ @comment stdio.h @comment BSD @deftypefun void setlinebuf (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} This function makes @var{stream} be line buffered, and allocates the buffer for you. @@ -4748,6 +4991,7 @@ @comment stdio_ext.h @comment GNU @deftypefun int __flbf (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{__flbf} function will return a nonzero value in case the stream @var{stream} is line buffered. Otherwise the return value is zero. @@ -4761,6 +5005,7 @@ @comment stdio_ext.h @comment GNU @deftypefun size_t __fbufsize (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}} The @code{__fbufsize} function return the size of the buffer in the stream @var{stream}. This value can be used to optimize the use of the stream. @@ -4771,6 +5016,7 @@ @comment stdio_ext.h @comment GNU @deftypefun size_t __fpending (FILE *@var{stream}) +@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}} The @code{__fpending} function returns the number of bytes currently in the output buffer. For wide-oriented stream the measuring unit is wide characters. This @@ -4818,6 +5064,10 @@ @comment stdio.h @comment GNU @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} +@c Unlike open_memstream, fmemopen does (indirectly) call _IO_link_in, +@c bringing with it additional potential for async trouble with +@c list_all_lock. This function opens a stream that allows the access specified by the @var{opentype} argument, that reads from or writes to the buffer specified by the argument @var{buf}. This array must be at least @var{size} bytes long. @@ -4870,6 +5120,7 @@ @comment stdio.h @comment GNU @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function opens a stream for writing to a buffer. The buffer is allocated dynamically and grown as necessary, using @code{malloc}. After you've closed the stream, this buffer is your responsibility to @@ -4985,6 +5236,7 @@ @comment stdio.h @comment GNU @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} This function actually creates the stream for communicating with the @var{cookie} using the functions in the @var{io-functions} argument. The @var{opentype} argument is interpreted as for @code{fopen}; @@ -5053,26 +5305,26 @@ @comment stdio.h @comment GNU -@deftp {Data Type} cookie_read_function +@deftp {Data Type} cookie_read_function_t This is the data type that the read function for a custom stream should have. If you declare the function as shown above, this is the type it will have. @end deftp @comment stdio.h @comment GNU -@deftp {Data Type} cookie_write_function +@deftp {Data Type} cookie_write_function_t The data type of the write function for a custom stream. @end deftp @comment stdio.h @comment GNU -@deftp {Data Type} cookie_seek_function +@deftp {Data Type} cookie_seek_function_t The data type of the seek function for a custom stream. @end deftp @comment stdio.h @comment GNU -@deftp {Data Type} cookie_close_function +@deftp {Data Type} cookie_close_function_t The data type of the close function for a custom stream. @end deftp @@ -5166,6 +5418,7 @@ @comment fmtmsg.h @comment XPG @deftypefun int fmtmsg (long int @var{classification}, const char *@var{label}, int @var{severity}, const char *@var{text}, const char *@var{action}, const char *@var{tag}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acsafe{}} Display a message described by its parameters on the device(s) specified in the @var{classification} parameter. The @var{label} parameter identifies the source of the message. The string should consist of two @@ -5306,6 +5559,7 @@ but this is toilsome. @deftypefun int addseverity (int @var{severity}, const char *@var{string}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} This function allows the introduction of new severity classes which can be addressed by the @var{severity} parameter of the @code{fmtmsg} function. The @var{severity} parameter of @code{addseverity} must match the value diff -urN glibc-2.17-c758a686/manual/string.texi glibc-2.17-c758a686/manual/string.texi --- glibc-2.17-c758a686/manual/string.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/string.texi 2014-09-12 16:10:06.045792717 -0400 @@ -200,7 +200,7 @@ @cindex parameter promotion Some of the memory and string functions take single characters as arguments. Since a value of type @code{char} is automatically promoted -into an value of type @code{int} when used as a parameter, the functions +into a value of type @code{int} when used as a parameter, the functions are declared with @code{int} as the type of the parameter in question. In case of the wide character function the situation is similarly: the parameter type for a single wide character is @code{wint_t} and not @@ -219,6 +219,7 @@ @comment string.h @comment ISO @deftypefun size_t strlen (const char *@var{s}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strlen} function returns the length of the null-terminated string @var{s} in bytes. (In other words, it returns the offset of the terminating null character within the array.) @@ -285,6 +286,7 @@ @comment wchar.h @comment ISO @deftypefun size_t wcslen (const wchar_t *@var{ws}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcslen} function is the wide character equivalent to @code{strlen}. The return value is the number of wide characters in the wide character string pointed to by @var{ws} (this is also the offset of @@ -300,6 +302,7 @@ @comment string.h @comment GNU @deftypefun size_t strnlen (const char *@var{s}, size_t @var{maxlen}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strnlen} function returns the length of the string @var{s} in bytes if this length is smaller than @var{maxlen} bytes. Otherwise it returns @var{maxlen}. Therefore this function is equivalent to @@ -322,6 +325,7 @@ @comment wchar.h @comment GNU @deftypefun size_t wcsnlen (const wchar_t *@var{ws}, size_t @var{maxlen}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{wcsnlen} is the wide character equivalent to @code{strnlen}. The @var{maxlen} parameter specifies the maximum number of wide characters. @@ -367,6 +371,7 @@ @comment string.h @comment ISO @deftypefun {void *} memcpy (void *restrict @var{to}, const void *restrict @var{from}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{memcpy} function copies @var{size} bytes from the object beginning at @var{from} into the object beginning at @var{to}. The behavior of this function is undefined if the two arrays @var{to} and @@ -388,6 +393,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wmemcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wmemcpy} function copies @var{size} wide characters from the object beginning at @var{wfrom} into the object beginning at @var{wto}. The behavior of this function is undefined if the two arrays @var{wto} and @@ -413,6 +419,7 @@ @comment string.h @comment GNU @deftypefun {void *} mempcpy (void *restrict @var{to}, const void *restrict @var{from}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{mempcpy} function is nearly identical to the @code{memcpy} function. It copies @var{size} bytes from the object beginning at @code{from} into the object pointed to by @var{to}. But instead of @@ -440,6 +447,7 @@ @comment wchar.h @comment GNU @deftypefun {wchar_t *} wmempcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wmempcpy} function is nearly identical to the @code{wmemcpy} function. It copies @var{size} wide characters from the object beginning at @code{wfrom} into the object pointed to by @var{wto}. But @@ -468,6 +476,7 @@ @comment string.h @comment ISO @deftypefun {void *} memmove (void *@var{to}, const void *@var{from}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{memmove} copies the @var{size} bytes at @var{from} into the @var{size} bytes at @var{to}, even if those two blocks of space overlap. In the case of overlap, @code{memmove} is careful to copy the @@ -479,7 +488,8 @@ @comment wchar.h @comment ISO -@deftypefun {wchar_t *} wmemmove (wchar *@var{wto}, const wchar_t *@var{wfrom}, size_t @var{size}) +@deftypefun {wchar_t *} wmemmove (wchar_t *@var{wto}, const wchar_t *@var{wfrom}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{wmemmove} copies the @var{size} wide characters at @var{wfrom} into the @var{size} wide characters at @var{wto}, even if those two blocks of space overlap. In the case of overlap, @code{memmove} is @@ -507,6 +517,7 @@ @comment string.h @comment SVID @deftypefun {void *} memccpy (void *restrict @var{to}, const void *restrict @var{from}, int @var{c}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies no more than @var{size} bytes from @var{from} to @var{to}, stopping if a byte matching @var{c} is found. The return value is a pointer into @var{to} one byte past where @var{c} was copied, @@ -517,6 +528,7 @@ @comment string.h @comment ISO @deftypefun {void *} memset (void *@var{block}, int @var{c}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies the value of @var{c} (converted to an @code{unsigned char}) into each of the first @var{size} bytes of the object beginning at @var{block}. It returns the value of @var{block}. @@ -525,6 +537,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wmemset (wchar_t *@var{block}, wchar_t @var{wc}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function copies the value of @var{wc} into each of the first @var{size} wide characters of the object beginning at @var{block}. It returns the value of @var{block}. @@ -533,6 +546,7 @@ @comment string.h @comment ISO @deftypefun {char *} strcpy (char *restrict @var{to}, const char *restrict @var{from}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This copies characters from the string @var{from} (up to and including the terminating null character) into the string @var{to}. Like @code{memcpy}, this function has undefined results if the strings @@ -542,6 +556,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wcscpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This copies wide characters from the string @var{wfrom} (up to and including the terminating null wide character) into the string @var{wto}. Like @code{wmemcpy}, this function has undefined results if @@ -551,6 +566,7 @@ @comment string.h @comment ISO @deftypefun {char *} strncpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{strcpy} but always copies exactly @var{size} characters into @var{to}. @@ -576,6 +592,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wcsncpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{wcscpy} but always copies exactly @var{size} wide characters into @var{wto}. @@ -602,6 +619,7 @@ @comment string.h @comment SVID @deftypefun {char *} strdup (const char *@var{s}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function copies the null-terminated string @var{s} into a newly allocated string. The string is allocated using @code{malloc}; see @ref{Unconstrained Allocation}. If @code{malloc} cannot allocate space @@ -612,6 +630,7 @@ @comment wchar.h @comment GNU @deftypefun {wchar_t *} wcsdup (const wchar_t *@var{ws}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function copies the null-terminated wide character string @var{ws} into a newly allocated string. The string is allocated using @code{malloc}; see @ref{Unconstrained Allocation}. If @code{malloc} @@ -625,6 +644,7 @@ @comment string.h @comment GNU @deftypefun {char *} strndup (const char *@var{s}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} This function is similar to @code{strdup} but always copies at most @var{size} characters into the newly allocated string. @@ -642,6 +662,7 @@ @comment string.h @comment Unknown origin @deftypefun {char *} stpcpy (char *restrict @var{to}, const char *restrict @var{from}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is like @code{strcpy}, except that it returns a pointer to the end of the string @var{to} (that is, the address of the terminating null character @code{to + strlen (from)}) rather than the beginning. @@ -664,6 +685,7 @@ @comment wchar.h @comment GNU @deftypefun {wchar_t *} wcpcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is like @code{wcscpy}, except that it returns a pointer to the end of the string @var{wto} (that is, the address of the terminating null character @code{wto + strlen (wfrom)}) rather than the beginning. @@ -679,10 +701,11 @@ @comment string.h @comment GNU @deftypefun {char *} stpncpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{stpcpy} but copies always exactly @var{size} characters into @var{to}. -If the length of @var{from} is more then @var{size}, then @code{stpncpy} +If the length of @var{from} is more than @var{size}, then @code{stpncpy} copies just the first @var{size} characters and returns a pointer to the character directly following the one which was copied last. Note that in this case there is no null terminator written into @var{to}. @@ -704,10 +727,11 @@ @comment wchar.h @comment GNU @deftypefun {wchar_t *} wcpncpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{wcpcpy} but copies always exactly @var{wsize} characters into @var{wto}. -If the length of @var{wfrom} is more then @var{size}, then +If the length of @var{wfrom} is more than @var{size}, then @code{wcpncpy} copies just the first @var{size} wide characters and returns a pointer to the wide character directly following the last non-null wide character which was copied last. Note that in this case @@ -731,6 +755,7 @@ @comment string.h @comment GNU @deftypefn {Macro} {char *} strdupa (const char *@var{s}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This macro is similar to @code{strdup} but allocates the new string using @code{alloca} instead of @code{malloc} (@pxref{Variable Size Automatic}). This means of course the returned string has the same @@ -757,6 +782,7 @@ @comment string.h @comment GNU @deftypefn {Macro} {char *} strndupa (const char *@var{s}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is similar to @code{strndup} but like @code{strdupa} it allocates the new string using @code{alloca} @pxref{Variable Size Automatic}. The same advantages and limitations @@ -772,6 +798,7 @@ @comment string.h @comment ISO @deftypefun {char *} strcat (char *restrict @var{to}, const char *restrict @var{from}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strcat} function is similar to @code{strcpy}, except that the characters from @var{from} are concatenated or appended to the end of @var{to}, instead of overwriting it. That is, the first character from @@ -794,6 +821,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wcscat (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcscat} function is similar to @code{wcscpy}, except that the characters from @var{wfrom} are concatenated or appended to the end of @var{wto}, instead of overwriting it. That is, the first character from @@ -942,6 +970,7 @@ @comment string.h @comment ISO @deftypefun {char *} strncat (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is like @code{strcat} except that not more than @var{size} characters from @var{from} are appended to the end of @var{to}. A single null character is also always appended to @var{to}, so the total @@ -955,8 +984,8 @@ char * strncat (char *to, const char *from, size_t size) @{ - to[strlen (to) + size] = '\0'; - strncpy (to + strlen (to), from, size); + memcpy (to + strlen (to), from, strnlen (from, size)); + to[strlen (to) + strnlen (from, size)] = '\0'; return to; @} @end group @@ -968,6 +997,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wcsncat (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is like @code{wcscat} except that not more than @var{size} characters from @var{from} are appended to the end of @var{to}. A single null character is also always appended to @var{to}, so the total @@ -982,8 +1012,8 @@ wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size) @{ - wto[wcslen (to) + size] = L'\0'; - wcsncpy (wto + wcslen (wto), wfrom, size); + memcpy (wto + wcslen (wto), wfrom, wcsnlen (wfrom, size) * sizeof (wchar_t)); + wto[wcslen (to) + wcsnlen (wfrom, size)] = '\0'; return wto; @} @end group @@ -1012,6 +1042,7 @@ @comment string.h @comment BSD @deftypefun void bcopy (const void *@var{from}, void *@var{to}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is a partially obsolete alternative for @code{memmove}, derived from BSD. Note that it is not quite equivalent to @code{memmove}, because the arguments are not in the same order and there is no return value. @@ -1020,6 +1051,7 @@ @comment string.h @comment BSD @deftypefun void bzero (void *@var{block}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is a partially obsolete alternative for @code{memset}, derived from BSD. Note that it is not as general as @code{memset}, because the only value it can store is zero. @@ -1055,6 +1087,7 @@ @comment string.h @comment ISO @deftypefun int memcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{memcmp} compares the @var{size} bytes of memory beginning at @var{a1} against the @var{size} bytes of memory beginning at @var{a2}. The value returned has the same sign as the difference @@ -1065,9 +1098,10 @@ @code{0}. @end deftypefun -@comment wcjar.h +@comment wchar.h @comment ISO @deftypefun int wmemcmp (const wchar_t *@var{a1}, const wchar_t *@var{a2}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{wmemcmp} compares the @var{size} wide characters beginning at @var{a1} against the @var{size} wide characters beginning at @var{a2}. The value returned is smaller than or larger than zero @@ -1120,6 +1154,7 @@ @comment string.h @comment ISO @deftypefun int strcmp (const char *@var{s1}, const char *@var{s2}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strcmp} function compares the string @var{s1} against @var{s2}, returning a value that has the same sign as the difference between the first differing pair of characters (interpreted as @@ -1139,6 +1174,7 @@ @comment wchar.h @comment ISO @deftypefun int wcscmp (const wchar_t *@var{ws1}, const wchar_t *@var{ws2}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcscmp} function compares the wide character string @var{ws1} against @var{ws2}. The value returned is smaller than or larger than zero @@ -1159,6 +1195,11 @@ @comment string.h @comment BSD @deftypefun int strcasecmp (const char *@var{s1}, const char *@var{s2}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c Although this calls tolower multiple times, it's a macro, and +@c strcasecmp is optimized so that the locale pointer is read only once. +@c There are some asm implementations too, for which the single-read +@c from locale TLS pointers also applies. This function is like @code{strcmp}, except that differences in case are ignored. How uppercase and lowercase characters are related is determined by the currently selected locale. In the standard @code{"C"} @@ -1171,7 +1212,10 @@ @comment wchar.h @comment GNU -@deftypefun int wcscasecmp (const wchar_t *@var{ws1}, const wchar_T *@var{ws2}) +@deftypefun int wcscasecmp (const wchar_t *@var{ws1}, const wchar_t *@var{ws2}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c Since towlower is not a macro, the locale object may be read multiple +@c times. This function is like @code{wcscmp}, except that differences in case are ignored. How uppercase and lowercase characters are related is determined by the currently selected locale. In the standard @code{"C"} @@ -1185,6 +1229,7 @@ @comment string.h @comment ISO @deftypefun int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is the similar to @code{strcmp}, except that no more than @var{size} characters are compared. In other words, if the two strings are the same in their first @var{size} characters, the @@ -1194,6 +1239,7 @@ @comment wchar.h @comment ISO @deftypefun int wcsncmp (const wchar_t *@var{ws1}, const wchar_t *@var{ws2}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function is the similar to @code{wcscmp}, except that no more than @var{size} wide characters are compared. In other words, if the two strings are the same in their first @var{size} wide characters, the @@ -1203,6 +1249,7 @@ @comment string.h @comment BSD @deftypefun int strncasecmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is like @code{strncmp}, except that differences in case are ignored. Like @code{strcasecmp}, it is locale dependent how uppercase and lowercase characters are related. @@ -1214,6 +1261,7 @@ @comment wchar.h @comment GNU @deftypefun int wcsncasecmp (const wchar_t *@var{ws1}, const wchar_t *@var{s2}, size_t @var{n}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} This function is like @code{wcsncmp}, except that differences in case are ignored. Like @code{wcscasecmp}, it is locale dependent how uppercase and lowercase characters are related. @@ -1247,6 +1295,8 @@ @comment string.h @comment GNU @deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c Calls isdigit multiple times, locale may change in between. The @code{strverscmp} function compares the string @var{s1} against @var{s2}, considering them as holding indices/version numbers. The return value follows the same conventions as found in the @@ -1258,7 +1308,7 @@ mode, where each sequence of digits is taken as a whole. If we reach the end of these two parts without noticing a difference, we return to the standard comparison mode. There are two types of numeric parts: -"integral" and "fractional" (those begin with a '0'). The types +"integral" and "fractional" (those begin with a '0'). The types of the numeric parts affect the way we sort them: @itemize @bullet @@ -1297,6 +1347,7 @@ @comment string.h @comment BSD @deftypefun int bcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is an obsolete alias for @code{memcmp}, derived from BSD. @end deftypefun @@ -1343,6 +1394,9 @@ @comment string.h @comment ISO @deftypefun int strcoll (const char *@var{s1}, const char *@var{s2}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c Calls strcoll_l with the current locale, which dereferences only the +@c LC_COLLATE data pointer. The @code{strcoll} function is similar to @code{strcmp} but uses the collating sequence of the current locale for collation (the @code{LC_COLLATE} locale). @@ -1351,6 +1405,8 @@ @comment wchar.h @comment ISO @deftypefun int wcscoll (const wchar_t *@var{ws1}, const wchar_t *@var{ws2}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c Same as strcoll, but calling wcscoll_l. The @code{wcscoll} function is similar to @code{wcscmp} but uses the collating sequence of the current locale for collation (the @code{LC_COLLATE} locale). @@ -1370,7 +1426,7 @@ compare_elements (const void *v1, const void *v2) @{ char * const *p1 = v1; - char * const *p1 = v2; + char * const *p2 = v2; return strcoll (*p1, *p2); @} @@ -1391,6 +1447,7 @@ @comment string.h @comment ISO @deftypefun size_t strxfrm (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The function @code{strxfrm} transforms the string @var{from} using the collation transformation determined by the locale currently selected for collation, and stores the transformed string in the array @var{to}. Up @@ -1420,6 +1477,7 @@ @comment wchar.h @comment ISO @deftypefun size_t wcsxfrm (wchar_t *restrict @var{wto}, const wchar_t *@var{wfrom}, size_t @var{size}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The function @code{wcsxfrm} transforms wide character string @var{wfrom} using the collation transformation determined by the locale currently selected for collation, and stores the transformed string in the array @@ -1514,8 +1572,8 @@ @} /* @r{Sort @code{temp_array} by comparing transformed strings.} */ - qsort (temp_array, sizeof (struct sorter), - nstrings, compare_elements); + qsort (temp_array, nstrings, + sizeof (struct sorter), compare_elements); /* @r{Put the elements back in the permanent array} @r{in their sorted order.} */ @@ -1579,6 +1637,7 @@ @comment string.h @comment ISO @deftypefun {void *} memchr (const void *@var{block}, int @var{c}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function finds the first occurrence of the byte @var{c} (converted to an @code{unsigned char}) in the initial @var{size} bytes of the object beginning at @var{block}. The return value is a pointer to the @@ -1588,6 +1647,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wmemchr (const wchar_t *@var{block}, wchar_t @var{wc}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function finds the first occurrence of the wide character @var{wc} in the initial @var{size} wide characters of the object beginning at @var{block}. The return value is a pointer to the located wide @@ -1597,6 +1657,7 @@ @comment string.h @comment GNU @deftypefun {void *} rawmemchr (const void *@var{block}, int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Often the @code{memchr} function is used with the knowledge that the byte @var{c} is available in the memory block specified by the parameters. But this means that the @var{size} parameter is not really @@ -1627,6 +1688,7 @@ @comment string.h @comment GNU @deftypefun {void *} memrchr (const void *@var{block}, int @var{c}, size_t @var{size}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{memrchr} is like @code{memchr}, except that it searches backwards from the end of the block defined by @var{block} and @var{size} (instead of forwards from the front). @@ -1637,6 +1699,7 @@ @comment string.h @comment ISO @deftypefun {char *} strchr (const char *@var{string}, int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strchr} function finds the first occurrence of the character @var{c} (converted to a @code{char}) in the null-terminated string beginning at @var{string}. The return value is a pointer to the located @@ -1663,6 +1726,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wcschr (const wchar_t *@var{wstring}, int @var{wc}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcschr} function finds the first occurrence of the wide character @var{wc} in the null-terminated wide character string beginning at @var{wstring}. The return value is a pointer to the @@ -1678,6 +1742,7 @@ @comment string.h @comment GNU @deftypefun {char *} strchrnul (const char *@var{string}, int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{strchrnul} is the same as @code{strchr} except that if it does not find the character, it returns a pointer to string's terminating null character rather than a null pointer. @@ -1688,6 +1753,7 @@ @comment wchar.h @comment GNU @deftypefun {wchar_t *} wcschrnul (const wchar_t *@var{wstring}, wchar_t @var{wc}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{wcschrnul} is the same as @code{wcschr} except that if it does not find the wide character, it returns a pointer to wide character string's terminating null wide character rather than a null pointer. @@ -1723,6 +1789,7 @@ @comment string.h @comment ISO @deftypefun {char *} strrchr (const char *@var{string}, int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{strrchr} is like @code{strchr}, except that it searches backwards from the end of the string @var{string} (instead of forwards from the front). @@ -1737,6 +1804,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wcsrchr (const wchar_t *@var{wstring}, wchar_t @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The function @code{wcsrchr} is like @code{wcschr}, except that it searches backwards from the end of the string @var{wstring} (instead of forwards from the front). @@ -1745,6 +1813,7 @@ @comment string.h @comment ISO @deftypefun {char *} strstr (const char *@var{haystack}, const char *@var{needle}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{strchr}, except that it searches @var{haystack} for a substring @var{needle} rather than just a single character. It returns a pointer into the string @var{haystack} that is the first @@ -1763,6 +1832,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wcsstr (const wchar_t *@var{haystack}, const wchar_t *@var{needle}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{wcschr}, except that it searches @var{haystack} for a substring @var{needle} rather than just a single wide character. It returns a pointer into the string @var{haystack} that is the first wide @@ -1773,7 +1843,8 @@ @comment wchar.h @comment XPG @deftypefun {wchar_t *} wcswcs (const wchar_t *@var{haystack}, const wchar_t *@var{needle}) -@code{wcswcs} is an deprecated alias for @code{wcsstr}. This is the +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@code{wcswcs} is a deprecated alias for @code{wcsstr}. This is the name originally used in the X/Open Portability Guide before the @w{Amendment 1} to @w{ISO C90} was published. @end deftypefun @@ -1782,6 +1853,9 @@ @comment string.h @comment GNU @deftypefun {char *} strcasestr (const char *@var{haystack}, const char *@var{needle}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c There may be multiple calls of strncasecmp, each accessing the locale +@c object independently. This is like @code{strstr}, except that it ignores case in searching for the substring. Like @code{strcasecmp}, it is locale dependent how uppercase and lowercase characters are related. @@ -1800,6 +1874,7 @@ @comment string.h @comment GNU @deftypefun {void *} memmem (const void *@var{haystack}, size_t @var{haystack-len},@*const void *@var{needle}, size_t @var{needle-len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This is like @code{strstr}, but @var{needle} and @var{haystack} are byte arrays rather than null-terminated strings. @var{needle-len} is the length of @var{needle} and @var{haystack-len} is the length of @@ -1811,6 +1886,7 @@ @comment string.h @comment ISO @deftypefun size_t strspn (const char *@var{string}, const char *@var{skipset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strspn} (``string span'') function returns the length of the initial substring of @var{string} that consists entirely of characters that are members of the set specified by the string @var{skipset}. The order @@ -1831,6 +1907,7 @@ @comment wchar.h @comment ISO @deftypefun size_t wcsspn (const wchar_t *@var{wstring}, const wchar_t *@var{skipset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcsspn} (``wide character string span'') function returns the length of the initial substring of @var{wstring} that consists entirely of wide characters that are members of the set specified by the string @@ -1841,6 +1918,7 @@ @comment string.h @comment ISO @deftypefun size_t strcspn (const char *@var{string}, const char *@var{stopset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strcspn} (``string complement span'') function returns the length of the initial substring of @var{string} that consists entirely of characters that are @emph{not} members of the set specified by the string @var{stopset}. @@ -1862,6 +1940,7 @@ @comment wchar.h @comment ISO @deftypefun size_t wcscspn (const wchar_t *@var{wstring}, const wchar_t *@var{stopset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcscspn} (``wide character string complement span'') function returns the length of the initial substring of @var{wstring} that consists entirely of wide characters that are @emph{not} members of the @@ -1873,6 +1952,7 @@ @comment string.h @comment ISO @deftypefun {char *} strpbrk (const char *@var{string}, const char *@var{stopset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{strpbrk} (``string pointer break'') function is related to @code{strcspn}, except that it returns a pointer to the first character in @var{string} that is a member of the set @var{stopset} instead of the @@ -1897,6 +1977,7 @@ @comment wchar.h @comment ISO @deftypefun {wchar_t *} wcspbrk (const wchar_t *@var{wstring}, const wchar_t *@var{stopset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{wcspbrk} (``wide character string pointer break'') function is related to @code{wcscspn}, except that it returns a pointer to the first wide character in @var{wstring} that is a member of the set @@ -1910,6 +1991,7 @@ @comment string.h @comment BSD @deftypefun {char *} index (const char *@var{string}, int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{index} is another name for @code{strchr}; they are exactly the same. New code should always use @code{strchr} since this name is defined in @w{ISO C} while @code{index} is a BSD invention which never was available @@ -1919,6 +2001,7 @@ @comment string.h @comment BSD @deftypefun {char *} rindex (const char *@var{string}, int @var{c}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{rindex} is another name for @code{strrchr}; they are exactly the same. New code should always use @code{strrchr} since this name is defined in @w{ISO C} while @code{rindex} is a BSD invention which never was available @@ -1940,6 +2023,7 @@ @comment string.h @comment ISO @deftypefun {char *} strtok (char *restrict @var{newstring}, const char *restrict @var{delimiters}) +@safety{@prelim{}@mtunsafe{@mtasurace{:strtok}}@asunsafe{}@acsafe{}} A string can be split into tokens by making a series of calls to the function @code{strtok}. @@ -1978,7 +2062,8 @@ @comment wchar.h @comment ISO -@deftypefun {wchar_t *} wcstok (wchar_t *@var{newstring}, const char *@var{delimiters}) +@deftypefun {wchar_t *} wcstok (wchar_t *@var{newstring}, const wchar_t *@var{delimiters}, wchar_t **@var{save_ptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} A string can be split into tokens by making a series of calls to the function @code{wcstok}. @@ -1986,11 +2071,8 @@ the first call only. The @code{wcstok} function uses this to set up some internal state information. Subsequent calls to get additional tokens from the same wide character string are indicated by passing a -null pointer as the @var{newstring} argument. Calling @code{wcstok} -with another non-null @var{newstring} argument reinitializes the state -information. It is guaranteed that no other library function ever calls -@code{wcstok} behind your back (which would mess up this internal state -information). +null pointer as the @var{newstring} argument, which causes the pointer +previously stored in @var{save_ptr} to be used instead. The @var{delimiters} argument is a wide character string that specifies a set of delimiters that may surround the token being extracted. All @@ -1999,8 +2081,10 @@ delimiters marks the beginning of the next token. The end of the token is found by looking for the next wide character that is a member of the delimiter set. This wide character in the original wide character -string @var{newstring} is overwritten by a null wide character, and the -pointer to the beginning of the token in @var{newstring} is returned. +string @var{newstring} is overwritten by a null wide character, the +pointer past the overwritten wide character is saved in @var{save_ptr}, +and the pointer to the beginning of the token in @var{newstring} is +returned. On the next call to @code{wcstok}, the searching begins at the next wide character beyond the one that marked the end of the previous token. @@ -2010,11 +2094,6 @@ If the end of the wide character string @var{newstring} is reached, or if the remainder of string consists only of delimiter wide characters, @code{wcstok} returns a null pointer. - -Note that ``character'' is here used in the sense of byte. In a string -using a multibyte character encoding (abstract) character consisting of -more than one byte are not treated as an entity. Each byte is treated -separately. The function is not locale-dependent. @end deftypefun @strong{Warning:} Since @code{strtok} and @code{wcstok} alter the string @@ -2039,7 +2118,7 @@ structure, then it is error-prone to modify the data structure temporarily. -The functions @code{strtok} and @code{wcstok} are not reentrant. +The function @code{strtok} is not reentrant, whereas @code{wcstok} is. @xref{Nonreentrancy}, for a discussion of where and why reentrancy is important. @@ -2075,13 +2154,15 @@ @comment string.h @comment POSIX @deftypefun {char *} strtok_r (char *@var{newstring}, const char *@var{delimiters}, char **@var{save_ptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Just like @code{strtok}, this function splits the string into several tokens which can be accessed by successive calls to @code{strtok_r}. -The difference is that the information about the next token is stored in -the space pointed to by the third argument, @var{save_ptr}, which is a -pointer to a string pointer. Calling @code{strtok_r} with a null -pointer for @var{newstring} and leaving @var{save_ptr} between the calls -unchanged does the job without hindering reentrancy. +The difference is that, as in @code{wcstok}, the information about the +next token is stored in the space pointed to by the third argument, +@var{save_ptr}, which is a pointer to a string pointer. Calling +@code{strtok_r} with a null pointer for @var{newstring} and leaving +@var{save_ptr} between the calls unchanged does the job without +hindering reentrancy. This function is defined in POSIX.1 and can be found on many systems which support multi-threading. @@ -2090,6 +2171,7 @@ @comment string.h @comment BSD @deftypefun {char *} strsep (char **@var{string_ptr}, const char *@var{delimiter}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function has a similar functionality as @code{strtok_r} with the @var{newstring} argument replaced by the @var{save_ptr} argument. The initialization of the moving pointer has to be done by the user. @@ -2141,6 +2223,7 @@ @comment string.h @comment GNU @deftypefun {char *} basename (const char *@var{filename}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The GNU version of the @code{basename} function returns the last component of the path in @var{filename}. This function is the preferred usage, since it does not modify the argument, @var{filename}, and @@ -2175,8 +2258,9 @@ @comment libgen.h @comment XPG -@deftypefun {char *} basename (char *@var{path}) -This is the standard XPG defined @code{basename}. It is similar in +@deftypefun {char *} basename (const char *@var{path}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +This is the standard XPG defined @code{basename}. It is similar in spirit to the GNU version, but may modify the @var{path} by removing trailing '/' characters. If the @var{path} is made up entirely of '/' characters, then "/" will be returned. Also, if @var{path} is @@ -2211,6 +2295,7 @@ @comment libgen.h @comment XPG @deftypefun {char *} dirname (char *@var{path}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{dirname} function is the compliment to the XPG version of @code{basename}. It returns the parent directory of the file specified by @var{path}. If @var{path} is @code{NULL}, an empty string, or @@ -2233,6 +2318,8 @@ @comment string.h @comment GNU @deftypefun {char *} strfry (char *@var{string}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Calls initstate_r, time, getpid, strlen, and random_r. @code{strfry} creates a pseudorandom anagram of a string, replacing the input with the anagram in place. For each position in the string, @@ -2268,6 +2355,7 @@ @comment string.h @comment GNU @deftypefun {void *} memfrob (void *@var{mem}, size_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{memfrob} transforms (frobnicates) each byte of the data structure at @var{mem}, which is @var{length} bytes long, by bitwise exclusive @@ -2291,13 +2379,14 @@ To store or transfer binary data in environments which only support text one has to encode the binary data by mapping the input bytes to -characters in the range allowed for storing or transfering. SVID +characters in the range allowed for storing or transferring. SVID systems (and nowadays XPG compliant systems) provide minimal support for this task. @comment stdlib.h @comment XPG @deftypefun {char *} l64a (long int @var{n}) +@safety{@prelim{}@mtunsafe{@mtasurace{:l64a}}@asunsafe{}@acsafe{}} This function encodes a 32-bit input value using characters from the basic character set. It returns a pointer to a 7 character buffer which contains an encoded version of @var{n}. To encode a series of bytes the @@ -2373,6 +2462,7 @@ @comment stdlib.h @comment XPG @deftypefun {long int} a64l (const char *@var{string}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The parameter @var{string} should contain a string which was produced by a call to @code{l64a}. The function processes at least 6 characters of this string, and decodes the characters it finds according to the table @@ -2459,6 +2549,7 @@ @comment argz.h @comment GNU @deftypefun {error_t} argz_create (char *const @var{argv}[], char **@var{argz}, size_t *@var{argz_len}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{argz_create} function converts the Unix-style argument vector @var{argv} (a vector of pointers to normal C strings, terminated by @code{(char *)0}; @pxref{Program Arguments}) into an argz vector with @@ -2468,6 +2559,7 @@ @comment argz.h @comment GNU @deftypefun {error_t} argz_create_sep (const char *@var{string}, int @var{sep}, char **@var{argz}, size_t *@var{argz_len}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{argz_create_sep} function converts the null-terminated string @var{string} into an argz vector (returned in @var{argz} and @var{argz_len}) by splitting it into elements at every occurrence of the @@ -2477,13 +2569,15 @@ @comment argz.h @comment GNU @deftypefun {size_t} argz_count (const char *@var{argz}, size_t @var{arg_len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} Returns the number of elements in the argz vector @var{argz} and @var{argz_len}. @end deftypefun @comment argz.h @comment GNU -@deftypefun {void} argz_extract (char *@var{argz}, size_t @var{argz_len}, char **@var{argv}) +@deftypefun {void} argz_extract (const char *@var{argz}, size_t @var{argz_len}, char **@var{argv}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{argz_extract} function converts the argz vector @var{argz} and @var{argz_len} into a Unix-style argument vector stored in @var{argv}, by putting pointers to every element in @var{argz} into successive @@ -2501,6 +2595,7 @@ @comment argz.h @comment GNU @deftypefun {void} argz_stringify (char *@var{argz}, size_t @var{len}, int @var{sep}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{argz_stringify} converts @var{argz} into a normal string with the elements separated by the character @var{sep}, by replacing each @code{'\0'} inside @var{argz} (except the last one, which terminates the @@ -2511,6 +2606,8 @@ @comment argz.h @comment GNU @deftypefun {error_t} argz_add (char **@var{argz}, size_t *@var{argz_len}, const char *@var{str}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c Calls strlen and argz_append. The @code{argz_add} function adds the string @var{str} to the end of the argz vector @code{*@var{argz}}, and updates @code{*@var{argz}} and @code{*@var{argz_len}} accordingly. @@ -2519,6 +2616,7 @@ @comment argz.h @comment GNU @deftypefun {error_t} argz_add_sep (char **@var{argz}, size_t *@var{argz_len}, const char *@var{str}, int @var{delim}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{argz_add_sep} function is similar to @code{argz_add}, but @var{str} is split into separate elements in the result at occurrences of the character @var{delim}. This is useful, for instance, for @@ -2529,6 +2627,7 @@ @comment argz.h @comment GNU @deftypefun {error_t} argz_append (char **@var{argz}, size_t *@var{argz_len}, const char *@var{buf}, size_t @var{buf_len}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{argz_append} function appends @var{buf_len} bytes starting at @var{buf} to the argz vector @code{*@var{argz}}, reallocating @code{*@var{argz}} to accommodate it, and adding @var{buf_len} to @@ -2538,6 +2637,8 @@ @comment argz.h @comment GNU @deftypefun {void} argz_delete (char **@var{argz}, size_t *@var{argz_len}, char *@var{entry}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c Calls free if no argument is left. If @var{entry} points to the beginning of one of the elements in the argz vector @code{*@var{argz}}, the @code{argz_delete} function will remove this entry and reallocate @code{*@var{argz}}, modifying @@ -2549,6 +2650,8 @@ @comment argz.h @comment GNU @deftypefun {error_t} argz_insert (char **@var{argz}, size_t *@var{argz_len}, char *@var{before}, const char *@var{entry}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c Calls argz_add or realloc and memmove. The @code{argz_insert} function inserts the string @var{entry} into the argz vector @code{*@var{argz}} at a point just before the existing element pointed to by @var{before}, reallocating @code{*@var{argz}} and @@ -2561,7 +2664,8 @@ @comment argz.h @comment GNU -@deftypefun {char *} argz_next (char *@var{argz}, size_t @var{argz_len}, const char *@var{entry}) +@deftypefun {char *} argz_next (const char *@var{argz}, size_t @var{argz_len}, const char *@var{entry}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{argz_next} function provides a convenient way of iterating over the elements in the argz vector @var{argz}. It returns a pointer to the next element in @var{argz} after the element @var{entry}, or @@ -2595,6 +2699,7 @@ @comment argz.h @comment GNU @deftypefun error_t argz_replace (@w{char **@var{argz}, size_t *@var{argz_len}}, @w{const char *@var{str}, const char *@var{with}}, @w{unsigned *@var{replace_count}}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} Replace any occurrences of the string @var{str} in @var{argz} with @var{with}, reallocating @var{argz} as necessary. If @var{replace_count} is non-zero, @code{*@var{replace_count}} will be @@ -2630,6 +2735,7 @@ @comment envz.h @comment GNU @deftypefun {char *} envz_entry (const char *@var{envz}, size_t @var{envz_len}, const char *@var{name}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{envz_entry} function finds the entry in @var{envz} with the name @var{name}, and returns a pointer to the whole entry---that is, the argz element which begins with @var{name} followed by a @code{'='} character. If @@ -2639,6 +2745,7 @@ @comment envz.h @comment GNU @deftypefun {char *} envz_get (const char *@var{envz}, size_t @var{envz_len}, const char *@var{name}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{envz_get} function finds the entry in @var{envz} with the name @var{name} (like @code{envz_entry}), and returns a pointer to the value portion of that entry (following the @code{'='}). If there is no entry with @@ -2648,6 +2755,9 @@ @comment envz.h @comment GNU @deftypefun {error_t} envz_add (char **@var{envz}, size_t *@var{envz_len}, const char *@var{name}, const char *@var{value}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +@c Calls envz_remove, which calls enz_entry and argz_delete, and then +@c argz_add or equivalent code that reallocs and appends name=value. The @code{envz_add} function adds an entry to @code{*@var{envz}} (updating @code{*@var{envz}} and @code{*@var{envz_len}}) with the name @var{name}, and value @var{value}. If an entry with the same name @@ -2659,6 +2769,7 @@ @comment envz.h @comment GNU @deftypefun {error_t} envz_merge (char **@var{envz}, size_t *@var{envz_len}, const char *@var{envz2}, size_t @var{envz2_len}, int @var{override}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} The @code{envz_merge} function adds each entry in @var{envz2} to @var{envz}, as if with @code{envz_add}, updating @code{*@var{envz}} and @code{*@var{envz_len}}. If @var{override} is true, then values in @var{envz2} @@ -2672,6 +2783,10 @@ @comment envz.h @comment GNU @deftypefun {void} envz_strip (char **@var{envz}, size_t *@var{envz_len}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The @code{envz_strip} function removes any null entries from @var{envz}, updating @code{*@var{envz}} and @code{*@var{envz_len}}. @end deftypefun + +@c FIXME this are undocumented: +@c strcasecmp_l @safety{@mtsafe{}@assafe{}@acsafe{}} see strcasecmp diff -urN glibc-2.17-c758a686/manual/summary.awk glibc-2.17-c758a686/manual/summary.awk --- glibc-2.17-c758a686/manual/summary.awk 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/summary.awk 2014-09-12 16:10:06.042792724 -0400 @@ -1,5 +1,5 @@ # awk script to create summary.texinfo from the library texinfo files. -# Copyright (C) 1992, 1993, 1997, 2001 Free Software Foundation, Inc. +# Copyright (C) 1992-2014 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 diff -urN glibc-2.17-c758a686/manual/sysinfo.texi glibc-2.17-c758a686/manual/sysinfo.texi --- glibc-2.17-c758a686/manual/sysinfo.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/sysinfo.texi 2014-09-12 16:10:06.048792709 -0400 @@ -91,6 +91,9 @@ @comment unistd.h @comment BSD @deftypefun int gethostname (char *@var{name}, size_t @var{size}) +@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. This function returns the host name of the system on which it is called, in the array @var{name}. The @var{size} argument specifies the size of this array, in bytes. Note that this is @emph{not} the DNS hostname. @@ -121,6 +124,9 @@ @comment unistd.h @comment BSD @deftypefun int sethostname (const char *@var{name}, size_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall on unix; implemented in terms of hurd_set_host_config +@c on hurd. The @code{sethostname} function sets the host name of the system that calls it to @var{name}, a string with length @var{length}. Only privileged processes are permitted to do this. @@ -145,6 +151,8 @@ @comment unistd.h @comment ??? @deftypefun int getdomainnname (char *@var{name}, size_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Syscalls uname, then strlen and memcpy. @cindex NIS domain name @cindex YP domain name @@ -159,6 +167,8 @@ @comment unistd.h @comment ??? @deftypefun int setdomainname (const char *@var{name}, size_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall. @cindex NIS domain name @cindex YP domain name @@ -173,6 +183,10 @@ @comment unistd.h @comment BSD @deftypefun {long int} gethostid (void) +@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 +@c gethostname and gethostbyname_r to use the h_addr. This function returns the ``host ID'' of the machine the program is running on. By convention, this is usually the primary Internet IP address of that machine, converted to a @w{@code{long int}}. However, on some @@ -190,6 +204,7 @@ @comment unistd.h @comment BSD @deftypefun int sethostid (long int @var{id}) +@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 it happens just once, at system boot time. @@ -226,7 +241,7 @@ As a bonus, @code{uname} also gives some information identifying the particular system your program is running on. This is the same information -which you can get with functions targetted to this purpose described in +which you can get with functions targeted to this purpose described in @ref{Host Identification}. @@ -296,6 +311,10 @@ @comment sys/utsname.h @comment POSIX.1 @deftypefun int uname (struct utsname *@var{info}) +@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 +@c proc_uname and then gethostname. The @code{uname} function fills in the structure pointed to by @var{info} with information about the operating system and host machine. A non-negative value indicates that the data was successfully stored. @@ -471,6 +490,12 @@ @comment fstab.h @comment BSD @deftypefun int setfsent (void) +@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 +@c malloc dup @ascuheap @acsmem +@c rewind dup @asucorrupt @acucorrupt [no @aculock] +@c setmntent dup @ascuheap @asulock @acsmem @acsfd @aculock This function makes sure that the internal read pointer for the @file{fstab} file is at the beginning of the file. This is done by either opening the file or resetting the read pointer. @@ -486,6 +511,9 @@ @comment fstab.h @comment BSD @deftypefun void endfsent (void) +@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 This function makes sure that all resources acquired by a prior call to @code{setfsent} (explicitly or implicitly by calling @code{getfsent}) are freed. @@ -494,6 +522,13 @@ @comment fstab.h @comment BSD @deftypefun {struct fstab *} getfsent (void) +@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 +@c fstab_fetch @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem +@c getmntent_r dup @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem +@c fstab_convert @mtasurace:fsent +@c hasmntopt dup ok This function returns the next entry of the @file{fstab} file. If this is the first call to any of the functions handling @file{fstab} since program start or the last call of @code{endfsent}, the file will be @@ -508,6 +543,12 @@ @comment fstab.h @comment BSD @deftypefun {struct fstab *} getfsspec (const char *@var{name}) +@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 +@c fstab_fetch dup @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem +@c strcmp dup ok +@c fstab_convert dup @mtasurace:fsent This function returns the next entry of the @file{fstab} file which has a string equal to @var{name} pointed to by the @code{fs_spec} element. Since there is normally exactly one entry for each special device it @@ -525,6 +566,12 @@ @comment fstab.h @comment BSD @deftypefun {struct fstab *} getfsfile (const char *@var{name}) +@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 +@c fstab_fetch dup @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem +@c strcmp dup ok +@c fstab_convert dup @mtasurace:fsent This function returns the next entry of the @file{fstab} file which has a string equal to @var{name} pointed to by the @code{fs_file} element. Since there is normally exactly one entry for each mount point it @@ -640,6 +687,13 @@ @comment mntent.h @comment BSD @deftypefun {FILE *} setmntent (const char *@var{file}, const char *@var{mode}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} +@c setmntent @ascuheap @asulock @acsmem @acsfd @aculock +@c strlen dup ok +@c mempcpy dup ok +@c memcpy dup ok +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fsetlocking dup ok [no @mtasurace:stream @asulock: exclusive stream] The @code{setmntent} function prepares the file named @var{FILE} which must be in the format of a @file{fstab} and @file{mtab} file for the upcoming processing through the other functions of the family. The @@ -655,6 +709,9 @@ @comment mntent.h @comment BSD @deftypefun int endmntent (FILE *@var{stream}) +@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 This function takes for the @var{stream} parameter a file handle which previously was returned from the @code{setmntent} call. @code{endmntent} closes the stream and frees all resources. @@ -666,6 +723,12 @@ @comment mntent.h @comment BSD @deftypefun {struct mntent *} getmntent (FILE *@var{stream}) +@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 +@c allocate @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c getmntent_r dup @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem The @code{getmntent} function takes as the parameter a file handle previously returned by successful call to @code{setmntent}. It returns a pointer to a static variable of type @code{struct mntent} which is @@ -691,7 +754,17 @@ @comment mntent.h @comment BSD -@deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mentent *@var{result}, char *@var{buffer}, int @var{bufsize}) +@deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mntent *@var{result}, char *@var{buffer}, int @var{bufsize}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c getmntent_r @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem +@c flockfile dup @aculock +@c fgets_unlocked dup @asucorrupt @acucorrupt [locked, so no @mtsrace:stream] +@c funlockfile dup @aculock +@c strchr dup ok +@c strspn dup ok +@c strsep dup ok +@c decode_name ok +@c sscanf dup @mtslocale @ascuheap @acsmem The @code{getmntent_r} function is the reentrant variant of @code{getmntent}. It also returns the next entry from the file and returns a pointer. The actual variable the values are stored in is not @@ -717,6 +790,12 @@ @comment mntent.h @comment BSD @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt}) +@safety{@prelim{}@mtunsafe{@mtasurace{:stream} @mtslocale{}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +@c addmntent @mtasurace:stream @mtslocale @asucorrupt @acucorrupt +@c fseek dup @asucorrupt @acucorrupt [no @aculock] +@c encode_name ok +@c fprintf dup @mtslocale @asucorrupt @acucorrupt [no @ascuheap @acsmem, no @aculock] +@c fflush dup @asucorrupt @acucorrupt [no @aculock] The @code{addmntent} function allows adding a new entry to the file previously opened with @code{setmntent}. The new entries are always appended. I.e., even if the position of the file descriptor is not at @@ -740,6 +819,11 @@ @comment mntent.h @comment BSD @deftypefun {char *} hasmntopt (const struct mntent *@var{mnt}, const char *@var{opt}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c hasmntopt ok +@c strlen dup ok +@c strstr dup ok +@c strchr dup ok This function can be used to check whether the string pointed to by the @code{mnt_opts} element of the variable pointed to by @var{mnt} contains the option @var{opt}. If this is true a pointer to the beginning of the @@ -778,6 +862,8 @@ @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}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall. @code{mount} mounts or remounts a filesystem. The two operations are quite different and are merged rather unnaturally into this one function. @@ -982,6 +1068,8 @@ @comment sys/mount.h @comment GNU @deftypefun {int} umount2 (const char *@var{file}, int @var{flags}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall. @code{umount2} unmounts a filesystem. @@ -1047,6 +1135,8 @@ @comment sys/mount.h @comment SVID, GNU @deftypefun {int} umount (const char *@var{file}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall or wrapper for umount2. @code{umount} does the same thing as @code{umount2} with @var{flags} set to zeroes. It is more widely available than @code{umount2} but since it @@ -1062,11 +1152,13 @@ This section describes the @code{sysctl} function, which gets and sets a variety of system parameters. -The symbols used in this section are declared in the file @file{sysctl.h}. +The symbols used in this section are declared in the file @file{sys/sysctl.h}. -@comment 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}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct syscall, Linux only. @code{sysctl} gets or sets a specified system parameter. There are so many of these parameters that it is not practical to list them all here, @@ -1090,7 +1182,7 @@ a particular parameter, you specify a path through the structure in a way analogous to specifying the pathname of a file. Each component of the path is specified by an integer and each of these integers has a -macro defined for it by @file{sysctl.h}. @var{names} is the path, in +macro defined for it by @file{sys/sysctl.h}. @var{names} is the path, in the form of an array of integers. Each component of the path is one element of the array, in order. @var{nlen} is the number of components in the path. diff -urN glibc-2.17-c758a686/manual/syslog.texi glibc-2.17-c758a686/manual/syslog.texi --- glibc-2.17-c758a686/manual/syslog.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/syslog.texi 2014-09-12 16:10:06.044792719 -0400 @@ -147,6 +147,17 @@ @comment syslog.h @comment BSD @deftypefun void openlog (const char *@var{ident}, int @var{option}, int @var{facility}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} +@c openlog @asulock @aculock @acsfd +@c libc_lock_lock @asulock @aculock +@c openlog_internal @acsfd [always guarded by syslog_lock, so no race] +@c strncpy dup ok +@c socket dup @acsfd +@c fcntl dup ok +@c connect dup ok +@c close dup @acsfd +@c cancel_handler(NULL) @aculock +@c libc_lock_unlock @aculock @code{openlog} opens or reopens a connection to Syslog in preparation for submitting messages. @@ -275,7 +286,39 @@ @c syslog() is implemented as a call to vsyslog(). @comment syslog.h @comment BSD -@deftypefun void syslog (int @var{facility_priority}, char *@var{format}, @dots{}) +@deftypefun void syslog (int @var{facility_priority}, const char *@var{format}, @dots{}) +@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 +@c vsyslog_chk @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c syslog(INTERNALLOG) dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c open_memstream @ascuheap @acsmem +@c stpcpy dup ok +@c getpid dup ok +@c mempcpy dup ok +@c fsetlocking [no @mtasurace:stream @asulock for exclusive stream] +@c fprintf @mtslocale @ascuheap @acsmem [no @asucorrupt @aculock @acucorrupt on temp memstream] +@c time dup ok +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c strftime_l(C) dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c ftell dup ok [no @asucorrupt @aculock @acucorrupt on temp memstream] +@c fputs_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream] +@c putc_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream] +@c vfprintf/vfprintf_chk dup @mtslocale @ascuheap @acsmem [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream] +@c fclose dup @ascuheap @acsmem [no @asulock @aculock @acsfd on caller-locked memstream] +@c writev dup ok +@c libc_lock_lock dup @asulock @aculock +@c memset dup ok +@c sigemptyset dup ok +@c sigaction(SIGPIPE) dup @mtasusig:PIPE @acusig:PIPE +@c openlog_internal dup @acsfd +@c send dup ok +@c closelog_internal dup @acsfd +@c open dup @acsfd +@c dprintf dup ok +@c libc_lock_unlock @asulock @aculock +@c free dup @acsuheap @acsmem +@c va_end dup ok @code{syslog} submits a message to the Syslog facility. It does this by writing to the Unix domain socket @code{/dev/log}. @@ -403,7 +446,10 @@ @comment syslog.h @comment BSD -@deftypefun void vsyslog (int @var{facility_priority}, char *@var{format}, va_list @var{arglist}) +@deftypefun void vsyslog (int @var{facility_priority}, const char *@var{format}, va_list @var{arglist}) +@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 This is functionally identical to @code{syslog}, with the BSD style variable length argument. @@ -420,6 +466,13 @@ @comment syslog.h @comment BSD @deftypefun void closelog (void) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} +@c closelog @asulock @aculock @acsfd +@c libc_lock_lock @asulock @aculock +@c closelog_internal @acsfd [always guarded by syslog_lock, so no race] +@c close dup@acsfd +@c cancel_handler(NULL) @aculock +@c libc_lock_unlock @aculock @code{closelog} closes the current Syslog connection, if there is one. This includes closing the @file{/dev/log} socket, if it is open. @@ -450,6 +503,10 @@ @comment syslog.h @comment BSD @deftypefun int setlogmask (int @var{mask}) +@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, +@c at least for modifications. @code{setlogmask} sets a mask (the ``logmask'') that determines which future @code{syslog} calls shall be ignored. If a program has not diff -urN glibc-2.17-c758a686/manual/terminal.texi glibc-2.17-c758a686/manual/terminal.texi --- glibc-2.17-c758a686/manual/terminal.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/terminal.texi 2014-09-12 16:10:06.047792712 -0400 @@ -44,6 +44,9 @@ @comment unistd.h @comment POSIX.1 @deftypefun int isatty (int @var{filedes}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c isatty ok +@c tcgetattr dup ok This function returns @code{1} if @var{filedes} is a file descriptor associated with an open terminal device, and @math{0} otherwise. @end deftypefun @@ -55,6 +58,20 @@ @comment unistd.h @comment POSIX.1 @deftypefun {char *} ttyname (int @var{filedes}) +@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 +@c fstat dup ok +@c memcpy dup ok +@c getttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd +@c opendir @ascuheap @acsmem @acsfd +@c readdir ok [protected by exclusive access] +@c strcmp dup ok +@c free dup @asulock @aculock @acsfd @acsmem +@c malloc dup @asulock @aculock @acsfd @acsmem +@c closedir @ascuheap @acsmem @acsfd +@c mempcpy dup ok +@c stat dup ok If the file descriptor @var{filedes} is associated with a terminal device, the @code{ttyname} function returns a pointer to a statically-allocated, null-terminated string containing the file name of @@ -65,6 +82,18 @@ @comment unistd.h @comment POSIX.1 @deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} +@c ttyname_r @ascuheap @acsmem @acsfd +@c isatty dup ok +@c fstat dup ok +@c memcpy dup ok +@c getttyname_r @ascuheap @acsmem @acsfd +@c opendir @ascuheap @acsmem @acsfd +@c readdir ok [protected by exclusive access] +@c strcmp dup ok +@c closedir @ascuheap @acsmem @acsfd +@c stpncpy dup ok +@c stat dup ok The @code{ttyname_r} function is similar to the @code{ttyname} function except that it places its result into the user-specified buffer starting at @var{buf} with length @var{len}. @@ -264,6 +293,9 @@ @comment termios.h @comment POSIX.1 @deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p}) +@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. This function is used to examine the attributes of the terminal device with file descriptor @var{filedes}. The attributes are returned in the structure that @var{termios-p} points to. @@ -284,6 +316,9 @@ @comment termios.h @comment POSIX.1 @deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Converting the incoming termios data structure to the kernel format +@c does not ensure atomic or consistent reading. This function sets the attributes of the terminal device with file descriptor @var{filedes}. The new attributes are taken from the structure that @var{termios-p} points to. @@ -621,7 +656,7 @@ of characters, carriage return followed by linefeed. @end deftypevr -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro tcflag_t OXTABS If this bit is set, convert tab characters on output into the appropriate @@ -630,7 +665,7 @@ @gnulinuxsystems{} it is available as @code{XTABS}. @end deftypevr -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro tcflag_t ONOEOT If this bit is set, discard @kbd{C-d} characters (code @code{004}) on @@ -962,7 +997,7 @@ While this bit is set, all output is discarded. @xref{Other Special}. @end deftypevr -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro tcflag_t NOKERNINFO Setting this bit disables handling of the STATUS character. @@ -1016,6 +1051,10 @@ @comment termios.h @comment POSIX.1 @deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p}) +@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 +@c must ensure mutual exclusion on such non-opaque types. This function returns the output line speed stored in the structure @code{*@var{termios-p}}. @end deftypefun @@ -1023,6 +1062,7 @@ @comment termios.h @comment POSIX.1 @deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} This function returns the input line speed stored in the structure @code{*@var{termios-p}}. @end deftypefun @@ -1030,6 +1070,7 @@ @comment termios.h @comment POSIX.1 @deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@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} indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} @@ -1039,6 +1080,7 @@ @comment termios.h @comment POSIX.1 @deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@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} indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} @@ -1048,6 +1090,14 @@ @comment termios.h @comment BSD @deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed}) +@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 +@c termios object. + +@c cfsetspeed ok +@c cfsetispeed ok +@c cfsetospeed ok This function stores @var{speed} in @code{*@var{termios-p}} as both the input and output speeds. The normal return value is @math{0}; a value of @math{-1} indicates an error. If @var{speed} is not a speed, @@ -1625,6 +1675,10 @@ @comment termios.h @comment BSD @deftypefun void cfmakeraw (struct termios *@var{termios-p}) +@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 +@c object. This function provides an easy way to set up @code{*@var{termios-p}} for what has traditionally been called ``raw mode'' in BSD. This uses noncanonical input, and turns off most processing to give an unmodified @@ -1678,6 +1732,8 @@ @comment sgtty.h @comment BSD @deftypefun int gtty (int @var{filedes}, struct sgttyb *@var{attributes}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct ioctl, BSD only. This function gets the attributes of a terminal. @code{gtty} sets *@var{attributes} to describe the terminal attributes @@ -1686,7 +1742,9 @@ @comment sgtty.h @comment BSD -@deftypefun int stty (int @var{filedes}, struct sgttyb *@var{attributes}) +@deftypefun int stty (int @var{filedes}, const struct sgttyb *@var{attributes}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct ioctl, BSD only. This function sets the attributes of a terminal. @@ -1710,6 +1768,12 @@ @comment termios.h @comment POSIX.1 @deftypefun int tcsendbreak (int @var{filedes}, int @var{duration}) +@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 +@c setting and the latter clearing the break status. The BSD +@c implementation may leave the break enabled if cancelled, and threads +@c and signals may cause the break to be interrupted before requested. This function generates a break condition by transmitting a stream of zero bits on the terminal associated with the file descriptor @var{filedes}. The duration of the break is controlled by the @@ -1738,6 +1802,8 @@ @comment termios.h @comment POSIX.1 @deftypefun int tcdrain (int @var{filedes}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct ioctl. The @code{tcdrain} function waits until all queued output to the terminal @var{filedes} has been transmitted. @@ -1772,6 +1838,8 @@ @comment termios.h @comment POSIX.1 @deftypefun int tcflush (int @var{filedes}, int @var{queue}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Direct ioctl. The @code{tcflush} function is used to clear the input and/or output queues associated with the terminal file @var{filedes}. The @var{queue} argument specifies which queue(s) to clear, and can be one of the @@ -1822,6 +1890,11 @@ @comment termios.h @comment POSIX.1 @deftypefun int tcflow (int @var{filedes}, int @var{action}) +@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 +@c the c_cc character corresponding to the action; there's a window for +@c another thread to change the xon/xoff characters. The @code{tcflow} function is used to perform operations relating to XON/XOFF flow control on the terminal file specified by @var{filedes}. @@ -1931,6 +2004,14 @@ @comment stdlib.h @comment GNU @deftypefun int getpt (void) +@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 +@c the BSD implementation. The posix implementation opens the ptmx +@c device, checks with statfs that /dev/pts is a devpts or that /dev is +@c a devfs, and returns the fd; static variables devpts_mounted and +@c have_no_dev_ptmx are safely initialized so as to avoid repeated +@c tests. The @code{getpt} function returns a new file descriptor for the next available master pseudo-terminal. The normal return value from @code{getpt} is a non-negative integer file descriptor. In the case of @@ -1948,6 +2029,32 @@ @comment stdlib.h @comment SVID, XPG4.2 @deftypefun int grantpt (int @var{filedes}) +@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 +@c ptsname_internal dup ok (but this is Linux-only!) +@c memchr dup ok +@c realloc dup @acsuheap @acsmem +@c malloc dup @acsuheap @acsmem +@c free dup @acsuheap @acsmem +@c fcntl dup ok +@c getuid dup ok +@c chown dup ok +@c sysconf(_SC_GETGR_R_SIZE_MAX) ok +@c getgrnam_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c getgid dup ok +@c chmod dup ok +@c fork dup @aculock +@c [child] +@c setrlimit +@c dup2 +@c CLOSE_ALL_FDS +@c execle +@c _exit +@c waitpid dup ok +@c WIFEXITED dup ok +@c WEXITSTATUS dup ok +@c free dup @ascuheap @acsmem The @code{grantpt} function changes the ownership and access permission of the slave pseudo-terminal device corresponding to the master pseudo-terminal device associated with the file descriptor @@ -1985,6 +2092,13 @@ @comment stdlib.h @comment SVID, XPG4.2 @deftypefun int unlockpt (int @var{filedes}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} +@c unlockpt @ascuheap/bsd @acsmem @acsfd +@c /bsd +@c ptsname_r dup @ascuheap @acsmem @acsfd +@c revoke ok (syscall) +@c /linux +@c ioctl dup ok The @code{unlockpt} function unlocks the slave pseudo-terminal device corresponding to the master pseudo-terminal device associated with the file descriptor @var{filedes}. On many systems, the slave can only be @@ -2008,6 +2122,9 @@ @comment stdlib.h @comment SVID, XPG4.2 @deftypefun {char *} ptsname (int @var{filedes}) +@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 If the file descriptor @var{filedes} is associated with a master pseudo-terminal device, the @code{ptsname} function returns a pointer to a statically-allocated, null-terminated string containing the @@ -2018,6 +2135,37 @@ @comment stdlib.h @comment GNU @deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} +@c ptsname_r @ascuheap/bsd @acsmem @acsfd +@c /hurd +@c term_get_peername ok +@c strlen dup ok +@c memcpy dup ok +@c /bsd +@c isatty dup ok +@c strlen dup ok +@c ttyname_r dup @ascuheap @acsmem @acsfd +@c stat dup ok +@c /linux +@c ptsname_internal ok +@c isatty dup ok +@c ioctl dup ok +@c strlen dup ok +@c itoa_word dup ok +@c stpcpy dup ok +@c memcpy dup ok +@c fxstat64 dup ok +@c MASTER_P ok +@c major ok +@c gnu_dev_major ok +@c minor ok +@c gnu_dev_minor ok +@c minor dup ok +@c xstat64 dup ok +@c S_ISCHR dup ok +@c SLAVE_P ok +@c major dup ok +@c minor dup ok The @code{ptsname_r} function is similar to the @code{ptsname} function except that it places its result into the user-specified buffer starting at @var{buf} with length @var{len}. @@ -2083,6 +2231,22 @@ @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}) +@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 +@c grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c unlockpt dup @ascuheap/bsd @acsmem @acsfd +@c openpty:pts_name @acsuheap @acsmem @acsfd +@c ptsname_r dup @ascuheap/bsd @acsmem @acsfd +@c realloc dup @acsuheap @acsmem +@c malloc dup @acsuheap @acsmem +@c free dup @acsuheap @acsmem +@c open dup @acsfd +@c free dup @acsuheap @acsmem +@c tcsetattr dup ok +@c ioctl dup ok +@c strcpy dup ok +@c close dup @acsfd This function allocates and opens a pseudo-terminal pair, returning the file descriptor for the master in @var{*amaster}, and the file descriptor for the slave in @var{*aslave}. If the argument @var{name} @@ -2114,6 +2278,16 @@ @comment pty.h @comment BSD @deftypefun int forkpty (int *@var{amaster}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp}) +@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 +@c fork dup @aculock +@c close dup @acsfd +@c /child +@c close dup @acsfd +@c login_tty dup @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd +@c _exit dup ok +@c close dup @acsfd This function is similar to the @code{openpty} function, but in addition, forks a new process (@pxref{Creating a Process}) and makes the newly opened slave pseudo-terminal device the controlling terminal diff -urN glibc-2.17-c758a686/manual/texinfo.tex glibc-2.17-c758a686/manual/texinfo.tex --- glibc-2.17-c758a686/manual/texinfo.tex 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/texinfo.tex 2014-09-12 16:10:06.047792712 -0400 @@ -3,11 +3,11 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2012-01-19.16} +\def\texinfoversion{2014-05-05.10} % % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -% 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +% 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc. % % This texinfo.tex file is free software: you can redistribute it and/or % modify it under the terms of the GNU General Public License as @@ -24,13 +24,14 @@ % % As a special exception, when this file is read by TeX when processing % a Texinfo source document, you may use the result without -% restriction. (This has been our intent since Texinfo was invented.) +% restriction. This Exception is an additional permission under section 7 +% of the GNU General Public License, version 3 ("GPLv3"). % % Please try the latest version of texinfo.tex before submitting bug % reports; you can get the latest version from: -% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or -% ftp://tug.org/tex/texinfo.tex -% (and all CTAN mirrors, see http://www.ctan.org). +% http://ftp.gnu.org/gnu/texinfo/ (the Texinfo release area), or +% http://ftpmirror.gnu.org/texinfo/ (same, via a mirror), or +% http://www.gnu.org/software/texinfo/ (the Texinfo home page) % The texinfo.tex in any given distribution could well be out % of date, so if that's what you're using, please check. % @@ -280,9 +281,9 @@ \toks6=\expandafter{\prevsectiondefs}% \toks8=\expandafter{\lastcolordefs}% \mark{% - \the\toks0 \the\toks2 - \noexpand\or \the\toks4 \the\toks6 - \noexpand\else \the\toks8 + \the\toks0 \the\toks2 % 0: top marks (\last...) + \noexpand\or \the\toks4 \the\toks6 % 1: bottom marks (default, \prev...) + \noexpand\else \the\toks8 % 2: color marks }% } % \topmark doesn't work for the very first chapter (after the title @@ -321,10 +322,13 @@ % % Do this outside of the \shipout so @code etc. will be expanded in % the headline as they should be, not taken literally (outputting ''code). + \def\commmonheadfootline{\let\hsize=\pagewidth \texinfochars} + % \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi - \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% + \global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}% + % \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi - \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% + \global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}% % {% % Have to do this stuff outside the \shipout because we want it to @@ -594,7 +598,7 @@ \def\:{\spacefactor=1000 } % @* forces a line break. -\def\*{\hfil\break\hbox{}\ignorespaces} +\def\*{\unskip\hfil\break\hbox{}\ignorespaces} % @/ allows a line break. \let\/=\allowbreak @@ -887,7 +891,7 @@ \def\popthisfilestack{\errthisfilestackempty} \def\errthisfilestackempty{\errmessage{Internal error: the stack of filenames is empty.}} - +% \def\thisfile{} % @center line @@ -895,36 +899,46 @@ % \parseargdef\center{% \ifhmode - \let\next\centerH + \let\centersub\centerH \else - \let\next\centerV + \let\centersub\centerV \fi - \next{\hfil \ignorespaces#1\unskip \hfil}% + \centersub{\hfil \ignorespaces#1\unskip \hfil}% + \let\centersub\relax % don't let the definition persist, just in case } -\def\centerH#1{% - {% - \hfil\break - \advance\hsize by -\leftskip - \advance\hsize by -\rightskip - \line{#1}% - \break - }% +\def\centerH#1{{% + \hfil\break + \advance\hsize by -\leftskip + \advance\hsize by -\rightskip + \line{#1}% + \break +}} +% +\newcount\centerpenalty +\def\centerV#1{% + % The idea here is the same as in \startdefun, \cartouche, etc.: if + % @center is the first thing after a section heading, we need to wipe + % out the negative parskip inserted by \sectionheading, but still + % prevent a page break here. + \centerpenalty = \lastpenalty + \ifnum\centerpenalty>10000 \vskip\parskip \fi + \ifnum\centerpenalty>9999 \penalty\centerpenalty \fi + \line{\kern\leftskip #1\kern\rightskip}% } -\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}} % @sp n outputs n lines of vertical space - +% \parseargdef\sp{\vskip #1\baselineskip} % @comment ...line which is ignored... % @c is the same as @comment % @ignore ... @end ignore is another way to write a comment - +% \def\comment{\begingroup \catcode`\^^M=\other% \catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% \commentxxx} {\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}} - +% \let\c=\comment % @paragraphindent NCHARS @@ -1097,7 +1111,7 @@ % for display in the outlines, and in other places. Thus, we have to % double any backslashes. Otherwise, a name like "\node" will be % interpreted as a newline (\n), followed by o, d, e. Not good. -% +% % See http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html and % related messages. The final outcome is that it is up to the TeX user % to double the backslashes and otherwise make the string valid, so @@ -1107,7 +1121,7 @@ % #1 is a control sequence in which to do the replacements, % which we \xdef. \def\txiescapepdf#1{% - \ifx\pdfescapestring\relax + \ifx\pdfescapestring\thisisundefined % No primitive available; should we give a warning or log? % Many times it won't matter. \else @@ -1124,10 +1138,12 @@ \ifpdf % - % Color manipulation macros based on pdfcolor.tex, + % Color manipulation macros using ideas from pdfcolor.tex, % except using rgb instead of cmyk; the latter is said to render as a % very dark gray on-screen and a very dark halftone in print, instead - % of actual black. + % of actual black. The dark red here is dark enough to print on paper as + % nearly black, but still distinguishable for online viewing. We use + % black by default, though. \def\rgbDarkRed{0.50 0.09 0.12} \def\rgbBlack{0 0 0} % @@ -1173,8 +1189,8 @@ % % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto). \def\dopdfimage#1#2#3{% - \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% - \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% + \def\pdfimagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% + \def\pdfimageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% % % pdftex (and the PDF format) support .pdf, .png, .jpg (among % others). Let's try in that order, PDF first since if @@ -1212,8 +1228,8 @@ \else \immediate\pdfximage \fi - \ifdim \wd0 >0pt width \imagewidth \fi - \ifdim \wd2 >0pt height \imageheight \fi + \ifdim \wd0 >0pt width \pdfimagewidth \fi + \ifdim \wd2 >0pt height \pdfimageheight \fi \ifnum\pdftexversion<13 #1.\pdfimgext \else @@ -1237,10 +1253,9 @@ % used to mark target names; must be expandable. \def\pdfmkpgn#1{#1} % - % by default, use a color that is dark enough to print on paper as - % nearly black, but still distinguishable for online viewing. - \def\urlcolor{\rgbDarkRed} - \def\linkcolor{\rgbDarkRed} + % by default, use black for everything. + \def\urlcolor{\rgbBlack} + \def\linkcolor{\rgbBlack} \def\endlink{\setcolor{\maincolor}\pdfendlink} % % Adding outlines to PDF; macros for calculating structure of outlines @@ -1357,12 +1372,17 @@ \def\skipspaces#1{\def\PP{#1}\def\D{|}% \ifx\PP\D\let\nextsp\relax \else\let\nextsp\skipspaces - \ifx\p\space\else\addtokens{\filename}{\PP}% - \advance\filenamelength by 1 - \fi + \addtokens{\filename}{\PP}% + \advance\filenamelength by 1 \fi \nextsp} - \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax} + \def\getfilename#1{% + \filenamelength=0 + % If we don't expand the argument now, \skipspaces will get + % snagged on things like "@value{foo}". + \edef\temp{#1}% + \expandafter\skipspaces\temp|\relax + } \ifnum\pdftexversion < 14 \let \startlink \pdfannotlink \else @@ -1459,9 +1479,6 @@ \def\ttsl{\setfontstyle{ttsl}} -% Default leading. -\newdimen\textleading \textleading = 13.2pt - % Set the baselineskip to #1, and the lineskip and strut size % correspondingly. There is no deep meaning behind these magic numbers % used as factors; they just match (closely enough) what Knuth defined. @@ -1473,6 +1490,7 @@ % can get a sort of poor man's double spacing by redefining this. \def\baselinefactor{1} % +\newdimen\textleading \def\setleading#1{% \dimen0 = #1\relax \normalbaselineskip = \baselinefactor\dimen0 @@ -1745,18 +1763,24 @@ \fi\fi -% Set the font macro #1 to the font named #2, adding on the -% specified font prefix (normally `cm'). +% Set the font macro #1 to the font named \fontprefix#2. % #3 is the font's design size, #4 is a scale factor, #5 is the CMap -% encoding (currently only OT1, OT1IT and OT1TT are allowed, pass -% empty to omit). +% encoding (only OT1, OT1IT and OT1TT are allowed, or empty to omit). +% Example: +% #1 = \textrm +% #2 = \rmshape +% #3 = 10 +% #4 = \mainmagstep +% #5 = OT1 +% \def\setfont#1#2#3#4#5{% \font#1=\fontprefix#2#3 scaled #4 \csname cmap#5\endcsname#1% } % This is what gets called when #5 of \setfont is empty. \let\cmap\gobble -% emacs-page end of cmaps +% +% (end of cmaps) % Use cm as the default font prefix. % To specify the font prefix, you must define \fontprefix @@ -1766,7 +1790,7 @@ \fi % Support font families that don't use the same naming scheme as CM. \def\rmshape{r} -\def\rmbshape{bx} %where the normal face is bold +\def\rmbshape{bx} % where the normal face is bold \def\bfshape{b} \def\bxshape{bx} \def\ttshape{tt} @@ -1781,8 +1805,7 @@ \def\scshape{csc} \def\scbshape{csc} -% Definitions for a main text size of 11pt. This is the default in -% Texinfo. +% Definitions for a main text size of 11pt. (The default in Texinfo.) % \def\definetextfontsizexi{% % Text fonts (11.2pt, magstep1). @@ -1907,7 +1930,7 @@ \textleading = 13.2pt % line spacing for 11pt CM \textfonts % reset the current fonts \rm -} % end of 11pt text font size definitions +} % end of 11pt text font size definitions, \definetextfontsizexi % Definitions to make the main text be 10pt Computer Modern, with @@ -2039,7 +2062,7 @@ \textleading = 12pt % line spacing for 10pt CM \textfonts % reset the current fonts \rm -} % end of 10pt text font size definitions +} % end of 10pt text font size definitions, \definetextfontsizex % We provide the user-level command @@ -2123,7 +2146,7 @@ \let\tenttsl=\secttsl \def\curfontsize{sec}% \def\lsize{subsec}\def\lllsize{reduced}% - \resetmathfonts \setleading{16pt}} + \resetmathfonts \setleading{17pt}} \def\subsecfonts{% \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc @@ -2254,8 +2277,6 @@ \gdef\markupsetcodequoteleft{\let`\codequoteleft} \gdef\markupsetcodequoteright{\let'\codequoteright} - -\gdef\markupsetnoligaturesquoteleft{\let`\noligaturesquoteleft} } \let\markupsetuplqcode \markupsetcodequoteleft @@ -2264,6 +2285,9 @@ \let\markupsetuplqexample \markupsetcodequoteleft \let\markupsetuprqexample \markupsetcodequoteright % +\let\markupsetuplqkbd \markupsetcodequoteleft +\let\markupsetuprqkbd \markupsetcodequoteright +% \let\markupsetuplqsamp \markupsetcodequoteleft \let\markupsetuprqsamp \markupsetcodequoteright % @@ -2273,8 +2297,6 @@ \let\markupsetuplqverbatim \markupsetcodequoteleft \let\markupsetuprqverbatim \markupsetcodequoteright -\let\markupsetuplqkbd \markupsetnoligaturesquoteleft - % Allow an option to not use regular directed right quote/apostrophe % (char 0x27), but instead the undirected quote from cmtt (char 0x0d). % The undirected quote is ugly, so don't make it the default, but it @@ -2359,13 +2381,14 @@ \ifx\next,% \else\ifx\next-% \else\ifx\next.% + \else\ifx\next\.% + \else\ifx\next\comma% \else\ptexslash - \fi\fi\fi + \fi\fi\fi\fi\fi \aftersmartic } -% like \smartslanted except unconditionally uses \ttsl, and no ic. -% @var is set to this for defun arguments. +% Unconditional use \ttsl, and no ic. @var is set to this for defuns. \def\ttslanted#1{{\ttsl #1}} % @cite is like \smartslanted except unconditionally use \sl. We never want @@ -2430,34 +2453,12 @@ % @samp. \def\samp#1{{\setupmarkupstyle{samp}\lq\tclose{#1}\rq\null}} -% definition of @key that produces a lozenge. Doesn't adjust to text size. -%\setfont\keyrm\rmshape{8}{1000}{OT1} -%\font\keysy=cmsy9 -%\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{% -% \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% -% \vbox{\hrule\kern-0.4pt -% \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% -% \kern-0.4pt\hrule}% -% \kern-.06em\raise0.4pt\hbox{\angleright}}}} - -% definition of @key with no lozenge. If the current font is already -% monospace, don't change it; that way, we respect @kbdinputstyle. But -% if it isn't monospace, then use \tt. -% -\def\key#1{{\setupmarkupstyle{key}% - \nohyphenation - \ifmonospace\else\tt\fi - #1}\null} - -% ctrl is no longer a Texinfo command. -\def\ctrl #1{{\tt \rawbackslash \hat}#1} +% @indicateurl is \samp, that is, with quotes. +\let\indicateurl=\samp -% @file, @option are the same as @samp. -\let\file=\samp -\let\option=\samp - -% @code is a modification of @t, -% which makes spaces the same size as normal in the surrounding text. +% @code (and similar) prints in typewriter, but with spaces the same +% size as normal in the surrounding text, without hyphenation, etc. +% This is a subroutine for that. \def\tclose#1{% {% % Change normal interword space to be same as for the current font. @@ -2480,14 +2481,14 @@ } % We *must* turn on hyphenation at `-' and `_' in @code. +% (But see \codedashfinish below.) % Otherwise, it is too hard to avoid overfull hboxes % in the Emacs manual, the Library manual, etc. - +% % Unfortunately, TeX uses one parameter (\hyphenchar) to control % both hyphenation at - and hyphenation within words. % We must therefore turn them both off (\tclose does that) -% and arrange explicitly to hyphenate at a dash. -% -- rms. +% and arrange explicitly to hyphenate at a dash. -- rms. { \catcode`\-=\active \catcode`\_=\active \catcode`\'=\active \catcode`\`=\active @@ -2501,17 +2502,38 @@ \let-\codedash \let_\codeunder \else - \let-\realdash + \let-\normaldash \let_\realunder \fi + % Given -foo (with a single dash), we do not want to allow a break + % after the hyphen. + \global\let\codedashprev=\codedash + % \codex } + % + \gdef\codedash{\futurelet\next\codedashfinish} + \gdef\codedashfinish{% + \normaldash % always output the dash character itself. + % + % Now, output a discretionary to allow a line break, unless + % (a) the next character is a -, or + % (b) the preceding character is a -. + % E.g., given --posix, we do not want to allow a break after either -. + % Given --foo-bar, we do want to allow a break between the - and the b. + \ifx\next\codedash \else + \ifx\codedashprev\codedash + \else \discretionary{}{}{}\fi + \fi + % we need the space after the = for the case when \next itself is a + % space token; it would get swallowed otherwise. As in @code{- a}. + \global\let\codedashprev= \next + } } - +\def\normaldash{-} +% \def\codex #1{\tclose{#1}\endgroup} -\def\realdash{-} -\def\codedash{-\discretionary{}{}{}} \def\codeunder{% % this is all so @math{@code{var_name}+1} can work. In math mode, _ % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) @@ -2525,9 +2547,9 @@ } % An additional complication: the above will allow breaks after, e.g., -% each of the four underscores in __typeof__. This is undesirable in -% some manuals, especially if they don't have long identifiers in -% general. @allowcodebreaks provides a way to control this. +% each of the four underscores in __typeof__. This is bad. +% @allowcodebreaks provides a document-level way to turn breaking at - +% and _ on and off. % \newif\ifallowcodebreaks \allowcodebreakstrue @@ -2546,37 +2568,28 @@ \fi\fi } -% @uref (abbreviation for `urlref') takes an optional (comma-separated) -% second argument specifying the text to display and an optional third -% arg as text to display instead of (rather than in addition to) the url -% itself. First (mandatory) arg is the url. -% (This \urefnobreak definition isn't used now, leaving it for a while -% for comparison.) -\def\urefnobreak#1{\dourefnobreak #1,,,\finish} -\def\dourefnobreak#1,#2,#3,#4\finish{\begingroup - \unsepspaces - \pdfurl{#1}% - \setbox0 = \hbox{\ignorespaces #3}% - \ifdim\wd0 > 0pt - \unhbox0 % third arg given, show only that - \else - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0 > 0pt - \ifpdf - \unhbox0 % PDF: 2nd arg given, show only it - \else - \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url - \fi - \else - \code{#1}% only url given, so show it - \fi - \fi - \endlink -\endgroup} +% For @command, @env, @file, @option quotes seem unnecessary, +% so use \code rather than \samp. +\let\command=\code +\let\env=\code +\let\file=\code +\let\option=\code -% This \urefbreak definition is the active one. +% @uref (abbreviation for `urlref') aka @url takes an optional +% (comma-separated) second argument specifying the text to display and +% an optional third arg as text to display instead of (rather than in +% addition to) the url itself. First (mandatory) arg is the url. + +% TeX-only option to allow changing PDF output to show only the second +% arg (if given), and not the url (which is then just the link target). +\newif\ifurefurlonlylink + +% The main macro is \urefbreak, which allows breaking at expected +% places within the url. (There used to be another version, which +% didn't support automatic breaking.) \def\urefbreak{\begingroup \urefcatcodes \dourefbreak} \let\uref=\urefbreak +% \def\dourefbreak#1{\urefbreakfinish #1,,,\finish} \def\urefbreakfinish#1,#2,#3,#4\finish{% doesn't work in @example \unsepspaces @@ -2585,12 +2598,19 @@ \ifdim\wd0 > 0pt \unhbox0 % third arg given, show only that \else - \setbox0 = \hbox{\ignorespaces #2}% + \setbox0 = \hbox{\ignorespaces #2}% look for second arg \ifdim\wd0 > 0pt \ifpdf - \unhbox0 % PDF: 2nd arg given, show only it + \ifurefurlonlylink + % PDF plus option to not display url, show just arg + \unhbox0 + \else + % PDF, normally display both arg and url for consistency, + % visibility, if the pdf is eventually used to print, etc. + \unhbox0\ (\urefcode{#1})% + \fi \else - \unhbox0\ (\urefcode{#1})% DVI: 2nd arg given, show both it and url + \unhbox0\ (\urefcode{#1})% DVI, always show arg and url \fi \else \urefcode{#1}% only url given, so show it @@ -2630,8 +2650,10 @@ % we put a little stretch before and after the breakable chars, to help % line breaking of long url's. The unequal skips make look better in % cmtt at least, especially for dots. -\def\urefprestretch{\urefprebreak \hskip0pt plus.13em } -\def\urefpoststretch{\urefpostbreak \hskip0pt plus.1em } +\def\urefprestretchamount{.13em} +\def\urefpoststretchamount{.1em} +\def\urefprestretch{\urefprebreak \hskip0pt plus\urefprestretchamount\relax} +\def\urefpoststretch{\urefpostbreak \hskip0pt plus\urefprestretchamount\relax} % \def\urefcodeamp{\urefprestretch \&\urefpoststretch} \def\urefcodedot{\urefprestretch .\urefpoststretch} @@ -2692,10 +2714,6 @@ \let\email=\uref \fi -% @kbd is like @code, except that if the argument is just one @key command, -% then @kbd has no effect. -\def\kbd#1{{\setupmarkupstyle{kbd}\def\look{#1}\expandafter\kbdfoo\look??\par}} - % @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), % `example' (@kbd uses ttsl only inside of @example and friends), % or `code' (@kbd uses normal tty font always). @@ -2719,16 +2737,36 @@ % Default is `distinct'. \kbdinputstyle distinct +% @kbd is like @code, except that if the argument is just one @key command, +% then @kbd has no effect. +\def\kbd#1{{\def\look{#1}\expandafter\kbdsub\look??\par}} + \def\xkey{\key} -\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% -\ifx\one\xkey\ifx\threex\three \key{#2}% -\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi -\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi} +\def\kbdsub#1#2#3\par{% + \def\one{#1}\def\three{#3}\def\threex{??}% + \ifx\one\xkey\ifx\threex\three \key{#2}% + \else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi + \else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi +} -% For @indicateurl, @env, @command quotes seem unnecessary, so use \code. -\let\indicateurl=\code -\let\env=\code -\let\command=\code +% definition of @key that produces a lozenge. Doesn't adjust to text size. +%\setfont\keyrm\rmshape{8}{1000}{OT1} +%\font\keysy=cmsy9 +%\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{% +% \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% +% \vbox{\hrule\kern-0.4pt +% \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% +% \kern-0.4pt\hrule}% +% \kern-.06em\raise0.4pt\hbox{\angleright}}}} + +% definition of @key with no lozenge. If the current font is already +% monospace, don't change it; that way, we respect @kbdinputstyle. But +% if it isn't monospace, then use \tt. +% +\def\key#1{{\setupmarkupstyle{key}% + \nohyphenation + \ifmonospace\else\tt\fi + #1}\null} % @clicksequence{File @click{} Open ...} \def\clicksequence#1{\begingroup #1\endgroup} @@ -2836,6 +2874,9 @@ } } +% ctrl is no longer a Texinfo command, but leave this definition for fun. +\def\ctrl #1{{\tt \rawbackslash \hat}#1} + % @inlinefmt{FMTNAME,PROCESSED-TEXT} and @inlineraw{FMTNAME,RAW-TEXT}. % Ignore unless FMTNAME == tex; then it is like @iftex and @tex, % except specified as a normal braced arg, so no newlines to worry about. @@ -2847,6 +2888,15 @@ \def\inlinefmtname{#1}% \ifx\inlinefmtname\outfmtnametex \ignorespaces #2\fi } +% +% @inlinefmtifelse{FMTNAME,THEN-TEXT,ELSE-TEXT} expands THEN-TEXT if +% FMTNAME is tex, else ELSE-TEXT. +\long\def\inlinefmtifelse#1{\doinlinefmtifelse #1,,,\finish} +\long\def\doinlinefmtifelse#1,#2,#3,#4,\finish{% + \def\inlinefmtname{#1}% + \ifx\inlinefmtname\outfmtnametex \ignorespaces #2\else \ignorespaces #3\fi +} +% % For raw, must switch into @tex before parsing the argument, to avoid % setting catcodes prematurely. Doing it this way means that, for % example, @inlineraw{html, foo{bar} gets a parse error instead of being @@ -2863,6 +2913,23 @@ \endgroup % close group opened by \tex. } +% @inlineifset{VAR, TEXT} expands TEXT if VAR is @set. +% +\long\def\inlineifset#1{\doinlineifset #1,\finish} +\long\def\doinlineifset#1,#2,\finish{% + \def\inlinevarname{#1}% + \expandafter\ifx\csname SET\inlinevarname\endcsname\relax + \else\ignorespaces#2\fi +} + +% @inlineifclear{VAR, TEXT} expands TEXT if VAR is not @set. +% +\long\def\inlineifclear#1{\doinlineifclear #1,\finish} +\long\def\doinlineifclear#1,#2,\finish{% + \def\inlinevarname{#1}% + \expandafter\ifx\csname SET\inlinevarname\endcsname\relax \ignorespaces#2\fi +} + \message{glyphs,} % and logos. @@ -3126,12 +3193,17 @@ % hopefully nobody will notice/care. \edef\ecsize{\csname\curfontsize ecsize\endcsname}% \edef\nominalsize{\csname\curfontsize nominalsize\endcsname}% - \ifx\curfontstyle\bfstylename - % bold: - \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize - \else - % regular: - \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize + \ifmonospace + % typewriter: + \font\thisecfont = ectt\ecsize \space at \nominalsize + \else + \ifx\curfontstyle\bfstylename + % bold: + \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize + \else + % regular: + \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize + \fi \fi \thisecfont } @@ -3244,6 +3316,20 @@ \finishedtitlepagetrue } +% Settings used for typesetting titles: no hyphenation, no indentation, +% don't worry much about spacing, ragged right. This should be used +% inside a \vbox, and fonts need to be set appropriately first. Because +% it is always used for titles, nothing else, we call \rmisbold. \par +% should be specified before the end of the \vbox, since a vbox is a group. +% +\def\raggedtitlesettings{% + \rmisbold + \hyphenpenalty=10000 + \parindent=0pt + \tolerance=5000 + \ptexraggedright +} + % Macros to be used within @titlepage: \let\subtitlerm=\tenrm @@ -3251,7 +3337,7 @@ \parseargdef\title{% \checkenv\titlepage - \leftline{\titlefonts\rmisbold #1} + \vbox{\titlefonts \raggedtitlesettings #1\par}% % print a rule at the page bottom also. \finishedtitlepagefalse \vskip4pt \hrule height 4pt width \hsize \vskip4pt @@ -3599,7 +3685,7 @@ \parskip=\smallskipamount \ifdim\parskip=0pt \parskip=2pt \fi % - % Try typesetting the item mark that if the document erroneously says + % Try typesetting the item mark so that if the document erroneously says % something like @itemize @samp (intending @table), there's an error % right away at the @itemize. It's not the best error message in the % world, but it's better than leaving it to the @item. This means if @@ -3850,18 +3936,22 @@ % multitable-only commands. % -% @headitem starts a heading row, which we typeset in bold. -% Assignments have to be global since we are inside the implicit group -% of an alignment entry. \everycr resets \everytab so we don't have to +% @headitem starts a heading row, which we typeset in bold. Assignments +% have to be global since we are inside the implicit group of an +% alignment entry. \everycr below resets \everytab so we don't have to % undo it ourselves. \def\headitemfont{\b}% for people to use in the template row; not changeable \def\headitem{% \checkenv\multitable \crcr + \gdef\headitemcrhook{\nobreak}% attempt to avoid page break after headings \global\everytab={\bf}% can't use \headitemfont since the parsing differs \the\everytab % for the first item }% % +% default for tables with no headings. +\let\headitemcrhook=\relax +% % A \tab used to include \hskip1sp. But then the space in a template % line is not enough. That is bad. So let's go back to just `&' until % we again encounter the problem the 1sp was intended to solve. @@ -3892,15 +3982,15 @@ % \everycr = {% \noalign{% - \global\everytab={}% + \global\everytab={}% Reset from possible headitem. \global\colcount=0 % Reset the column counter. - % Check for saved footnotes, etc. + % + % Check for saved footnotes, etc.: \checkinserts - % Keeps underfull box messages off when table breaks over pages. - %\filbreak - % Maybe so, but it also creates really weird page breaks when the - % table breaks over pages. Wouldn't \vfil be better? Wait until the - % problem manifests itself, so it can be fixed for real --karl. + % + % Perhaps a \nobreak, then reset: + \headitemcrhook + \global\let\headitemcrhook=\relax }% }% % @@ -4139,7 +4229,7 @@ \def\value{\begingroup\makevalueexpandable\valuexxx} \def\valuexxx#1{\expandablevalue{#1}\endgroup} { - \catcode`\- = \active \catcode`\_ = \active + \catcode`\-=\active \catcode`\_=\active % \gdef\makevalueexpandable{% \let\value = \expandablevalue @@ -4148,7 +4238,7 @@ % ..., but we might end up with active ones in the argument if % we're called from @code, as @code{@value{foo-bar_}}, though. % So \let them to their normal equivalents. - \let-\realdash \let_\normalunderscore + \let-\normaldash \let_\normalunderscore } } @@ -4160,6 +4250,11 @@ % it will fail (although perhaps we could fix that with sufficient work % to do a one-level expansion on the result, instead of complete). % +% Unfortunately, this has the consequence that when _ is in the *value* +% of an @set, it does not print properly in the roman fonts (get the cmr +% dot accent at position 126 instead). No fix comes to mind, and it's +% been this way since 2003 or earlier, so just ignore it. +% \def\expandablevalue#1{% \expandafter\ifx\csname SET#1\endcsname\relax {[No value for ``#1'']}% @@ -4172,7 +4267,8 @@ % @ifset VAR ... @end ifset reads the `...' iff VAR has been defined % with @set. % -% To get special treatment of `@end ifset,' call \makeond and the redefine. +% To get the special treatment we need for `@end ifset,' we call +% \makecond and then redefine. % \makecond{ifset} \def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}} @@ -4188,7 +4284,7 @@ } \def\ifsetfail{\doignore{ifset}} -% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been +% @ifclear VAR ... @end executes the `...' iff VAR has never been % defined with @set, or has been undefined with @clear. % % The `\else' inside the `\doifset' parameter is a trick to reuse the @@ -4199,6 +4295,35 @@ \def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}} \def\ifclearfail{\doignore{ifclear}} +% @ifcommandisdefined CMD ... @end executes the `...' if CMD (written +% without the @) is in fact defined. We can only feasibly check at the +% TeX level, so something like `mathcode' is going to considered +% defined even though it is not a Texinfo command. +% +\makecond{ifcommanddefined} +\def\ifcommanddefined{\parsearg{\doifcmddefined{\let\next=\ifcmddefinedfail}}} +% +\def\doifcmddefined#1#2{{% + \makevalueexpandable + \let\next=\empty + \expandafter\ifx\csname #2\endcsname\relax + #1% If not defined, \let\next as above. + \fi + \expandafter + }\next +} +\def\ifcmddefinedfail{\doignore{ifcommanddefined}} + +% @ifcommandnotdefined CMD ... handled similar to @ifclear above. +\makecond{ifcommandnotdefined} +\def\ifcommandnotdefined{% + \parsearg{\doifcmddefined{\else \let\next=\ifcmdnotdefinedfail}}} +\def\ifcmdnotdefinedfail{\doignore{ifcommandnotdefined}} + +% Set the `txicommandconditionals' variable, so documents have a way to +% test if the @ifcommand...defined conditionals are available. +\set txicommandconditionals + % @dircategory CATEGORY -- specify a category of the dir file % which this file should belong to. Ignore this in TeX. \let\dircategory=\comment @@ -4307,7 +4432,7 @@ % complicated, when \tex is in effect and \{ is a \delimiter again. % We can't use \lbracecmd and \rbracecmd because texindex assumes % braces and backslashes are used only as delimiters. Perhaps we - % should define @lbrace and @rbrace commands a la @comma. + % should use @lbracechar and @rbracechar? \def\{{{\tt\char123}}% \def\}{{\tt\char125}}% % @@ -4328,8 +4453,7 @@ % @end macro % ... % @funindex commtest - % - % The above is not enough to reproduce the bug, but it gives the flavor. + % This is not enough to reproduce the bug, but it gives the flavor. % % Sample whatsit resulting: % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} @@ -4435,6 +4559,7 @@ \definedummyword\guillemetright \definedummyword\guilsinglleft \definedummyword\guilsinglright + \definedummyword\lbracechar \definedummyword\leq \definedummyword\minus \definedummyword\ogonek @@ -4447,6 +4572,7 @@ \definedummyword\quoteleft \definedummyword\quoteright \definedummyword\quotesinglbase + \definedummyword\rbracechar \definedummyword\result \definedummyword\textdegree % @@ -4498,6 +4624,7 @@ \definedummyword\t % % Commands that take arguments. + \definedummyword\abbr \definedummyword\acronym \definedummyword\anchor \definedummyword\cite @@ -4509,7 +4636,9 @@ \definedummyword\emph \definedummyword\env \definedummyword\file + \definedummyword\image \definedummyword\indicateurl + \definedummyword\inforef \definedummyword\kbd \definedummyword\key \definedummyword\math @@ -4525,8 +4654,21 @@ \definedummyword\verb \definedummyword\w \definedummyword\xref + % + % Consider: + % @macro mkind{arg1,arg2} + % @cindex \arg2\ + % @end macro + % @mkind{foo, bar} + % The space after the comma will end up in the temporary definition + % that we make for arg2 (see \parsemargdef ff.). We want all this to be + % expanded for the sake of the index, so we end up just seeing "bar". + \let\xeatspaces = \eatspaces } +% For testing: output @{ and @} in index sort strings as \{ and \}. +\newif\ifusebracesinindexes + % \indexnofonts is used when outputting the strings to sort the index % by, and when constructing control sequence names. It eliminates all % control sequences and just writes whatever the best ASCII sort string @@ -4555,8 +4697,16 @@ % Unfortunately, texindex is not prepared to handle braces in the % content at all. So for index sorting, we map @{ and @} to strings % starting with |, since that ASCII character is between ASCII { and }. - \def\{{|a}% - \def\}{|b}% + \ifusebracesinindexes + \def\lbracechar{\lbracecmd}% + \def\rbracechar{\rbracecmd}% + \else + \def\lbracechar{|a}% + \def\rbracechar{|b}% + \fi + \let\{=\lbracechar + \let\}=\rbracechar + % % % Non-English letters. \def\AA{AA}% @@ -4732,10 +4882,9 @@ % % ..., ready, GO: % -\def\safewhatsit#1{% -\ifhmode +\def\safewhatsit#1{\ifhmode #1% -\else + \else % \lastskip and \lastpenalty cannot both be nonzero simultaneously. \whatsitskip = \lastskip \edef\lastskipmacro{\the\lastskip}% @@ -4759,7 +4908,6 @@ % to re-insert the same penalty (values >10000 are used for various % signals); since we just inserted a non-discardable item, any % following glue (such as a \parskip) would be a breakpoint. For example: - % % @deffn deffn-whatever % @vindex index-whatever % Description. @@ -4772,8 +4920,7 @@ % (the whatsit from the \write), so we must insert a \nobreak. \nobreak\vskip\whatsitskip \fi -\fi -} +\fi} % The index entry written in the file actually looks like % \entry {sortstring}{page}{topic} @@ -5520,14 +5667,6 @@ % Define @majorheading, @heading and @subheading -% NOTE on use of \vbox for chapter headings, section headings, and such: -% 1) We use \vbox rather than the earlier \line to permit -% overlong headings to fold. -% 2) \hyphenpenalty is set to 10000 because hyphenation in a -% heading is obnoxious; this forbids it. -% 3) Likewise, headings look best if no \parindent is used, and -% if justification is not attempted. Hence \raggedright. - \def\majorheading{% {\advance\chapheadingskip by 10pt \chapbreak }% \parsearg\chapheadingzzz @@ -5535,10 +5674,8 @@ \def\chapheading{\chapbreak \parsearg\chapheadingzzz} \def\chapheadingzzz#1{% - {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\ptexraggedright - \rmisbold #1\hfill}}% - \bigskip \par\penalty 200\relax + \vbox{\chapfonts \raggedtitlesettings #1\par}% + \nobreak\bigskip \nobreak \suppressfirstparagraphindent } @@ -5697,8 +5834,7 @@ % % Typeset the actual heading. \nobreak % Avoid page breaks at the interline glue. - \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \ptexraggedright - \hangindent=\wd0 \centerparametersmaybe + \vbox{\raggedtitlesettings \hangindent=\wd0 \centerparametersmaybe \unhbox0 #1\par}% }% \nobreak\bigskip % no page break after a chapter title @@ -5720,18 +5856,18 @@ \def\setchapterstyle #1 {\csname CHAPF#1\endcsname} % \def\unnchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\ptexraggedright - \rmisbold #1\hfill}}\bigskip \par\nobreak + \chapoddpage + \vbox{\chapfonts \raggedtitlesettings #1\par}% + \nobreak\bigskip\nobreak } \def\chfopen #1#2{\chapoddpage {\chapfonts \vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% \par\penalty 5000 % } \def\centerchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt - \hfill {\rmisbold #1}\hfill}}\bigskip \par\nobreak + \chapoddpage + \vbox{\chapfonts \raggedtitlesettings \hfill #1\hfill}% + \nobreak\bigskip \nobreak } \def\CHAPFopen{% \global\let\chapmacro=\chfopen @@ -5822,7 +5958,7 @@ % % Now the second mark, after the heading break. No break points % between here and the heading. - \let\prevsectiondefs=\lastsectiondefs + \global\let\prevsectiondefs=\lastsectiondefs \domark % % Only insert the space after the number if we have a section number. @@ -5876,14 +6012,15 @@ % % We'll almost certainly start a paragraph next, so don't let that % glue accumulate. (Not a breakpoint because it's preceded by a - % discardable item.) + % discardable item.) However, when a paragraph is not started next + % (\startdefun, \cartouche, \center, etc.), this needs to be wiped out + % or the negative glue will cause weirdly wrong output, typically + % obscuring the section heading with something else. \vskip-\parskip % - % This is purely so the last item on the list is a known \penalty > - % 10000. This is so \startdefun can avoid allowing breakpoints after - % section headings. Otherwise, it would insert a valid breakpoint between: - % @section sec-whatever - % @deffn def-whatever + % This is so the last item on the main vertical list is a known + % \penalty > 10000, so \startdefun, etc., can recognize the situation + % and do the needful. \penalty 10001 } @@ -6188,8 +6325,8 @@ \catcode `\|=\other \catcode `\<=\other \catcode `\>=\other - \catcode`\`=\other - \catcode`\'=\other + \catcode `\`=\other + \catcode `\'=\other \escapechar=`\\ % % ' is active in math mode (mathcode"8000). So reset it, and all our @@ -6213,7 +6350,7 @@ \let\/=\ptexslash \let\*=\ptexstar \let\t=\ptext - \expandafter \let\csname top\endcsname=\ptextop % outer + \expandafter \let\csname top\endcsname=\ptextop % we've made it outer \let\frenchspacing=\plainfrenchspacing % \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% @@ -6297,13 +6434,11 @@ % side, and for 6pt waste from % each corner char, and rule thickness \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip - % Flag to tell @lisp, etc., not to narrow margin. - \let\nonarrowing = t% % % If this cartouche directly follows a sectioning command, we need the % \parskip glue (backspaced over by default) or the cartouche can % collide with the section heading. - \ifnum\lastpenalty>10000 \vskip\parskip \fi + \ifnum\lastpenalty>10000 \vskip\parskip \penalty\lastpenalty \fi % \vbox\bgroup \baselineskip=0pt\parskip=0pt\lineskip=0pt @@ -6338,7 +6473,7 @@ \newdimen\nonfillparindent \def\nonfillstart{% \aboveenvbreak - \hfuzz = 12pt % Don't be fussy + \ifdim\hfuzz < 12pt \hfuzz = 12pt \fi % Don't be fussy \sepspaces % Make spaces be word-separators rather than space tokens. \let\par = \lisppar % don't ignore blank lines \obeylines % each line of input is a line of output @@ -6465,9 +6600,13 @@ % @raggedright does more-or-less normal line breaking but no right -% justification. From plain.tex. +% justification. From plain.tex. Don't stretch around special +% characters in urls in this environment, since the stretch at the right +% should be enough. \envdef\raggedright{% - \rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax + \rightskip0pt plus2.4em \spaceskip.3333em \xspaceskip.5em\relax + \def\urefprestretchamount{0pt}% + \def\urefpoststretchamount{0pt}% } \let\Eraggedright\par @@ -6496,16 +6635,9 @@ \makedispenvdef{quotation}{\quotationstart} % \def\quotationstart{% - {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip - \parindent=0pt - % - % @cartouche defines \nonarrowing to inhibit narrowing at next level down. + \indentedblockstart % same as \indentedblock, but increase right margin too. \ifx\nonarrowing\relax - \advance\leftskip by \lispnarrowing \advance\rightskip by \lispnarrowing - \exdentamount = \lispnarrowing - \else - \let\nonarrowing = \relax \fi \parsearg\quotationlabel } @@ -6531,6 +6663,32 @@ \fi } +% @indentedblock is like @quotation, but indents only on the left and +% has no optional argument. +% +\makedispenvdef{indentedblock}{\indentedblockstart} +% +\def\indentedblockstart{% + {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip + \parindent=0pt + % + % @cartouche defines \nonarrowing to inhibit narrowing at next level down. + \ifx\nonarrowing\relax + \advance\leftskip by \lispnarrowing + \exdentamount = \lispnarrowing + \else + \let\nonarrowing = \relax + \fi +} + +% Keep a nonzero parskip for the environment, since we're doing normal filling. +% +\def\Eindentedblock{% + \par + {\parskip=0pt \afterenvbreak}% +} +\def\Esmallindentedblock{\Eindentedblock} + % LaTeX-like @verbatim...@end verbatim and @verb{...} % If we want to allow any as delimiter, @@ -7009,7 +7167,10 @@ \df \sl \hyphenchar\font=0 % % On the other hand, if an argument has two dashes (for instance), we - % want a way to get ttsl. Let's try @var for that. + % want a way to get ttsl. We used to recommend @var for that, so + % leave the code in, but it's strange for @var to lead to typewriter. + % Nowadays we recommend @code, since the difference between a ttsl hyphen + % and a tt hyphen is pretty tiny. @code also disables ?` !`. \def\var##1{{\setupmarkupstyle{var}\ttslanted{##1}}}% #1% \sl\hyphenchar\font=45 @@ -7338,7 +7499,7 @@ % Parse the optional {params} list. Set up \paramno and \paramlist % so \defmacro knows what to do. Define \macarg.BLAH for each BLAH -% in the params list to some hook where the argument si to be expanded. If +% in the params list to some hook where the argument is to be expanded. If % there are less than 10 arguments that hook is to be replaced by ##N where N % is the position in that list, that is to say the macro arguments are to be % defined `a la TeX in the macro body. @@ -7793,7 +7954,7 @@ \fi\fi } - +% % @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is % the node name, #2 the name of the Info cross-reference, #3 the printed % node name, #4 the name of the Info file, #5 the name of the printed @@ -7803,16 +7964,21 @@ \def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} \def\ref#1{\xrefX[#1,,,,,,,]} % -\newbox\topbox +\newbox\toprefbox \newbox\printedrefnamebox +\newbox\infofilenamebox \newbox\printedmanualbox % \def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup \unsepspaces % + % Get args without leading/trailing spaces. \def\printedrefname{\ignorespaces #3}% \setbox\printedrefnamebox = \hbox{\printedrefname\unskip}% % + \def\infofilename{\ignorespaces #4}% + \setbox\infofilenamebox = \hbox{\infofilename\unskip}% + % \def\printedmanual{\ignorespaces #5}% \setbox\printedmanualbox = \hbox{\printedmanual\unskip}% % @@ -7845,12 +8011,20 @@ \ifpdf {\indexnofonts \turnoffactive + \makevalueexpandable % This expands tokens, so do it after making catcode changes, so _ - % etc. don't get their TeX definitions. + % etc. don't get their TeX definitions. This ignores all spaces in + % #4, including (wrongly) those in the middle of the filename. \getfilename{#4}% % + % This (wrongly) does not take account of leading or trailing + % spaces in #1, which should be ignored. \edef\pdfxrefdest{#1}% - \txiescapepdf\pdfxrefdest + \ifx\pdfxrefdest\empty + \def\pdfxrefdest{Top}% no empty targets + \else + \txiescapepdf\pdfxrefdest % escape PDF special chars + \fi % \leavevmode \startlink attr{/Border [0 0 0]}% @@ -7883,7 +8057,7 @@ \printedrefname \fi % - % if the user also gave the printed manual name (fifth arg), append + % If the user also gave the printed manual name (fifth arg), append % "in MANUALNAME". \ifdim \wd\printedmanualbox > 0pt \space \putwordin{} \cite{\printedmanual}% @@ -7898,32 +8072,20 @@ % this is a loss. Therefore, we give the text of the node name % again, so it is as if TeX is seeing it for the first time. % - % Cross-manual reference. Only include the "Section ``foo'' in" if - % the foo is neither missing or Top. Thus, @xref{,,,foo,The Foo Manual} - % outputs simply "see The Foo Manual". \ifdim \wd\printedmanualbox > 0pt - % What is the 7sp about? The idea is that we also want to omit - % the Section part if we would be printing "Top", since they are - % clearly trying to refer to the whole manual. But, this being - % TeX, we can't easily compare strings while ignoring the possible - % spaces before and after in the input. By adding the arbitrary - % 7sp, we make it much less likely that a real node name would - % happen to have the same width as "Top" (e.g., in a monospaced font). - % I hope it will never happen in practice. + % Cross-manual reference with a printed manual name. % - % For the same basic reason, we retypeset the "Top" at every - % reference, since the current font is indeterminate. + \crossmanualxref{\cite{\printedmanual\unskip}}% + % + \else\ifdim \wd\infofilenamebox > 0pt + % Cross-manual reference with only an info filename (arg 4), no + % printed manual name (arg 5). This is essentially the same as + % the case above; we output the filename, since we have nothing else. % - \setbox\topbox = \hbox{Top\kern7sp}% - \setbox2 = \hbox{\ignorespaces \printedrefname \unskip \kern7sp}% - \ifdim \wd2 > 7sp - \ifdim \wd2 = \wd\topbox \else - \putwordSection{} ``\printedrefname'' \putwordin{}\space - \fi - \fi - \cite{\printedmanual}% + \crossmanualxref{\code{\infofilename\unskip}}% + % \else - % Reference in this manual. + % Reference within this manual. % % _ (for example) has to be the character _ for the purposes of the % control sequence corresponding to the node, but it has to expand @@ -7944,11 +8106,37 @@ % % output the `page 3'. \turnoffactive \putwordpage\tie\refx{#1-pg}{}% - \fi + \fi\fi \fi \endlink \endgroup} +% Output a cross-manual xref to #1. Used just above (twice). +% +% Only include the text "Section ``foo'' in" if the foo is neither +% missing or Top. Thus, @xref{,,,foo,The Foo Manual} outputs simply +% "see The Foo Manual", the idea being to refer to the whole manual. +% +% But, this being TeX, we can't easily compare our node name against the +% string "Top" while ignoring the possible spaces before and after in +% the input. By adding the arbitrary 7sp below, we make it much less +% likely that a real node name would have the same width as "Top" (e.g., +% in a monospaced font). Hopefully it will never happen in practice. +% +% For the same basic reason, we retypeset the "Top" at every +% reference, since the current font is indeterminate. +% +\def\crossmanualxref#1{% + \setbox\toprefbox = \hbox{Top\kern7sp}% + \setbox2 = \hbox{\ignorespaces \printedrefname \unskip \kern7sp}% + \ifdim \wd2 > 7sp % nonempty? + \ifdim \wd2 = \wd\toprefbox \else % same as Top? + \putwordSection{} ``\printedrefname'' \putwordin{}\space + \fi + \fi + #1% +} + % This macro is called from \xrefX for the `[nodename]' part of xref % output. It's a separate macro only so it can be changed more easily, % since square brackets don't work well in some documents. Particularly @@ -8173,6 +8361,7 @@ \gdef\footnote{% \let\indent=\ptexindent \let\noindent=\ptexnoindent + % \global\advance\footnoteno by \@ne \edef\thisfootno{$^{\the\footnoteno}$}% % @@ -8196,6 +8385,11 @@ % \gdef\dofootnote{% \insert\footins\bgroup + % + % Nested footnotes are not supported in TeX, that would take a lot + % more work. (\startsavinginserts does not suffice.) + \let\footnote=\errfootnote + % % We want to typeset this text as a normal paragraph, even if the % footnote reference occurs in (for example) a display environment. % So reset some parameters. @@ -8233,13 +8427,19 @@ } }%end \catcode `\@=11 +\def\errfootnote{% + \errhelp=\EMsimple + \errmessage{Nested footnotes not supported in texinfo.tex, + even though they work in makeinfo; sorry} +} + % In case a @footnote appears in a vbox, save the footnote text and create % the real \insert just after the vbox finished. Otherwise, the insertion % would be lost. % Similarly, if a @footnote appears inside an alignment, save the footnote % text to a box and make the \insert when a row of the table is finished. % And the same can be done for other insert classes. --kasal, 16nov03. - +% % Replace the \insert primitive by a cheating macro. % Deeper inside, just make sure that the saved insertions are not spilled % out prematurely. @@ -8316,7 +8516,7 @@ it from ftp://tug.org/tex/epsf.tex.} % \def\image#1{% - \ifx\epsfbox\thisiundefined + \ifx\epsfbox\thisisundefined \ifwarnednoepsf \else \errhelp = \noepsfhelp \errmessage{epsf.tex not found, images will be ignored}% @@ -8340,6 +8540,13 @@ % If the image is by itself, center it. \ifvmode \imagevmodetrue + \else \ifx\centersub\centerV + % for @center @image, we need a vbox so we can have our vertical space + \imagevmodetrue + \vbox\bgroup % vbox has better behavior than vtop herev + \fi\fi + % + \ifimagevmode \nobreak\medskip % Usually we'll have text after the image which will insert % \parskip glue, so insert it here too to equalize the space @@ -8349,9 +8556,13 @@ \fi % % Leave vertical mode so that indentation from an enclosing - % environment such as @quotation is respected. On the other hand, if - % it's at the top level, we don't want the normal paragraph indentation. - \noindent + % environment such as @quotation is respected. + % However, if we're at the top level, we don't want the + % normal paragraph indentation. + % On the other hand, if we are in the case of @center @image, we don't + % want to start a paragraph, which will create a hsize-width box and + % eradicate the centering. + \ifx\centersub\centerV\else \noindent \fi % % Output the image. \ifpdf @@ -8363,7 +8574,10 @@ \epsfbox{#1.eps}% \fi % - \ifimagevmode \medskip \fi % space after the standalone image + \ifimagevmode + \medskip % space after a standalone image + \fi + \ifx\centersub\centerV \egroup \fi \endgroup} @@ -9793,11 +10007,9 @@ \catcode`\"=\active \def\activedoublequote{{\tt\char34}} \let"=\activedoublequote -\catcode`\~=\active -\def~{{\tt\char126}} +\catcode`\~=\active \def\activetilde{{\tt\char126}} \let~ = \activetilde \chardef\hat=`\^ -\catcode`\^=\active -\def^{{\tt \hat}} +\catcode`\^=\active \def\activehat{{\tt \hat}} \let^ = \activehat \catcode`\_=\active \def_{\ifusingtt\normalunderscore\_} @@ -9807,16 +10019,26 @@ \catcode`\|=\active \def|{{\tt\char124}} + \chardef \less=`\< -\catcode`\<=\active -\def<{{\tt \less}} +\catcode`\<=\active \def\activeless{{\tt \less}}\let< = \activeless \chardef \gtr=`\> -\catcode`\>=\active -\def>{{\tt \gtr}} -\catcode`\+=\active -\def+{{\tt \char 43}} -\catcode`\$=\active -\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix +\catcode`\>=\active \def\activegtr{{\tt \gtr}}\let> = \activegtr +\catcode`\+=\active \def+{{\tt \char 43}} +\catcode`\$=\active \def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix + +% used for headline/footline in the output routine, in case the page +% breaks in the middle of an @tex block. +\def\texinfochars{% + \let< = \activeless + \let> = \activegtr + \let~ = \activetilde + \let^ = \activehat + \markupsetuplqdefault \markupsetuprqdefault + \let\b = \strong + \let\i = \smartitalic + % in principle, all other definitions in \tex have to be undone too. +} % If a .fmt file is being used, characters that might appear in a file % name cannot be active until we have parsed the command line. @@ -9866,22 +10088,26 @@ @gdef@otherbackslash{@let\=@realbackslash} % Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of -% the literal character `\'. +% the literal character `\'. Also revert - to its normal character, in +% case the active - from code has slipped in. % -@def@normalturnoffactive{% - @let"=@normaldoublequote - @let$=@normaldollar %$ font-lock fix - @let+=@normalplus - @let<=@normalless - @let>=@normalgreater - @let\=@normalbackslash - @let^=@normalcaret - @let_=@normalunderscore - @let|=@normalverticalbar - @let~=@normaltilde - @markupsetuplqdefault - @markupsetuprqdefault - @unsepspaces +{@catcode`- = @active + @gdef@normalturnoffactive{% + @let-=@normaldash + @let"=@normaldoublequote + @let$=@normaldollar %$ font-lock fix + @let+=@normalplus + @let<=@normalless + @let>=@normalgreater + @let\=@normalbackslash + @let^=@normalcaret + @let_=@normalunderscore + @let|=@normalverticalbar + @let~=@normaltilde + @markupsetuplqdefault + @markupsetuprqdefault + @unsepspaces + } } % Make _ and + \other characters, temporarily. diff -urN glibc-2.17-c758a686/manual/threads.texi glibc-2.17-c758a686/manual/threads.texi --- glibc-2.17-c758a686/manual/threads.texi 1969-12-31 19:00:00.000000000 -0500 +++ glibc-2.17-c758a686/manual/threads.texi 2014-09-12 16:10:06.042792724 -0400 @@ -0,0 +1,254 @@ +@node POSIX Threads +@c @node POSIX Threads, Internal Probes, Cryptographic Functions, Top +@chapter POSIX Threads +@c %MENU% POSIX Threads +@cindex pthreads + +This chapter describes the @glibcadj{} POSIX Thread implementation. + +@menu +* Thread-specific Data:: Support for creating and + managing thread-specific data +* Non-POSIX Extensions:: Additional functions to extend + POSIX Thread functionality +@end menu + +@node Thread-specific Data +@section Thread-specific Data + +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*)) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c pthread_key_create ok +@c KEY_UNUSED ok +@c KEY_USABLE ok +Create a thread-specific data key for the calling thread, referenced by +@var{key}. + +Objects declared with the C++11 @code{thread_local} keyword are destroyed +before thread-specific data, so they should not be used in thread-specific +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}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c pthread_key_delete ok +@c This uses atomic compare and exchange to increment the seq number +@c after testing it's not a KEY_UNUSED seq number. +@c KEY_UNUSED dup ok +Destroy the thread-specific data @var{key} in the calling thread. The +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}) +@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}) +@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 +@c another call already made a decision to allocate it, thus losing +@c the allocated value. the seq number is updated before the +@c value, which might cause an earlier-generation value to seem +@c current if setspecific is cancelled or interrupted by a signal +@c KEY_UNUSED ok +@c calloc dup @ascuheap @acsmem +Associate the thread-specific @var{value} with @var{key} in the calling thread. +@end deftypefun + + +@node Non-POSIX Extensions +@section Non-POSIX Extensions + +In addition to implementing the POSIX API for threads, @theglibc{} provides +additional functions and interfaces to provide functionality not specified in +the standard. + +@menu +* Default Thread Attributes:: Setting default attributes for + threads in a process. +@end menu + +@node Default Thread Attributes +@subsection Setting Process-wide defaults for thread attributes + +@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}) +@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 +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}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} +@c pthread_setattr_default_np @ascuheap @asulock @aculock @acsmem +@c check_sched_policy_attr ok +@c check_sched_priority_attr ok +@c sched_get_priority_min dup ok +@c sched_get_priority_max dup ok +@c check_cpuset_attr ok +@c determine_cpumask_size ok +@c check_stacksize_attr ok +@c lll_lock @asulock @aculock +@c free dup @ascuheap @acsmem +@c realloc dup @ascuheap @acsmem +@c memcpy dup ok +@c lll_unlock @asulock @aculock +Set the default attribute values to match the values in @var{attr}. The +function returns @math{0} on success and a non-zero error code on failure. +The following error codes are defined for this function: + +@table @code +@item EINVAL +At least one of the values in @var{attr} does not qualify as valid for the +attributes or the stack address is set in the attribute. +@item ENOMEM +The system does not have sufficient memory. +@end table +@end deftypefun + +@c FIXME these are undocumented: +@c pthread_atfork +@c pthread_attr_destroy +@c pthread_attr_getaffinity_np +@c pthread_attr_getdetachstate +@c pthread_attr_getguardsize +@c pthread_attr_getinheritsched +@c pthread_attr_getschedparam +@c pthread_attr_getschedpolicy +@c pthread_attr_getscope +@c pthread_attr_getstack +@c pthread_attr_getstackaddr +@c pthread_attr_getstacksize +@c pthread_attr_init +@c pthread_attr_setaffinity_np +@c pthread_attr_setdetachstate +@c pthread_attr_setguardsize +@c pthread_attr_setinheritsched +@c pthread_attr_setschedparam +@c pthread_attr_setschedpolicy +@c pthread_attr_setscope +@c pthread_attr_setstack +@c pthread_attr_setstackaddr +@c pthread_attr_setstacksize +@c pthread_barrierattr_destroy +@c pthread_barrierattr_getpshared +@c pthread_barrierattr_init +@c pthread_barrierattr_setpshared +@c pthread_barrier_destroy +@c pthread_barrier_init +@c pthread_barrier_wait +@c pthread_cancel +@c pthread_cleanup_push +@c pthread_cleanup_pop +@c pthread_condattr_destroy +@c pthread_condattr_getclock +@c pthread_condattr_getpshared +@c pthread_condattr_init +@c pthread_condattr_setclock +@c pthread_condattr_setpshared +@c pthread_cond_broadcast +@c pthread_cond_destroy +@c pthread_cond_init +@c pthread_cond_signal +@c pthread_cond_timedwait +@c pthread_cond_wait +@c pthread_create +@c pthread_detach +@c pthread_equal +@c pthread_exit +@c pthread_getaffinity_np +@c pthread_getattr_np +@c pthread_getconcurrency +@c pthread_getcpuclockid +@c pthread_getname_np +@c pthread_getschedparam +@c pthread_join +@c pthread_kill +@c pthread_kill_other_threads_np +@c pthread_mutexattr_destroy +@c pthread_mutexattr_getkind_np +@c pthread_mutexattr_getprioceiling +@c pthread_mutexattr_getprotocol +@c pthread_mutexattr_getpshared +@c pthread_mutexattr_getrobust +@c pthread_mutexattr_getrobust_np +@c pthread_mutexattr_gettype +@c pthread_mutexattr_init +@c pthread_mutexattr_setkind_np +@c pthread_mutexattr_setprioceiling +@c pthread_mutexattr_setprotocol +@c pthread_mutexattr_setpshared +@c pthread_mutexattr_setrobust +@c pthread_mutexattr_setrobust_np +@c pthread_mutexattr_settype +@c pthread_mutex_consistent +@c pthread_mutex_consistent_np +@c pthread_mutex_destroy +@c pthread_mutex_getprioceiling +@c pthread_mutex_init +@c pthread_mutex_lock +@c pthread_mutex_setprioceiling +@c pthread_mutex_timedlock +@c pthread_mutex_trylock +@c pthread_mutex_unlock +@c pthread_once +@c pthread_rwlockattr_destroy +@c pthread_rwlockattr_getkind_np +@c pthread_rwlockattr_getpshared +@c pthread_rwlockattr_init +@c pthread_rwlockattr_setkind_np +@c pthread_rwlockattr_setpshared +@c pthread_rwlock_destroy +@c pthread_rwlock_init +@c pthread_rwlock_rdlock +@c pthread_rwlock_timedrdlock +@c pthread_rwlock_timedwrlock +@c pthread_rwlock_tryrdlock +@c pthread_rwlock_trywrlock +@c pthread_rwlock_unlock +@c pthread_rwlock_wrlock +@c pthread_self +@c pthread_setaffinity_np +@c pthread_setcancelstate +@c pthread_setcanceltype +@c pthread_setconcurrency +@c pthread_setname_np +@c pthread_setschedparam +@c pthread_setschedprio +@c pthread_sigmask +@c pthread_sigqueue +@c pthread_spin_destroy +@c pthread_spin_init +@c pthread_spin_lock +@c pthread_spin_trylock +@c pthread_spin_unlock +@c pthread_testcancel +@c pthread_timedjoin_np +@c pthread_tryjoin_np +@c pthread_yield diff -urN glibc-2.17-c758a686/manual/time.texi glibc-2.17-c758a686/manual/time.texi --- glibc-2.17-c758a686/manual/time.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/time.texi 2014-09-12 16:10:06.044792719 -0400 @@ -79,6 +79,7 @@ @comment time.h @comment ISO @deftypefun double difftime (time_t @var{time1}, time_t @var{time0}) +@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 a value of type @code{double}. The difference ignores leap seconds @@ -246,6 +247,12 @@ @comment time.h @comment ISO @deftypefun clock_t clock (void) +@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, +@c calls times and adds utime and stime. On bsd, calls getrusage and +@c safely converts stime and utime to clock. On linux, calls +@c clock_gettime. This function returns the calling process' current CPU time. If the CPU time is not available or cannot be represented, @code{clock} returns the value @code{(clock_t)(-1)}. @@ -310,6 +317,12 @@ @comment sys/times.h @comment POSIX.1 @deftypefun clock_t times (struct tms *@var{buffer}) +@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 +@c compute the real time. On BSD, it calls getclktck, getrusage (twice) +@c and time. On Linux, it's a syscall with special handling to account +@c for clock_t counts that look like error values. The @code{times} function stores the processor time information for the calling process in @var{buffer}. @@ -409,6 +422,7 @@ @comment time.h @comment ISO @deftypefun time_t time (time_t *@var{result}) +@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, the calendar time value is also stored in @code{*@var{result}}. If the @@ -420,7 +434,9 @@ @c Linux. @comment time.h @comment SVID, XPG -@deftypefun int stime (time_t *@var{newtime}) +@deftypefun int stime (const time_t *@var{newtime}) +@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 current calendar time is @var{newtime}, where @code{newtime} is interpreted as described in the above definition of @code{time_t}. @@ -475,6 +491,12 @@ @comment sys/time.h @comment BSD @deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp}) +@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 +@c localtime_r, saving and restoring tzname in an unsafe manner. +@c On some GNU/Linux variants, ifunc resolvers are used in shared libc +@c for vdso resolution. ifunc-vdso-revisit. The @code{gettimeofday} function returns the current calendar time as the elapsed time since the epoch in the @code{struct timeval} structure indicated by @var{tp}. (@pxref{Elapsed Time} for a description of @@ -498,6 +520,9 @@ @comment sys/time.h @comment BSD @deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp}) +@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. The @code{settimeofday} function sets the current calendar time in the system clock according to the arguments. As for @code{gettimeofday}, the calendar time is represented as the elapsed time since the epoch. @@ -539,6 +564,10 @@ @comment sys/time.h @comment BSD @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta}) +@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 +@c a syscall. This function speeds up or slows down the system clock in order to make a gradual adjustment. This ensures that the calendar time reported by the system clock is always monotonically increasing, which might not @@ -577,6 +606,8 @@ @comment sys/timex.h @comment GNU @deftypefun int adjtimex (struct timex *@var{timex}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c It's a syscall, only available on linux. @code{adjtimex} is functionally identical to @code{ntp_adjtime}. @xref{High Accuracy Clock}. @@ -674,6 +705,10 @@ @comment time.h @comment ISO @deftypefun {struct tm *} localtime (const time_t *@var{time}) +@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 +@c tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd The @code{localtime} function converts the simple time pointed to by @var{time} to broken-down time representation, expressed relative to the user's specified time zone. @@ -687,9 +722,8 @@ as a broken-down time; typically this is because the year cannot fit into an @code{int}. -Calling @code{localtime} has one other effect: it sets the variable -@code{tzname} with information about the current time zone. @xref{Time -Zone Functions}. +Calling @code{localtime} also sets the current time zone as if +@code{tzset} were called. @xref{Time Zone Functions}. @end deftypefun Using the @code{localtime} function is a big problem in multi-threaded @@ -699,6 +733,87 @@ @comment time.h @comment POSIX.1c @deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp}) +@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 +@c libc_lock_lock dup @asulock @aculock +@c tzset_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c always called with tzset_lock held +@c sets static is_initialized before initialization; +@c reads and sets old_tz; sets tz_rules. +@c some of the issues only apply on the first call. +@c subsequent calls only trigger these when called by localtime; +@c otherwise, they're ok. +@c getenv dup @mtsenv +@c strcmp dup ok +@c strdup @ascuheap +@c tzfile_read @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c memcmp dup ok +@c strstr dup ok +@c getenv dup @mtsenv +@c asprintf dup @mtslocale @ascuheap @acsmem +@c stat64 dup ok +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fileno dup ok +@c fstat64 dup ok +@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd +@c free dup @ascuheap @acsmem +@c fsetlocking dup ok [no @mtasurace:stream @asulock, exclusive] +@c fread_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt] +@c memcpy dup ok +@c decode ok +@c bswap_32 dup ok +@c fseek dup ok [no @mtasurace:stream @asucorrupt @acucorrupt] +@c ftello dup ok [no @mtasurace:stream @asucorrupt @acucorrupt] +@c malloc dup @ascuheap @acsmem +@c decode64 ok +@c bswap_64 dup ok +@c getc_unlocked ok [no @mtasurace:stream @asucorrupt @acucorrupt] +@c tzstring dup @ascuheap @acsmem +@c compute_tzname_max dup ok [guarded by tzset_lock] +@c memset dup ok +@c update_vars ok [guarded by tzset_lock] +@c sets daylight, timezone, tzname and tzname_cur_max; +@c called only with tzset_lock held, unless tzset_parse_tz +@c (internal, but not static) gets called by users; given the its +@c double-underscore-prefixed name, this interface violation could +@c be regarded as undefined behavior. +@c strlen ok +@c tzset_parse_tz @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c sscanf dup @mtslocale @ascuheap @acsmem +@c isalnum dup @mtsenv +@c tzstring @ascuheap @acsmem +@c reads and changes tzstring_list without synchronization, but +@c only called with tzset_lock held (save for interface violations) +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c strcpy dup ok +@c isdigit dup @mtslocale +@c compute_offset ok +@c tzfile_default @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c sets tzname, timezone, types, zone_names, rule_*off, etc; no guards +@c strlen dup ok +@c tzfile_read dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c mempcpy dup ok +@c compute_tzname_max ok [if guarded by tzset_lock] +@c iterates over zone_names; no guards +@c free dup @ascuheap @acsmem +@c strtoul dup @mtslocale +@c update_vars dup ok +@c tzfile_compute(use_localtime) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c sets tzname; no guards. with !use_localtime, as in gmtime, it's ok +@c tzstring dup @acsuheap @acsmem +@c tzset_parse_tz dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c offtime dup ok +@c tz_compute dup ok +@c strcmp dup ok +@c offtime ok +@c isleap dup ok +@c tz_compute ok +@c compute_change ok +@c isleap ok +@c libc_lock_unlock dup @aculock + The @code{localtime_r} function works just like the @code{localtime} function. It takes a pointer to a variable containing a simple time and converts it to the broken-down time format. @@ -715,6 +830,9 @@ @comment time.h @comment ISO @deftypefun {struct tm *} gmtime (const time_t *@var{time}) +@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 This function is similar to @code{localtime}, except that the broken-down time is expressed as Coordinated Universal Time (UTC) (formerly called Greenwich Mean Time (GMT)) rather than relative to a local time zone. @@ -728,6 +846,15 @@ @comment time.h @comment POSIX.1c @deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp}) +@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 +@c about all possible AS and AC problems when it's first called. +@c Calling any of localtime,gmtime_r once would run the initialization +@c and avoid the heap, mem and fd issues in gmtime* in subsequent calls, +@c but the unsafe locking would remain. +@c gmtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c tz_convert(gmtime_r) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd This function is similar to @code{localtime_r}, except that it converts just like @code{gmtime} the given time as Coordinated Universal Time. @@ -739,30 +866,58 @@ @comment time.h @comment ISO @deftypefun time_t mktime (struct tm *@var{brokentime}) -The @code{mktime} function is used to convert a broken-down time structure -to a simple time representation. It also ``normalizes'' the contents of -the broken-down time structure, by filling in the day of week and day of -year based on the other date and time components. +@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 +@c once, used as an initial guess, and updated at the end, but not +@c used except as a guess for subsequent calls, so it should be safe. +@c Even though a compiler might delay the load and perform it multiple +@c times (bug 16346), there are at least two unconditional uses of the +@c auto variable in which the first load is stored, separated by a +@c call to an external function, and a conditional change of the +@c variable before the external call, so refraining from allocating a +@c local variable at the first load would be a very bad optimization. +@c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c mktime_internal(localtime_r) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c ydhms_diff ok +@c ranged_convert(localtime_r) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c *convert = localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c time_t_avg dup ok +@c guess_time_tm dup ok +@c ydhms_diff dup ok +@c time_t_add_ok ok +@c time_t_avg ok +@c isdst_differ ok +@c time_t_int_add_ok ok +The @code{mktime} function converts a broken-down time structure to a +simple time representation. It also normalizes the contents of the +broken-down time structure, and fills in some components based on the +values of the others. The @code{mktime} function ignores the specified contents of the -@code{tm_wday} and @code{tm_yday} members of the broken-down time +@code{tm_wday}, @code{tm_yday}, @code{tm_gmtoff}, and @code{tm_zone} +members of the broken-down time structure. It uses the values of the other components to determine the calendar time; it's permissible for these components to have unnormalized values outside their normal ranges. The last thing that @code{mktime} does is adjust the components of the @var{brokentime} -structure (including the @code{tm_wday} and @code{tm_yday}). +structure, including the members that were initially ignored. If the specified broken-down time cannot be represented as a simple time, @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify the contents of @var{brokentime}. -Calling @code{mktime} also sets the variable @code{tzname} with -information about the current time zone. @xref{Time Zone Functions}. +Calling @code{mktime} also sets the current time zone as if +@code{tzset} were called; @code{mktime} uses this information instead +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}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c Alias to mktime. @code{timelocal} is functionally identical to @code{mktime}, but more mnemonically named. Note that it is the inverse of the @code{localtime} @@ -776,6 +931,19 @@ @comment time.h @comment ??? @deftypefun time_t timegm (struct tm *@var{brokentime}) +@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. +@c although gmtime_r, as called by mktime, might save some issues, +@c tzset calls tzset_internal with always, which forces +@c reinitialization, so all issues may arise. +@c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c mktime_internal(gmtime_r) @asulock @aculock +@c ..gmtime_r @asulock @aculock +@c ... dup ok +@c tz_convert(!use_localtime) @asulock @aculock +@c ... dup @asulock @aculock +@c tzfile_compute(!use_localtime) ok @code{timegm} is functionally identical to @code{mktime} except it always takes the input values to be Coordinated Universal Time (UTC) @@ -837,6 +1005,8 @@ @comment sys/timex.h @comment GNU @deftypefun int ntp_gettime (struct ntptimeval *@var{tptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Wrapper for adjtimex. The @code{ntp_gettime} function sets the structure pointed to by @var{tptr} to current values. The elements of the structure afterwards contain the values the timer implementation in the kernel assumes. They @@ -954,6 +1124,8 @@ @comment sys/timex.h @comment GNU @deftypefun int ntp_adjtime (struct timex *@var{tptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Alias to adjtimex syscall. The @code{ntp_adjtime} function sets the structure specified by @var{tptr} to current values. @@ -1008,6 +1180,13 @@ @comment time.h @comment ISO @deftypefun {char *} asctime (const struct tm *@var{brokentime}) +@safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}} +@c asctime @mtasurace:asctime @mtslocale +@c Uses a static buffer. +@c asctime_internal @mtslocale +@c snprintf dup @mtslocale [no @acsuheap @acsmem] +@c ab_day_name @mtslocale +@c ab_month_name @mtslocale The @code{asctime} function converts the broken-down time value that @var{brokentime} points to into a string in a standard format: @@ -1031,6 +1210,9 @@ @comment time.h @comment POSIX.1c @deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c asctime_r @mtslocale +@c asctime_internal dup @mtslocale This function is similar to @code{asctime} but instead of placing the result in a static buffer it writes the string in the buffer pointed to by the parameter @var{buffer}. This buffer should have room @@ -1045,6 +1227,10 @@ @comment time.h @comment ISO @deftypefun {char *} ctime (const time_t *@var{time}) +@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 +@c asctime dup @mtasurace:asctime @mtslocale The @code{ctime} function is similar to @code{asctime}, except that you specify the calendar time argument as a @code{time_t} simple time value rather than in broken-down local time format. It is equivalent to @@ -1053,13 +1239,17 @@ asctime (localtime (@var{time})) @end smallexample -@code{ctime} sets the variable @code{tzname}, because @code{localtime} -does so. @xref{Time Zone Functions}. +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}) +@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 +@c asctime_r dup @mtslocale This function is similar to @code{ctime}, but places the result in the string pointed to by @var{buffer}. It is equivalent to (written using gcc extensions, @pxref{Statement Exprs,,,gcc,Porting and Using gcc}): @@ -1077,17 +1267,75 @@ @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}) +@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 +@c strftime_internal @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c add ok +@c memset_zero dup ok +@c memset_space dup ok +@c strlen dup ok +@c mbrlen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps] +@c mbsinit dup ok +@c cpy ok +@c add dup ok +@c memcpy_lowcase ok +@c TOLOWER ok +@c tolower_l ok +@c memcpy_uppcase ok +@c TOUPPER ok +@c toupper_l ok +@c MEMCPY ok +@c memcpy dup ok +@c ISDIGIT ok +@c STRLEN ok +@c strlen dup ok +@c strftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c TOUPPER dup ok +@c nl_get_era_entry @ascuheap @asulock @acsmem @aculock +@c nl_init_era_entries @ascuheap @asulock @acsmem @aculock +@c libc_rwlock_wrlock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c memset dup ok +@c free dup @ascuheap @acsmem +@c realloc dup @ascuheap @acsmem +@c memcpy dup ok +@c strchr dup ok +@c wcschr dup ok +@c libc_rwlock_unlock dup @asulock @aculock +@c ERA_DATE_CMP ok +@c DO_NUMBER ok +@c DO_NUMBER_SPACEPAD ok +@c nl_get_alt_digit @ascuheap @asulock @acsmem @aculock +@c libc_rwlock_wrlock dup @asulock @aculock +@c nl_init_alt_digit @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c memset dup ok +@c strchr dup ok +@c libc_rwlock_unlock dup @aculock +@c memset_space ok +@c memset dup ok +@c memset_zero ok +@c memset dup ok +@c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c iso_week_days ok +@c isleap ok +@c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c gmtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c tm_diff ok This function is similar to the @code{sprintf} function (@pxref{Formatted Input}), but the conversion specifications that can appear in the format template @var{template} are specialized for printing components of the date and time @var{brokentime} according to the locale currently specified for -time conversion (@pxref{Locales}). +time conversion (@pxref{Locales}) and the current time zone +(@pxref{Time Zone Functions}). Ordinary characters appearing in the @var{template} are copied to the output string @var{s}; this can include multibyte character sequences. Conversion specifiers are introduced by a @samp{%} character, followed by an optional flag which can be one of the following. These flags -are all GNU extensions. The first three affect only the output of +are all GNU extensions. The first three affect only the output of numbers: @table @code @@ -1392,9 +1640,10 @@ If @var{s} is a null pointer, @code{strftime} does not actually write anything, but instead returns the number of characters it would have written. -According to POSIX.1 every call to @code{strftime} implies a call to -@code{tzset}. So the contents of the environment variable @code{TZ} -is examined before any output is produced. +Calling @code{strftime} also sets the current time zone as if +@code{tzset} were called; @code{strftime} uses this information +instead of @var{brokentime}'s @code{tm_gmtoff} and @code{tm_zone} +members. @xref{Time Zone Functions}. For an example of @code{strftime}, see @ref{Time Functions Example}. @end deftypefun @@ -1402,6 +1651,53 @@ @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}) +@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 +@c wcsftime_internal @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c add ok +@c memset_zero dup ok +@c memset_space dup ok +@c wcslen dup ok +@c cpy ok +@c add dup ok +@c memcpy_lowcase ok +@c TOLOWER ok +@c towlower_l dup ok +@c memcpy_uppcase ok +@c TOUPPER ok +@c towupper_l dup ok +@c MEMCPY ok +@c wmemcpy dup ok +@c widen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c memset dup ok +@c mbsrtowcs_l @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps] +@c ISDIGIT ok +@c STRLEN ok +@c wcslen dup ok +@c wcsftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c TOUPPER dup ok +@c nl_get_era_entry dup @ascuheap @asulock @acsmem @aculock +@c DO_NUMBER ok +@c DO_NUMBER_SPACEPAD ok +@c nl_get_walt_digit dup @ascuheap @asulock @acsmem @aculock +@c libc_rwlock_wrlock dup @asulock @aculock +@c nl_init_alt_digit dup @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c memset dup ok +@c wcschr dup ok +@c libc_rwlock_unlock dup @aculock +@c memset_space ok +@c wmemset dup ok +@c memset_zero ok +@c wmemset dup ok +@c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c iso_week_days ok +@c isleap ok +@c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c gmtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c tm_diff ok The @code{wcsftime} function is equivalent to the @code{strftime} function with the difference that it operates on wide character strings. The buffer where the result is stored, pointed to by @var{s}, @@ -1452,6 +1748,32 @@ @comment time.h @comment XPG4 @deftypefun {char *} strptime (const char *@var{s}, const char *@var{fmt}, struct tm *@var{tp}) +@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 +@c memset dup ok +@c ISSPACE ok +@c isspace_l dup ok +@c match_char ok +@c match_string ok +@c strlen dup ok +@c strncasecmp_l dup ok +@c strcmp dup ok +@c recursive @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c strptime_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c get_number ok +@c ISSPACE dup ok +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c nl_select_era_entry @ascuheap @asulock @acsmem @aculock +@c nl_init_era_entries dup @ascuheap @asulock @acsmem @aculock +@c get_alt_number dup @ascuheap @asulock @acsmem @aculock +@c nl_parse_alt_digit dup @ascuheap @asulock @acsmem @aculock +@c libc_rwlock_wrlock dup @asulock @aculock +@c nl_init_alt_digit dup @ascuheap @acsmem +@c libc_rwlock_unlock dup @aculock +@c get_number dup ok +@c day_of_the_week ok +@c day_of_the_year ok The @code{strptime} function parses the input string @var{s} according to the format string @var{fmt} and stores its results in the structure @var{tp}. @@ -1865,6 +2187,9 @@ @comment time.h @comment Unix98 @deftypefun {struct tm *} getdate (const char *@var{string}) +@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 The interface to @code{getdate} is the simplest possible for a function to parse a string and return the value. @var{string} is the input string and the result is returned in a statically-allocated variable. @@ -1976,6 +2301,30 @@ @comment time.h @comment GNU @deftypefun int getdate_r (const char *@var{string}, struct tm *@var{tp}) +@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 +@c stat64 dup ok +@c access dup ok +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fsetlocking dup ok [no @mtasurace:stream @asulock, exclusive] +@c isspace dup @mtslocale +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd +@c memcpy dup ok +@c getline dup @ascuheap @acsmem [no @asucorrupt @aculock @acucorrupt, exclusive] +@c strptime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c feof_unlocked dup ok +@c free dup @ascuheap @acsmem +@c ferror_unlocked dup dup ok +@c time dup ok +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c first_wday @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c memset dup ok +@c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c check_mday ok +@c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd The @code{getdate_r} function is the reentrant counterpart of @code{getdate}. It does not use the global variable @code{getdate_err} to signal an error, but instead returns an error code. The same error @@ -2037,7 +2386,7 @@ [@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]]. This is positive if the local time zone is west of the Prime Meridian and negative if it is east. The hour must be between @code{0} and -@code{23}, and the minute and seconds between @code{0} and @code{59}. +@code{24}, and the minute and seconds between @code{0} and @code{59}. For example, here is how we would specify Eastern Standard Time, but without any Daylight Saving Time alternative: @@ -2082,17 +2431,51 @@ The @var{time} fields specify when, in the local time currently in effect, the change to the other time occurs. If omitted, the default is -@code{02:00:00}. - -For example, here is how you would specify the Eastern time zone in the -United States, including the appropriate Daylight Saving Time and its dates -of applicability. The normal offset from UTC is 5 hours; since this is +@code{02:00:00}. The hours part of the time fields can range from +@minus{}167 through 167; this is an extension to POSIX.1, which allows +only the range 0 through 24. + +Here are some example @code{TZ} values, including the appropriate +Daylight Saving Time and its dates of applicability. In North +American Eastern Standard Time (EST) and Eastern Daylight Time (EDT), +the normal offset from UTC is 5 hours; since this is west of the prime meridian, the sign is positive. Summer time begins on -the first Sunday in April at 2:00am, and ends on the last Sunday in October +March's second Sunday at 2:00am, and ends on November's first Sunday at 2:00am. @smallexample -EST+5EDT,M4.1.0/2,M10.5.0/2 +EST+5EDT,M3.2.0/2,M11.1.0/2 +@end smallexample + +Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours +ahead of the prime meridian in winter, springing forward an hour on +March's fourth Thursday at 26:00 (i.e., 02:00 on the first Friday on or +after March 23), and falling back on October's last Sunday at 02:00. + +@smallexample +IST-2IDT,M3.4.4/26,M10.5.0 +@end smallexample + +Western Argentina Summer Time (WARST) is 3 hours behind the prime +meridian all year. There is a dummy fall-back transition on December +31 at 25:00 daylight saving time (i.e., 24:00 standard time, +equivalent to January 1 at 00:00 standard time), and a simultaneous +spring-forward transition on January 1 at 00:00 standard time, so +daylight saving time is in effect all year and the initial @code{WART} +is a placeholder. + +@smallexample +WART4WARST,J1/0,J365/25 +@end smallexample + +Western Greenland Time (WGT) and Western Greenland Summer Time (WGST) +are 3 hours behind UTC in the winter. Its clocks follow the European +Union rules of springing forward by one hour on March's last Sunday at +01:00 UTC (@minus{}02:00 local time) and falling back on October's +last Sunday at 01:00 UTC (@minus{}01:00 local time). + +@smallexample +WGT3WGST,M3.5.0/-2,M10.5.0/-1 @end smallexample The schedule of Daylight Saving Time in any particular jurisdiction has @@ -2177,6 +2560,11 @@ @comment time.h @comment POSIX.1 @deftypefun void tzset (void) +@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 +@c tzset_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_lock_unlock dup @aculock The @code{tzset} function initializes the @code{tzname} variable from the value of the @code{TZ} environment variable. It is not usually necessary for your program to call this function, because it is called @@ -2314,7 +2702,16 @@ @comment sys/time.h @comment BSD -@deftypefun int setitimer (int @var{which}, struct itimerval *@var{new}, struct itimerval *@var{old}) +@deftypefun int setitimer (int @var{which}, const struct itimerval *@var{new}, struct itimerval *@var{old}) +@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 +@c may interfere with timers set by another thread. This interference +@c is not regarded as destructive, because the interface specification +@c makes this overriding while returning the previous value the expected +@c behavior, and the kernel will serialize concurrent calls so that the +@c last one prevails, with each call getting the timer information from +@c the timer installed by the previous call in that serialization. The @code{setitimer} function sets the timer specified by @var{which} according to @var{new}. The @var{which} argument can have a value of @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}. @@ -2335,6 +2732,7 @@ @comment sys/time.h @comment BSD @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old}) +@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}. @@ -2367,6 +2765,8 @@ @comment unistd.h @comment POSIX.1 @deftypefun {unsigned int} alarm (unsigned int @var{seconds}) +@safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}} +@c Wrapper for setitimer. The @code{alarm} function sets the real-time timer to expire in @var{seconds} seconds. If you want to cancel any existing alarm, you can do this by calling @code{alarm} with a @var{seconds} argument of @@ -2426,6 +2826,10 @@ @comment unistd.h @comment POSIX.1 @deftypefun {unsigned int} sleep (unsigned int @var{seconds}) +@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 +@c AS-Unsafe, and in a way that makes it AC-Unsafe (C-unsafe, even!). The @code{sleep} function waits for @var{seconds} or until a signal is delivered, whichever happens first. @@ -2470,6 +2874,9 @@ @comment time.h @comment POSIX.1 @deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c On Linux, it's a syscall. On Mach, it calls gettimeofday and uses +@c ports. If resolution to seconds is not enough the @code{nanosleep} function can be used. As the name suggests the sleep interval can be specified in nanoseconds. The actual elapsed time of the sleep interval might be diff -urN glibc-2.17-c758a686/manual/tsort.awk glibc-2.17-c758a686/manual/tsort.awk --- glibc-2.17-c758a686/manual/tsort.awk 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/tsort.awk 2014-09-12 16:10:06.043792722 -0400 @@ -1,6 +1,6 @@ #! /usr/bin/awk -f # Generate topologically sorted list of manual chapters. -# (C) Copyright 1998, 1999 Free Software Foundation, Inc. +# Copyright (C) 1998-2014 Free Software Foundation, Inc. # Written by Ulrich Drepper , 1998. BEGIN { diff -urN glibc-2.17-c758a686/manual/users.texi glibc-2.17-c758a686/manual/users.texi --- glibc-2.17-c758a686/manual/users.texi 2012-12-24 22:02:13.000000000 -0500 +++ glibc-2.17-c758a686/manual/users.texi 2014-09-12 16:10:06.043792722 -0400 @@ -71,7 +71,7 @@ @cindex group ID Users are classified in @dfn{groups}. Each user name belongs to one @dfn{default group} and may also belong to any number of -@dfn{supplementary groups}. Users who are members of the same group can +@dfn{supplementary groups}. Users who are members of the same group can share resources (such as files) that are not accessible to users who are not a member of that group. Each group has a @dfn{group name} and @dfn{group ID}. @xref{Group Database}, for how to find information @@ -221,30 +221,37 @@ @comment unistd.h @comment POSIX.1 @deftypefun uid_t getuid (void) +@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) +@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) +@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) +@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}) +@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 stored in the array @var{groups}; the return value from the function is @@ -291,6 +298,34 @@ @comment unistd.h @comment POSIX.1 @deftypefun int seteuid (uid_t @var{neweuid}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c seteuid @asulock @aculock +@c INLINE_SETXID_SYSCALL @asulock @aculock +@c This may be just a unix syscall, or the ugliness below used by +@c nptl to propagate the syscall to all cloned processes used to +@c implement threads. +@c nptl_setxid @asulock @aculock +@c while holding the stack_alloc_lock, mark with SETXID_BITMASK all +@c threads that are not exiting, signal them until no thread remains +@c marked, clear the marks and run the syscall, then release the lock. +@c lll_lock @asulock @aculock +@c list_for_each ok +@c list_entry ok +@c setxid_mark_thread ok +@c if a thread is initializing, wait for it to be cloned. +@c mark it with SETXID_BITMASK if it's not exiting +@c setxid_signal_thread ok +@c if a thread is marked with SETXID_BITMASK, +@c send it the SIGSETXID signal +@c setxid_unmark_thread ok +@c clear SETXID_BITMASK and release the futex if SETXID_BITMASK is +@c set. +@c ok +@c lll_unlock @aculock +@c +@c sighandler_setxid ok +@c issue the syscall, clear SETXID_BITMASK, release the futex, and +@c wake up the signaller loop if the counter reached zero. This function sets the effective user ID of a process to @var{neweuid}, provided that the process is allowed to change its effective user ID. A privileged process (effective user ID zero) can change its effective @@ -318,6 +353,9 @@ @comment unistd.h @comment POSIX.1 @deftypefun int setuid (uid_t @var{newuid}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c setuid @asulock @aculock +@c INLINE_SETXID_SYSCALL dup @asulock @aculock If the calling process is privileged, this function sets both the real and effective user ID of the process to @var{newuid}. It also deletes the file user ID of the process, if any. @var{newuid} may be any @@ -334,6 +372,9 @@ @comment unistd.h @comment BSD @deftypefun int setreuid (uid_t @var{ruid}, uid_t @var{euid}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c setreuid @asulock @aculock +@c INLINE_SETXID_SYSCALL dup @asulock @aculock This function sets the real user ID of the process to @var{ruid} and the effective user ID to @var{euid}. If @var{ruid} is @code{-1}, it means not to change the real user ID; likewise if @var{euid} is @code{-1}, it @@ -369,6 +410,9 @@ @comment unistd.h @comment POSIX.1 @deftypefun int setegid (gid_t @var{newgid}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c setegid @asulock @aculock +@c INLINE_SETXID_SYSCALL dup @asulock @aculock This function sets the effective group ID of the process to @var{newgid}, provided that the process is allowed to change its group ID. Just as with @code{seteuid}, if the process is privileged it may @@ -388,6 +432,9 @@ @comment unistd.h @comment POSIX.1 @deftypefun int setgid (gid_t @var{newgid}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c setgid @asulock @aculock +@c INLINE_SETXID_SYSCALL dup @asulock @aculock This function sets both the real and effective group ID of the process to @var{newgid}, provided that the process is privileged. It also deletes the file group ID, if any. @@ -402,6 +449,9 @@ @comment unistd.h @comment BSD @deftypefun int setregid (gid_t @var{rgid}, gid_t @var{egid}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c setregid @asulock @aculock +@c INLINE_SETXID_SYSCALL dup @asulock @aculock This function sets the real group ID of the process to @var{rgid} and the effective group ID to @var{egid}. If @var{rgid} is @code{-1}, it means not to change the real group ID; likewise if @var{egid} is @@ -437,7 +487,10 @@ @comment grp.h @comment BSD -@deftypefun int setgroups (size_t @var{count}, gid_t *@var{groups}) +@deftypefun int setgroups (size_t @var{count}, const gid_t *@var{groups}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c setgroups @asulock @aculock +@c INLINE_SETXID_SYSCALL dup @asulock @aculock This function sets the process's supplementary group IDs. It can only be called from privileged processes. The @var{count} argument specifies the number of group IDs in the array @var{groups}. @@ -455,6 +508,36 @@ @comment grp.h @comment BSD @deftypefun int initgroups (const char *@var{user}, gid_t @var{group}) +@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 +@c MIN dup ok +@c malloc @ascuheap @acsmem +@c internal_getgrouplist @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nscd_getgrouplist @ascuheap @acsfd @acsmem +@c nscd_get_map_ref dup @ascuheap @acsfd @acsmem +@c nscd_cache_search dup ok +@c nscd_open_socket dup @acsfd +@c realloc dup @ascuheap @acsmem +@c readall dup ok +@c memcpy dup ok +@c close_not_cancel_no_status dup @acsfd +@c nscd_drop_map_ref dup @ascuheap @acsmem +@c nscd_unmap dup @ascuheap @acsmem +@c nss_database_lookup dup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock +@c nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c compat_call @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c sysconf(_SC_GETGR_R_SIZE_MAX) ok +@c nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *getgrent_fct @ascuplugin +@c *setgrent_fct @ascuplugin +@c *endgrent_fct @ascuplugin +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c *initgroups_dyn_fct @ascuplugin +@c nss_next_action dup ok +@c setgroups dup @asulock @aculock +@c free dup @ascuheap @acsmem The @code{initgroups} function sets the process's supplementary group IDs to be the normal default for the user name @var{user}. The group @var{group} is automatically included. @@ -476,6 +559,13 @@ @comment grp.h @comment BSD @deftypefun int getgrouplist (const char *@var{user}, gid_t @var{group}, gid_t *@var{groups}, int *@var{ngroups}) +@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 +@c malloc dup @ascuheap @acsmem +@c internal_getgrouplist dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c memcpy dup ok +@c free dup @ascuheap @acsmem The @code{getgrouplist} function scans the group database for all the groups @var{user} belongs to. Up to *@var{ngroups} group IDs corresponding to these groups are stored in the array @var{groups}; the @@ -740,7 +830,7 @@ Be cautious about using the @code{exec} functions in combination with changing the effective user ID. Don't let users of your program execute arbitrary programs under a changed user ID. Executing a shell is -especially bad news. Less obviously, the @code{execlp} and @code{execvp} +especially bad news. Less obviously, the @code{execlp} and @code{execvp} functions are a potential risk (since the program they execute depends on the user's @code{PATH} environment variable). @@ -792,6 +882,41 @@ @comment unistd.h @comment POSIX.1 @deftypefun {char *} getlogin (void) +@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 +@c getlogin_fd0 (unix) @mtasurace:getlogin @mtasurace:utent @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsfd @acsmem +@c uses static buffer name => @mtasurace:getlogin +@c ttyname_r dup @ascuheap @acsmem @acsfd +@c strncpy dup ok +@c setutent dup @mtasurace:utent @asulock @aculock @acsfd +@c getutline_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd +@c endutent dup @mtasurace:utent @asulock @aculock +@c libc_lock_unlock dup ok +@c strlen dup ok +@c memcpy dup ok +@c +@c getlogin_r (linux) @mtasurace:utent @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c getlogin_r_loginuid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c open_not_cancel_2 dup @acsfd +@c read_not_cancel dup ok +@c close_not_cancel_no_status dup @acsfd +@c strtoul @mtslocale +@c getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @asulock @aculock @acsfd @acsmem +@c strlen dup ok +@c memcpy dup ok +@c free dup @asulock @aculock @acsfd @acsmem +@c getlogin_r_fd0 (unix) @mtasurace:utent @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsmem @acsfd +@c ttyname_r dup @ascuheap @acsmem @acsfd +@c strncpy dup ok +@c libc_lock_lock dup @asulock @aculock +@c *libc_utmp_jump_table->setutent dup @mtasurace:utent @acsfd +@c *libc_utmp_jump_table->getutline_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer +@c *libc_utmp_jump_table->endutent dup @mtasurace:utent @asulock @aculock +@c libc_lock_unlock dup ok +@c strlen dup ok +@c memcpy dup ok The @code{getlogin} function returns a pointer to a string containing the name of the user logged in on the controlling terminal of the process, or a null pointer if this information cannot be determined. The string @@ -802,6 +927,11 @@ @comment stdio.h @comment POSIX.1 @deftypefun {char *} cuserid (char *@var{string}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c cuserid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c geteuid dup ok +@c getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c strncpy dup ok The @code{cuserid} function returns a pointer to a string containing a user name associated with the effective ID of the process. If @var{string} is not a null pointer, it should be an array that can hold @@ -1013,6 +1143,22 @@ @comment utmp.h @comment SVID @deftypefun void setutent (void) +@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 +@c cause the variables to be modified between calling this function and +@c others that rely on the internal state it sets up. + +@c setutent @mtasurace:utent @asulock @aculock @acsfd +@c libc_lock_lock dup @asulock @aculock +@c *libc_utmp_jump_table->setutent @mtasurace:utent @acsfd +@c setutent_unknown @mtasurace:utent @acsfd +@c *libc_utmp_file_functions.setutent = setutent_file @mtasurace:utent @acsfd +@c open_not_cancel_2 dup @acsfd +@c fcntl_not_cancel dup ok +@c close_not_cancel_no_status dup @acsfd +@c lseek64 dup ok +@c libc_lock_unlock dup ok This function opens the user accounting database to begin scanning it. You can then call @code{getutent}, @code{getutid} or @code{getutline} to read entries and @code{pututline} to write entries. @@ -1024,6 +1170,14 @@ @comment utmp.h @comment SVID @deftypefun {struct utmp *} getutent (void) +@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 +@c calls could malloc multiple buffers. + +@c getutent @mtuinit @mtasurace:utent @mtasurace:utentbuf @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsfd @acsmem +@c malloc @asulock @aculock @acsfd @acsmem +@c getutent_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd The @code{getutent} function reads the next entry from the user accounting database. It returns a pointer to the entry, which is statically allocated and may be overwritten by subsequent calls to @@ -1037,12 +1191,27 @@ @comment utmp.h @comment SVID @deftypefun void endutent (void) +@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} +@c endutent @mtasurace:utent @asulock @aculock @acsfd +@c libc_lock_lock dup @asulock @aculock +@c *libc_utmp_jump_table->endutent @mtasurace:utent @acsfd +@c endutent_unknown ok +@c endutent_file @mtasurace:utent @acsfd +@c close_not_cancel_no_status dup @acsfd +@c libc_lock_unlock dup ok This function closes the user accounting database. @end deftypefun @comment utmp.h @comment SVID @deftypefun {struct utmp *} getutid (const struct utmp *@var{id}) +@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c Same caveats as getutline. +@c +@c getutid @mtuinit @mtasurace:utent @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsmem @acsfd +@c uses a static buffer malloced on the first call +@c malloc dup @ascuheap @acsmem +@c getutid_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd This function searches forward from the current point in the database for an entry that matches @var{id}. If the @code{ut_type} member of the @var{id} structure is one of @code{RUN_LVL}, @code{BOOT_TIME}, @@ -1073,6 +1242,14 @@ @comment utmp.h @comment SVID @deftypefun {struct utmp *} getutline (const struct utmp *@var{line}) +@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 +@c calls could malloc multiple buffers. + +@c getutline @mtuinit @mtasurace:utent @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsfd @acsmem +@c malloc @asulock @aculock @acsfd @acsmem +@c getutline_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd This function searches forward from the current point in the database until it finds an entry whose @code{ut_type} value is @code{LOGIN_PROCESS} or @code{USER_PROCESS}, and whose @code{ut_line} @@ -1095,6 +1272,29 @@ @comment utmp.h @comment SVID @deftypefun {struct utmp *} pututline (const struct utmp *@var{utmp}) +@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 +@c *libc_utmp_jump_table->pututline @mtasurace:utent @mtascusig:ALRM @mtascutimer @acsfd +@c pututline_unknown @mtasurace:utent @acsfd +@c setutent_unknown dup @mtasurace:utent @acsfd +@c pututline_file @mtascusig:ALRM @mtascutimer @acsfd +@c TRANSFORM_UTMP_FILE_NAME ok +@c strcmp dup ok +@c acesss dup ok +@c open_not_cancel_2 dup @acsfd +@c fcntl_not_cancel dup ok +@c close_not_cancel_no_status dup @acsfd +@c llseek dup ok +@c dup2 dup ok +@c utmp_equal dup ok +@c internal_getut_r dup @mtascusig:ALRM @mtascutimer +@c LOCK_FILE dup @mtascusig:ALRM @mtasctimer +@c LOCKING_FAILED dup ok +@c ftruncate64 dup ok +@c write_not_cancel dup ok +@c UNLOCK_FILE dup @mtasctimer +@c libc_lock_unlock dup @aculock The @code{pututline} function inserts the entry @code{*@var{utmp}} at the appropriate place in the user accounting database. If it finds that it is not already at the correct place in the database, it uses @@ -1125,6 +1325,27 @@ @comment utmp.h @comment GNU @deftypefun int getutent_r (struct utmp *@var{buffer}, struct utmp **@var{result}) +@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 +@c *libc_utmp_jump_table->getutent_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @acsfd +@c getutent_r_unknown @mtasurace:utent @acsfd +@c setutent_unknown dup @mtasurace:utent @acsfd +@c getutent_r_file @mtasurace:utent @mtascusig:ALRM @mtascutimer +@c LOCK_FILE @mtascusig:ALRM @mtascutimer +@c alarm dup @mtascutimer +@c sigemptyset dup ok +@c sigaction dup ok +@c memset dup ok +@c fcntl_not_cancel dup ok +@c LOCKING_FAILED ok +@c read_not_cancel dup ok +@c UNLOCK_FILE @mtascutimer +@c fcntl_not_cancel dup ok +@c alarm dup @mtascutimer +@c sigaction dup ok +@c memcpy dup ok +@c libc_lock_unlock dup ok The @code{getutent_r} is equivalent to the @code{getutent} function. It returns the next entry from the database. But instead of storing the information in a static buffer it stores it in the buffer pointed to by @@ -1142,6 +1363,22 @@ @comment utmp.h @comment GNU @deftypefun int getutid_r (const struct utmp *@var{id}, struct utmp *@var{buffer}, struct utmp **@var{result}) +@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 +@c *libc_utmp_jump_table->getutid_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @acsfd +@c getutid_r_unknown @mtasurace:utent @acsfd +@c setutent_unknown dup @mtasurace:utent @acsfd +@c getutid_r_file @mtascusig:ALRM @mtascutimer +@c internal_getut_r @mtascusig:ALRM @mtascutimer +@c LOCK_FILE dup @mtascusig:ALRM @mtascutimer +@c LOCKING_FAILED dup ok +@c read_not_cancel dup ok +@c utmp_equal ok +@c strncmp dup ok +@c UNLOCK_FILE dup @mtascutimer +@c memcpy dup ok +@c libc_lock_unlock dup @aculock This function retrieves just like @code{getutid} the next entry matching the information stored in @var{id}. But the result is stored in the buffer pointed to by the parameter @var{buffer}. @@ -1157,6 +1394,28 @@ @comment utmp.h @comment GNU @deftypefun int getutline_r (const struct utmp *@var{line}, struct utmp *@var{buffer}, struct utmp **@var{result}) +@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 +@c *libc_utmp_jump_table->getutline_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @acsfd +@c getutline_r_unknown @mtasurace:utent @acsfd +@c setutent_unknown dup @mtasurace:utent @acsfd +@c getutline_r_file @mtasurace:utent @mtascusig:ALRM @mtascutimer +@c LOCK_FILE @mtascusig:ALRM @mtascutimer +@c alarm dup @mtascutimer +@c sigemptyset dup ok +@c sigaction dup ok +@c memset dup ok +@c fcntl_not_cancel dup ok +@c LOCKING_FAILED ok +@c read_not_cancel dup ok +@c strncmp dup ok +@c UNLOCK_FILE @mtascutimer +@c fcntl_not_cancel dup ok +@c alarm dup @mtascutimer +@c sigaction dup ok +@c memcpy dup ok +@c libc_lock_unlock dup ok This function retrieves just like @code{getutline} the next entry matching the information stored in @var{line}. But the result is stored in the buffer pointed to by the parameter @var{buffer}. @@ -1180,6 +1439,14 @@ @comment utmp.h @comment SVID @deftypefun int utmpname (const char *@var{file}) +@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 +@c *libc_utmp_jump_table->endutent dup @mtasurace:utent +@c strcmp dup ok +@c free dup @ascuheap @acsmem +@c strdup dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock The @code{utmpname} function changes the name of the database to be examined to @var{file}, and closes any previously opened database. By default @code{getutent}, @code{getutid}, @code{getutline} and @@ -1208,6 +1475,18 @@ @comment utmp.h @comment SVID @deftypefun void updwtmp (const char *@var{wtmp_file}, const struct utmp *@var{utmp}) +@safety{@prelim{}@mtunsafe{@mtascusig{:ALRM} @mtascutimer{}}@asunsafe{}@acunsafe{@acsfd{}}} +@c updwtmp @mtascusig:ALRM @mtascutimer @acsfd +@c TRANSFORM_UTMP_FILE_NAME dup ok +@c *libc_utmp_file_functions->updwtmp = updwtmp_file @mtascusig:ALRM @mtascutimer @acsfd +@c open_not_cancel_2 dup @acsfd +@c LOCK_FILE dup @mtascusig:ALRM @mtascutimer +@c LOCKING_FAILED dup ok +@c lseek64 dup ok +@c ftruncate64 dup ok +@c write_not_cancel dup ok +@c UNLOCK_FILE dup @mtascutimer +@c close_not_cancel_no_status dup @acsfd The @code{updwtmp} function appends the entry *@var{utmp} to the database specified by @var{wtmp_file}. For possible values for the @var{wtmp_file} argument see the @code{utmpname} function. @@ -1330,6 +1609,7 @@ @comment utmpx.h @comment XPG4.2 @deftypefun void setutxent (void) +@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 @@ -1337,6 +1617,7 @@ @comment utmpx.h @comment XPG4.2 @deftypefun {struct utmpx *} getutxent (void) +@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}. @@ -1345,6 +1626,7 @@ @comment utmpx.h @comment XPG4.2 @deftypefun void endutxent (void) +@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 @@ -1352,6 +1634,7 @@ @comment utmpx.h @comment XPG4.2 @deftypefun {struct utmpx *} getutxid (const struct utmpx *@var{id}) +@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}. @@ -1360,6 +1643,7 @@ @comment utmpx.h @comment XPG4.2 @deftypefun {struct utmpx *} getutxline (const struct utmpx *@var{line}) +@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}. @@ -1368,6 +1652,7 @@ @comment utmpx.h @comment XPG4.2 @deftypefun {struct utmpx *} pututxline (const struct utmpx *@var{utmp}) +@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 utmp}. In @theglibc{}, @code{pututxline} is simply an alias for @@ -1377,6 +1662,7 @@ @comment utmpx.h @comment XPG4.2 @deftypefun int utmpxname (const char *@var{file}) +@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 alias for @code{utmpname}. @@ -1391,6 +1677,7 @@ @comment utmp.h @comment GNU @deftypefun int getutmp (const struct utmpx *@var{utmpx}, struct utmp *@var{utmp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{getutmp} copies the information, insofar as the structures are compatible, from @var{utmpx} to @var{utmp}. @end deftypefun @@ -1399,6 +1686,7 @@ @comment utmp.h @comment GNU @deftypefun int getutmpx (const struct utmp *@var{utmp}, struct utmpx *@var{utmpx}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @code{getutmpx} copies the information, insofar as the structures are compatible, from @var{utmp} to @var{utmpx}. @end deftypefun @@ -1418,6 +1706,17 @@ @comment utmp.h @comment BSD @deftypefun int login_tty (int @var{filedes}) +@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. +@c Should there be a safety annotation for this? +@c login_tty @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd +@c setsid dup ok +@c ioctl dup ok +@c ttyname dup @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd +@c close dup @acsfd +@c open dup @acsfd +@c dup2 dup ok This function makes @var{filedes} the controlling terminal of the current process, redirects standard input, standard output and standard error output to this terminal, and closes @var{filedes}. @@ -1429,6 +1728,24 @@ @comment utmp.h @comment BSD @deftypefun void login (const struct utmp *@var{entry}) +@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 +@c tty_name @ascuheap @acucorrupt @acsmem @acsfd +@c ttyname_r dup @ascuheap @acsmem @acsfd +@c memchr dup ok +@c realloc dup @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c strncmp dup ok +@c basename dup ok +@c strncpy dup ok +@c utmpname dup @mtasurace:utent @asulock @ascuheap @aculock @acsmem +@c setutent dup @mtasurace:utent @asulock @aculock @acsfd +@c pututline dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd +@c endutent dup @mtasurace:utent @asulock @aculock +@c free dup @ascuheap @acsmem +@c updwtmp dup @mtascusig:ALRM @mtascutimer @acsfd The @code{login} functions inserts an entry into the user accounting database. The @code{ut_line} member is set to the name of the terminal on standard input. If standard input is not a terminal @code{login} @@ -1444,6 +1761,17 @@ @comment utmp.h @comment BSD @deftypefun int logout (const char *@var{ut_line}) +@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 +@c setutent dup @mtasurace:utent @asulock @aculock @acsfd +@c strncpy dup ok +@c getutline_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd +@c bzero dup ok +@c gettimeofday dup ok +@c time dup ok +@c pututline dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd +@c endutent dup @mtasurace:utent @asulock @aculock This function modifies the user accounting database to indicate that the user on @var{ut_line} has logged out. @@ -1454,6 +1782,14 @@ @comment utmp.h @comment BSD @deftypefun void logwtmp (const char *@var{ut_line}, const char *@var{ut_name}, const char *@var{ut_host}) +@safety{@prelim{}@mtunsafe{@mtascusig{:ALRM} @mtascutimer{}}@asunsafe{}@acunsafe{@acsfd{}}} +@c logwtmp @mtascusig:ALRM @mtascutimer @acsfd +@c memset dup ok +@c getpid dup ok +@c strncpy dup ok +@c gettimeofday dup ok +@c time dup ok +@c updwtmp dup @mtascusig:ALRM @mtascutimer @acsfd The @code{logwtmp} function appends an entry to the user accounting log file, for the current time and the information provided in the @var{ut_line}, @var{ut_name} and @var{ut_host} arguments. @@ -1535,6 +1871,14 @@ @comment pwd.h @comment POSIX.1 @deftypefun {struct passwd *} getpwuid (uid_t @var{uid}) +@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 +@c malloc dup @ascuheap @acsmem +@c getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock This function returns a pointer to a statically-allocated structure containing information about the user whose user ID is @var{uid}. This structure may be overwritten on subsequent calls to @code{getpwuid}. @@ -1546,6 +1890,208 @@ @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}) +@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 +@c itoa_word dup ok +@c nscd_getpw_r @ascuheap @acsfd @acsmem +@c nscd_get_map_ref @ascuheap @acsfd @acsmem +@c nscd_acquire_maplock ok +@c nscd_get_mapping @ascuheap @acsfd @acsmem +@c open_socket dup @acsfd +@c memset dup ok +@c wait_on_socket dup ok +@c recvmsg dup ok +@c strcmp dup ok +@c fstat64 dup ok +@c mmap dup @acsmem +@c munmap dup @acsmem +@c malloc dup @ascuheap @acsmem +@c close dup ok +@c nscd_unmap dup @ascuheap @acsmem +@c nscd_cache_search ok +@c nis_hash ok +@c memcmp dup ok +@c nscd_open_socket @acsfd +@c open_socket @acsfd +@c socket dup @acsfd +@c fcntl dup ok +@c strcpy dup ok +@c connect dup ok +@c send dup ok +@c gettimeofday dup ok +@c poll dup ok +@c close_not_cancel_no_status dup @acsfd +@c wait_on_socket dup ok +@c read dup ok +@c close_not_cancel_no_status dup @acsfd +@c readall ok +@c read dup ok +@c wait_on_socket ok +@c poll dup ok +@c gettimeofday dup ok +@c memcpy dup ok +@c close_not_cancel_no_status dup @acsfd +@c nscd_drop_map_ref @ascuheap @acsmem +@c nscd_unmap dup @ascuheap @acsmem +@c nscd_unmap @ascuheap @acsmem +@c munmap dup ok +@c free dup @ascuheap @acsmem +@c nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_database_lookup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock +@c libc_lock_lock @asulock @aculock +@c libc_lock_unlock @aculock +@c nss_parse_file @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fsetlocking dup ok [no concurrent uses] +@c malloc dup @asulock @aculock @acsfd @acsmem +@c fclose dup @ascuheap @asulock @acsmem @acsfd @aculock +@c getline dup @ascuheap @aculock @acucorrupt @acsmem +@c strchrnul dup ok +@c nss_getline @mtslocale @ascuheap @acsmem +@c isspace @mtslocale^^ +@c strlen dup ok +@c malloc dup @asulock @aculock @acsfd @acsmem +@c memcpy dup ok +@c nss_parse_service_list dup @mtslocale^, @ascuheap @acsmem +@c feof_unlocked dup ok +@c free dup @asulock @aculock @acsfd @acsmem +@c strcmp dup ok +@c nss_parse_service_list @mtslocale^, @ascuheap @acsmem +@c isspace @mtslocale^^ +@c malloc dup @asulock @aculock @acsfd @acsmem +@c mempcpy dup ok +@c strncasecmp dup ok +@c free dup @asulock @aculock @acsfd @acsmem +@c malloc dup @asulock @aculock @acsfd @acsmem +@c nss_lookup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup_function @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock @asulock @aculock +@c tsearch @ascuheap @acucorrupt @acsmem [no @mtsrace or @asucorrupt due to locking] +@c known_compare ok +@c strcmp dup ok +@c malloc dup @ascuheap @acsmem +@c tdelete @ascuheap @acucorrupt @acsmem [no @mtsrace or @asucorrupt due to locking] +@c free dup @ascuheap @acsmem +@c nss_load_library @ascudlopen @ascuplugin @ascuheap @asulock @aculock @acsfd @acsmem +@c nss_new_service @ascuheap @acsmem +@c strcmp dup ok +@c malloc dup @ascuheap @acsmem +@c strlen dup ok +@c stpcpy dup ok +@c libc_dlopen @ascudlopen @ascuheap @asulock @aculock @acsfd @acsmem +@c libc_dlsym dup @asulock @aculock @acsfd @acsmem +@c *ifct(*nscd_init_cb) @ascuplugin +@c stpcpy dup ok +@c libc_dlsym dup @asulock @aculock @acsfd @acsmem +@c libc_lock_unlock dup ok +@c nss_next_action ok +@c *fct.l -> _nss_*_getpwuid_r @ascuplugin +@c nss_next2 @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_next_action dup ok +@c nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem + +@c _nss_files_getpwuid_r @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_lock_lock dup @asulock @aculock +@c internal_setent @ascuheap @asulock @aculock @acsmem @acsfd +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fileno dup ok +@c fcntl dup ok +@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd +@c rewind dup @aculock [stream guarded by non-recursive pwent lock] +@c internal_getent @mtslocale^ +@c fgets_unlocked dup ok [stream guarded by non-recursive pwent lock] +@c isspace dup @mtslocale^^ +@c _nss_files_parse_pwent = parse_line ok +@c strpbrk dup ok +@c internal_endent @ascuheap @asulock @aculock @acsmem @acsfd +@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_lock_unlock dup @aculock + +@c _nss_nis_getpwuid_r ... not fully reviewed (assumed) @asuinit @asulock @acucorrupt @aculock +@c yp_get_default_domain @asulock @aculock +@c libc_lock_lock dup @asulock @aculock +@c getdomainname dup ok +@c strcmp dup ok +@c libc_lock_unlock dup @aculock +@c snprintf dup @ascuheap @acsmem +@c yp_match +@c do_ypcall_tr(xdr_ypreq_key,xdr_ypresp_val) +@c do_ypcall(xdr_ypreq_key,xdr_ypresp_val) +@c libc_lock_lock @asulock @aculock +@c strcmp +@c yp_bind +@c ypclnt_call +@c clnt_call +@c clnt_perror +@c libc_lock_unlock @aculock +@c yp_unbind_locked +@c yp_unbind +@c strcmp dup ok +@c calloc dup @asulock @aculock @acsfd @acsmem +@c yp_bind_file +@c strlen dup ok +@c snprintf dup @ascuheap @acsmem +@c open dup @acsfd [cancelpt] +@c pread dup [cancelpt] +@c yp_bind_client_create +@c close dup @acsfd [cancelpt] +@c yp_bind_ypbindprog +@c clnttcp_create +@c clnt_destroy +@c clnt_call(xdr_domainname,xdr_ypbind_resp) +@c memset dup ok +@c yp_bind_client_create +@c free dup @asulock @aculock @acsfd @acsmem +@c calloc dup @asulock @aculock @acsfd @acsmem +@c free dup @asulock @aculock @acsfd @acsmem +@c ypprot_err +@c memcpy dup ok +@c xdr_free(xdr_ypresp_val) +@c xdr_ypresp_val +@c xdr_ypstat +@c xdr_enum +@c XDR_PUTLONG +@c *x_putlong +@c XDR_GETLONG +@c *x_getlong +@c xdr_long +@c XDR_PUTLONG dup +@c XDR_GETLONG dup +@c xdr_short +@c XDR_PUTLONG dup +@c XDR_GETLONG dup +@c xdr_valdat +@c xdr_bytes +@c xdr_u_int +@c XDR_PUTLONG dup +@c XDR_GETLONG dup +@c mem_alloc @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c xdr_opaque +@c XDR_GETBYTES +@c *x_getbytes +@c XDR_PUTBYTES +@c *x_putbytes +@c mem_free @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c yperr2nss ok +@c strchr dup ok +@c _nls_default_nss @asuinit @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock +@c init @asuinit^, @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fsetlocking ok [no concurrent uses] +@c feof_unlocked dup ok +@c getline dup @ascuheap @aculock @acucorrupt @acsmem +@c isspace dup @mtslocale^^ +@c strncmp dup ok +@c free dup @asulock @acsmem @acsfd @aculock +@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd +@c free dup @asulock @acsmem @acsfd @aculock +@c mempcpy dup ok +@c strncpy dup ok +@c isspace dup @mtslocale^^ +@c _nss_files_parse_pwent ok This function is similar to @code{getpwuid} in that it returns information about the user whose user ID is @var{uid}. However, it fills the user supplied structure pointed to by @var{result_buf} with @@ -1568,6 +2114,14 @@ @comment pwd.h @comment POSIX.1 @deftypefun {struct passwd *} getpwnam (const char *@var{name}) +@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 +@c malloc dup @ascuheap @acsmem +@c getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock This function returns a pointer to a statically-allocated structure containing information about the user whose user name is @var{name}. This structure may be overwritten on subsequent calls to @@ -1579,6 +2133,25 @@ @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}) +@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 +@c strlen dup ok +@c nscd_getpw_r dup @ascuheap @asulock @aculock @acsfd @acsmem +@c nss_passwd_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c +@c _nss_files_getpwnam_r @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_lock_lock dup @asulock @aculock +@c internal_setent dup @ascuheap @asulock @aculock @acsmem @acsfd +@c internal_getent dup @mtslocale^ +@c strcmp dup ok +@c internal_endent dup @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_lock_unlock dup @aculock +@c +@c _nss_*_getpwnam_r (assumed) @asuinit @asulock @acucorrupt @aculock + This function is similar to @code{getpwnam} in that is returns information about the user whose user name is @var{name}. However, like @code{getpwuid_r}, it fills the user supplied buffers in @@ -1603,6 +2176,16 @@ @comment pwd.h @comment SVID @deftypefun {struct passwd *} fgetpwent (FILE *@var{stream}) +@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 +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c fgetpwent_r dup @asucorrupt @acucorrupt @aculock +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c fsetpos dup @asucorrupt @aculock @acucorrupt +@c libc_lock_unlock dup @aculock This function reads the next user entry from @var{stream} and returns a pointer to the entry. The structure is statically allocated and is rewritten on subsequent calls to @code{fgetpwent}. You must copy the @@ -1615,6 +2198,14 @@ @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}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} +@c fgetpwent_r @asucorrupt @acucorrupt @aculock +@c flockfile dup @aculock +@c fgets_unlocked @asucorrupt @acucorrupt [no @mtsrace due to explicit locking] +@c feof_unlocked dup ok +@c funlockfile dup @aculock +@c isspace dup @mtslocale^^ +@c parse_line dup ok This function is similar to @code{fgetpwent} in that it reads the next user entry from @var{stream}. But the result is returned in the structure pointed to by @var{result_buf}. The @@ -1637,6 +2228,17 @@ @comment pwd.h @comment SVID, BSD @deftypefun void setpwent (void) +@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 +@c nss_setent(nss_passwd_lookup2) @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c ** resolv's res_maybe_init not called here +@c setup(nss_passwd_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *lookup_fct = nss_passwd_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:pwent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock @aculock This function initializes a stream which @code{getpwent} and @code{getpwent_r} use to read the user database. @end deftypefun @@ -1644,6 +2246,15 @@ @comment pwd.h @comment POSIX.1 @deftypefun {struct passwd *} getpwent (void) +@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 +@c nss_getent(getpwent_r) @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c malloc dup @ascuheap @acsmem +@c *func = getpwent_r dup @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock The @code{getpwent} function reads the next entry from the stream initialized by @code{setpwent}. It returns a pointer to the entry. The structure is statically allocated and is rewritten on subsequent calls @@ -1655,7 +2266,21 @@ @comment pwd.h @comment GNU -@deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, int @var{buflen}, struct passwd **@var{result}) +@deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) +@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 +@c whatever internal state the nss backend uses to keep track of the +@c last read entry. +@c getpwent_r @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_lock dup @asulock @aculock +@c nss_getent_r(nss_passwd_lookup2) @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:pwent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *sfct.f @mtasurace:pwent @ascuplugin +@c libc_lock_unlock dup @aculock This function is similar to @code{getpwent} in that it returns the next entry from the stream initialized by @code{setpwent}. Like @code{fgetpwent_r}, it uses the user-supplied buffers in @@ -1668,6 +2293,15 @@ @comment pwd.h @comment SVID, BSD @deftypefun void endpwent (void) +@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 +@c nss_endent(nss_passwd_lookup2) @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c ** resolv's res_maybe_init not called here +@c setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @mtasurace:pwent @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c libc_lock_unlock @aculock This function closes the internal stream used by @code{getpwent} or @code{getpwent_r}. @end deftypefun @@ -1678,6 +2312,9 @@ @comment pwd.h @comment SVID @deftypefun int putpwent (const struct passwd *@var{p}, FILE *@var{stream}) +@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] This function writes the user entry @code{*@var{p}} to the stream @var{stream}, in the format used for the standard user database file. The return value is zero on success and nonzero on failure. @@ -1751,6 +2388,9 @@ @comment grp.h @comment POSIX.1 @deftypefun {struct group *} getgrgid (gid_t @var{gid}) +@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 This function returns a pointer to a statically-allocated structure containing information about the group whose group ID is @var{gid}. This structure may be overwritten by subsequent calls to @@ -1762,6 +2402,26 @@ @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}) +@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 +@c itoa_word dup ok +@c nscd_getgr_r @ascuheap @acsfd @acsmem +@c nscd_get_map_ref dup @ascuheap @acsfd @acsmem +@c nscd_cache_search dup ok +@c nscd_open_socket dup @acsfd +@c readvall ok +@c readv dup ok +@c memcpy dup ok +@c wait_on_socket dup ok +@c memcpy dup ok +@c readall dup ok +@c close_not_cancel_no_status dup @acsfd +@c nscd_drop_map_ref dup @ascuheap @acsmem +@c nscd_unmap dup @ascuheap @acsmem +@c nss_group_lookup2 =~ nss_passwd_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l -> _nss_*_getgrgid_r @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem This function is similar to @code{getgrgid} in that it returns information about the group whose group ID is @var{gid}. However, it fills the user supplied structure pointed to by @var{result_buf} with @@ -1783,6 +2443,9 @@ @comment grp.h @comment SVID, BSD @deftypefun {struct group *} getgrnam (const char *@var{name}) +@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 This function returns a pointer to a statically-allocated structure containing information about the group whose group name is @var{name}. This structure may be overwritten by subsequent calls to @@ -1794,6 +2457,14 @@ @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}) +@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 +@c strlen dup ok +@c nscd_getgr_r dup @ascuheap @asulock @aculock @acsfd @acsmem +@c nss_group_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.l @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem This function is similar to @code{getgrnam} in that is returns information about the group whose group name is @var{name}. Like @code{getgrgid_r}, it uses the user supplied buffers in @@ -1817,6 +2488,16 @@ @comment grp.h @comment SVID @deftypefun {struct group *} fgetgrent (FILE *@var{stream}) +@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 +@c libc_lock_lock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c fgetgrent_r dup @asucorrupt @acucorrupt @aculock +@c realloc dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c fsetpos dup @asucorrupt @aculock @acucorrupt +@c libc_lock_unlock dup @aculock The @code{fgetgrent} function reads the next entry from @var{stream}. It returns a pointer to the entry. The structure is statically allocated and is overwritten on subsequent calls to @code{fgetgrent}. You @@ -1830,6 +2511,14 @@ @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}) +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} +@c fgetgrent_r @asucorrupt @acucorrupt @aculock +@c flockfile dup @aculock +@c fgets_unlocked @asucorrupt @acucorrupt [no @mtsrace due to explicit locking] +@c feof_unlocked dup ok +@c funlockfile dup @aculock +@c isspace dup @mtslocale^^ +@c parse_line dup ok This function is similar to @code{fgetgrent} in that it reads the next user entry from @var{stream}. But the result is returned in the structure pointed to by @var{result_buf}. The first @var{buflen} bytes @@ -1852,6 +2541,9 @@ @comment grp.h @comment SVID, BSD @deftypefun void setgrent (void) +@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 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 @@ -1859,6 +2551,9 @@ @comment grp.h @comment SVID, BSD @deftypefun {struct group *} getgrent (void) +@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 The @code{getgrent} function reads the next entry from the stream initialized by @code{setgrent}. It returns a pointer to the entry. The structure is statically allocated and is overwritten on subsequent calls @@ -1869,6 +2564,8 @@ @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}) +@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 entry from the stream initialized by @code{setgrent}. Like @code{fgetgrent_r}, it places the result in user-supplied buffers @@ -1882,6 +2579,8 @@ @comment grp.h @comment SVID, BSD @deftypefun void endgrent (void) +@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 @code{getgrent_r}. @end deftypefun @@ -1966,6 +2665,40 @@ @comment netdb.h @comment BSD @deftypefun int setnetgrent (const char *@var{netgroup}) +@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 +@c nscd_setnetgrent @ascuheap @acsfd @acsmem +@c __nscd_setnetgrent @ascuheap @acsfd @acsmem +@c strlen dup ok +@c nscd_get_map_ref dup @ascuheap @acsfd @acsmem +@c nscd_cache_search dup ok +@c nscd_open_socket dup @acsfd +@c malloc dup @ascuheap @acsmem +@c readall dup ok +@c free dup @ascuheap @acsmem +@c close_not_cancel_no_status dup @acsfd +@c nscd_drop_map_ref dup @ascuheap @acsmem +@c nscd_unmap dup @ascuheap @acsmem +@c internal_setnetgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c free_memory dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c internal_setnetgrent_reuse @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c endnetgrent_hook dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *endfct @ascuplugin +@c (netgroup::)setup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_netgroup_lookup dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_netgroup_lookup2 =~ nss_passwd_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct.f @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *endfct @ascuplugin +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c memcpy dup ok +@c libc_lock_unlock dup @aculock A call to this function initializes the internal state of the library to allow following calls of the @code{getnetgrent} to iterate over all entries in the netgroup with name @var{netgroup}. @@ -1991,6 +2724,12 @@ @comment netdb.h @comment BSD @deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp}) +@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 +@c allocate (libc_once) @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c getnetgrent_r dup @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem This function returns the next unprocessed entry of the currently selected netgroup. The string pointers, in which addresses are passed in the arguments @var{hostp}, @var{userp}, and @var{domainp}, will contain @@ -2005,7 +2744,20 @@ @comment netdb.h @comment GNU -@deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, int @var{buflen}) +@deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, size_t @var{buflen}) +@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 +@c internal_getnetgrent_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *fct @ascuplugin +@c nscd_getnetgrent ok +@c rawmemchr dup ok +@c internal_setnetgrent_reuse dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c strcmp dup ok +@c malloc dup @ascuheap @acsmem +@c memcpy dup ok +@c libc_lock_unlock dup @aculock This function is similar to @code{getnetgrent} with only one exception: the strings the three string pointers @var{hostp}, @var{userp}, and @var{domainp} point to, are placed in the buffer of @var{buflen} bytes @@ -2024,6 +2776,13 @@ @comment netdb.h @comment BSD @deftypefun void endnetgrent (void) +@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 +@c internal_endnetgrent @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c endnetgrent_hook dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c free_memory dup @ascuheap @acsmem +@c libc_lock_unlock dup @aculock This function frees all buffers which were allocated to process the last selected netgroup. As a result all string pointers returned by calls to @code{getnetgrent} are invalid afterwards. @@ -2039,6 +2798,37 @@ @comment netdb.h @comment BSD @deftypefun int innetgr (const char *@var{netgroup}, const char *@var{host}, const char *@var{user}, const char *@var{domain}) +@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 +@c to support iteration and concurrent iteration will interfere +@c destructively, we regard this internal state as a static buffer. +@c getnetgrent_r iteration in each nss backend. +@c innetgr @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c nscd_innetgr @ascuheap @acsfd @acsmem +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c stpcpy dup ok +@c nscd_get_map_ref dup @ascuheap @acsfd @acsmem +@c nscd_cache_search dup ok +@c nscd_open_socket dup @acsfd +@c close_not_cancel_no_status dup @acsfd +@c nscd_drop_map_ref dup @ascuheap @acsmem +@c nscd_unmap dup @ascuheap @acsmem +@c free dup @ascuheap @acsmem +@c memset dup ok +@c (netgroup::)setup dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *setfct.f @ascuplugin +@c nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c *getfct @ascuplugin +@c strcmp dup ok +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c memcpy dup ok +@c strcasecmp dup +@c *endfct @ascuplugin +@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c free_memory dup @ascuheap @acsmem This function tests whether the triple specified by the parameters @var{hostp}, @var{userp}, and @var{domainp} is part of the netgroup @var{netgroup}. Using this function has the advantage that @@ -2062,3 +2852,7 @@ itself is not found, the netgroup does not contain the triple or internal errors occurred. @end deftypefun + +@c FIXME these are undocumented: +@c setresgid +@c setresuid