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