summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/POSIX.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/POSIX.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/POSIX.pod318
1 files changed, 162 insertions, 156 deletions
diff --git a/Master/tlpkg/tlperl/lib/POSIX.pod b/Master/tlpkg/tlperl/lib/POSIX.pod
index 0ca7bb77bb2..1d263a7bc40 100644
--- a/Master/tlpkg/tlperl/lib/POSIX.pod
+++ b/Master/tlpkg/tlperl/lib/POSIX.pod
@@ -629,6 +629,17 @@ This is identical to Perl's builtin C<getlogin()> function for
returning the user name associated with the current session, see
L<perlfunc/getlogin>.
+=item C<getpayload>
+
+ use POSIX ':nan_payload';
+ getpayload($var)
+
+Returns the C<NaN> payload.
+
+Note the API instability warning in L</setpayload>.
+
+See L</nan> for more discussion about C<NaN>.
+
=item C<getpgrp>
This is identical to Perl's builtin C<getpgrp()> function for
@@ -702,38 +713,15 @@ See also L</isinf>, and L</fpclassify>.
=item C<isalnum>
-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<C<qr/ ^ [[:alnum:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
-
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
-
-You may want to use the C<L<E<sol>\wE<sol>|perlrecharclass/Word
-characters>> construct instead.
+This function has been removed as of v5.24. It was very similar to
+matching against S<C<qr/ ^ [[:alnum:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
=item C<isalpha>
-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<C<qr/ ^ [[:alpha:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
-
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
+This function has been removed as of v5.24. It was very similar to
+matching against S<C<qr/ ^ [[:alpha:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
=item C<isatty>
@@ -742,38 +730,15 @@ to a tty. Similar to the C<-t> operator, see L<perlfunc/-X>.
=item C<iscntrl>
-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<C<qr/ ^ [[:cntrl:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
-
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
+This function has been removed as of v5.24. It was very similar to
+matching against S<C<qr/ ^ [[:cntrl:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
=item C<isdigit>
-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<C<qr/ ^ [[:digit:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
-
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
-
-You may want to use the C<L<E<sol>\dE<sol>|perlrecharclass/Digits>>
-construct instead.
+This function has been removed as of v5.24. It was very similar to
+matching against S<C<qr/ ^ [[:digit:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
=item C<isfinite>
@@ -784,19 +749,9 @@ See also L</isinf>, L</isnan>, and L</fpclassify>.
=item C<isgraph>
-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<C<qr/ ^ [[:graph:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
-
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
+This function has been removed as of v5.24. It was very similar to
+matching against S<C<qr/ ^ [[:graph:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
=item C<isgreater>
@@ -813,21 +768,9 @@ See also L</Inf>, L</isnan>, L</isfinite>, and L</fpclassify>.
=item C<islower>
-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<C<qr/ ^ [[:lower:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
-
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
-
-Do B<not> use C</[a-z]/> 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<C<qr/ ^ [[:lower:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
=item C<isnan>
@@ -850,88 +793,44 @@ See also L</isfinite>, and L</fpclassify>.
=item C<isprint>
-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<C<qr/ ^ [[:print:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
-
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
+This function has been removed as of v5.24. It was very similar to
+matching against S<C<qr/ ^ [[:print:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
=item C<ispunct>
-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<C<qr/ ^ [[:punct:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
+This function has been removed as of v5.24. It was very similar to
+matching against S<C<qr/ ^ [[:punct:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
+=item C<issignaling>
-=item C<isspace>
+ 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<C<qr/ ^ [[:space:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
+Return true if the argument is a I<signaling> NaN.
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
+Note the API instability warning in L</setpayload>.
-You may want to use the C<L<E<sol>\sE<sol>|perlrecharclass/Whitespace>>
-construct instead.
+See L</nan> for more discussion about C<NaN>.
-=item C<isupper>
+=item C<isspace>
-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<C<qr/ ^ [[:upper:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
+This function has been removed as of v5.24. It was very similar to
+matching against S<C<qr/ ^ [[:space:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
+=item C<isupper>
-Do B<not> use C</[A-Z]/> 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<C<qr/ ^ [[:upper:]]+ $ /x>>, which you should convert
+to use instead. See L<perlrecharclass/POSIX Character Classes>.
=item C<isxdigit>
-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<C<qr/ ^ [[:xdigit:]]+ $ /x>>, 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<TRUE> 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<perlre/Character set modifiers> and L<perlre/Which character set
-modifier is in effect?>).
-
-The function returns C<TRUE> if the input string is empty, or if the
-corresponding C function returns C<TRUE> for every byte in the string.
+This function has been removed as of v5.24. It was very similar to
+matching against S<C<qr/ ^ [[:xdigit:]]+ $ /x>>, which you should
+convert to use instead. See L<perlrecharclass/POSIX Character Classes>.
=item C<j0>
@@ -1112,6 +1011,10 @@ Like L</round>, but as integer, as opposed to floating point [C99].
See also L</ceil>, L</floor>, L</trunc>.
+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. This will be changed in Perl 5.26.
+
=item C<malloc>
Not implemented. C<malloc()> is C-specific. Perl does memory management transparently.
@@ -1215,9 +1118,40 @@ See also L</nan>, C</isnan>, and L</fpclassify>.
=item C<nan>
-Returns not-a-number [C99].
+ my $nan = nan();
+
+Returns C<NaN>, not-a-number [C99].
+
+The returned NaN is always a I<quiet> NaN, as opposed to I<signaling>.
+
+With an argument, can be used to generate a NaN with I<payload>.
+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</getpayload>.
+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</isnan> and L</NaN>.
+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<setpayload>
+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</isnan>, L</NaN>, L</setpayload> and L</issignaling>.
=item C<nearbyint>
@@ -1395,7 +1329,7 @@ Not implemented. C<realloc()> is C-specific. Perl does memory management trans
=item C<remainder>
Given C<x> and C<y>, returns the value S<C<x - n*y>>, where C<n> is the integer
-closest to C<x/y>. [C99]
+closest to C<x>/C<y>. [C99]
my $remainder = POSIX::remainder($x, $y)
@@ -1471,6 +1405,13 @@ see L<perlfunc/eval>.
=item C<setlocale>
+WARNING! Do NOT use this function in a L<thread|threads>. 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<perllocale>, whch provides a comprehensive
discussion of Perl locale handling, knowledge of which is necessary to
@@ -1511,6 +1452,38 @@ out which locales are available in your system.
$loc = setlocale( LC_COLLATE, "es_AR.ISO8859-1" );
+=item C<setpayload>
+
+ use POSIX ':nan_payload';
+ setpayload($var, $payload);
+
+Sets the C<NaN> 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</nan> for more discussion about C<NaN>.
+
+See also L</setpayloadsig>, L</isnan>, L</getpayload>, and L</issignaling>.
+
+=item C<setpayloadsig>
+
+ use POSIX ':nan_payload';
+ setpayloadsig($var, $payload);
+
+Like L</setpayload> but also makes the NaN I<signaling>.
+
+Depending on the platform the NaN may or may not behave differently.
+
+Note the API instability warning in L</setpayload>.
+
+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</nan>, L</isnan>, L</getpayload>, and L</issignaling>.
+
=item C<setpgid>
This is similar to the C function C<setpgid()> for
@@ -1556,6 +1529,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<code> 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:
@@ -1563,6 +1539,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<siginfo> structure: if a system has
@@ -2571,6 +2549,12 @@ C<SA_SIGINFO> C<SIGABRT> C<SIGALRM> C<SIGCHLD> C<SIGCONT> C<SIGFPE> C<SIGHUP> C<
C<SIGKILL> C<SIGPIPE> C<SIGQUIT> C<SIGSEGV> C<SIGSTOP> C<SIGTERM> C<SIGTSTP> C<SIGTTIN> C<SIGTTOU>
C<SIGUSR1> C<SIGUSR2> C<SIG_BLOCK> C<SIG_DFL> C<SIG_ERR> C<SIG_IGN> C<SIG_SETMASK>
C<SIG_UNBLOCK>
+C<ILL_ILLOPC> C<ILL_ILLOPN> C<ILL_ILLADR> C<ILL_ILLTRP> C<ILL_PRVOPC> C<ILL_PRVREG> C<ILL_COPROC>
+C<ILL_BADSTK> C<FPE_INTDIV> C<FPE_INTOVF> C<FPE_FLTDIV> C<FPE_FLTOVF> C<FPE_FLTUND> C<FPE_FLTRES>
+C<FPE_FLTINV> C<FPE_FLTSUB> C<SEGV_MAPERR> C<SEGV_ACCERR> C<BUS_ADRALN> C<BUS_ADRERR>
+C<BUS_OBJERR> C<TRAP_BRKPT> C<TRAP_TRACE> C<CLD_EXITED> C<CLD_KILLED> C<CLD_DUMPED> C<CLD_TRAPPED>
+C<CLD_STOPPED> C<CLD_CONTINUED> C<POLL_IN> C<POLL_OUT> C<POLL_MSG> C<POLL_ERR> C<POLL_PRI>
+C<POLL_HUP> C<SI_USER> C<SI_QUEUE> C<SI_TIMER> C<SI_ASYNCIO> C<SI_MESGQ>
=back
@@ -2696,3 +2680,25 @@ is true)
=back
+=head1 WINSOCK
+
+(Windows only.)
+
+=over 8
+
+=item Constants
+
+C<WSAEINTR> C<WSAEBADF> C<WSAEACCES> C<WSAEFAULT> C<WSAEINVAL> C<WSAEMFILE> C<WSAEWOULDBLOCK>
+C<WSAEINPROGRESS> C<WSAEALREADY> C<WSAENOTSOCK> C<WSAEDESTADDRREQ> C<WSAEMSGSIZE>
+C<WSAEPROTOTYPE> C<WSAENOPROTOOPT> C<WSAEPROTONOSUPPORT> C<WSAESOCKTNOSUPPORT>
+C<WSAEOPNOTSUPP> C<WSAEPFNOSUPPORT> C<WSAEAFNOSUPPORT> C<WSAEADDRINUSE>
+C<WSAEADDRNOTAVAIL> C<WSAENETDOWN> C<WSAENETUNREACH> C<WSAENETRESET> C<WSAECONNABORTED>
+C<WSAECONNRESET> C<WSAENOBUFS> C<WSAEISCONN> C<WSAENOTCONN> C<WSAESHUTDOWN>
+C<WSAETOOMANYREFS> C<WSAETIMEDOUT> C<WSAECONNREFUSED> C<WSAELOOP> C<WSAENAMETOOLONG>
+C<WSAEHOSTDOWN> C<WSAEHOSTUNREACH> C<WSAENOTEMPTY> C<WSAEPROCLIM> C<WSAEUSERS>
+C<WSAEDQUOT> C<WSAESTALE> C<WSAEREMOTE> C<WSAEDISCON> C<WSAENOMORE> C<WSAECANCELLED>
+C<WSAEINVALIDPROCTABLE> C<WSAEINVALIDPROVIDER> C<WSAEPROVIDERFAILEDINIT>
+C<WSAEREFUSED>
+
+=back
+