This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
POSIX.pod: Document [C99] notation
[perl5.git] / ext / POSIX / lib / POSIX.pod
CommitLineData
37120919
AD
1=head1 NAME
2
3POSIX - Perl interface to IEEE Std 1003.1
4
cb1a09d0
AD
5=head1 SYNOPSIS
6
a17b2d91 7 use POSIX ();
cb1a09d0
AD
8 use POSIX qw(setsid);
9 use POSIX qw(:errno_h :fcntl_h);
10
11 printf "EINTR is %d\n", EINTR;
12
13 $sess_id = POSIX::setsid();
14
15 $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644);
16 # note: that's a filedescriptor, *NOT* a filehandle
17
37120919
AD
18=head1 DESCRIPTION
19
20The POSIX module permits you to access all (or nearly all) the standard
21POSIX 1003.1 identifiers. Many of these identifiers have been given Perl-ish
90b1bb76
MS
22interfaces.
23
37120919
AD
24This document gives a condensed list of the features available in the POSIX
25module. Consult your operating system's manpages for general information on
26most features. Consult L<perlfunc> for functions which are noted as being
dc416353 27identical or almost identical to Perl's builtin functions.
37120919
AD
28
29The first section describes POSIX functions from the 1003.1 specification.
30The second section describes some classes for signal objects, TTY objects,
31and other miscellaneous objects. The remaining sections list various
32constants and macros in an organization which roughly follows IEEE Std
331003.1b-1993.
34
2f02cce3
KW
35The notation C<[C99]> indicates functions that were added in the ISO/IEC
369899:1999 version of the C language standard. Some may not be available
37on your system if it adheres to an earlier standard. Attempts to use
38any missing one will result in a fatal runtime error message.
39
3609ea0d 40=head1 CAVEATS
37120919 41
ea660a4b
AP
42I<Everything is exported by default> (with a handful of exceptions).
43This is an unfortunate backwards compatibility feature and its use is
44B<strongly L<discouraged|perlpolicy/discouraged>>.
45You should either prevent the exporting (by saying S<C<use POSIX ();>>,
46as usual) and then use fully qualified names (e.g. C<POSIX::SEEK_END>),
47or give an explicit import list.
48If you do neither and opt for the default (as in S<C<use POSIX;>>), you
49will import I<hundreds and hundreds> of symbols into your namespace.
50
37120919
AD
51A few functions are not implemented because they are C specific. If you
52attempt to call these, they will print a message telling you that they
41cd218c
KW
53aren't implemented, and suggest using the Perl equivalent, should one
54exist. For example, trying to access the C<setjmp()> call will elicit the
55message "C<setjmp() is C-specific: use eval {} instead>".
37120919
AD
56
57Furthermore, some evil vendors will claim 1003.1 compliance, but in fact
58are not so: they will not pass the PCTS (POSIX Compliance Test Suites).
41cd218c
KW
59For example, one vendor may not define C<EDEADLK>, or the semantics of the
60errno values set by C<open(2)> might not be quite right. Perl does not
37120919
AD
61attempt to verify POSIX compliance. That means you can currently
62successfully say "use POSIX", and then later in your program you find
41cd218c 63that your vendor has been lax and there's no usable C<ICANON> macro after
37120919
AD
64all. This could be construed to be a bug.
65
66=head1 FUNCTIONS
67
68=over 8
69
41cd218c 70=item C<_exit>
37120919 71
4755096e
GS
72This is identical to the C function C<_exit()>. It exits the program
73immediately which means among other things buffered I/O is B<not> flushed.
37120919 74
15978375
JH
75Note that when using threads and in Linux this is B<not> a good way to
76exit a thread because in Linux processes and threads are kind of the
77same thing (Note: while this is the situation in early 2003 there are
78projects under way to have threads with more POSIXly semantics in Linux).
79If you want not to return from a thread, detach the thread.
80
41cd218c 81=item C<abort>
37120919 82
4755096e
GS
83This is identical to the C function C<abort()>. It terminates the
84process with a C<SIGABRT> signal unless caught by a signal handler or
85if the handler does not return normally (it e.g. does a C<longjmp>).
37120919 86
41cd218c 87=item C<abs>
37120919 88
bda53d3e
JK
89This is identical to Perl's builtin C<abs()> function, returning the absolute
90value of its numerical argument (except that C<POSIX::abs()> must be provided
91an explicit value (rather than relying on an implicit C<$_>):
92
93 $absolute_value = POSIX::abs(42); # good
94
95 $absolute_value = POSIX::abs(); # throws exception
37120919 96
41cd218c 97=item C<access>
37120919
AD
98
99Determines the accessibility of a file.
100
101 if( POSIX::access( "/", &POSIX::R_OK ) ){
102 print "have read permission\n";
103 }
104
4755096e
GS
105Returns C<undef> on failure. Note: do not use C<access()> for
106security purposes. Between the C<access()> call and the operation
107you are preparing for the permissions might change: a classic
108I<race condition>.
37120919 109
41cd218c 110=item C<acos>
37120919 111
4755096e 112This is identical to the C function C<acos()>, returning
c2e66d9e 113the arcus cosine of its numerical argument. See also L<Math::Trig>.
37120919 114
9d233e12
JH
115=item C<acosh>
116
4d0de388 117This is identical to the C function C<acosh()>, returning the
9d233e12 118hyperbolic arcus cosine of its numerical argument [C99]. See also
912a1e06 119L<Math::Trig>. Added in Perl v5.22.
9d233e12 120
41cd218c 121=item C<alarm>
37120919 122
bda53d3e
JK
123This is identical to Perl's builtin C<alarm()> function, either for arming or
124disarming the C<SIGARLM> timer, except that C<POSIX::alarm()> must be provided
125an explicit value (rather than relying on an implicit C<$_>):
126
127 POSIX::alarm(3) # good
128
129 POSIX::alarm() # throws exception
37120919 130
41cd218c 131=item C<asctime>
37120919 132
4755096e
GS
133This is identical to the C function C<asctime()>. It returns
134a string of the form
135
136 "Fri Jun 2 18:22:13 2000\n\0"
137
138and it is called thusly
139
b70c169c
FC
140 $asctime = asctime($sec, $min, $hour, $mday, $mon,
141 $year, $wday, $yday, $isdst);
4755096e
GS
142
143The C<$mon> is zero-based: January equals C<0>. The C<$year> is
c1646883
RGS
1441900-based: 2001 equals C<101>. C<$wday> and C<$yday> default to zero
145(and are usually ignored anyway), and C<$isdst> defaults to -1.
37120919 146
ff22dd70
KW
147Note the result is always in English. Use C<L</strftime>> instead to
148get a result suitable for the current locale. That function's C<%c>
149format yields the locale's preferred representation.
150
41cd218c 151=item C<asin>
37120919 152
4755096e 153This is identical to the C function C<asin()>, returning
c2e66d9e 154the arcus sine of its numerical argument. See also L<Math::Trig>.
37120919 155
9d233e12
JH
156=item C<asinh>
157
4d0de388 158This is identical to the C function C<asinh()>, returning the
9d233e12 159hyperbolic arcus sine of its numerical argument [C99]. See also
912a1e06 160L<Math::Trig>. Added in Perl v5.22.
9d233e12 161
41cd218c 162=item C<assert>
37120919 163
4755096e
GS
164Unimplemented, but you can use L<perlfunc/die> and the L<Carp> module
165to achieve similar things.
37120919 166
41cd218c 167=item C<atan>
37120919 168
4755096e 169This is identical to the C function C<atan()>, returning the
c2e66d9e 170arcus tangent of its numerical argument. See also L<Math::Trig>.
37120919 171
9d233e12
JH
172=item C<atanh>
173
4d0de388 174This is identical to the C function C<atanh()>, returning the
9d233e12 175hyperbolic arcus tangent of its numerical argument [C99]. See also
912a1e06 176L<Math::Trig>. Added in Perl v5.22.
9d233e12 177
41cd218c 178=item C<atan2>
37120919 179
4755096e
GS
180This is identical to Perl's builtin C<atan2()> function, returning
181the arcus tangent defined by its two numerical arguments, the I<y>
c2e66d9e 182coordinate and the I<x> coordinate. See also L<Math::Trig>.
37120919 183
41cd218c 184=item C<atexit>
37120919 185
4d0de388 186Not implemented. C<atexit()> is C-specific: use C<END {}> instead, see L<perlmod>.
37120919 187
41cd218c 188=item C<atof>
37120919 189
4d0de388 190Not implemented. C<atof()> is C-specific. Perl converts strings to numbers transparently.
4755096e 191If you need to force a scalar to a number, add a zero to it.
37120919 192
41cd218c 193=item C<atoi>
37120919 194
4d0de388 195Not implemented. C<atoi()> is C-specific. Perl converts strings to numbers transparently.
4755096e
GS
196If you need to force a scalar to a number, add a zero to it.
197If you need to have just the integer part, see L<perlfunc/int>.
37120919 198
41cd218c 199=item C<atol>
37120919 200
4d0de388 201Not implemented. C<atol()> is C-specific. Perl converts strings to numbers transparently.
4755096e
GS
202If you need to force a scalar to a number, add a zero to it.
203If you need to have just the integer part, see L<perlfunc/int>.
37120919 204
41cd218c 205=item C<bsearch>
37120919 206
41cd218c 207C<bsearch()> not supplied. For doing binary search on wordlists,
4755096e 208see L<Search::Dict>.
37120919 209
41cd218c 210=item C<calloc>
37120919 211
4d0de388 212Not implemented. C<calloc()> is C-specific. Perl does memory management transparently.
37120919 213
9d233e12
JH
214=item C<cbrt>
215
912a1e06 216The cube root [C99]. Added in Perl v5.22.
9d233e12 217
41cd218c 218=item C<ceil>
37120919 219
4755096e
GS
220This is identical to the C function C<ceil()>, returning the smallest
221integer value greater than or equal to the given numerical argument.
37120919 222
41cd218c 223=item C<chdir>
37120919 224
bda53d3e
JK
225This is identical to Perl's builtin C<chdir()> function, allowing one to
226change the working (default) directory -- see L<perlfunc/chdir> -- with the
227exception that C<POSIX::chdir()> must be provided an explicit value (rather
228than relying on an implicit C<$_>):
229
230 $rv = POSIX::chdir('path/to/dir'); # good
231
232 $rv = POSIX::chdir(); # throws exception
37120919 233
41cd218c 234=item C<chmod>
37120919 235
4755096e 236This is identical to Perl's builtin C<chmod()> function, allowing
bda53d3e
JK
237one to change file and directory permissions -- see L<perlfunc/chmod> -- with
238the exception that C<POSIX::chmod()> can only change one file at a time
239(rather than a list of files):
240
241 $c = chmod 0664, $file1, $file2; # good
242
243 $c = POSIX::chmod 0664, $file1; # throws exception
244
245 $c = POSIX::chmod 0664, $file1, $file2; # throws exception
37120919 246
c6f0b8ca
TC
247As with the built-in C<chmod()>, C<$file> may be a filename or a file
248handle.
249
41cd218c 250=item C<chown>
37120919 251
4755096e
GS
252This is identical to Perl's builtin C<chown()> function, allowing one
253to change file and directory owners and groups, see L<perlfunc/chown>.
37120919 254
41cd218c 255=item C<clearerr>
37120919 256
4d0de388 257Not implemented. Use the method C<IO::Handle::clearerr()> instead, to reset the error
4755096e 258state (if any) and EOF state (if any) of the given stream.
37120919 259
41cd218c 260=item C<clock>
37120919 261
4755096e
GS
262This is identical to the C function C<clock()>, returning the
263amount of spent processor time in microseconds.
37120919 264
41cd218c 265=item C<close>
37120919 266
cb1a09d0
AD
267Close the file. This uses file descriptors such as those obtained by calling
268C<POSIX::open>.
269
270 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
271 POSIX::close( $fd );
37120919
AD
272
273Returns C<undef> on failure.
274
4755096e
GS
275See also L<perlfunc/close>.
276
41cd218c 277=item C<closedir>
37120919 278
4755096e
GS
279This is identical to Perl's builtin C<closedir()> function for closing
280a directory handle, see L<perlfunc/closedir>.
37120919 281
41cd218c 282=item C<cos>
37120919 283
4755096e
GS
284This is identical to Perl's builtin C<cos()> function, for returning
285the cosine of its numerical argument, see L<perlfunc/cos>.
c2e66d9e 286See also L<Math::Trig>.
37120919 287
41cd218c 288=item C<cosh>
37120919 289
4755096e 290This is identical to the C function C<cosh()>, for returning
c2e66d9e 291the hyperbolic cosine of its numeric argument. See also L<Math::Trig>.
37120919 292
9d233e12
JH
293=item C<copysign>
294
912a1e06 295Returns C<x> but with the sign of C<y> [C99]. Added in Perl v5.22.
4d0de388
KW
296
297 $x_with_sign_of_y = POSIX::copysign($x, $y);
9d233e12
JH
298
299See also L</signbit>.
300
41cd218c 301=item C<creat>
37120919 302
cb1a09d0
AD
303Create a new file. This returns a file descriptor like the ones returned by
304C<POSIX::open>. Use C<POSIX::close> to close the file.
305
306 $fd = POSIX::creat( "foo", 0611 );
307 POSIX::close( $fd );
37120919 308
4755096e
GS
309See also L<perlfunc/sysopen> and its C<O_CREAT> flag.
310
41cd218c 311=item C<ctermid>
37120919 312
cb1a09d0 313Generates the path name for the controlling terminal.
37120919
AD
314
315 $path = POSIX::ctermid();
316
41cd218c 317=item C<ctime>
37120919 318
4755096e
GS
319This is identical to the C function C<ctime()> and equivalent
320to C<asctime(localtime(...))>, see L</asctime> and L</localtime>.
37120919 321
631637d8 322=item C<cuserid> [POSIX.1-1988]
37120919 323
4755096e 324Get the login name of the owner of the current process.
37120919
AD
325
326 $name = POSIX::cuserid();
327
631637d8
MB
328Note: this function has not been specified by POSIX since 1990 and is included
329only for backwards compatibility. New code should use L<C<getlogin()>|perlfunc/getlogin> instead.
330
41cd218c 331=item C<difftime>
37120919 332
4755096e
GS
333This is identical to the C function C<difftime()>, for returning
334the time difference (in seconds) between two times (as returned
335by C<time()>), see L</time>.
37120919 336
41cd218c 337=item C<div>
37120919 338
4d0de388 339Not implemented. C<div()> is C-specific, use L<perlfunc/int> on the usual C</> division and
4755096e 340the modulus C<%>.
37120919 341
41cd218c 342=item C<dup>
37120919 343
4755096e
GS
344This is similar to the C function C<dup()>, for duplicating a file
345descriptor.
cb1a09d0
AD
346
347This uses file descriptors such as those obtained by calling
348C<POSIX::open>.
37120919
AD
349
350Returns C<undef> on failure.
351
41cd218c 352=item C<dup2>
37120919 353
4755096e
GS
354This is similar to the C function C<dup2()>, for duplicating a file
355descriptor to an another known file descriptor.
cb1a09d0
AD
356
357This uses file descriptors such as those obtained by calling
358C<POSIX::open>.
37120919
AD
359
360Returns C<undef> on failure.
361
9d233e12
JH
362=item C<erf>
363
912a1e06 364The error function [C99]. Added in Perl v5.22.
9d233e12
JH
365
366=item C<erfc>
367
912a1e06 368The complementary error function [C99]. Added in Perl v5.22.
9d233e12 369
41cd218c 370=item C<errno>
37120919
AD
371
372Returns the value of errno.
373
374 $errno = POSIX::errno();
375
4755096e
GS
376This identical to the numerical values of the C<$!>, see L<perlvar/$ERRNO>.
377
41cd218c 378=item C<execl>
37120919 379
4d0de388 380Not implemented. C<execl()> is C-specific, see L<perlfunc/exec>.
37120919 381
41cd218c 382=item C<execle>
37120919 383
4d0de388 384Not implemented. C<execle()> is C-specific, see L<perlfunc/exec>.
37120919 385
41cd218c 386=item C<execlp>
37120919 387
4d0de388 388Not implemented. C<execlp()> is C-specific, see L<perlfunc/exec>.
37120919 389
41cd218c 390=item C<execv>
37120919 391
4d0de388 392Not implemented. C<execv()> is C-specific, see L<perlfunc/exec>.
37120919 393
41cd218c 394=item C<execve>
37120919 395
4d0de388 396Not implemented. C<execve()> is C-specific, see L<perlfunc/exec>.
37120919 397
41cd218c 398=item C<execvp>
37120919 399
4d0de388 400Not implemented. C<execvp()> is C-specific, see L<perlfunc/exec>.
37120919 401
41cd218c 402=item C<exit>
37120919 403
4755096e
GS
404This is identical to Perl's builtin C<exit()> function for exiting the
405program, see L<perlfunc/exit>.
37120919 406
41cd218c 407=item C<exp>
37120919 408
4755096e
GS
409This is identical to Perl's builtin C<exp()> function for
410returning the exponent (I<e>-based) of the numerical argument,
411see L<perlfunc/exp>.
37120919 412
9d233e12
JH
413=item C<expm1>
414
415Equivalent to C<exp(x) - 1>, but more precise for small argument values [C99].
912a1e06 416Added in Perl v5.22.
9d233e12
JH
417
418See also L</log1p>.
419
41cd218c 420=item C<fabs>
37120919 421
4755096e
GS
422This is identical to Perl's builtin C<abs()> function for returning
423the absolute value of the numerical argument, see L<perlfunc/abs>.
37120919 424
41cd218c 425=item C<fclose>
37120919 426
4d0de388 427Not implemented. Use method C<IO::Handle::close()> instead, or see L<perlfunc/close>.
37120919 428
41cd218c 429=item C<fcntl>
37120919 430
4755096e
GS
431This is identical to Perl's builtin C<fcntl()> function,
432see L<perlfunc/fcntl>.
37120919 433
41cd218c 434=item C<fdopen>
37120919 435
4d0de388 436Not implemented. Use method C<IO::Handle::new_from_fd()> instead, or see L<perlfunc/open>.
37120919 437
41cd218c 438=item C<feof>
37120919 439
4d0de388 440Not implemented. Use method C<IO::Handle::eof()> instead, or see L<perlfunc/eof>.
37120919 441
41cd218c 442=item C<ferror>
37120919 443
4d0de388 444Not implemented. Use method C<IO::Handle::error()> instead.
37120919 445
41cd218c 446=item C<fflush>
37120919 447
4d0de388 448Not implemented. Use method C<IO::Handle::flush()> instead.
41cd218c 449See also C<L<perlvar/$OUTPUT_AUTOFLUSH>>.
37120919 450
41cd218c 451=item C<fgetc>
37120919 452
4d0de388 453Not implemented. Use method C<IO::Handle::getc()> instead, or see L<perlfunc/read>.
37120919 454
41cd218c 455=item C<fgetpos>
37120919 456
4d0de388 457Not implemented. Use method C<IO::Seekable::getpos()> instead, or see L<perlfunc/seek>.
37120919 458
41cd218c 459=item C<fgets>
37120919 460
4d0de388 461Not implemented. Use method C<IO::Handle::gets()> instead. Similar to E<lt>E<gt>, also known
4755096e 462as L<perlfunc/readline>.
37120919 463
41cd218c 464=item C<fileno>
37120919 465
4d0de388 466Not implemented. Use method C<IO::Handle::fileno()> instead, or see L<perlfunc/fileno>.
37120919 467
41cd218c 468=item C<floor>
37120919 469
4755096e
GS
470This is identical to the C function C<floor()>, returning the largest
471integer value less than or equal to the numerical argument.
37120919 472
9d233e12
JH
473=item C<fdim>
474
4d0de388 475"Positive difference", S<C<x - y>> if S<C<x E<gt> y>>, zero otherwise [C99].
912a1e06 476Added in Perl v5.22.
9d233e12
JH
477
478=item C<fegetround>
479
480Returns the current floating point rounding mode, one of
481
387e2cd4 482 FE_TONEAREST FE_TOWARDZERO FE_UPWARD FE_DOWNWARD
9d233e12 483
4d0de388 484C<FE_TONEAREST> is like L</round>, C<FE_TOWARDZERO> is like L</trunc> [C99].
912a1e06 485Added in Perl v5.22.
9d233e12
JH
486
487=item C<fesetround>
488
912a1e06
DB
489Sets the floating point rounding mode, see L</fegetround> [C99]. Added in
490Perl v5.22.
9d233e12
JH
491
492=item C<fma>
493
4d0de388 494"Fused multiply-add", S<C<x * y + z>>, possibly faster (and less lossy)
912a1e06 495than the explicit two operations [C99]. Added in Perl v5.22.
9d233e12 496
4d0de388
KW
497 my $fused = POSIX::fma($x, $y, $z);
498
9d233e12
JH
499=item C<fmax>
500
4d0de388 501Maximum of C<x> and C<y>, except when either is C<NaN>, returns the other [C99].
912a1e06 502Added in Perl v5.22.
4d0de388
KW
503
504 my $min = POSIX::fmax($x, $y);
9d233e12
JH
505
506=item C<fmin>
507
4d0de388 508Minimum of C<x> and C<y>, except when either is C<NaN>, returns the other [C99].
912a1e06 509Added in Perl v5.22.
4d0de388
KW
510
511 my $min = POSIX::fmin($x, $y);
9d233e12 512
41cd218c 513=item C<fmod>
37120919
AD
514
515This is identical to the C function C<fmod()>.
516
847f7ebc 517 $r = fmod($x, $y);
4755096e 518
4d0de388 519It returns the remainder S<C<$r = $x - $n*$y>>, where S<C<$n = trunc($x/$y)>>.
4755096e
GS
520The C<$r> has the same sign as C<$x> and magnitude (absolute value)
521less than the magnitude of C<$y>.
522
41cd218c 523=item C<fopen>
37120919 524
4d0de388 525Not implemented. Use method C<IO::File::open()> instead, or see L<perlfunc/open>.
37120919 526
41cd218c 527=item C<fork>
37120919 528
c2e66d9e
GS
529This is identical to Perl's builtin C<fork()> function
530for duplicating the current process, see L<perlfunc/fork>
531and L<perlfork> if you are in Windows.
37120919 532
41cd218c 533=item C<fpathconf>
37120919 534
cb1a09d0
AD
535Retrieves the value of a configurable limit on a file or directory. This
536uses file descriptors such as those obtained by calling C<POSIX::open>.
537
538The following will determine the maximum length of the longest allowable
f703fc96 539pathname on the filesystem which holds F</var/foo>.
cb1a09d0 540
2359510d 541 $fd = POSIX::open( "/var/foo", &POSIX::O_RDONLY );
b70c169c 542 $path_max = POSIX::fpathconf($fd, &POSIX::_PC_PATH_MAX);
37120919
AD
543
544Returns C<undef> on failure.
545
9d233e12
JH
546=item C<fpclassify>
547
548Returns one of
549
550 FP_NORMAL FP_ZERO FP_SUBNORMAL FP_INFINITE FP_NAN
551
d7a0f0b0
JH
552telling the class of the argument [C99]. C<FP_INFINITE> is positive
553or negative infinity, C<FP_NAN> is not-a-number. C<FP_SUBNORMAL>
554means subnormal numbers (also known as denormals), very small numbers
555with low precision. C<FP_ZERO> is zero. C<FP_NORMAL> is all the rest.
912a1e06 556Added in Perl v5.22.
9d233e12 557
41cd218c 558=item C<fprintf>
37120919 559
4d0de388 560Not implemented. C<fprintf()> is C-specific, see L<perlfunc/printf> instead.
37120919 561
41cd218c 562=item C<fputc>
37120919 563
4d0de388 564Not implemented. C<fputc()> is C-specific, see L<perlfunc/print> instead.
37120919 565
41cd218c 566=item C<fputs>
37120919 567
4d0de388 568Not implemented. C<fputs()> is C-specific, see L<perlfunc/print> instead.
37120919 569
41cd218c 570=item C<fread>
37120919 571
4d0de388 572Not implemented. C<fread()> is C-specific, see L<perlfunc/read> instead.
37120919 573
41cd218c 574=item C<free>
37120919 575
4d0de388 576Not implemented. C<free()> is C-specific. Perl does memory management transparently.
37120919 577
41cd218c 578=item C<freopen>
37120919 579
4d0de388 580Not implemented. C<freopen()> is C-specific, see L<perlfunc/open> instead.
37120919 581
41cd218c 582=item C<frexp>
37120919 583
cb1a09d0
AD
584Return the mantissa and exponent of a floating-point number.
585
4755096e 586 ($mantissa, $exponent) = POSIX::frexp( 1.234e56 );
37120919 587
41cd218c 588=item C<fscanf>
37120919 589
4d0de388 590Not implemented. C<fscanf()> is C-specific, use E<lt>E<gt> and regular expressions instead.
37120919 591
41cd218c 592=item C<fseek>
37120919 593
4d0de388 594Not implemented. Use method C<IO::Seekable::seek()> instead, or see L<perlfunc/seek>.
37120919 595
41cd218c 596=item C<fsetpos>
37120919 597
4d0de388 598Not implemented. Use method C<IO::Seekable::setpos()> instead, or seek L<perlfunc/seek>.
37120919 599
41cd218c 600=item C<fstat>
37120919 601
cb1a09d0
AD
602Get file status. This uses file descriptors such as those obtained by
603calling C<POSIX::open>. The data returned is identical to the data from
604Perl's builtin C<stat> function.
605
606 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
607 @stats = POSIX::fstat( $fd );
37120919 608
41cd218c 609=item C<fsync>
f0709b24 610
4d0de388 611Not implemented. Use method C<IO::Handle::sync()> instead.
f0709b24 612
41cd218c 613=item C<ftell>
37120919 614
4d0de388 615Not implemented. Use method C<IO::Seekable::tell()> instead, or see L<perlfunc/tell>.
37120919 616
41cd218c 617=item C<fwrite>
37120919 618
4d0de388 619Not implemented. C<fwrite()> is C-specific, see L<perlfunc/print> instead.
37120919 620
41cd218c 621=item C<getc>
37120919 622
4755096e
GS
623This is identical to Perl's builtin C<getc()> function,
624see L<perlfunc/getc>.
37120919 625
41cd218c 626=item C<getchar>
37120919 627
4755096e
GS
628Returns one character from STDIN. Identical to Perl's C<getc()>,
629see L<perlfunc/getc>.
37120919 630
41cd218c 631=item C<getcwd>
37120919
AD
632
633Returns the name of the current working directory.
4755096e 634See also L<Cwd>.
37120919 635
41cd218c 636=item C<getegid>
37120919 637
4755096e
GS
638Returns the effective group identifier. Similar to Perl' s builtin
639variable C<$(>, see L<perlvar/$EGID>.
37120919 640
41cd218c 641=item C<getenv>
37120919 642
d7f8936a 643Returns the value of the specified environment variable.
4755096e 644The same information is available through the C<%ENV> array.
37120919 645
41cd218c 646=item C<geteuid>
37120919 647
4755096e
GS
648Returns the effective user identifier. Identical to Perl's builtin C<$E<gt>>
649variable, see L<perlvar/$EUID>.
37120919 650
41cd218c 651=item C<getgid>
37120919 652
4755096e
GS
653Returns the user's real group identifier. Similar to Perl's builtin
654variable C<$)>, see L<perlvar/$GID>.
37120919 655
41cd218c 656=item C<getgrgid>
37120919 657
4755096e
GS
658This is identical to Perl's builtin C<getgrgid()> function for
659returning group entries by group identifiers, see
660L<perlfunc/getgrgid>.
37120919 661
41cd218c 662=item C<getgrnam>
37120919 663
4755096e
GS
664This is identical to Perl's builtin C<getgrnam()> function for
665returning group entries by group names, see L<perlfunc/getgrnam>.
37120919 666
41cd218c 667=item C<getgroups>
37120919 668
4755096e
GS
669Returns the ids of the user's supplementary groups. Similar to Perl's
670builtin variable C<$)>, see L<perlvar/$GID>.
37120919 671
41cd218c 672=item C<getlogin>
37120919 673
4755096e
GS
674This is identical to Perl's builtin C<getlogin()> function for
675returning the user name associated with the current session, see
676L<perlfunc/getlogin>.
37120919 677
07bb61ac
JH
678=item C<getpayload>
679
680 use POSIX ':nan_payload';
681 getpayload($var)
682
912a1e06 683Returns the C<NaN> payload. Added in Perl v5.24.
07bb61ac
JH
684
685Note the API instability warning in L</setpayload>.
686
687See L</nan> for more discussion about C<NaN>.
688
41cd218c 689=item C<getpgrp>
37120919 690
4755096e 691This is identical to Perl's builtin C<getpgrp()> function for
d7f8936a 692returning the process group identifier of the current process, see
4755096e 693L<perlfunc/getpgrp>.
37120919 694
41cd218c 695=item C<getpid>
37120919 696
4755096e
GS
697Returns the process identifier. Identical to Perl's builtin
698variable C<$$>, see L<perlvar/$PID>.
37120919 699
41cd218c 700=item C<getppid>
37120919 701
4755096e
GS
702This is identical to Perl's builtin C<getppid()> function for
703returning the process identifier of the parent process of the current
704process , see L<perlfunc/getppid>.
37120919 705
41cd218c 706=item C<getpwnam>
37120919 707
4755096e
GS
708This is identical to Perl's builtin C<getpwnam()> function for
709returning user entries by user names, see L<perlfunc/getpwnam>.
37120919 710
41cd218c 711=item C<getpwuid>
37120919 712
4755096e
GS
713This is identical to Perl's builtin C<getpwuid()> function for
714returning user entries by user identifiers, see L<perlfunc/getpwuid>.
37120919 715
41cd218c 716=item C<gets>
37120919 717
4755096e
GS
718Returns one line from C<STDIN>, similar to E<lt>E<gt>, also known
719as the C<readline()> function, see L<perlfunc/readline>.
720
721B<NOTE>: if you have C programs that still use C<gets()>, be very
722afraid. The C<gets()> function is a source of endless grief because
723it has no buffer overrun checks. It should B<never> be used. The
724C<fgets()> function should be preferred instead.
37120919 725
41cd218c 726=item C<getuid>
37120919 727
4755096e
GS
728Returns the user's identifier. Identical to Perl's builtin C<$E<lt>> variable,
729see L<perlvar/$UID>.
37120919 730
41cd218c 731=item C<gmtime>
37120919 732
4755096e
GS
733This is identical to Perl's builtin C<gmtime()> function for
734converting seconds since the epoch to a date in Greenwich Mean Time,
735see L<perlfunc/gmtime>.
37120919 736
9d233e12
JH
737=item C<hypot>
738
4d0de388 739Equivalent to C<S<sqrt(x * x + y * y)>> except more stable on very large
912a1e06 740or very small arguments [C99]. Added in Perl v5.22.
9d233e12
JH
741
742=item C<ilogb>
743
912a1e06 744Integer binary logarithm [C99]. Added in Perl v5.22.
9d233e12 745
4d0de388 746For example C<ilogb(20)> is 4, as an integer.
351ab2ad
JH
747
748See also L</logb>.
9d233e12 749
d7a0f0b0
JH
750=item C<Inf>
751
752The infinity as a constant:
753
754 use POSIX qw(Inf);
755 my $pos_inf = +Inf; # Or just Inf.
756 my $neg_inf = -Inf;
757
758See also L</isinf>, and L</fpclassify>.
759
41cd218c 760=item C<isalnum>
37120919 761
912a1e06 762This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
763matching against S<C<qr/ ^ [[:alnum:]]+ $ /x>>, which you should convert
764to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 765
41cd218c 766=item C<isalpha>
37120919 767
912a1e06 768This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
769matching against S<C<qr/ ^ [[:alpha:]]+ $ /x>>, which you should convert
770to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 771
41cd218c 772=item C<isatty>
37120919
AD
773
774Returns a boolean indicating whether the specified filehandle is connected
4755096e 775to a tty. Similar to the C<-t> operator, see L<perlfunc/-X>.
37120919 776
41cd218c 777=item C<iscntrl>
37120919 778
912a1e06 779This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
780matching against S<C<qr/ ^ [[:cntrl:]]+ $ /x>>, which you should convert
781to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 782
41cd218c 783=item C<isdigit>
37120919 784
912a1e06 785This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
786matching against S<C<qr/ ^ [[:digit:]]+ $ /x>>, which you should convert
787to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 788
9d233e12
JH
789=item C<isfinite>
790
791Returns true if the argument is a finite number (that is, not an
912a1e06 792infinity, or the not-a-number) [C99]. Added in Perl v5.22.
9d233e12 793
3823048b 794See also L</isinf>, L</isnan>, and L</fpclassify>.
9d233e12 795
41cd218c 796=item C<isgraph>
37120919 797
912a1e06 798This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
799matching against S<C<qr/ ^ [[:graph:]]+ $ /x>>, which you should convert
800to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 801
9d233e12
JH
802=item C<isgreater>
803
804(Also C<isgreaterequal>, C<isless>, C<islessequal>, C<islessgreater>,
805C<isunordered>)
806
912a1e06
DB
807Floating point comparisons which handle the C<NaN> [C99]. Added in Perl
808v5.22.
9d233e12
JH
809
810=item C<isinf>
811
812Returns true if the argument is an infinity (positive or negative) [C99].
912a1e06 813Added in Perl v5.22.
9d233e12 814
d7a0f0b0 815See also L</Inf>, L</isnan>, L</isfinite>, and L</fpclassify>.
9d233e12 816
41cd218c 817=item C<islower>
37120919 818
912a1e06 819This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
820matching against S<C<qr/ ^ [[:lower:]]+ $ /x>>, which you should convert
821to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 822
9d233e12
JH
823=item C<isnan>
824
912a1e06
DB
825Returns true if the argument is C<NaN> (not-a-number) [C99]. Added in
826Perl v5.22.
9d233e12 827
4d0de388 828Note that you cannot test for "C<NaN>-ness" with
9d233e12
JH
829
830 $x == $x
831
4d0de388 832since the C<NaN> is not equivalent to anything, B<including itself>.
9d233e12 833
d7a0f0b0 834See also L</nan>, L</NaN>, L</isinf>, and L</fpclassify>.
9d233e12
JH
835
836=item C<isnormal>
837
838Returns true if the argument is normal (that is, not a subnormal/denormal,
912a1e06 839and not an infinity, or a not-a-number) [C99]. Added in Perl v5.22.
9d233e12
JH
840
841See also L</isfinite>, and L</fpclassify>.
842
41cd218c 843=item C<isprint>
37120919 844
912a1e06 845This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
846matching against S<C<qr/ ^ [[:print:]]+ $ /x>>, which you should convert
847to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 848
41cd218c 849=item C<ispunct>
37120919 850
912a1e06 851This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
852matching against S<C<qr/ ^ [[:punct:]]+ $ /x>>, which you should convert
853to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 854
07bb61ac
JH
855=item C<issignaling>
856
857 use POSIX ':nan_payload';
858 issignaling($var, $payload)
859
912a1e06 860Return true if the argument is a I<signaling> NaN. Added in Perl v5.24.
07bb61ac
JH
861
862Note the API instability warning in L</setpayload>.
863
864See L</nan> for more discussion about C<NaN>.
865
41cd218c 866=item C<isspace>
37120919 867
912a1e06 868This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
869matching against S<C<qr/ ^ [[:space:]]+ $ /x>>, which you should convert
870to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 871
41cd218c 872=item C<isupper>
37120919 873
912a1e06 874This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
875matching against S<C<qr/ ^ [[:upper:]]+ $ /x>>, which you should convert
876to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 877
41cd218c 878=item C<isxdigit>
37120919 879
912a1e06 880This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
881matching against S<C<qr/ ^ [[:xdigit:]]+ $ /x>>, which you should
882convert to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 883
9d233e12
JH
884=item C<j0>
885
98ab3abf
AP
886=item C<j1>
887
888=item C<jn>
889
890=item C<y0>
891
892=item C<y1>
893
894=item C<yn>
9d233e12
JH
895
896The Bessel function of the first kind of the order zero.
897
41cd218c 898=item C<kill>
37120919 899
4755096e 900This is identical to Perl's builtin C<kill()> function for sending
c2e66d9e 901signals to processes (often to terminate them), see L<perlfunc/kill>.
37120919 902
41cd218c 903=item C<labs>
37120919 904
4d0de388 905Not implemented. (For returning absolute values of long integers.)
41cd218c 906C<labs()> is C-specific, see L<perlfunc/abs> instead.
37120919 907
41cd218c 908=item C<lchown>
c5eef087
DFC
909
910This is identical to the C function, except the order of arguments is
911consistent with Perl's builtin C<chown()> with the added restriction
4d0de388
KW
912of only one path, not a list of paths. Does the same thing as the
913C<chown()> function but changes the owner of a symbolic link instead
c5eef087
DFC
914of the file the symbolic link points to.
915
4d0de388
KW
916 POSIX::lchown($uid, $gid, $file_path);
917
41cd218c 918=item C<ldexp>
37120919 919
4755096e
GS
920This is identical to the C function C<ldexp()>
921for multiplying floating point numbers with powers of two.
922
923 $x_quadrupled = POSIX::ldexp($x, 2);
37120919 924
41cd218c 925=item C<ldiv>
37120919 926
4d0de388 927Not implemented. (For computing dividends of long integers.)
41cd218c 928C<ldiv()> is C-specific, use C</> and C<int()> instead.
37120919 929
9d233e12
JH
930=item C<lgamma>
931
912a1e06 932The logarithm of the Gamma function [C99]. Added in Perl v5.22.
9d233e12
JH
933
934See also L</tgamma>.
935
936=item C<log1p>
937
4d0de388 938Equivalent to S<C<log(1 + x)>>, but more stable results for small argument
912a1e06 939values [C99]. Added in Perl v5.22.
9d233e12
JH
940
941=item C<log2>
942
912a1e06 943Logarithm base two [C99]. Added in Perl v5.22.
9d233e12
JH
944
945See also L</expm1>.
946
947=item C<logb>
948
912a1e06 949Integer binary logarithm [C99]. Added in Perl v5.22.
9d233e12 950
4d0de388 951For example C<logb(20)> is 4, as a floating point number.
351ab2ad
JH
952
953See also L</ilogb>.
9d233e12 954
41cd218c 955=item C<link>
37120919 956
4755096e
GS
957This is identical to Perl's builtin C<link()> function
958for creating hard links into files, see L<perlfunc/link>.
37120919 959
41cd218c 960=item C<localeconv>
37120919 961
cb1a09d0 962Get numeric formatting information. Returns a reference to a hash
f6fc135b
KW
963containing the formatting values of the locale that currently underlies
964the program, regardless of whether or not it is called from within the
965scope of a S<C<use locale>>. Users of this function should also read
966L<perllocale>, which provides a comprehensive discussion of Perl locale
967handling, including
dfcc8045 968L<a section devoted to this function|perllocale/The localeconv function>.
e9bc6d6b 969Prior to Perl 5.28, or when operating in a non thread-safe environment,
8b24ca2d 970it should not be used in a threaded application unless it's certain that
aa2bc4d3
KW
971the underlying locale is C or POSIX. This is because it otherwise
972changes the locale, which globally affects all threads simultaneously.
69c5e0db
KW
973Windows platforms starting with Visual Studio 2005 are mostly
974thread-safe, but use of this function in those prior to Visual Studio
71c3d40b 9752015 can interfere with a thread that has called
69c5e0db 976L<perlapi/switch_to_global_locale>.
cb1a09d0 977
4755096e 978Here is how to query the database for the B<de> (Deutsch or German) locale.
cb1a09d0 979
c4e34987
DP
980 my $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" );
981 print "Locale: \"$loc\"\n";
982 my $lconv = POSIX::localeconv();
983 foreach my $property (qw(
984 decimal_point
985 thousands_sep
986 grouping
987 int_curr_symbol
988 currency_symbol
989 mon_decimal_point
990 mon_thousands_sep
991 mon_grouping
992 positive_sign
993 negative_sign
994 int_frac_digits
995 frac_digits
996 p_cs_precedes
997 p_sep_by_space
998 n_cs_precedes
999 n_sep_by_space
1000 p_sign_posn
1001 n_sign_posn
b15c1b56
AF
1002 int_p_cs_precedes
1003 int_p_sep_by_space
1004 int_n_cs_precedes
1005 int_n_sep_by_space
1006 int_p_sign_posn
1007 int_n_sign_posn
c4e34987
DP
1008 ))
1009 {
b70c169c
FC
1010 printf qq(%s: "%s",\n),
1011 $property, $lconv->{$property};
c4e34987 1012 }
37120919 1013
4d0de388
KW
1014The members whose names begin with C<int_p_> and C<int_n_> were added by
1015POSIX.1-2008 and are only available on systems that support them.
b15c1b56 1016
41cd218c 1017=item C<localtime>
37120919 1018
4755096e 1019This is identical to Perl's builtin C<localtime()> function for
dc416353
JK
1020converting seconds since the epoch to a date see L<perlfunc/localtime> except
1021that C<POSIX::localtime()> must be provided an explicit value (rather than
bda53d3e 1022relying on an implicit C<$_>):
dc416353 1023
bda53d3e 1024 @localtime = POSIX::localtime(time); # good
dc416353 1025
bda53d3e 1026 @localtime = localtime(); # good
dc416353 1027
bda53d3e 1028 @localtime = POSIX::localtime(); # throws exception
37120919 1029
41cd218c 1030=item C<log>
37120919 1031
4755096e
GS
1032This is identical to Perl's builtin C<log()> function,
1033returning the natural (I<e>-based) logarithm of the numerical argument,
1034see L<perlfunc/log>.
37120919 1035
41cd218c 1036=item C<log10>
37120919 1037
4755096e
GS
1038This is identical to the C function C<log10()>,
1039returning the 10-base logarithm of the numerical argument.
1040You can also use
1041
1042 sub log10 { log($_[0]) / log(10) }
1043
1044or
1045
3609ea0d 1046 sub log10 { log($_[0]) / 2.30258509299405 }
4755096e
GS
1047
1048or
1049
1050 sub log10 { log($_[0]) * 0.434294481903252 }
37120919 1051
41cd218c 1052=item C<longjmp>
37120919 1053
4d0de388 1054Not implemented. C<longjmp()> is C-specific: use L<perlfunc/die> instead.
37120919 1055
41cd218c 1056=item C<lseek>
37120919 1057
8903cb82 1058Move the file's read/write position. This uses file descriptors such as
cb1a09d0
AD
1059those obtained by calling C<POSIX::open>.
1060
1061 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
1062 $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET );
37120919
AD
1063
1064Returns C<undef> on failure.
1065
9d233e12
JH
1066=item C<lrint>
1067
351ab2ad
JH
1068Depending on the current floating point rounding mode, rounds the
1069argument either toward nearest (like L</round>), toward zero (like
1070L</trunc>), downward (toward negative infinity), or upward (toward
912a1e06 1071positive infinity) [C99]. Added in Perl v5.22.
9d233e12 1072
351ab2ad 1073For the rounding mode, see L</fegetround>.
9d233e12 1074
9e010b89
JH
1075=item C<lround>
1076
912a1e06
DB
1077Like L</round>, but as integer, as opposed to floating point [C99]. Added
1078in Perl v5.22.
9e010b89
JH
1079
1080See also L</ceil>, L</floor>, L</trunc>.
1081
25a9f0e7
AC
1082Owing to an oversight, this is not currently exported by default, or as part of
1083the C<:math_h_c99> export tag; importing it must therefore be done by explicit
abc9e18b 1084name.
25a9f0e7 1085
41cd218c 1086=item C<malloc>
37120919 1087
4d0de388 1088Not implemented. C<malloc()> is C-specific. Perl does memory management transparently.
37120919 1089
41cd218c 1090=item C<mblen>
37120919 1091
d2c9cb53
KW
1092This is the same as the C function C<mblen()> on unthreaded perls. On
1093threaded perls, it transparently (almost) substitutes the more
1094thread-safe L<C<mbrlen>(3)>, if available, instead of C<mblen>.
1095
1096Core Perl does not have any support for wide and multibyte locales,
1097except Unicode UTF-8 locales. This function, in conjunction with
1098L</mbtowc> and L</wctomb> may be used to roll your own decoding/encoding
1099of other types of multi-byte locales.
1100
1101Use C<undef> as the first parameter to this function to get the effect
1102of passing NULL as the first parameter to C<mblen>. This resets any
1103shift state to its initial value. The return value is undefined if
1104C<mbrlen> was substituted, so you should never rely on it.
1105
1106When the first parameter is a scalar containing a value that either is a
1107PV string or can be forced into one, the return value is the number of
1108bytes occupied by the first character of that string; or 0 if that first
1109character is the wide NUL character; or negative if there is an error.
1110This is based on the locale that currently underlies the program,
1111regardless of whether or not the function is called from Perl code that
1112is within the scope of S<C<use locale>>. Perl makes no attempt at
1113hiding from your code any differences in the C<errno> setting between
1114C<mblen> and C<mbrlen>. It does set C<errno> to 0 before calling them.
37120919 1115
63bebc14
KW
1116The optional second parameter is ignored if it is larger than the
1117actual length of the first parameter string.
37120919 1118
41cd218c 1119=item C<mbtowc>
37120919 1120
5a6637f0
KW
1121This is the same as the C function C<mbtowc()> on unthreaded perls. On
1122threaded perls, it transparently (almost) substitutes the more
1123thread-safe L<C<mbrtowc>(3)>, if available, instead of C<mbtowc>.
351ab2ad 1124
5a6637f0
KW
1125Core Perl does not have any support for wide and multibyte locales,
1126except Unicode UTF-8 locales. This function, in conjunction with
1127L</mblen> and L</wctomb> may be used to roll your own decoding/encoding
1128of other types of multi-byte locales.
1129
1130The first parameter is a scalar into which, upon success, the wide
1131character represented by the multi-byte string contained in the second
1132parameter is stored. The optional third parameter is ignored if it is
1133larger than the actual length of the second parameter string.
1134
1135Use C<undef> as the second parameter to this function to get the effect
1136of passing NULL as the second parameter to C<mbtowc>. This resets any
1137shift state to its initial value. The return value is undefined if
1138C<mbrtowc> was substituted, so you should never rely on it.
1139
1140When the second parameter is a scalar containing a value that either is
1141a PV string or can be forced into one, the return value is the number of
1142bytes occupied by the first character of that string; or 0 if that first
1143character is the wide NUL character; or negative if there is an error.
1144This is based on the locale that currently underlies the program,
1145regardless of whether or not the function is called from Perl code that
1146is within the scope of S<C<use locale>>. Perl makes no attempt at
1147hiding from your code any differences in the C<errno> setting between
1148C<mbtowc> and C<mbrtowc>. It does set C<errno> to 0 before calling
1149them.
37120919 1150
41cd218c 1151=item C<memchr>
37120919 1152
4d0de388 1153Not implemented. C<memchr()> is C-specific, see L<perlfunc/index> instead.
37120919 1154
41cd218c 1155=item C<memcmp>
37120919 1156
4d0de388 1157Not implemented. C<memcmp()> is C-specific, use C<eq> instead, see L<perlop>.
37120919 1158
41cd218c 1159=item C<memcpy>
37120919 1160
4d0de388 1161Not implemented. C<memcpy()> is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
37120919 1162
41cd218c 1163=item C<memmove>
37120919 1164
4d0de388 1165Not implemented. C<memmove()> is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
37120919 1166
41cd218c 1167=item C<memset>
37120919 1168
4d0de388 1169Not implemented. C<memset()> is C-specific, use C<x> instead, see L<perlop>.
37120919 1170
41cd218c 1171=item C<mkdir>
37120919 1172
4755096e
GS
1173This is identical to Perl's builtin C<mkdir()> function
1174for creating directories, see L<perlfunc/mkdir>.
37120919 1175
41cd218c 1176=item C<mkfifo>
37120919 1177
4755096e
GS
1178This is similar to the C function C<mkfifo()> for creating
1179FIFO special files.
37120919 1180
4755096e
GS
1181 if (mkfifo($path, $mode)) { ....
1182
1183Returns C<undef> on failure. The C<$mode> is similar to the
220f811a
JH
1184mode of C<mkdir()>, see L<perlfunc/mkdir>, though for C<mkfifo>
1185you B<must> specify the C<$mode>.
37120919 1186
41cd218c 1187=item C<mktime>
37120919 1188
cb1a09d0
AD
1189Convert date/time info to a calendar time.
1190
1191Synopsis:
1192
b70c169c
FC
1193 mktime(sec, min, hour, mday, mon, year, wday = 0,
1194 yday = 0, isdst = -1)
cb1a09d0 1195
4d0de388
KW
1196The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero,
1197I<i.e.>, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
1198year (C<year>) is given in years since 1900; I<i.e.>, the year 1995 is 95; the
cb1a09d0
AD
1199year 2001 is 101. Consult your system's C<mktime()> manpage for details
1200about these and the other arguments.
1201
1202Calendar time for December 12, 1995, at 10:30 am.
1203
1204 $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 );
1205 print "Date = ", POSIX::ctime($time_t);
37120919
AD
1206
1207Returns C<undef> on failure.
1208
41cd218c 1209=item C<modf>
37120919 1210
cb1a09d0
AD
1211Return the integral and fractional parts of a floating-point number.
1212
1213 ($fractional, $integral) = POSIX::modf( 3.14 );
37120919 1214
351ab2ad
JH
1215See also L</round>.
1216
d7a0f0b0
JH
1217=item C<NaN>
1218
1219The not-a-number as a constant:
1220
1221 use POSIX qw(NaN);
1222 my $nan = NaN;
1223
1224See also L</nan>, C</isnan>, and L</fpclassify>.
1225
9d233e12
JH
1226=item C<nan>
1227
07bb61ac
JH
1228 my $nan = nan();
1229
912a1e06 1230Returns C<NaN>, not-a-number [C99]. Added in Perl v5.22.
07bb61ac
JH
1231
1232The returned NaN is always a I<quiet> NaN, as opposed to I<signaling>.
1233
1234With an argument, can be used to generate a NaN with I<payload>.
1235The argument is first interpreted as a floating point number,
1236but then any fractional parts are truncated (towards zero),
1237and the value is interpreted as an unsigned integer.
1238The bits of this integer are stored in the unused bits of the NaN.
1239
1240The result has a dual nature: it is a NaN, but it also carries
1241the integer inside it. The integer can be retrieved with L</getpayload>.
1242Note, though, that the payload is not propagated, not even on copies,
1243and definitely not in arithmetic operations.
1244
1245How many bits fit in the NaN depends on what kind of floating points
1246are being used, but on the most common platforms (64-bit IEEE 754,
1247or the x86 80-bit long doubles) there are 51 and 61 bits available,
1248respectively. (There would be 52 and 62, but the quiet/signaling
1249bit of NaNs takes away one.) However, because of the floating-point-to-
1250integer-and-back conversions, please test carefully whether you get back
1251what you put in. If your integers are only 32 bits wide, you probably
1252should not rely on more than 32 bits of payload.
9d233e12 1253
07bb61ac
JH
1254Whether a "signaling" NaN is in any way different from a "quiet" NaN,
1255depends on the platform. Also note that the payload of the default
1256NaN (no argument to nan()) is not necessarily zero, use C<setpayload>
8384a6d6
JH
1257to explicitly set the payload. On some platforms like the 32-bit x86,
1258(unless using the 80-bit long doubles) the signaling bit is not supported
1259at all.
07bb61ac 1260
d7a0f0b0 1261See also L</isnan>, L</NaN>, L</setpayload> and L</issignaling>.
351ab2ad 1262
9d233e12
JH
1263=item C<nearbyint>
1264
1265Returns the nearest integer to the argument, according to the current
912a1e06 1266rounding mode (see L</fegetround>) [C99]. Added in Perl v5.22.
9d233e12
JH
1267
1268=item C<nextafter>
1269
4d0de388 1270Returns the next representable floating point number after C<x> in the
912a1e06 1271direction of C<y> [C99]. Added in Perl v5.22.
4d0de388
KW
1272
1273 my $nextafter = POSIX::nextafter($x, $y);
9d233e12
JH
1274
1275Like L</nexttoward>, but potentially less accurate.
1276
1277=item C<nexttoward>
1278
4d0de388 1279Returns the next representable floating point number after C<x> in the
912a1e06 1280direction of C<y> [C99]. Added in Perl v5.22.
4d0de388
KW
1281
1282 my $nexttoward = POSIX::nexttoward($x, $y);
9d233e12
JH
1283
1284Like L</nextafter>, but potentially more accurate.
1285
41cd218c 1286=item C<nice>
37120919 1287
4755096e
GS
1288This is similar to the C function C<nice()>, for changing
1289the scheduling preference of the current process. Positive
4d0de388
KW
1290arguments mean a more polite process, negative values a more
1291needy process. Normal (non-root) user processes can only change towards
1292being more polite.
37120919
AD
1293
1294Returns C<undef> on failure.
1295
41cd218c 1296=item C<offsetof>
37120919 1297
4d0de388 1298Not implemented. C<offsetof()> is C-specific, you probably want to see L<perlfunc/pack> instead.
37120919 1299
41cd218c 1300=item C<open>
37120919 1301
cb1a09d0
AD
1302Open a file for reading for writing. This returns file descriptors, not
1303Perl filehandles. Use C<POSIX::close> to close the file.
1304
1305Open a file read-only with mode 0666.
1306
1307 $fd = POSIX::open( "foo" );
1308
1309Open a file for read and write.
1310
1311 $fd = POSIX::open( "foo", &POSIX::O_RDWR );
1312
1313Open a file for write, with truncation.
1314
b70c169c
FC
1315 $fd = POSIX::open(
1316 "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC
1317 );
cb1a09d0
AD
1318
1319Create a new file with mode 0640. Set up the file for writing.
1320
b70c169c
FC
1321 $fd = POSIX::open(
1322 "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640
1323 );
37120919
AD
1324
1325Returns C<undef> on failure.
1326
4755096e
GS
1327See also L<perlfunc/sysopen>.
1328
41cd218c 1329=item C<opendir>
37120919 1330
cb1a09d0
AD
1331Open a directory for reading.
1332
2359510d 1333 $dir = POSIX::opendir( "/var" );
cb1a09d0
AD
1334 @files = POSIX::readdir( $dir );
1335 POSIX::closedir( $dir );
1336
1337Returns C<undef> on failure.
37120919 1338
41cd218c 1339=item C<pathconf>
37120919
AD
1340
1341Retrieves the value of a configurable limit on a file or directory.
1342
1343The following will determine the maximum length of the longest allowable
2359510d 1344pathname on the filesystem which holds C</var>.
37120919 1345
b70c169c
FC
1346 $path_max = POSIX::pathconf( "/var",
1347 &POSIX::_PC_PATH_MAX );
37120919
AD
1348
1349Returns C<undef> on failure.
1350
41cd218c 1351=item C<pause>
37120919 1352
4755096e
GS
1353This is similar to the C function C<pause()>, which suspends
1354the execution of the current process until a signal is received.
37120919
AD
1355
1356Returns C<undef> on failure.
1357
41cd218c 1358=item C<perror>
37120919 1359
4755096e 1360This is identical to the C function C<perror()>, which outputs to the
41cd218c 1361standard error stream the specified message followed by C<": "> and the
4755096e
GS
1362current error string. Use the C<warn()> function and the C<$!>
1363variable instead, see L<perlfunc/warn> and L<perlvar/$ERRNO>.
37120919 1364
41cd218c 1365=item C<pipe>
37120919 1366
cb1a09d0
AD
1367Create an interprocess channel. This returns file descriptors like those
1368returned by C<POSIX::open>.
1369
b27d06da
MS
1370 my ($read, $write) = POSIX::pipe();
1371 POSIX::write( $write, "hello", 5 );
1372 POSIX::read( $read, $buf, 5 );
37120919 1373
4755096e
GS
1374See also L<perlfunc/pipe>.
1375
41cd218c 1376=item C<pow>
37120919 1377
4755096e 1378Computes C<$x> raised to the power C<$exponent>.
37120919
AD
1379
1380 $ret = POSIX::pow( $x, $exponent );
1381
4755096e
GS
1382You can also use the C<**> operator, see L<perlop>.
1383
41cd218c 1384=item C<printf>
37120919 1385
4d0de388 1386Formats and prints the specified arguments to C<STDOUT>.
4755096e 1387See also L<perlfunc/printf>.
37120919 1388
41cd218c 1389=item C<putc>
37120919 1390
4d0de388 1391Not implemented. C<putc()> is C-specific, see L<perlfunc/print> instead.
37120919 1392
41cd218c 1393=item C<putchar>
37120919 1394
4d0de388 1395Not implemented. C<putchar()> is C-specific, see L<perlfunc/print> instead.
37120919 1396
41cd218c 1397=item C<puts>
37120919 1398
4d0de388 1399Not implemented. C<puts()> is C-specific, see L<perlfunc/print> instead.
37120919 1400
41cd218c 1401=item C<qsort>
37120919 1402
4d0de388 1403Not implemented. C<qsort()> is C-specific, see L<perlfunc/sort> instead.
37120919 1404
41cd218c 1405=item C<raise>
37120919
AD
1406
1407Sends the specified signal to the current process.
4755096e 1408See also L<perlfunc/kill> and the C<$$> in L<perlvar/$PID>.
37120919 1409
41cd218c 1410=item C<rand>
37120919 1411
4d0de388 1412Not implemented. C<rand()> is non-portable, see L<perlfunc/rand> instead.
37120919 1413
41cd218c 1414=item C<read>
37120919 1415
cb1a09d0
AD
1416Read from a file. This uses file descriptors such as those obtained by
1417calling C<POSIX::open>. If the buffer C<$buf> is not large enough for the
1418read then Perl will extend it to make room for the request.
1419
1420 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
1421 $bytes = POSIX::read( $fd, $buf, 3 );
37120919
AD
1422
1423Returns C<undef> on failure.
1424
4755096e
GS
1425See also L<perlfunc/sysread>.
1426
41cd218c 1427=item C<readdir>
37120919 1428
4755096e
GS
1429This is identical to Perl's builtin C<readdir()> function
1430for reading directory entries, see L<perlfunc/readdir>.
37120919 1431
41cd218c 1432=item C<realloc>
37120919 1433
4d0de388 1434Not implemented. C<realloc()> is C-specific. Perl does memory management transparently.
37120919 1435
9d233e12
JH
1436=item C<remainder>
1437
4d0de388 1438Given C<x> and C<y>, returns the value S<C<x - n*y>>, where C<n> is the integer
912a1e06 1439closest to C<x>/C<y> [C99]. Added in Perl v5.22.
4d0de388
KW
1440
1441 my $remainder = POSIX::remainder($x, $y)
9d233e12
JH
1442
1443See also L</remquo>.
1444
41cd218c 1445=item C<remove>
37120919 1446
c6f0b8ca
TC
1447Deletes a name from the filesystem. Calls L<perlfunc/unlink> for
1448files and L<perlfunc/rmdir> for directories.
37120919 1449
9d233e12
JH
1450=item C<remquo>
1451
1452Like L</remainder> but also returns the low-order bits of the quotient (n)
912a1e06 1453[C99]. Added in Perl v5.22.
9d233e12
JH
1454
1455(This is quite esoteric interface, mainly used to implement numerical
1456algorithms.)
1457
41cd218c 1458=item C<rename>
37120919 1459
4755096e
GS
1460This is identical to Perl's builtin C<rename()> function
1461for renaming files, see L<perlfunc/rename>.
37120919 1462
41cd218c 1463=item C<rewind>
37120919
AD
1464
1465Seeks to the beginning of the file.
1466
41cd218c 1467=item C<rewinddir>
37120919 1468
4755096e
GS
1469This is identical to Perl's builtin C<rewinddir()> function for
1470rewinding directory entry streams, see L<perlfunc/rewinddir>.
37120919 1471
9d233e12
JH
1472=item C<rint>
1473
1474Identical to L</lrint>.
1475
41cd218c 1476=item C<rmdir>
37120919 1477
4755096e
GS
1478This is identical to Perl's builtin C<rmdir()> function
1479for removing (empty) directories, see L<perlfunc/rmdir>.
37120919 1480
9d233e12
JH
1481=item C<round>
1482
9e010b89 1483Returns the integer (but still as floating point) nearest to the
912a1e06 1484argument [C99]. Added in Perl v5.22.
9d233e12 1485
351ab2ad 1486See also L</ceil>, L</floor>, L</lround>, L</modf>, and L</trunc>.
9d233e12
JH
1487
1488=item C<scalbn>
1489
912a1e06 1490Returns S<C<x * 2**y>> [C99]. Added in Perl v5.22.
9d233e12
JH
1491
1492See also L</frexp> and L</ldexp>.
1493
41cd218c 1494=item C<scanf>
37120919 1495
4d0de388 1496Not implemented. C<scanf()> is C-specific, use E<lt>E<gt> and regular expressions instead,
4755096e 1497see L<perlre>.
37120919 1498
41cd218c 1499=item C<setgid>
37120919 1500
a043a685
GW
1501Sets the real group identifier and the effective group identifier for
1502this process. Similar to assigning a value to the Perl's builtin
2bc0d022 1503C<$)> variable, see L<perlvar/$EGID>, except that the latter
a043a685
GW
1504will change only the real user identifier, and that the setgid()
1505uses only a single numeric argument, as opposed to a space-separated
1506list of numbers.
37120919 1507
41cd218c 1508=item C<setjmp>
37120919 1509
4d0de388 1510Not implemented. C<setjmp()> is C-specific: use C<eval {}> instead,
4755096e 1511see L<perlfunc/eval>.
37120919 1512
41cd218c 1513=item C<setlocale>
37120919 1514
06283613
KW
1515WARNING! Prior to Perl 5.28 or on a system that does not support
1516thread-safe locale operations, do NOT use this function in a
1517L<thread|threads>. The locale will change in all other threads at the
1518same time, and should your thread get paused by the operating system,
1519and another started, that thread will not have the locale it is
1520expecting. On some platforms, there can be a race leading to segfaults
5f08f0bb
KW
1521if two threads call this function nearly simultaneously. This warning
1522does not apply on unthreaded builds, or on perls where
1523C<${^SAFE_LOCALES}> exists and is non-zero; namely Perl 5.28 and later
1524compiled to be locale-thread-safe.
06283613
KW
1525
1526This function
1527modifies and queries the program's underlying locale. Users of this
dfcc8045
KW
1528function should read L<perllocale>, whch provides a comprehensive
1529discussion of Perl locale handling, knowledge of which is necessary to
1530properly use this function. It contains
1531L<a section devoted to this function|perllocale/The setlocale function>.
1532The discussion here is merely a summary reference for C<setlocale()>.
6ea81ccf
KW
1533Note that Perl itself is almost entirely unaffected by the locale
1534except within the scope of S<C<"use locale">>. (Exceptions are listed
06283613
KW
1535in L<perllocale/Not within the scope of "use locale">, and
1536locale-dependent functions within the POSIX module ARE always affected
1537by the current locale.)
6ea81ccf
KW
1538
1539The following examples assume
c26abfa6
JH
1540
1541 use POSIX qw(setlocale LC_ALL LC_CTYPE);
1542
1543has been issued.
37120919 1544
8966fa01
JH
1545The following will set the traditional UNIX system locale behavior
1546(the second argument C<"C">).
37120919 1547
c26abfa6 1548 $loc = setlocale( LC_ALL, "C" );
37120919 1549
41cd218c 1550The following will query the current C<LC_CTYPE> category. (No second
c26abfa6 1551argument means 'query'.)
8966fa01 1552
c26abfa6 1553 $loc = setlocale( LC_CTYPE );
8966fa01 1554
41cd218c 1555The following will set the C<LC_CTYPE> behaviour according to the locale
8966fa01 1556environment variables (the second argument C<"">).
4c9b78f4 1557Please see your system's C<setlocale(3)> documentation for the locale
71be2cbc 1558environment variables' meaning or consult L<perllocale>.
8966fa01 1559
c26abfa6 1560 $loc = setlocale( LC_CTYPE, "" );
8966fa01 1561
41cd218c 1562The following will set the C<LC_COLLATE> behaviour to Argentinian
8966fa01 1563Spanish. B<NOTE>: The naming and availability of locales depends on
71be2cbc 1564your operating system. Please consult L<perllocale> for how to find
8966fa01
JH
1565out which locales are available in your system.
1566
801ed997 1567 $loc = setlocale( LC_COLLATE, "es_AR.ISO8859-1" );
8966fa01 1568
07bb61ac
JH
1569=item C<setpayload>
1570
1571 use POSIX ':nan_payload';
1572 setpayload($var, $payload);
1573
912a1e06 1574Sets the C<NaN> payload of var. Added in Perl v5.24.
07bb61ac
JH
1575
1576NOTE: the NaN payload APIs are based on the latest (as of June 2015)
1577proposed ISO C interfaces, but they are not yet a standard. Things
1578may change.
1579
1580See L</nan> for more discussion about C<NaN>.
1581
1582See also L</setpayloadsig>, L</isnan>, L</getpayload>, and L</issignaling>.
1583
1584=item C<setpayloadsig>
1585
1586 use POSIX ':nan_payload';
1587 setpayloadsig($var, $payload);
1588
912a1e06
DB
1589Like L</setpayload> but also makes the NaN I<signaling>. Added in Perl
1590v5.24.
07bb61ac
JH
1591
1592Depending on the platform the NaN may or may not behave differently.
1593
1594Note the API instability warning in L</setpayload>.
1595
1596Note that because how the floating point formats work out, on the most
1597common platforms signaling payload of zero is best avoided,
1598since it might end up being identical to C<+Inf>.
1599
1600See also L</nan>, L</isnan>, L</getpayload>, and L</issignaling>.
1601
41cd218c 1602=item C<setpgid>
37120919 1603
4755096e
GS
1604This is similar to the C function C<setpgid()> for
1605setting the process group identifier of the current process.
37120919
AD
1606
1607Returns C<undef> on failure.
1608
41cd218c 1609=item C<setsid>
37120919 1610
4755096e
GS
1611This is identical to the C function C<setsid()> for
1612setting the session identifier of the current process.
37120919 1613
41cd218c 1614=item C<setuid>
37120919 1615
a043a685
GW
1616Sets the real user identifier and the effective user identifier for
1617this process. Similar to assigning a value to the Perl's builtin
1618C<$E<lt>> variable, see L<perlvar/$UID>, except that the latter
1619will change only the real user identifier.
37120919 1620
41cd218c 1621=item C<sigaction>
37120919 1622
3609ea0d
JH
1623Detailed signal management. This uses C<POSIX::SigAction> objects for
1624the C<action> and C<oldaction> arguments (the oldaction can also be
1625just a hash reference). Consult your system's C<sigaction> manpage
1626for details, see also C<POSIX::SigRt>.
cb1a09d0
AD
1627
1628Synopsis:
1629
1d81eac9 1630 sigaction(signal, action, oldaction = 0)
37120919 1631
1d81eac9 1632Returns C<undef> on failure. The C<signal> must be a number (like
41cd218c 1633C<SIGHUP>), not a string (like C<"SIGHUP">), though Perl does try hard
1d81eac9 1634to understand you.
37120919 1635
41cd218c 1636If you use the C<SA_SIGINFO> flag, the signal handler will in addition to
8aad04aa
JH
1637the first argument, the signal name, also receive a second argument, a
1638hash reference, inside which are the following keys with the following
1639semantics, as defined by POSIX/SUSv3:
1640
1641 signo the signal number
1642 errno the error number
1643 code if this is zero or less, the signal was sent by
1644 a user process and the uid and pid make sense,
1645 otherwise the signal was sent by the kernel
79dec0f4 1646
34e79b75 1647The constants for specific C<code> values can be imported individually
912a1e06 1648or using the C<:signal_h_si_code> tag, since Perl v5.24.
34e79b75 1649
79dec0f4
JH
1650The following are also defined by POSIX/SUSv3, but unfortunately
1651not very widely implemented:
1652
8aad04aa
JH
1653 pid the process id generating the signal
1654 uid the uid of the process id generating the signal
1655 status exit value or signal for SIGCHLD
1656 band band event for SIGPOLL
408b5f5e
KW
1657 addr address of faulting instruction or memory
1658 reference for SIGILL, SIGFPE, SIGSEGV or SIGBUS
8aad04aa
JH
1659
1660A third argument is also passed to the handler, which contains a copy
41cd218c
KW
1661of the raw binary contents of the C<siginfo> structure: if a system has
1662some non-POSIX fields, this third argument is where to C<unpack()> them
8aad04aa
JH
1663from.
1664
41cd218c 1665Note that not all C<siginfo> values make sense simultaneously (some are
8aad04aa
JH
1666valid only for certain signals, for example), and not all values make
1667sense from Perl perspective, you should to consult your system's
1668C<sigaction> and possibly also C<siginfo> documentation.
1669
41cd218c 1670=item C<siglongjmp>
37120919 1671
4d0de388 1672Not implemented. C<siglongjmp()> is C-specific: use L<perlfunc/die> instead.
37120919 1673
9d233e12
JH
1674=item C<signbit>
1675
1676Returns zero for positive arguments, non-zero for negative arguments [C99].
912a1e06 1677Added in Perl v5.22.
9d233e12 1678
41cd218c 1679=item C<sigpending>
37120919 1680
cb1a09d0
AD
1681Examine signals that are blocked and pending. This uses C<POSIX::SigSet>
1682objects for the C<sigset> argument. Consult your system's C<sigpending>
1683manpage for details.
1684
1685Synopsis:
1686
1687 sigpending(sigset)
37120919
AD
1688
1689Returns C<undef> on failure.
1690
41cd218c 1691=item C<sigprocmask>
37120919 1692
cb1a09d0
AD
1693Change and/or examine calling process's signal mask. This uses
1694C<POSIX::SigSet> objects for the C<sigset> and C<oldsigset> arguments.
1695Consult your system's C<sigprocmask> manpage for details.
1696
1697Synopsis:
1698
1699 sigprocmask(how, sigset, oldsigset = 0)
37120919
AD
1700
1701Returns C<undef> on failure.
1702
faaf6836
LT
1703Note that you can't reliably block or unblock a signal from its own signal
1704handler if you're using safe signals. Other signals can be blocked or unblocked
1705reliably.
1706
41cd218c 1707=item C<sigsetjmp>
37120919 1708
4d0de388 1709Not implemented. C<sigsetjmp()> is C-specific: use C<eval {}> instead,
4755096e 1710see L<perlfunc/eval>.
37120919 1711
41cd218c 1712=item C<sigsuspend>
37120919 1713
cb1a09d0
AD
1714Install a signal mask and suspend process until signal arrives. This uses
1715C<POSIX::SigSet> objects for the C<signal_mask> argument. Consult your
1716system's C<sigsuspend> manpage for details.
1717
1718Synopsis:
1719
1720 sigsuspend(signal_mask)
37120919
AD
1721
1722Returns C<undef> on failure.
1723
41cd218c 1724=item C<sin>
37120919 1725
4755096e
GS
1726This is identical to Perl's builtin C<sin()> function
1727for returning the sine of the numerical argument,
c2e66d9e 1728see L<perlfunc/sin>. See also L<Math::Trig>.
37120919 1729
41cd218c 1730=item C<sinh>
37120919 1731
4755096e
GS
1732This is identical to the C function C<sinh()>
1733for returning the hyperbolic sine of the numerical argument.
c2e66d9e 1734See also L<Math::Trig>.
37120919 1735
41cd218c 1736=item C<sleep>
37120919 1737
2ab27a20
A
1738This is functionally identical to Perl's builtin C<sleep()> function
1739for suspending the execution of the current for process for certain
3609ea0d 1740number of seconds, see L<perlfunc/sleep>. There is one significant
2bad225e 1741difference, however: C<POSIX::sleep()> returns the number of
2ab27a20
A
1742B<unslept> seconds, while the C<CORE::sleep()> returns the
1743number of slept seconds.
37120919 1744
41cd218c 1745=item C<sprintf>
37120919 1746
4755096e
GS
1747This is similar to Perl's builtin C<sprintf()> function
1748for returning a string that has the arguments formatted as requested,
1749see L<perlfunc/sprintf>.
37120919 1750
41cd218c 1751=item C<sqrt>
37120919
AD
1752
1753This is identical to Perl's builtin C<sqrt()> function.
4755096e
GS
1754for returning the square root of the numerical argument,
1755see L<perlfunc/sqrt>.
37120919 1756
41cd218c 1757=item C<srand>
37120919 1758
4755096e 1759Give a seed the pseudorandom number generator, see L<perlfunc/srand>.
37120919 1760
41cd218c 1761=item C<sscanf>
37120919 1762
4d0de388 1763Not implemented. C<sscanf()> is C-specific, use regular expressions instead,
4755096e 1764see L<perlre>.
37120919 1765
41cd218c 1766=item C<stat>
37120919 1767
4755096e 1768This is identical to Perl's builtin C<stat()> function
d7f8936a 1769for returning information about files and directories.
37120919 1770
41cd218c 1771=item C<strcat>
37120919 1772
4d0de388 1773Not implemented. C<strcat()> is C-specific, use C<.=> instead, see L<perlop>.
37120919 1774
41cd218c 1775=item C<strchr>
37120919 1776
4d0de388 1777Not implemented. C<strchr()> is C-specific, see L<perlfunc/index> instead.
37120919 1778
41cd218c 1779=item C<strcmp>
37120919 1780
4d0de388 1781Not implemented. C<strcmp()> is C-specific, use C<eq> or C<cmp> instead, see L<perlop>.
37120919 1782
41cd218c 1783=item C<strcoll>
37120919 1784
4755096e
GS
1785This is identical to the C function C<strcoll()>
1786for collating (comparing) strings transformed using
1787the C<strxfrm()> function. Not really needed since
1788Perl can do this transparently, see L<perllocale>.
37120919 1789
393aa92a
KW
1790Beware that in a UTF-8 locale, anything you pass to this function must
1791be in UTF-8; and when not in a UTF-8 locale, anything passed must not be
1792UTF-8 encoded.
1793
41cd218c 1794=item C<strcpy>
37120919 1795
4d0de388 1796Not implemented. C<strcpy()> is C-specific, use C<=> instead, see L<perlop>.
37120919 1797
41cd218c 1798=item C<strcspn>
37120919 1799
4d0de388 1800Not implemented. C<strcspn()> is C-specific, use regular expressions instead,
4755096e 1801see L<perlre>.
37120919 1802
41cd218c 1803=item C<strerror>
37120919
AD
1804
1805Returns the error string for the specified errno.
4d0de388 1806Identical to the string form of C<$!>, see L<perlvar/$ERRNO>.
37120919 1807
41cd218c 1808=item C<strftime>
37120919 1809
cb1a09d0
AD
1810Convert date and time information to string. Returns the string.
1811
1812Synopsis:
1813
b70c169c
FC
1814 strftime(fmt, sec, min, hour, mday, mon, year,
1815 wday = -1, yday = -1, isdst = -1)
cb1a09d0 1816
4d0de388
KW
1817The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero,
1818I<i.e.>, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
1819year (C<year>) is given in years since 1900, I<i.e.>, the year 1995 is 95; the
cb1a09d0 1820year 2001 is 101. Consult your system's C<strftime()> manpage for details
659b4938 1821about these and the other arguments.
f14c76ed 1822
659b4938
DD
1823If you want your code to be portable, your format (C<fmt>) argument
1824should use only the conversion specifiers defined by the ANSI C
f14c76ed
RGS
1825standard (C89, to play safe). These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
1826But even then, the B<results> of some of the conversion specifiers are
1827non-portable. For example, the specifiers C<aAbBcpZ> change according
1828to the locale settings of the user, and both how to set locales (the
1829locale names) and what output to expect are non-standard.
1830The specifier C<c> changes according to the timezone settings of the
1831user and the timezone computation rules of the operating system.
1832The C<Z> specifier is notoriously unportable since the names of
1833timezones are non-standard. Sticking to the numeric specifiers is the
1834safest route.
1835
1836The given arguments are made consistent as though by calling
1837C<mktime()> before calling your system's C<strftime()> function,
1838except that the C<isdst> value is not affected.
cb1a09d0
AD
1839
1840The string for Tuesday, December 12, 1995.
1841
b70c169c
FC
1842 $str = POSIX::strftime( "%A, %B %d, %Y",
1843 0, 0, 0, 12, 11, 95, 2 );
cb1a09d0 1844 print "$str\n";
37120919 1845
41cd218c 1846=item C<strlen>
37120919 1847
4d0de388 1848Not implemented. C<strlen()> is C-specific, use C<length()> instead, see L<perlfunc/length>.
37120919 1849
41cd218c 1850=item C<strncat>
37120919 1851
4d0de388 1852Not implemented. C<strncat()> is C-specific, use C<.=> instead, see L<perlop>.
37120919 1853
41cd218c 1854=item C<strncmp>
37120919 1855
4d0de388 1856Not implemented. C<strncmp()> is C-specific, use C<eq> instead, see L<perlop>.
37120919 1857
41cd218c 1858=item C<strncpy>
37120919 1859
4d0de388 1860Not implemented. C<strncpy()> is C-specific, use C<=> instead, see L<perlop>.
37120919 1861
41cd218c 1862=item C<strpbrk>
37120919 1863
4d0de388 1864Not implemented. C<strpbrk()> is C-specific, use regular expressions instead,
4755096e 1865see L<perlre>.
37120919 1866
41cd218c 1867=item C<strrchr>
37120919 1868
4d0de388 1869Not implemented. C<strrchr()> is C-specific, see L<perlfunc/rindex> instead.
37120919 1870
41cd218c 1871=item C<strspn>
37120919 1872
4d0de388 1873Not implemented. C<strspn()> is C-specific, use regular expressions instead,
4755096e 1874see L<perlre>.
37120919 1875
41cd218c 1876=item C<strstr>
37120919 1877
4755096e
GS
1878This is identical to Perl's builtin C<index()> function,
1879see L<perlfunc/index>.
37120919 1880
41cd218c 1881=item C<strtod>
37120919 1882
a89d8a78
DH
1883String to double translation. Returns the parsed number and the number
1884of characters in the unparsed portion of the string. Truly
41cd218c 1885POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation
4d0de388 1886error, so clear C<$!> before calling C<strtod>. However, non-POSIX systems
41cd218c 1887may not check for overflow, and therefore will never set C<$!>.
a89d8a78 1888
4e6effb7 1889C<strtod> respects any POSIX C<setlocale()> C<LC_NUMERIC> settings,
458680b3 1890regardless of whether or not it is called from Perl code that is within
20e38015
KW
1891the scope of S<C<use locale>>. Prior to Perl 5.28, or when operating in
1892a non thread-safe environment, it should not be used in a threaded
1893application unless it's certain that the underlying locale is C
aa2bc4d3
KW
1894or POSIX. This is because it otherwise changes the locale, which
1895globally affects all threads simultaneously.
a89d8a78 1896
41cd218c 1897To parse a string C<$str> as a floating point number use
a89d8a78
DH
1898
1899 $! = 0;
1900 ($num, $n_unparsed) = POSIX::strtod($str);
1901
41cd218c 1902The second returned item and C<$!> can be used to check for valid input:
a89d8a78 1903
6309100e
DM
1904 if (($str eq '') || ($n_unparsed != 0) || $!) {
1905 die "Non-numeric input $str" . ($! ? ": $!\n" : "\n");
a89d8a78
DH
1906 }
1907
4d0de388 1908When called in a scalar context C<strtod> returns the parsed number.
37120919 1909
41cd218c 1910=item C<strtok>
37120919 1911
4d0de388 1912Not implemented. C<strtok()> is C-specific, use regular expressions instead, see
4755096e 1913L<perlre>, or L<perlfunc/split>.
37120919 1914
41cd218c 1915=item C<strtol>
37120919 1916
a89d8a78
DH
1917String to (long) integer translation. Returns the parsed number and
1918the number of characters in the unparsed portion of the string. Truly
41cd218c
KW
1919POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation
1920error, so clear C<$!> before calling C<strtol>. However, non-POSIX systems
1921may not check for overflow, and therefore will never set C<$!>.
a89d8a78 1922
41cd218c 1923C<strtol> should respect any POSIX I<setlocale()> settings.
a89d8a78 1924
41cd218c 1925To parse a string C<$str> as a number in some base C<$base> use
a89d8a78
DH
1926
1927 $! = 0;
1928 ($num, $n_unparsed) = POSIX::strtol($str, $base);
1929
1930The base should be zero or between 2 and 36, inclusive. When the base
4d0de388 1931is zero or omitted C<strtol> will use the string itself to determine the
a89d8a78
DH
1932base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
1933octal; any other leading characters mean decimal. Thus, "1234" is
1934parsed as a decimal number, "01234" as an octal number, and "0x1234"
1935as a hexadecimal number.
1936
41cd218c 1937The second returned item and C<$!> can be used to check for valid input:
a89d8a78
DH
1938
1939 if (($str eq '') || ($n_unparsed != 0) || !$!) {
1940 die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1941 }
1942
4d0de388 1943When called in a scalar context C<strtol> returns the parsed number.
a89d8a78 1944
0ff7b9da
JH
1945=item C<strtold>
1946
1947Like L</strtod> but for long doubles. Defined only if the
1948system supports long doubles.
1949
41cd218c 1950=item C<strtoul>
a89d8a78 1951
41cd218c
KW
1952String to unsigned (long) integer translation. C<strtoul()> is identical
1953to C<strtol()> except that C<strtoul()> only parses unsigned integers. See
4755096e 1954L</strtol> for details.
a89d8a78 1955
41cd218c
KW
1956Note: Some vendors supply C<strtod()> and C<strtol()> but not C<strtoul()>.
1957Other vendors that do supply C<strtoul()> parse "-1" as a valid value.
37120919 1958
41cd218c 1959=item C<strxfrm>
37120919 1960
cb1a09d0
AD
1961String transformation. Returns the transformed string.
1962
1963 $dst = POSIX::strxfrm( $src );
37120919 1964
4755096e
GS
1965Used in conjunction with the C<strcoll()> function, see L</strcoll>.
1966
1967Not really needed since Perl can do this transparently, see
1968L<perllocale>.
1969
393aa92a
KW
1970Beware that in a UTF-8 locale, anything you pass to this function must
1971be in UTF-8; and when not in a UTF-8 locale, anything passed must not be
1972UTF-8 encoded.
1973
41cd218c 1974=item C<sysconf>
37120919
AD
1975
1976Retrieves values of system configurable variables.
1977
1978The following will get the machine's clock speed.
1979
1980 $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
1981
1982Returns C<undef> on failure.
1983
41cd218c 1984=item C<system>
37120919 1985
4755096e
GS
1986This is identical to Perl's builtin C<system()> function, see
1987L<perlfunc/system>.
37120919 1988
41cd218c 1989=item C<tan>
37120919 1990
4755096e 1991This is identical to the C function C<tan()>, returning the
c2e66d9e 1992tangent of the numerical argument. See also L<Math::Trig>.
37120919 1993
41cd218c 1994=item C<tanh>
37120919 1995
4755096e 1996This is identical to the C function C<tanh()>, returning the
c2e66d9e 1997hyperbolic tangent of the numerical argument. See also L<Math::Trig>.
37120919 1998
41cd218c 1999=item C<tcdrain>
37120919 2000
4755096e
GS
2001This is similar to the C function C<tcdrain()> for draining
2002the output queue of its argument stream.
37120919
AD
2003
2004Returns C<undef> on failure.
2005
41cd218c 2006=item C<tcflow>
37120919 2007
4755096e
GS
2008This is similar to the C function C<tcflow()> for controlling
2009the flow of its argument stream.
37120919
AD
2010
2011Returns C<undef> on failure.
2012
41cd218c 2013=item C<tcflush>
37120919 2014
4755096e 2015This is similar to the C function C<tcflush()> for flushing
cc767757 2016the I/O buffers of its argument stream.
37120919
AD
2017
2018Returns C<undef> on failure.
2019
41cd218c 2020=item C<tcgetpgrp>
37120919 2021
4755096e
GS
2022This is identical to the C function C<tcgetpgrp()> for returning the
2023process group identifier of the foreground process group of the controlling
2024terminal.
37120919 2025
41cd218c 2026=item C<tcsendbreak>
37120919 2027
4755096e
GS
2028This is similar to the C function C<tcsendbreak()> for sending
2029a break on its argument stream.
37120919
AD
2030
2031Returns C<undef> on failure.
2032
41cd218c 2033=item C<tcsetpgrp>
37120919 2034
4755096e
GS
2035This is similar to the C function C<tcsetpgrp()> for setting the
2036process group identifier of the foreground process group of the controlling
2037terminal.
37120919
AD
2038
2039Returns C<undef> on failure.
2040
9d233e12
JH
2041=item C<tgamma>
2042
912a1e06 2043The Gamma function [C99]. Added in Perl v5.22.
9d233e12
JH
2044
2045See also L</lgamma>.
2046
41cd218c 2047=item C<time>
37120919 2048
4755096e
GS
2049This is identical to Perl's builtin C<time()> function
2050for returning the number of seconds since the epoch
2051(whatever it is for the system), see L<perlfunc/time>.
37120919 2052
41cd218c 2053=item C<times>
37120919 2054
41cd218c 2055The C<times()> function returns elapsed realtime since some point in the past
37120919
AD
2056(such as system startup), user and system times for this process, and user
2057and system times used by child processes. All times are returned in clock
2058ticks.
2059
4d0de388 2060 ($realtime, $user, $system, $cuser, $csystem)
b70c169c 2061 = POSIX::times();
37120919
AD
2062
2063Note: Perl's builtin C<times()> function returns four values, measured in
2064seconds.
2065
41cd218c 2066=item C<tmpfile>
37120919 2067
4d0de388 2068Not implemented. Use method C<IO::File::new_tmpfile()> instead, or see L<File::Temp>.
37120919 2069
41cd218c 2070=item C<tmpnam>
37120919 2071
60cba15a 2072For security reasons, which are probably detailed in your system's
41cd218c 2073documentation for the C library C<tmpnam()> function, this interface
912a1e06 2074is no longer available since Perl v5.26; instead use L<File::Temp>.
4755096e 2075
41cd218c 2076=item C<tolower>
37120919 2077
912a1e06 2078This function has been removed as of Perl v5.26.
4755096e 2079This is identical to the C function, except that it can apply to a single
4d0de388
KW
2080character or to a whole string, and currently operates as if the locale
2081always is "C". Consider using the C<lc()> function, see L<perlfunc/lc>,
4755096e
GS
2082see L<perlfunc/lc>, or the equivalent C<\L> operator inside doublequotish
2083strings.
37120919 2084
41cd218c 2085=item C<toupper>
37120919 2086
912a1e06 2087This function has been removed as of Perl v5.26.
4d0de388
KW
2088This is similar to the C function, except that it can apply to a single
2089character or to a whole string, and currently operates as if the locale
2090always is "C". Consider using the C<uc()> function, see L<perlfunc/uc>,
2091or the equivalent C<\U> operator inside doublequotish strings.
37120919 2092
9d233e12
JH
2093=item C<trunc>
2094
912a1e06
DB
2095Returns the integer toward zero from the argument [C99]. Added in Perl
2096v5.22.
9d233e12
JH
2097
2098See also L</ceil>, L</floor>, and L</round>.
2099
41cd218c 2100=item C<ttyname>
37120919 2101
4755096e
GS
2102This is identical to the C function C<ttyname()> for returning the
2103name of the current terminal.
37120919 2104
41cd218c 2105=item C<tzname>
37120919 2106
cb1a09d0
AD
2107Retrieves the time conversion information from the C<tzname> variable.
2108
2109 POSIX::tzset();
2110 ($std, $dst) = POSIX::tzname();
37120919 2111
41cd218c 2112=item C<tzset>
37120919 2113
4755096e
GS
2114This is identical to the C function C<tzset()> for setting
2115the current timezone based on the environment variable C<TZ>,
2116to be used by C<ctime()>, C<localtime()>, C<mktime()>, and C<strftime()>
2117functions.
37120919 2118
41cd218c 2119=item C<umask>
37120919 2120
4755096e
GS
2121This is identical to Perl's builtin C<umask()> function
2122for setting (and querying) the file creation permission mask,
2123see L<perlfunc/umask>.
37120919 2124
41cd218c 2125=item C<uname>
37120919 2126
cb1a09d0
AD
2127Get name of current operating system.
2128
b70c169c
FC
2129 ($sysname, $nodename, $release, $version, $machine)
2130 = POSIX::uname();
4755096e
GS
2131
2132Note that the actual meanings of the various fields are not
2133that well standardized, do not expect any great portability.
2134The C<$sysname> might be the name of the operating system,
2135the C<$nodename> might be the name of the host, the C<$release>
2136might be the (major) release number of the operating system,
2137the C<$version> might be the (minor) release number of the
2138operating system, and the C<$machine> might be a hardware identifier.
2139Maybe.
37120919 2140
41cd218c 2141=item C<ungetc>
37120919 2142
4d0de388 2143Not implemented. Use method C<IO::Handle::ungetc()> instead.
37120919 2144
41cd218c 2145=item C<unlink>
37120919 2146
4755096e
GS
2147This is identical to Perl's builtin C<unlink()> function
2148for removing files, see L<perlfunc/unlink>.
37120919 2149
41cd218c 2150=item C<utime>
37120919 2151
4755096e
GS
2152This is identical to Perl's builtin C<utime()> function
2153for changing the time stamps of files and directories,
2154see L<perlfunc/utime>.
37120919 2155
41cd218c 2156=item C<vfprintf>
37120919 2157
4d0de388 2158Not implemented. C<vfprintf()> is C-specific, see L<perlfunc/printf> instead.
37120919 2159
41cd218c 2160=item C<vprintf>
37120919 2161
4d0de388 2162Not implemented. C<vprintf()> is C-specific, see L<perlfunc/printf> instead.
37120919 2163
41cd218c 2164=item C<vsprintf>
37120919 2165
4d0de388 2166Not implemented. C<vsprintf()> is C-specific, see L<perlfunc/sprintf> instead.
37120919 2167
41cd218c 2168=item C<wait>
37120919 2169
4755096e
GS
2170This is identical to Perl's builtin C<wait()> function,
2171see L<perlfunc/wait>.
37120919 2172
41cd218c 2173=item C<waitpid>
37120919 2174
cb1a09d0 2175Wait for a child process to change state. This is identical to Perl's
4755096e 2176builtin C<waitpid()> function, see L<perlfunc/waitpid>.
cb1a09d0 2177
2ac1ef3d 2178 $pid = POSIX::waitpid( -1, POSIX::WNOHANG );
cb1a09d0 2179 print "status = ", ($? / 256), "\n";
37120919 2180
351ab2ad 2181See L</mblen>.
37120919 2182
41cd218c 2183=item C<wctomb>
37120919 2184
5a6637f0
KW
2185This is the same as the C function C<wctomb()> on unthreaded perls. On
2186threaded perls, it transparently (almost) substitutes the more
2187thread-safe L<C<wcrtomb>(3)>, if available, instead of C<wctomb>.
351ab2ad 2188
5a6637f0
KW
2189Core Perl does not have any support for wide and multibyte locales,
2190except Unicode UTF-8 locales. This function, in conjunction with
2191L</mblen> and L</mbtowc> may be used to roll your own decoding/encoding
2192of other types of multi-byte locales.
2193
2194Use C<undef> as the first parameter to this function to get the effect
2195of passing NULL as the first parameter to C<wctomb>. This resets any
2196shift state to its initial value. The return value is undefined if
2197C<wcrtomb> was substituted, so you should never rely on it.
2198
2199When the first parameter is a scalar, the code point contained in the
2200scalar second parameter is converted into a multi-byte string and stored
2201into the first parameter scalar. This is based on the locale that
2202currently underlies the program, regardless of whether or not the
2203function is called from Perl code that is within the scope of S<C<use
2204locale>>. The return value is the number of bytes stored; or negative
2205if the code point isn't representable in the current locale. Perl makes
2206no attempt at hiding from your code any differences in the C<errno>
2207setting between C<wctomb> and C<wcrtomb>. It does set C<errno> to 0
2208before calling them.
37120919 2209
41cd218c 2210=item C<write>
37120919 2211
cb1a09d0
AD
2212Write to a file. This uses file descriptors such as those obtained by
2213calling C<POSIX::open>.
2214
2215 $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
2216 $buf = "hello";
a0604b4c 2217 $bytes = POSIX::write( $fd, $buf, 5 );
37120919
AD
2218
2219Returns C<undef> on failure.
2220
4755096e
GS
2221See also L<perlfunc/syswrite>.
2222
37120919
AD
2223=back
2224
2225=head1 CLASSES
2226
41cd218c 2227=head2 C<POSIX::SigAction>
37120919
AD
2228
2229=over 8
2230
41cd218c 2231=item C<new>
37120919 2232
cb1a09d0 2233Creates a new C<POSIX::SigAction> object which corresponds to the C
3609ea0d
JH
2234C<struct sigaction>. This object will be destroyed automatically when
2235it is no longer needed. The first parameter is the handler, a sub
2236reference. The second parameter is a C<POSIX::SigSet> object, it
2237defaults to the empty set. The third parameter contains the
28757baa 2238C<sa_flags>, it defaults to 0.
cb1a09d0 2239
28757baa 2240 $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
b70c169c
FC
2241 $sigaction = POSIX::SigAction->new(
2242 \&handler, $sigset, &POSIX::SA_NOCLDSTOP
2243 );
cb1a09d0 2244
d36b6582 2245This C<POSIX::SigAction> object is intended for use with the C<POSIX::sigaction()>
cb1a09d0 2246function.
37120919
AD
2247
2248=back
2249
557c0de7
BD
2250=over 8
2251
41cd218c 2252=item C<handler>
557c0de7 2253
41cd218c 2254=item C<mask>
557c0de7 2255
41cd218c 2256=item C<flags>
557c0de7
BD
2257
2258accessor functions to get/set the values of a SigAction object.
2259
2260 $sigset = $sigaction->mask;
2261 $sigaction->flags(&POSIX::SA_RESTART);
2262
41cd218c 2263=item C<safe>
d36b6582
CS
2264
2265accessor function for the "safe signals" flag of a SigAction object; see
2266L<perlipc> for general information on safe (a.k.a. "deferred") signals. If
2267you wish to handle a signal safely, use this accessor to set the "safe" flag
2268in the C<POSIX::SigAction> object:
2269
2270 $sigaction->safe(1);
2271
2272You may also examine the "safe" flag on the output action object which is
2273filled in when given as the third parameter to C<POSIX::sigaction()>:
2274
2275 sigaction(SIGINT, $new_action, $old_action);
2276 if ($old_action->safe) {
2277 # previous SIGINT handler used safe signals
2278 }
2279
557c0de7
BD
2280=back
2281
41cd218c 2282=head2 C<POSIX::SigRt>
3609ea0d
JH
2283
2284=over 8
2285
41cd218c 2286=item C<%SIGRT>
3609ea0d
JH
2287
2288A hash of the POSIX realtime signal handlers. It is an extension of
41cd218c
KW
2289the standard C<%SIG>, the C<$POSIX::SIGRT{SIGRTMIN}> is roughly equivalent
2290to C<$SIG{SIGRTMIN}>, but the right POSIX moves (see below) are made with
2291the C<POSIX::SigSet> and C<POSIX::sigaction> instead of accessing the C<%SIG>.
3609ea0d 2292
41cd218c 2293You can set the C<%POSIX::SIGRT> elements to set the POSIX realtime
3609ea0d
JH
2294signal handlers, use C<delete> and C<exists> on the elements, and use
2295C<scalar> on the C<%POSIX::SIGRT> to find out how many POSIX realtime
41cd218c 2296signals there are available S<C<(SIGRTMAX - SIGRTMIN + 1>>, the C<SIGRTMAX> is
3609ea0d
JH
2297a valid POSIX realtime signal).
2298
41cd218c 2299Setting the C<%SIGRT> elements is equivalent to calling this:
3609ea0d
JH
2300
2301 sub new {
2302 my ($rtsig, $handler, $flags) = @_;
b8921b3e 2303 my $sigset = POSIX::SigSet($rtsig);
b70c169c 2304 my $sigact = POSIX::SigAction->new($handler,$sigset,$flags);
3609ea0d
JH
2305 sigaction($rtsig, $sigact);
2306 }
2307
2308The flags default to zero, if you want something different you can
41cd218c 2309either use C<local> on C<$POSIX::SigRt::SIGACTION_FLAGS>, or you can
3609ea0d 2310derive from POSIX::SigRt and define your own C<new()> (the tied hash
41cd218c
KW
2311STORE method of the C<%SIGRT> calls C<new($rtsig, $handler, $SIGACTION_FLAGS)>,
2312where the C<$rtsig> ranges from zero to S<C<SIGRTMAX - SIGRTMIN + 1)>>.
3609ea0d 2313
41cd218c 2314Just as with any signal, you can use C<sigaction($rtsig, undef, $oa)> to
3609ea0d
JH
2315retrieve the installed signal handler (or, rather, the signal action).
2316
2317B<NOTE:> whether POSIX realtime signals really work in your system, or
2318whether Perl has been compiled so that it works with them, is outside
2319of this discussion.
2320
41cd218c 2321=item C<SIGRTMIN>
3609ea0d
JH
2322
2323Return the minimum POSIX realtime signal number available, or C<undef>
2324if no POSIX realtime signals are available.
2325
41cd218c 2326=item C<SIGRTMAX>
3609ea0d
JH
2327
2328Return the maximum POSIX realtime signal number available, or C<undef>
2329if no POSIX realtime signals are available.
2330
2331=back
2332
41cd218c 2333=head2 C<POSIX::SigSet>
37120919
AD
2334
2335=over 8
2336
41cd218c 2337=item C<new>
37120919
AD
2338
2339Create a new SigSet object. This object will be destroyed automatically
2340when it is no longer needed. Arguments may be supplied to initialize the
2341set.
2342
2343Create an empty set.
2344
2345 $sigset = POSIX::SigSet->new;
2346
41cd218c 2347Create a set with C<SIGUSR1>.
37120919
AD
2348
2349 $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
2350
3a5c73f3
TC
2351Throws an error if any of the signals supplied cannot be added to the
2352set.
2353
41cd218c 2354=item C<addset>
37120919
AD
2355
2356Add a signal to a SigSet object.
2357
2358 $sigset->addset( &POSIX::SIGUSR2 );
2359
2360Returns C<undef> on failure.
2361
41cd218c 2362=item C<delset>
37120919
AD
2363
2364Remove a signal from the SigSet object.
2365
2366 $sigset->delset( &POSIX::SIGUSR2 );
2367
2368Returns C<undef> on failure.
2369
41cd218c 2370=item C<emptyset>
37120919
AD
2371
2372Initialize the SigSet object to be empty.
2373
2374 $sigset->emptyset();
2375
2376Returns C<undef> on failure.
2377
41cd218c 2378=item C<fillset>
37120919
AD
2379
2380Initialize the SigSet object to include all signals.
2381
2382 $sigset->fillset();
2383
2384Returns C<undef> on failure.
2385
41cd218c 2386=item C<ismember>
37120919
AD
2387
2388Tests the SigSet object to see if it contains a specific signal.
2389
2390 if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
2391 print "contains SIGUSR1\n";
2392 }
2393
2394=back
2395
41cd218c 2396=head2 C<POSIX::Termios>
37120919
AD
2397
2398=over 8
2399
41cd218c 2400=item C<new>
37120919
AD
2401
2402Create a new Termios object. This object will be destroyed automatically
4d0de388 2403when it is no longer needed. A Termios object corresponds to the C<termios>
41cd218c
KW
2404C struct. C<new()> mallocs a new one, C<getattr()> fills it from a file descriptor,
2405and C<setattr()> sets a file descriptor's parameters to match Termios' contents.
37120919
AD
2406
2407 $termios = POSIX::Termios->new;
2408
41cd218c 2409=item C<getattr>
37120919 2410
cb1a09d0
AD
2411Get terminal control attributes.
2412
4d0de388 2413Obtain the attributes for C<stdin>.
cb1a09d0 2414
220f811a 2415 $termios->getattr( 0 ) # Recommended for clarity.
cb1a09d0
AD
2416 $termios->getattr()
2417
2418Obtain the attributes for stdout.
2419
2420 $termios->getattr( 1 )
37120919
AD
2421
2422Returns C<undef> on failure.
2423
41cd218c 2424=item C<getcc>
37120919 2425
4d0de388 2426Retrieve a value from the C<c_cc> field of a C<termios> object. The C<c_cc> field is
37120919
AD
2427an array so an index must be specified.
2428
2429 $c_cc[1] = $termios->getcc(1);
2430
41cd218c 2431=item C<getcflag>
37120919 2432
4d0de388 2433Retrieve the C<c_cflag> field of a C<termios> object.
37120919
AD
2434
2435 $c_cflag = $termios->getcflag;
2436
41cd218c 2437=item C<getiflag>
37120919 2438
4d0de388 2439Retrieve the C<c_iflag> field of a C<termios> object.
37120919
AD
2440
2441 $c_iflag = $termios->getiflag;
2442
41cd218c 2443=item C<getispeed>
37120919
AD
2444
2445Retrieve the input baud rate.
2446
2447 $ispeed = $termios->getispeed;
2448
41cd218c 2449=item C<getlflag>
37120919 2450
4d0de388 2451Retrieve the C<c_lflag> field of a C<termios> object.
37120919
AD
2452
2453 $c_lflag = $termios->getlflag;
2454
41cd218c 2455=item C<getoflag>
37120919 2456
4d0de388 2457Retrieve the C<c_oflag> field of a C<termios> object.
37120919
AD
2458
2459 $c_oflag = $termios->getoflag;
2460
41cd218c 2461=item C<getospeed>
37120919
AD
2462
2463Retrieve the output baud rate.
2464
2465 $ospeed = $termios->getospeed;
2466
41cd218c 2467=item C<setattr>
37120919 2468
cb1a09d0
AD
2469Set terminal control attributes.
2470
2471Set attributes immediately for stdout.
2472
2473 $termios->setattr( 1, &POSIX::TCSANOW );
37120919
AD
2474
2475Returns C<undef> on failure.
2476
41cd218c 2477=item C<setcc>
37120919 2478
4d0de388 2479Set a value in the C<c_cc> field of a C<termios> object. The C<c_cc> field is an
37120919
AD
2480array so an index must be specified.
2481
6b7a6f50 2482 $termios->setcc( &POSIX::VEOF, 1 );
37120919 2483
41cd218c 2484=item C<setcflag>
37120919 2485
4d0de388 2486Set the C<c_cflag> field of a C<termios> object.
37120919 2487
55d729e4 2488 $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
37120919 2489
41cd218c 2490=item C<setiflag>
37120919 2491
4d0de388 2492Set the C<c_iflag> field of a C<termios> object.
37120919 2493
55d729e4 2494 $termios->setiflag( $c_iflag | &POSIX::BRKINT );
37120919 2495
41cd218c 2496=item C<setispeed>
37120919
AD
2497
2498Set the input baud rate.
2499
2500 $termios->setispeed( &POSIX::B9600 );
2501
2502Returns C<undef> on failure.
2503
41cd218c 2504=item C<setlflag>
37120919 2505
4d0de388 2506Set the C<c_lflag> field of a C<termios> object.
37120919 2507
55d729e4 2508 $termios->setlflag( $c_lflag | &POSIX::ECHO );
37120919 2509
41cd218c 2510=item C<setoflag>
37120919 2511
4d0de388 2512Set the C<c_oflag> field of a C<termios> object.
37120919 2513
55d729e4 2514 $termios->setoflag( $c_oflag | &POSIX::OPOST );
37120919 2515
41cd218c 2516=item C<setospeed>
37120919
AD
2517
2518Set the output baud rate.
2519
2520 $termios->setospeed( &POSIX::B9600 );
2521
2522Returns C<undef> on failure.
2523
2524=item Baud rate values
2525
41cd218c 2526C<B38400> C<B75> C<B200> C<B134> C<B300> C<B1800> C<B150> C<B0> C<B19200> C<B1200> C<B9600> C<B600> C<B4800> C<B50> C<B2400> C<B110>
37120919
AD
2527
2528=item Terminal interface values
2529
41cd218c 2530C<TCSADRAIN> C<TCSANOW> C<TCOON> C<TCIOFLUSH> C<TCOFLUSH> C<TCION> C<TCIFLUSH> C<TCSAFLUSH> C<TCIOFF> C<TCOOFF>
37120919 2531
41cd218c 2532=item C<c_cc> field values
37120919 2533
41cd218c 2534C<VEOF> C<VEOL> C<VERASE> C<VINTR> C<VKILL> C<VQUIT> C<VSUSP> C<VSTART> C<VSTOP> C<VMIN> C<VTIME> C<NCCS>
37120919 2535
41cd218c 2536=item C<c_cflag> field values
37120919 2537
41cd218c 2538C<CLOCAL> C<CREAD> C<CSIZE> C<CS5> C<CS6> C<CS7> C<CS8> C<CSTOPB> C<HUPCL> C<PARENB> C<PARODD>
37120919 2539
41cd218c 2540=item C<c_iflag> field values
37120919 2541
41cd218c 2542C<BRKINT> C<ICRNL> C<IGNBRK> C<IGNCR> C<IGNPAR> C<INLCR> C<INPCK> C<ISTRIP> C<IXOFF> C<IXON> C<PARMRK>
37120919 2543
41cd218c 2544=item C<c_lflag> field values
37120919 2545
41cd218c 2546C<ECHO> C<ECHOE> C<ECHOK> C<ECHONL> C<ICANON> C<IEXTEN> C<ISIG> C<NOFLSH> C<TOSTOP>
37120919 2547
41cd218c 2548=item C<c_oflag> field values
37120919 2549
41cd218c 2550C<OPOST>
37120919
AD
2551
2552=back
2553
2554=head1 PATHNAME CONSTANTS
2555
2556=over 8
2557
2558=item Constants
2559
41cd218c
KW
2560C<_PC_CHOWN_RESTRICTED> C<_PC_LINK_MAX> C<_PC_MAX_CANON> C<_PC_MAX_INPUT> C<_PC_NAME_MAX>
2561C<_PC_NO_TRUNC> C<_PC_PATH_MAX> C<_PC_PIPE_BUF> C<_PC_VDISABLE>
37120919
AD
2562
2563=back
2564
2565=head1 POSIX CONSTANTS
2566
2567=over 8
2568
2569=item Constants
2570
41cd218c
KW
2571C<_POSIX_ARG_MAX> C<_POSIX_CHILD_MAX> C<_POSIX_CHOWN_RESTRICTED> C<_POSIX_JOB_CONTROL>
2572C<_POSIX_LINK_MAX> C<_POSIX_MAX_CANON> C<_POSIX_MAX_INPUT> C<_POSIX_NAME_MAX>
2573C<_POSIX_NGROUPS_MAX> C<_POSIX_NO_TRUNC> C<_POSIX_OPEN_MAX> C<_POSIX_PATH_MAX>
2574C<_POSIX_PIPE_BUF> C<_POSIX_SAVED_IDS> C<_POSIX_SSIZE_MAX> C<_POSIX_STREAM_MAX>
2575C<_POSIX_TZNAME_MAX> C<_POSIX_VDISABLE> C<_POSIX_VERSION>
37120919
AD
2576
2577=back
2578
4fd667a8
TC
2579=head1 RESOURCE CONSTANTS
2580
2581Imported with the C<:sys_resource_h> tag.
2582
2583=over 8
2584
2585=item Constants
2586
912a1e06
DB
2587Added in Perl v5.28:
2588
4fd667a8
TC
2589C<PRIO_PROCESS> C<PRIO_PGRP> C<PRIO_USER>
2590
2591=back
2592
37120919
AD
2593=head1 SYSTEM CONFIGURATION
2594
2595=over 8
2596
2597=item Constants
2598
41cd218c
KW
2599C<_SC_ARG_MAX> C<_SC_CHILD_MAX> C<_SC_CLK_TCK> C<_SC_JOB_CONTROL> C<_SC_NGROUPS_MAX>
2600C<_SC_OPEN_MAX> C<_SC_PAGESIZE> C<_SC_SAVED_IDS> C<_SC_STREAM_MAX> C<_SC_TZNAME_MAX>
2601C<_SC_VERSION>
37120919
AD
2602
2603=back
2604
2605=head1 ERRNO
2606
2607=over 8
2608
2609=item Constants
2610
41cd218c
KW
2611C<E2BIG> C<EACCES> C<EADDRINUSE> C<EADDRNOTAVAIL> C<EAFNOSUPPORT> C<EAGAIN> C<EALREADY> C<EBADF> C<EBADMSG>
2612C<EBUSY> C<ECANCELED> C<ECHILD> C<ECONNABORTED> C<ECONNREFUSED> C<ECONNRESET> C<EDEADLK> C<EDESTADDRREQ>
2613C<EDOM> C<EDQUOT> C<EEXIST> C<EFAULT> C<EFBIG> C<EHOSTDOWN> C<EHOSTUNREACH> C<EIDRM> C<EILSEQ> C<EINPROGRESS>
2614C<EINTR> C<EINVAL> C<EIO> C<EISCONN> C<EISDIR> C<ELOOP> C<EMFILE> C<EMLINK> C<EMSGSIZE> C<ENAMETOOLONG>
2615C<ENETDOWN> C<ENETRESET> C<ENETUNREACH> C<ENFILE> C<ENOBUFS> C<ENODATA> C<ENODEV> C<ENOENT> C<ENOEXEC>
2616C<ENOLCK> C<ENOLINK> C<ENOMEM> C<ENOMSG> C<ENOPROTOOPT> C<ENOSPC> C<ENOSR> C<ENOSTR> C<ENOSYS> C<ENOTBLK>
2617C<ENOTCONN> C<ENOTDIR> C<ENOTEMPTY> C<ENOTRECOVERABLE> C<ENOTSOCK> C<ENOTSUP> C<ENOTTY> C<ENXIO>
2618C<EOPNOTSUPP> C<EOTHER> C<EOVERFLOW> C<EOWNERDEAD> C<EPERM> C<EPFNOSUPPORT> C<EPIPE> C<EPROCLIM> C<EPROTO>
2619C<EPROTONOSUPPORT> C<EPROTOTYPE> C<ERANGE> C<EREMOTE> C<ERESTART> C<EROFS> C<ESHUTDOWN>
2620C<ESOCKTNOSUPPORT> C<ESPIPE> C<ESRCH> C<ESTALE> C<ETIME> C<ETIMEDOUT> C<ETOOMANYREFS> C<ETXTBSY> C<EUSERS>
2621C<EWOULDBLOCK> C<EXDEV>
37120919
AD
2622
2623=back
2624
2625=head1 FCNTL
2626
2627=over 8
2628
2629=item Constants
2630
41cd218c
KW
2631C<FD_CLOEXEC> C<F_DUPFD> C<F_GETFD> C<F_GETFL> C<F_GETLK> C<F_OK> C<F_RDLCK> C<F_SETFD> C<F_SETFL> C<F_SETLK>
2632C<F_SETLKW> C<F_UNLCK> C<F_WRLCK> C<O_ACCMODE> C<O_APPEND> C<O_CREAT> C<O_EXCL> C<O_NOCTTY> C<O_NONBLOCK>
2633C<O_RDONLY> C<O_RDWR> C<O_TRUNC> C<O_WRONLY>
37120919
AD
2634
2635=back
2636
2637=head1 FLOAT
2638
2639=over 8
2640
2641=item Constants
2642
41cd218c
KW
2643C<DBL_DIG> C<DBL_EPSILON> C<DBL_MANT_DIG> C<DBL_MAX> C<DBL_MAX_10_EXP> C<DBL_MAX_EXP> C<DBL_MIN>
2644C<DBL_MIN_10_EXP> C<DBL_MIN_EXP> C<FLT_DIG> C<FLT_EPSILON> C<FLT_MANT_DIG> C<FLT_MAX>
2645C<FLT_MAX_10_EXP> C<FLT_MAX_EXP> C<FLT_MIN> C<FLT_MIN_10_EXP> C<FLT_MIN_EXP> C<FLT_RADIX>
2646C<FLT_ROUNDS> C<LDBL_DIG> C<LDBL_EPSILON> C<LDBL_MANT_DIG> C<LDBL_MAX> C<LDBL_MAX_10_EXP>
2647C<LDBL_MAX_EXP> C<LDBL_MIN> C<LDBL_MIN_10_EXP> C<LDBL_MIN_EXP>
37120919
AD
2648
2649=back
2650
98ab3abf
AP
2651=head1 FLOATING-POINT ENVIRONMENT
2652
2653=over 8
2654
2655=item Constants
2656
2657C<FE_DOWNWARD> C<FE_TONEAREST> C<FE_TOWARDZERO> C<FE_UPWARD>
2658on systems that support them.
2659
2660=back
2661
37120919
AD
2662=head1 LIMITS
2663
2664=over 8
2665
2666=item Constants
2667
41cd218c
KW
2668C<ARG_MAX> C<CHAR_BIT> C<CHAR_MAX> C<CHAR_MIN> C<CHILD_MAX> C<INT_MAX> C<INT_MIN> C<LINK_MAX> C<LONG_MAX>
2669C<LONG_MIN> C<MAX_CANON> C<MAX_INPUT> C<MB_LEN_MAX> C<NAME_MAX> C<NGROUPS_MAX> C<OPEN_MAX> C<PATH_MAX>
2670C<PIPE_BUF> C<SCHAR_MAX> C<SCHAR_MIN> C<SHRT_MAX> C<SHRT_MIN> C<SSIZE_MAX> C<STREAM_MAX> C<TZNAME_MAX>
2671C<UCHAR_MAX> C<UINT_MAX> C<ULONG_MAX> C<USHRT_MAX>
37120919
AD
2672
2673=back
2674
2675=head1 LOCALE
2676
2677=over 8
2678
2679=item Constants
2680
4d0de388
KW
2681C<LC_ALL> C<LC_COLLATE> C<LC_CTYPE> C<LC_MONETARY> C<LC_NUMERIC> C<LC_TIME> C<LC_MESSAGES>
2682on systems that support them.
37120919
AD
2683
2684=back
2685
2686=head1 MATH
2687
2688=over 8
2689
2690=item Constants
2691
41cd218c 2692C<HUGE_VAL>
37120919 2693
912a1e06
DB
2694Added in Perl v5.22:
2695
98ab3abf
AP
2696C<FP_ILOGB0> C<FP_ILOGBNAN> C<FP_INFINITE> C<FP_NAN> C<FP_NORMAL> C<FP_SUBNORMAL> C<FP_ZERO>
2697C<INFINITY> C<NAN> C<Inf> C<NaN>
2698C<M_1_PI> C<M_2_PI> C<M_2_SQRTPI> C<M_E> C<M_LN10> C<M_LN2> C<M_LOG10E> C<M_LOG2E> C<M_PI>
2699C<M_PI_2> C<M_PI_4> C<M_SQRT1_2> C<M_SQRT2>
2700on systems with C99 support.
2701
37120919
AD
2702=back
2703
2704=head1 SIGNAL
2705
2706=over 8
2707
2708=item Constants
2709
41cd218c
KW
2710C<SA_NOCLDSTOP> C<SA_NOCLDWAIT> C<SA_NODEFER> C<SA_ONSTACK> C<SA_RESETHAND> C<SA_RESTART>
2711C<SA_SIGINFO> C<SIGABRT> C<SIGALRM> C<SIGCHLD> C<SIGCONT> C<SIGFPE> C<SIGHUP> C<SIGILL> C<SIGINT>
2712C<SIGKILL> C<SIGPIPE> C<SIGQUIT> C<SIGSEGV> C<SIGSTOP> C<SIGTERM> C<SIGTSTP> C<SIGTTIN> C<SIGTTOU>
2713C<SIGUSR1> C<SIGUSR2> C<SIG_BLOCK> C<SIG_DFL> C<SIG_ERR> C<SIG_IGN> C<SIG_SETMASK>
2714C<SIG_UNBLOCK>
912a1e06
DB
2715
2716Added in Perl v5.24:
2717
34e79b75
DIM
2718C<ILL_ILLOPC> C<ILL_ILLOPN> C<ILL_ILLADR> C<ILL_ILLTRP> C<ILL_PRVOPC> C<ILL_PRVREG> C<ILL_COPROC>
2719C<ILL_BADSTK> C<FPE_INTDIV> C<FPE_INTOVF> C<FPE_FLTDIV> C<FPE_FLTOVF> C<FPE_FLTUND> C<FPE_FLTRES>
2720C<FPE_FLTINV> C<FPE_FLTSUB> C<SEGV_MAPERR> C<SEGV_ACCERR> C<BUS_ADRALN> C<BUS_ADRERR>
2721C<BUS_OBJERR> C<TRAP_BRKPT> C<TRAP_TRACE> C<CLD_EXITED> C<CLD_KILLED> C<CLD_DUMPED> C<CLD_TRAPPED>
2722C<CLD_STOPPED> C<CLD_CONTINUED> C<POLL_IN> C<POLL_OUT> C<POLL_MSG> C<POLL_ERR> C<POLL_PRI>
2723C<POLL_HUP> C<SI_USER> C<SI_QUEUE> C<SI_TIMER> C<SI_ASYNCIO> C<SI_MESGQ>
37120919
AD
2724
2725=back
2726
2727=head1 STAT
2728
2729=over 8
2730
2731=item Constants
2732
41cd218c
KW
2733C<S_IRGRP> C<S_IROTH> C<S_IRUSR> C<S_IRWXG> C<S_IRWXO> C<S_IRWXU> C<S_ISGID> C<S_ISUID> C<S_IWGRP> C<S_IWOTH>
2734C<S_IWUSR> C<S_IXGRP> C<S_IXOTH> C<S_IXUSR>
37120919
AD
2735
2736=item Macros
2737
41cd218c 2738C<S_ISBLK> C<S_ISCHR> C<S_ISDIR> C<S_ISFIFO> C<S_ISREG>
37120919
AD
2739
2740=back
2741
2742=head1 STDLIB
2743
2744=over 8
2745
2746=item Constants
2747
41cd218c 2748C<EXIT_FAILURE> C<EXIT_SUCCESS> C<MB_CUR_MAX> C<RAND_MAX>
37120919
AD
2749
2750=back
2751
2752=head1 STDIO
2753
2754=over 8
2755
2756=item Constants
2757
1cb852db 2758C<BUFSIZ> C<EOF> C<FILENAME_MAX> C<L_ctermid> C<L_cuserid> C<TMP_MAX>
37120919
AD
2759
2760=back
2761
2762=head1 TIME
2763
2764=over 8
2765
2766=item Constants
2767
41cd218c 2768C<CLK_TCK> C<CLOCKS_PER_SEC>
37120919
AD
2769
2770=back
2771
2772=head1 UNISTD
2773
2774=over 8
2775
2776=item Constants
2777
41cd218c 2778C<R_OK> C<SEEK_CUR> C<SEEK_END> C<SEEK_SET> C<STDIN_FILENO> C<STDOUT_FILENO> C<STDERR_FILENO> C<W_OK> C<X_OK>
37120919
AD
2779
2780=back
2781
2782=head1 WAIT
2783
2784=over 8
2785
2786=item Constants
2787
41cd218c 2788C<WNOHANG> C<WUNTRACED>
37120919 2789
9d6eb86e
JH
2790=over 16
2791
41cd218c 2792=item C<WNOHANG>
9d6eb86e
JH
2793
2794Do not suspend the calling process until a child process
2795changes state but instead return immediately.
2796
41cd218c 2797=item C<WUNTRACED>
9d6eb86e
JH
2798
2799Catch stopped child processes.
2800
2801=back
2802
37120919
AD
2803=item Macros
2804
41cd218c 2805C<WIFEXITED> C<WEXITSTATUS> C<WIFSIGNALED> C<WTERMSIG> C<WIFSTOPPED> C<WSTOPSIG>
37120919 2806
9d6eb86e
JH
2807=over 16
2808
41cd218c 2809=item C<WIFEXITED>
9d6eb86e 2810
41cd218c 2811C<WIFEXITED(${^CHILD_ERROR_NATIVE})> returns true if the child process
12a72a5a 2812exited normally (C<exit()> or by falling off the end of C<main()>)
9d6eb86e 2813
41cd218c 2814=item C<WEXITSTATUS>
9d6eb86e 2815
41cd218c
KW
2816C<WEXITSTATUS(${^CHILD_ERROR_NATIVE})> returns the normal exit status of
2817the child process (only meaningful if C<WIFEXITED(${^CHILD_ERROR_NATIVE})>
12a72a5a 2818is true)
9d6eb86e 2819
41cd218c 2820=item C<WIFSIGNALED>
9d6eb86e 2821
41cd218c 2822C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})> returns true if the child process
12a72a5a 2823terminated because of a signal
9d6eb86e 2824
41cd218c 2825=item C<WTERMSIG>
9d6eb86e 2826
41cd218c
KW
2827C<WTERMSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process
2828terminated for (only meaningful if
2829C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})>
12a72a5a 2830is true)
9d6eb86e 2831
41cd218c 2832=item C<WIFSTOPPED>
9d6eb86e 2833
41cd218c 2834C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})> returns true if the child process is
12a72a5a 2835currently stopped (can happen only if you specified the WUNTRACED flag
41cd218c 2836to C<waitpid()>)
9d6eb86e 2837
41cd218c 2838=item C<WSTOPSIG>
9d6eb86e 2839
41cd218c
KW
2840C<WSTOPSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process
2841was stopped for (only meaningful if
2842C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})>
12a72a5a 2843is true)
9d6eb86e
JH
2844
2845=back
2846
37120919
AD
2847=back
2848
a28fff51
SH
2849=head1 WINSOCK
2850
2851(Windows only.)
2852
2853=over 8
2854
2855=item Constants
2856
912a1e06
DB
2857Added in Perl v5.24:
2858
a28fff51
SH
2859C<WSAEINTR> C<WSAEBADF> C<WSAEACCES> C<WSAEFAULT> C<WSAEINVAL> C<WSAEMFILE> C<WSAEWOULDBLOCK>
2860C<WSAEINPROGRESS> C<WSAEALREADY> C<WSAENOTSOCK> C<WSAEDESTADDRREQ> C<WSAEMSGSIZE>
2861C<WSAEPROTOTYPE> C<WSAENOPROTOOPT> C<WSAEPROTONOSUPPORT> C<WSAESOCKTNOSUPPORT>
2862C<WSAEOPNOTSUPP> C<WSAEPFNOSUPPORT> C<WSAEAFNOSUPPORT> C<WSAEADDRINUSE>
2863C<WSAEADDRNOTAVAIL> C<WSAENETDOWN> C<WSAENETUNREACH> C<WSAENETRESET> C<WSAECONNABORTED>
2864C<WSAECONNRESET> C<WSAENOBUFS> C<WSAEISCONN> C<WSAENOTCONN> C<WSAESHUTDOWN>
2865C<WSAETOOMANYREFS> C<WSAETIMEDOUT> C<WSAECONNREFUSED> C<WSAELOOP> C<WSAENAMETOOLONG>
2866C<WSAEHOSTDOWN> C<WSAEHOSTUNREACH> C<WSAENOTEMPTY> C<WSAEPROCLIM> C<WSAEUSERS>
2867C<WSAEDQUOT> C<WSAESTALE> C<WSAEREMOTE> C<WSAEDISCON> C<WSAENOMORE> C<WSAECANCELLED>
2868C<WSAEINVALIDPROCTABLE> C<WSAEINVALIDPROVIDER> C<WSAEPROVIDERFAILEDINIT>
2869C<WSAEREFUSED>
2870
2871=back
2872