X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/351ab2ad048e0885b4076c07b0cb7a20904cc6dc..aa2bc4d385298947b20667efc390d3182feaebe1:/ext/POSIX/lib/POSIX.pod diff --git a/ext/POSIX/lib/POSIX.pod b/ext/POSIX/lib/POSIX.pod index 82bc213..712132b 100644 --- a/ext/POSIX/lib/POSIX.pod +++ b/ext/POSIX/lib/POSIX.pod @@ -21,19 +21,10 @@ The POSIX module permits you to access all (or nearly all) the standard POSIX 1003.1 identifiers. Many of these identifiers have been given Perl-ish interfaces. -I with the exception of any POSIX -functions with the same name as a built-in Perl function, such as -C, C, C, C, etc.., which will be exported -only if you ask for them explicitly. This is an unfortunate backwards -compatibility feature. You can stop the exporting by saying S> and then use the fully qualified names (I, C), -or by giving an explicit import list. If you do neither, and opt for the -default, S> has to import I<553 symbols>. - This document gives a condensed list of the features available in the POSIX module. Consult your operating system's manpages for general information on most features. Consult L for functions which are noted as being -identical to Perl's builtin functions. +identical or almost identical to Perl's builtin functions. The first section describes POSIX functions from the 1003.1 specification. The second section describes some classes for signal objects, TTY objects, @@ -41,34 +32,17 @@ and other miscellaneous objects. The remaining sections list various constants and macros in an organization which roughly follows IEEE Std 1003.1b-1993. -=head1 C99 "math" interfaces - -Mathematic functions and constants from the C99 standard are available -on many platforms. In the below functions list they are marked [C99]. - -The mathematical constants include: - - M_SQRT2 # the square root of two - M_E # the Euler's (or Napier's) constant - M_PI # the Pi - -and other related/similar ones - - M_SQRT1_2 # sqrt(1/2) - M_LN10 M_LN2 M_LOG10E M_LOG2E - M_1_PI M_2_PI M_2_SQRTPI M_PI_2 M_PI_4 # 1/Pi, ..., Pi/4 - -and the - - INFINITY - NAN - -The last two are also available as just Inf and NaN. - -The Bessel functions (j0, j1, jn, y0, y1, yn) are also available. - =head1 CAVEATS +I (with a handful of exceptions). +This is an unfortunate backwards compatibility feature and its use is +B>. +You should either prevent the exporting (by saying S>, +as usual) and then use fully qualified names (e.g. C), +or give an explicit import list. +If you do neither and opt for the default (as in S>), you +will import I of symbols into your namespace. + A few functions are not implemented because they are C specific. If you attempt to call these, they will print a message telling you that they aren't implemented, and suggest using the Perl equivalent, should one @@ -107,8 +81,13 @@ if the handler does not return normally (it e.g. does a C). =item C -This is identical to Perl's builtin C function, returning -the absolute value of its numerical argument. +This is identical to Perl's builtin C function, returning the absolute +value of its numerical argument (except that C must be provided +an explicit value (rather than relying on an implicit C<$_>): + + $absolute_value = POSIX::abs(42); # good + + $absolute_value = POSIX::abs(); # throws exception =item C @@ -130,14 +109,19 @@ the arcus cosine of its numerical argument. See also L. =item C -This is identical to the C function C, returning the +This is identical to the C function C, returning the hyperbolic arcus cosine of its numerical argument [C99]. See also L. =item C -This is identical to Perl's builtin C function, -either for arming or disarming the C timer. +This is identical to Perl's builtin C function, either for arming or +disarming the C timer, except that C must be provided +an explicit value (rather than relying on an implicit C<$_>): + + POSIX::alarm(3) # good + + POSIX::alarm() # throws exception =item C @@ -162,7 +146,7 @@ the arcus sine of its numerical argument. See also L. =item C -This is identical to the C function C, returning the +This is identical to the C function C, returning the hyperbolic arcus sine of its numerical argument [C99]. See also L. @@ -178,7 +162,7 @@ arcus tangent of its numerical argument. See also L. =item C -This is identical to the C function C, returning the +This is identical to the C function C, returning the hyperbolic arcus tangent of its numerical argument [C99]. See also L. @@ -190,22 +174,22 @@ coordinate and the I coordinate. See also L. =item C -C is C-specific: use C instead, see L. +Not implemented. C is C-specific: use C instead, see L. =item C -C is C-specific. Perl converts strings to numbers transparently. +Not implemented. C is C-specific. Perl converts strings to numbers transparently. If you need to force a scalar to a number, add a zero to it. =item C -C is C-specific. Perl converts strings to numbers transparently. +Not implemented. C is C-specific. Perl converts strings to numbers transparently. If you need to force a scalar to a number, add a zero to it. If you need to have just the integer part, see L. =item C -C is C-specific. Perl converts strings to numbers transparently. +Not implemented. C is C-specific. Perl converts strings to numbers transparently. If you need to force a scalar to a number, add a zero to it. If you need to have just the integer part, see L. @@ -216,7 +200,7 @@ see L. =item C -C is C-specific. Perl does memory management transparently. +Not implemented. C is C-specific. Perl does memory management transparently. =item C @@ -229,13 +213,27 @@ integer value greater than or equal to the given numerical argument. =item C -This is identical to Perl's builtin C function, allowing -one to change the working (default) directory, see L. +This is identical to Perl's builtin C function, allowing one to +change the working (default) directory -- see L -- with the +exception that C must be provided an explicit value (rather +than relying on an implicit C<$_>): + + $rv = POSIX::chdir('path/to/dir'); # good + + $rv = POSIX::chdir(); # throws exception =item C This is identical to Perl's builtin C function, allowing -one to change file and directory permissions, see L. +one to change file and directory permissions -- see L -- with +the exception that C can only change one file at a time +(rather than a list of files): + + $c = chmod 0664, $file1, $file2; # good + + $c = POSIX::chmod 0664, $file1; # throws exception + + $c = POSIX::chmod 0664, $file1, $file2; # throws exception =item C @@ -244,7 +242,7 @@ to change file and directory owners and groups, see L. =item C -Use the method C instead, to reset the error +Not implemented. Use the method C instead, to reset the error state (if any) and EOF state (if any) of the given stream. =item C @@ -282,7 +280,9 @@ the hyperbolic cosine of its numeric argument. See also L. =item C -Returns the x but with the sign of y [C99]. +Returns C but with the sign of C [C99]. + + $x_with_sign_of_y = POSIX::copysign($x, $y); See also L. @@ -321,7 +321,7 @@ by C), see L. =item C
-C is C-specific, use L on the usual C division and +Not implemented. C is C-specific, use L on the usual C division and the modulus C<%>. =item C @@ -362,27 +362,27 @@ This identical to the numerical values of the C<$!>, see L. =item C -C is C-specific, see L. +Not implemented. C is C-specific, see L. =item C -C is C-specific, see L. +Not implemented. C is C-specific, see L. =item C -C is C-specific, see L. +Not implemented. C is C-specific, see L. =item C -C is C-specific, see L. +Not implemented. C is C-specific, see L. =item C -C is C-specific, see L. +Not implemented. C is C-specific, see L. =item C -C is C-specific, see L. +Not implemented. C is C-specific, see L. =item C @@ -408,7 +408,7 @@ the absolute value of the numerical argument, see L. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C @@ -417,37 +417,37 @@ see L. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C -Use method C instead. +Not implemented. Use method C instead. =item C -Use method C instead. +Not implemented. Use method C instead. See also C>. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C -Use method C instead. Similar to EE, also known +Not implemented. Use method C instead. Similar to EE, also known as L. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C @@ -456,7 +456,7 @@ integer value less than or equal to the numerical argument. =item C -"Positive difference", x - y if x > y, zero otherwise [C99]. +"Positive difference", S> if S y>>, zero otherwise [C99]. =item C @@ -464,24 +464,30 @@ Returns the current floating point rounding mode, one of FE_TONEAREST FE_TOWARDZERO FE_UPWARD FE_UPWARD -FE_TONEAREST is like L, FE_TOWARDZERO is like L [C99]. +C is like L, C is like L [C99]. =item C -Sets the floating point rounding mode, see L. +Sets the floating point rounding mode, see L [C99]. =item C -"Fused multiply-add", x * y + z, possibly faster (and less lossy) +"Fused multiply-add", S>, possibly faster (and less lossy) than the explicit two operations [C99]. + my $fused = POSIX::fma($x, $y, $z); + =item C -Maximum of x and y, except when either is NaN, returns the other [C99]. +Maximum of C and C, except when either is C, returns the other [C99]. + + my $min = POSIX::fmax($x, $y); =item C -Minimum of x and y, except when either is NaN, returns the other [C99]. +Minimum of C and C, except when either is C, returns the other [C99]. + + my $min = POSIX::fmin($x, $y); =item C @@ -489,13 +495,13 @@ This is identical to the C function C. $r = fmod($x, $y); -It returns the remainder C<$r = $x - $n*$y>, where C<$n = trunc($x/$y)>. +It returns the remainder S>, where S>. The C<$r> has the same sign as C<$x> and magnitude (absolute value) less than the magnitude of C<$y>. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C @@ -522,31 +528,34 @@ Returns one of FP_NORMAL FP_ZERO FP_SUBNORMAL FP_INFINITE FP_NAN -telling the class of the argument [C99]. +telling the class of the argument [C99]. C is positive +or negative infinity, C is not-a-number. C +means subnormal numbers (also known as denormals), very small numbers +with low precision. C is zero. C is all the rest. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific. Perl does memory management transparently. +Not implemented. C is C-specific. Perl does memory management transparently. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C @@ -556,15 +565,15 @@ Return the mantissa and exponent of a floating-point number. =item C -C is C-specific, use EE and regular expressions instead. +Not implemented. C is C-specific, use EE and regular expressions instead. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C -Use method C instead, or seek L. +Not implemented. Use method C instead, or seek L. =item C @@ -577,15 +586,15 @@ Perl's builtin C function. =item C -Use method C instead. +Not implemented. Use method C instead. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C @@ -644,6 +653,17 @@ This is identical to Perl's builtin C function for returning the user name associated with the current session, see L. +=item C + + use POSIX ':nan_payload'; + getpayload($var) + +Returns the C payload. + +Note the API instability warning in L. + +See L for more discussion about C. + =item C This is identical to Perl's builtin C function for @@ -694,51 +714,38 @@ see L. =item C -Equivalent to sqrt(x * x + y * y) except more stable on very large +Equivalent to C> except more stable on very large or very small arguments [C99]. =item C Integer binary logarithm [C99] -For example ilogb(20) is 4, as an integer. +For example C is 4, as an integer. See also L. -=item C +=item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). +The infinity as a constant: -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. + use POSIX qw(Inf); + my $pos_inf = +Inf; # Or just Inf. + my $neg_inf = -Inf; -You may want to use the C\wE|perlrecharclass/Word -characters>> construct instead. +See also L, and L. -=item C +=item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. +=item C + +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. =item C @@ -747,38 +754,15 @@ to a tty. Similar to the C<-t> operator, see L. =item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). - -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. =item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). - -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. - -You may want to use the C\dE|perlrecharclass/Digits>> -construct instead. +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. =item C @@ -789,62 +773,40 @@ See also L, L, and L. =item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). - -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. =item C (Also C, C, C, C, C) -Floating point comparisons which handle the NaN [C99]. +Floating point comparisons which handle the C [C99]. =item C Returns true if the argument is an infinity (positive or negative) [C99]. -See also L, L, and L. +See also L, L, L, and L. =item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). - -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. - -Do B use C unless you don't care about the current locale. +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. =item C -Returns true if the argument is NaN (not-a-number) [C99]. +Returns true if the argument is C (not-a-number) [C99]. -Note that you cannot test for "NaN-ness" with +Note that you cannot test for "C-ness" with $x == $x -since the NaN is not equivalent to anything, B. +since the C is not equivalent to anything, B. -See also L, L, and L. +See also L, L, L, and L. =item C @@ -855,92 +817,56 @@ See also L, and L. =item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). - -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. =item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. +=item C -=item C + use POSIX ':nan_payload'; + issignaling($var, $payload) -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). +Return true if the argument is a I NaN. -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. +Note the API instability warning in L. -You may want to use the C\sE|perlrecharclass/Whitespace>> -construct instead. +See L for more discussion about C. -=item C +=item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. +=item C -Do B use C unless you don't care about the current locale. +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should convert +to use instead. See L. =item C -Deprecated function whose use raises a warning, and which is slated to -be removed in a future Perl version. It is very similar to matching -against S>, which you should convert to use -instead. The function is deprecated because 1) it doesn't handle UTF-8 -encoded strings properly; and 2) it returns C even if the input is -the empty string. The function return is always based on the current -locale, whereas using locale rules is optional with the regular -expression, based on pragmas in effect and pattern modifiers (see -L and L). - -The function returns C if the input string is empty, or if the -corresponding C function returns C for every byte in the string. +This function has been removed as of v5.24. It was very similar to +matching against S>, which you should +convert to use instead. See L. =item C -(Also C, C, C, C, C) +=item C + +=item C + +=item C + +=item C + +=item C The Bessel function of the first kind of the order zero. @@ -951,17 +877,19 @@ signals to processes (often to terminate them), see L. =item C -(For returning absolute values of long integers.) +Not implemented. (For returning absolute values of long integers.) C is C-specific, see L instead. =item C This is identical to the C function, except the order of arguments is consistent with Perl's builtin C with the added restriction -of only one path, not an list of paths. Does the same thing as the -C function but changes the owner of a symbolic link instead +of only one path, not a list of paths. Does the same thing as the +C function but changes the owner of a symbolic link instead of the file the symbolic link points to. + POSIX::lchown($uid, $gid, $file_path); + =item C This is identical to the C function C @@ -971,7 +899,7 @@ for multiplying floating point numbers with powers of two. =item C -(For computing dividends of long integers.) +Not implemented. (For computing dividends of long integers.) C is C-specific, use C and C instead. =item C @@ -982,7 +910,7 @@ See also L. =item C -Equivalent to log(1 + x), but more stable results for small argument +Equivalent to S>, but more stable results for small argument values [C99]. =item C @@ -995,7 +923,7 @@ See also L. Integer binary logarithm [C99]. -For example logb(20) is 4, as a floating point number. +For example C is 4, as a floating point number. See also L. @@ -1011,6 +939,9 @@ containing the current underlying locale's formatting values. Users of this fun should also read L, which provides a comprehensive discussion of Perl locale handling, including L. +It should not be used in a threaded application unless it's certain that +the underlying locale is C or POSIX. This is because it otherwise +changes the locale, which globally affects all threads simultaneously. Here is how to query the database for the B (Deutsch or German) locale. @@ -1036,16 +967,33 @@ Here is how to query the database for the B (Deutsch or German) locale. n_sep_by_space p_sign_posn n_sign_posn + int_p_cs_precedes + int_p_sep_by_space + int_n_cs_precedes + int_n_sep_by_space + int_p_sign_posn + int_n_sign_posn )) { printf qq(%s: "%s",\n), $property, $lconv->{$property}; } +The members whose names begin with C and C were added by +POSIX.1-2008 and are only available on systems that support them. + =item C This is identical to Perl's builtin C function for -converting seconds since the epoch to a date see L. +converting seconds since the epoch to a date see L except +that C must be provided an explicit value (rather than +relying on an implicit C<$_>): + + @localtime = POSIX::localtime(time); # good + + @localtime = localtime(); # good + + @localtime = POSIX::localtime(); # throws exception =item C @@ -1071,7 +1019,7 @@ or =item C -C is C-specific: use L instead. +Not implemented. C is C-specific: use L instead. =item C @@ -1098,17 +1046,21 @@ Like L, but as integer, as opposed to floating point [C99]. See also L, L, L. +Owing to an oversight, this is not currently exported by default, or as part of +the C<:math_h_c99> export tag; importing it must therefore be done by explicit +name. + =item C -C is C-specific. Perl does memory management transparently. +Not implemented. C is C-specific. Perl does memory management transparently. =item C This is identical to the C function C. Core Perl does not have any support for the wide and multibyte -characters of the C standards, so this might be a rather useless -function. +characters of the C standards, except under UTF-8 locales, so this might +be a rather useless function. However, Perl supports Unicode, see L. @@ -1126,23 +1078,23 @@ See L. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, use C instead, see L. +Not implemented. C is C-specific, use C instead, see L. =item C -C is C-specific, use C<=>, see L, or see L. +Not implemented. C is C-specific, use C<=>, see L, or see L. =item C -C is C-specific, use C<=>, see L, or see L. +Not implemented. C is C-specific, use C<=>, see L, or see L. =item C -C is C-specific, use C instead, see L. +Not implemented. C is C-specific, use C instead, see L. =item C @@ -1169,9 +1121,9 @@ Synopsis: mktime(sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = -1) -The month (C), weekday (C), and yearday (C) begin at zero. -I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The -year (C) is given in years since 1900. I.e. The year 1995 is 95; the +The month (C), weekday (C), and yearday (C) begin at zero, +I, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The +year (C) is given in years since 1900; I, the year 1995 is 95; the year 2001 is 101. Consult your system's C manpage for details about these and the other arguments. @@ -1190,11 +1142,51 @@ Return the integral and fractional parts of a floating-point number. See also L. +=item C + +The not-a-number as a constant: + + use POSIX qw(NaN); + my $nan = NaN; + +See also L, C, and L. + =item C -Returns not-a-number [C99]. + my $nan = nan(); + +Returns C, not-a-number [C99]. + +The returned NaN is always a I NaN, as opposed to I. + +With an argument, can be used to generate a NaN with I. +The argument is first interpreted as a floating point number, +but then any fractional parts are truncated (towards zero), +and the value is interpreted as an unsigned integer. +The bits of this integer are stored in the unused bits of the NaN. + +The result has a dual nature: it is a NaN, but it also carries +the integer inside it. The integer can be retrieved with L. +Note, though, that the payload is not propagated, not even on copies, +and definitely not in arithmetic operations. + +How many bits fit in the NaN depends on what kind of floating points +are being used, but on the most common platforms (64-bit IEEE 754, +or the x86 80-bit long doubles) there are 51 and 61 bits available, +respectively. (There would be 52 and 62, but the quiet/signaling +bit of NaNs takes away one.) However, because of the floating-point-to- +integer-and-back conversions, please test carefully whether you get back +what you put in. If your integers are only 32 bits wide, you probably +should not rely on more than 32 bits of payload. -See also L. +Whether a "signaling" NaN is in any way different from a "quiet" NaN, +depends on the platform. Also note that the payload of the default +NaN (no argument to nan()) is not necessarily zero, use C +to explicitly set the payload. On some platforms like the 32-bit x86, +(unless using the 80-bit long doubles) the signaling bit is not supported +at all. + +See also L, L, L and L. =item C @@ -1203,15 +1195,19 @@ rounding mode (see L) [C99]. =item C -Returns the next representable floating point number after x in the -direction of y [C99]. +Returns the next representable floating point number after C in the +direction of C [C99]. + + my $nextafter = POSIX::nextafter($x, $y); Like L, but potentially less accurate. =item C -Returns the next representable floating point number after x in the -direction of y [C99]. +Returns the next representable floating point number after C in the +direction of C [C99]. + + my $nexttoward = POSIX::nexttoward($x, $y); Like L, but potentially more accurate. @@ -1219,14 +1215,15 @@ Like L, but potentially more accurate. This is similar to the C function C, for changing the scheduling preference of the current process. Positive -arguments mean more polite process, negative values more -needy process. Normal user processes can only be more polite. +arguments mean a more polite process, negative values a more +needy process. Normal (non-root) user processes can only change towards +being more polite. Returns C on failure. =item C -C is C-specific, you probably want to see L instead. +Not implemented. C is C-specific, you probably want to see L instead. =item C @@ -1314,24 +1311,24 @@ You can also use the C<**> operator, see L. =item C -Formats and prints the specified arguments to STDOUT. +Formats and prints the specified arguments to C. See also L. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C @@ -1340,7 +1337,7 @@ See also L and the C<$$> in L. =item C -C is non-portable, see L instead. +Not implemented. C is non-portable, see L instead. =item C @@ -1362,12 +1359,14 @@ for reading directory entries, see L. =item C -C is C-specific. Perl does memory management transparently. +Not implemented. C is C-specific. Perl does memory management transparently. =item C -Given x and y, returns the value x - n*y, where n is the integer -closest to x/y. [C99] +Given C and C, returns the value S>, where C is the integer +closest to C/C. [C99] + + my $remainder = POSIX::remainder($x, $y) See also L. @@ -1416,13 +1415,13 @@ See also L, L, L, L, and L. =item C -Returns x * 2**y [C99]. +Returns S> [C99]. See also L and L. =item C -C is C-specific, use EE and regular expressions instead, +Not implemented. C is C-specific, use EE and regular expressions instead, see L. =item C @@ -1436,11 +1435,18 @@ list of numbers. =item C -C is C-specific: use C instead, +Not implemented. C is C-specific: use C instead, see L. =item C +WARNING! Do NOT use this function in a L. The locale +will change in all other threads at the same time, and should your +thread get paused by the operating system, and another started, that +thread will not have the locale it is expecting. On some platforms, +there can be a race leading to segfaults if two threads call this +function nearly simultaneously. + Modifies and queries the program's underlying locale. Users of this function should read L, whch provides a comprehensive discussion of Perl locale handling, knowledge of which is necessary to @@ -1481,6 +1487,38 @@ out which locales are available in your system. $loc = setlocale( LC_COLLATE, "es_AR.ISO8859-1" ); +=item C + + use POSIX ':nan_payload'; + setpayload($var, $payload); + +Sets the C payload of var. + +NOTE: the NaN payload APIs are based on the latest (as of June 2015) +proposed ISO C interfaces, but they are not yet a standard. Things +may change. + +See L for more discussion about C. + +See also L, L, L, and L. + +=item C + + use POSIX ':nan_payload'; + setpayloadsig($var, $payload); + +Like L but also makes the NaN I. + +Depending on the platform the NaN may or may not behave differently. + +Note the API instability warning in L. + +Note that because how the floating point formats work out, on the most +common platforms signaling payload of zero is best avoided, +since it might end up being identical to C<+Inf>. + +See also L, L, L, and L. + =item C This is similar to the C function C for @@ -1526,6 +1564,9 @@ semantics, as defined by POSIX/SUSv3: a user process and the uid and pid make sense, otherwise the signal was sent by the kernel +The constants for specific C values can be imported individually +or using the C<:signal_h_si_code> tag. + The following are also defined by POSIX/SUSv3, but unfortunately not very widely implemented: @@ -1533,6 +1574,8 @@ not very widely implemented: uid the uid of the process id generating the signal status exit value or signal for SIGCHLD band band event for SIGPOLL + addr address of faulting instruction or memory + reference for SIGILL, SIGFPE, SIGSEGV or SIGBUS A third argument is also passed to the handler, which contains a copy of the raw binary contents of the C structure: if a system has @@ -1546,7 +1589,7 @@ C and possibly also C documentation. =item C -C is C-specific: use L instead. +Not implemented. C is C-specific: use L instead. =item C @@ -1582,7 +1625,7 @@ reliably. =item C -C is C-specific: use C instead, +Not implemented. C is C-specific: use C instead, see L. =item C @@ -1636,7 +1679,7 @@ Give a seed the pseudorandom number generator, see L. =item C -C is C-specific, use regular expressions instead, +Not implemented. C is C-specific, use regular expressions instead, see L. =item C @@ -1646,15 +1689,15 @@ for returning information about files and directories. =item C -C is C-specific, use C<.=> instead, see L. +Not implemented. C is C-specific, use C<.=> instead, see L. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, use C or C instead, see L. +Not implemented. C is C-specific, use C or C instead, see L. =item C @@ -1663,19 +1706,23 @@ for collating (comparing) strings transformed using the C function. Not really needed since Perl can do this transparently, see L. +Beware that in a UTF-8 locale, anything you pass to this function must +be in UTF-8; and when not in a UTF-8 locale, anything passed must not be +UTF-8 encoded. + =item C -C is C-specific, use C<=> instead, see L. +Not implemented. C is C-specific, use C<=> instead, see L. =item C -C is C-specific, use regular expressions instead, +Not implemented. C is C-specific, use regular expressions instead, see L. =item C Returns the error string for the specified errno. -Identical to the string form of the C<$!>, see L. +Identical to the string form of C<$!>, see L. =item C @@ -1686,9 +1733,9 @@ Synopsis: strftime(fmt, sec, min, hour, mday, mon, year, wday = -1, yday = -1, isdst = -1) -The month (C), weekday (C), and yearday (C) begin at zero. -I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The -year (C) is given in years since 1900. I.e., the year 1995 is 95; the +The month (C), weekday (C), and yearday (C) begin at zero, +I, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The +year (C) is given in years since 1900, I, the year 1995 is 95; the year 2001 is 101. Consult your system's C manpage for details about these and the other arguments. @@ -1717,32 +1764,32 @@ The string for Tuesday, December 12, 1995. =item C -C is C-specific, use C instead, see L. +Not implemented. C is C-specific, use C instead, see L. =item C -C is C-specific, use C<.=> instead, see L. +Not implemented. C is C-specific, use C<.=> instead, see L. =item C -C is C-specific, use C instead, see L. +Not implemented. C is C-specific, use C instead, see L. =item C -C is C-specific, use C<=> instead, see L. +Not implemented. C is C-specific, use C<=> instead, see L. =item C -C is C-specific, use regular expressions instead, +Not implemented. C is C-specific, use regular expressions instead, see L. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, use regular expressions instead, +Not implemented. C is C-specific, use regular expressions instead, see L. =item C @@ -1755,12 +1802,15 @@ see L. String to double translation. Returns the parsed number and the number of characters in the unparsed portion of the string. Truly POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation -error, so clear C<$!> before calling strtod. However, non-POSIX systems +error, so clear C<$!> before calling C. However, non-POSIX systems may not check for overflow, and therefore will never set C<$!>. -strtod respects any POSIX I C settings, +C respects any POSIX C C settings, regardless of whether or not it is called from Perl code that is within -the scope of S>. +the scope of S>. This means it should not be used in a +threaded application unless it's certain that the underlying locale is C +or POSIX. This is because it otherwise changes the locale, which +globally affects all threads simultaneously. To parse a string C<$str> as a floating point number use @@ -1773,11 +1823,11 @@ The second returned item and C<$!> can be used to check for valid input: die "Non-numeric input $str" . ($! ? ": $!\n" : "\n"); } -When called in a scalar context strtod returns the parsed number. +When called in a scalar context C returns the parsed number. =item C -C is C-specific, use regular expressions instead, see +Not implemented. C is C-specific, use regular expressions instead, see L, or L. =item C @@ -1796,7 +1846,7 @@ To parse a string C<$str> as a number in some base C<$base> use ($num, $n_unparsed) = POSIX::strtol($str, $base); The base should be zero or between 2 and 36, inclusive. When the base -is zero or omitted strtol will use the string itself to determine the +is zero or omitted C will use the string itself to determine the base: a leading "0x" or "0X" means hexadecimal; a leading "0" means octal; any other leading characters mean decimal. Thus, "1234" is parsed as a decimal number, "01234" as an octal number, and "0x1234" @@ -1808,7 +1858,7 @@ The second returned item and C<$!> can be used to check for valid input: die "Non-numeric input $str" . $! ? ": $!\n" : "\n"; } -When called in a scalar context strtol returns the parsed number. +When called in a scalar context C returns the parsed number. =item C @@ -1835,6 +1885,10 @@ Used in conjunction with the C function, see L. Not really needed since Perl can do this transparently, see L. +Beware that in a UTF-8 locale, anything you pass to this function must +be in UTF-8; and when not in a UTF-8 locale, anything passed must not be +UTF-8 encoded. + =item C Retrieves values of system configurable variables. @@ -1921,7 +1975,7 @@ The C function returns elapsed realtime since some point in the past and system times used by child processes. All times are returned in clock ticks. - ($realtime, $user, $system, $cuser, $csystem) + ($realtime, $user, $system, $cuser, $csystem) = POSIX::times(); Note: Perl's builtin C function returns four values, measured in @@ -1929,31 +1983,28 @@ seconds. =item C -Use method C instead, or see L. +Not implemented. Use method C instead, or see L. =item C -Returns a name for a temporary file. - - $tmpfile = POSIX::tmpnam(); - For security reasons, which are probably detailed in your system's documentation for the C library C function, this interface -should not be used; instead see L. +is no longer available; instead use L. =item C This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using the C function, +character or to a whole string, and currently operates as if the locale +always is "C". Consider using the C function, see L, see L, or the equivalent C<\L> operator inside doublequotish strings. =item C -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using the C function, -see L, or the equivalent C<\U> operator inside doublequotish -strings. +This is similar to the C function, except that it can apply to a single +character or to a whole string, and currently operates as if the locale +always is "C". Consider using the C function, see L, +or the equivalent C<\U> operator inside doublequotish strings. =item C @@ -2004,7 +2055,7 @@ Maybe. =item C -Use method C instead. +Not implemented. Use method C instead. =item C @@ -2019,15 +2070,15 @@ see L. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C -C is C-specific, see L instead. +Not implemented. C is C-specific, see L instead. =item C @@ -2244,7 +2295,7 @@ Tests the SigSet object to see if it contains a specific signal. =item C Create a new Termios object. This object will be destroyed automatically -when it is no longer needed. A Termios object corresponds to the termios +when it is no longer needed. A Termios object corresponds to the C C struct. C mallocs a new one, C fills it from a file descriptor, and C sets a file descriptor's parameters to match Termios' contents. @@ -2254,7 +2305,7 @@ and C sets a file descriptor's parameters to match Termios' contents. Get terminal control attributes. -Obtain the attributes for stdin. +Obtain the attributes for C. $termios->getattr( 0 ) # Recommended for clarity. $termios->getattr() @@ -2267,20 +2318,20 @@ Returns C on failure. =item C -Retrieve a value from the c_cc field of a termios object. The c_cc field is +Retrieve a value from the C field of a C object. The C field is an array so an index must be specified. $c_cc[1] = $termios->getcc(1); =item C -Retrieve the c_cflag field of a termios object. +Retrieve the C field of a C object. $c_cflag = $termios->getcflag; =item C -Retrieve the c_iflag field of a termios object. +Retrieve the C field of a C object. $c_iflag = $termios->getiflag; @@ -2292,13 +2343,13 @@ Retrieve the input baud rate. =item C -Retrieve the c_lflag field of a termios object. +Retrieve the C field of a C object. $c_lflag = $termios->getlflag; =item C -Retrieve the c_oflag field of a termios object. +Retrieve the C field of a C object. $c_oflag = $termios->getoflag; @@ -2320,20 +2371,20 @@ Returns C on failure. =item C -Set a value in the c_cc field of a termios object. The c_cc field is an +Set a value in the C field of a C object. The C field is an array so an index must be specified. $termios->setcc( &POSIX::VEOF, 1 ); =item C -Set the c_cflag field of a termios object. +Set the C field of a C object. $termios->setcflag( $c_cflag | &POSIX::CLOCAL ); =item C -Set the c_iflag field of a termios object. +Set the C field of a C object. $termios->setiflag( $c_iflag | &POSIX::BRKINT ); @@ -2347,13 +2398,13 @@ Returns C on failure. =item C -Set the c_lflag field of a termios object. +Set the C field of a C object. $termios->setlflag( $c_lflag | &POSIX::ECHO ); =item C -Set the c_oflag field of a termios object. +Set the C field of a C object. $termios->setoflag( $c_oflag | &POSIX::OPOST ); @@ -2420,6 +2471,18 @@ C<_POSIX_TZNAME_MAX> C<_POSIX_VDISABLE> C<_POSIX_VERSION> =back +=head1 RESOURCE CONSTANTS + +Imported with the C<:sys_resource_h> tag. + +=over 8 + +=item Constants + +C C C + +=back + =head1 SYSTEM CONFIGURATION =over 8 @@ -2478,6 +2541,17 @@ C C C C =back +=head1 FLOATING-POINT ENVIRONMENT + +=over 8 + +=item Constants + +C C C C +on systems that support them. + +=back + =head1 LIMITS =over 8 @@ -2497,7 +2571,8 @@ C C C C =item Constants -C C C C C C +C C C C C C C +on systems that support them. =back @@ -2509,6 +2584,12 @@ C C C C C C C +C C C C C C C +C C C C +C C C C C C C C C +C C C C +on systems with C99 support. + =back =head1 SIGNAL @@ -2522,6 +2603,12 @@ C C C C C C C C< C C C C C C C C C C C C C C C C C +C C C C C C C +C C C C C C C +C C C C C C +C C C C C C C +C C C C C C C +C C C C C C =back @@ -2556,7 +2643,7 @@ C C C C =item Constants -C C C C C C C +C C C C C C =back @@ -2647,3 +2734,25 @@ is true) =back +=head1 WINSOCK + +(Windows only.) + +=over 8 + +=item Constants + +C C C C C C C +C C C C C +C C C C +C C C C +C C C C C +C C C C C +C C C C C +C C C C C +C C C C C C +C C C +C + +=back +