This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
POSIX.pod: Clarify strtod() text
[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>>.  Prior to Perl 5.28, or when operating in
1831 a non thread-safe environment, it should not be used in a threaded
1832 application unless it's certain that the underlying locale is C
1833 or POSIX.  This is because it otherwise changes the locale, which
1834 globally affects all threads simultaneously.
1835
1836 To parse a string C<$str> as a floating point number use
1837
1838     $! = 0;
1839     ($num, $n_unparsed) = POSIX::strtod($str);
1840
1841 The second returned item and C<$!> can be used to check for valid input:
1842
1843     if (($str eq '') || ($n_unparsed != 0) || $!) {
1844         die "Non-numeric input $str" . ($! ? ": $!\n" : "\n");
1845     }
1846
1847 When called in a scalar context C<strtod> returns the parsed number.
1848
1849 =item C<strtok>
1850
1851 Not implemented.  C<strtok()> is C-specific, use regular expressions instead, see
1852 L<perlre>, or L<perlfunc/split>.
1853
1854 =item C<strtol>
1855
1856 String to (long) integer translation.  Returns the parsed number and
1857 the number of characters in the unparsed portion of the string.  Truly
1858 POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation
1859 error, so clear C<$!> before calling C<strtol>.  However, non-POSIX systems
1860 may not check for overflow, and therefore will never set C<$!>.
1861
1862 C<strtol> should respect any POSIX I<setlocale()> settings.
1863
1864 To parse a string C<$str> as a number in some base C<$base> use
1865
1866     $! = 0;
1867     ($num, $n_unparsed) = POSIX::strtol($str, $base);
1868
1869 The base should be zero or between 2 and 36, inclusive.  When the base
1870 is zero or omitted C<strtol> will use the string itself to determine the
1871 base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
1872 octal; any other leading characters mean decimal.  Thus, "1234" is
1873 parsed as a decimal number, "01234" as an octal number, and "0x1234"
1874 as a hexadecimal number.
1875
1876 The second returned item and C<$!> can be used to check for valid input:
1877
1878     if (($str eq '') || ($n_unparsed != 0) || !$!) {
1879         die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1880     }
1881
1882 When called in a scalar context C<strtol> returns the parsed number.
1883
1884 =item C<strtold>
1885
1886 Like L</strtod> but for long doubles.  Defined only if the
1887 system supports long doubles.
1888
1889 =item C<strtoul>
1890
1891 String to unsigned (long) integer translation.  C<strtoul()> is identical
1892 to C<strtol()> except that C<strtoul()> only parses unsigned integers.  See
1893 L</strtol> for details.
1894
1895 Note: Some vendors supply C<strtod()> and C<strtol()> but not C<strtoul()>.
1896 Other vendors that do supply C<strtoul()> parse "-1" as a valid value.
1897
1898 =item C<strxfrm>
1899
1900 String transformation.  Returns the transformed string.
1901
1902         $dst = POSIX::strxfrm( $src );
1903
1904 Used in conjunction with the C<strcoll()> function, see L</strcoll>.
1905
1906 Not really needed since Perl can do this transparently, see
1907 L<perllocale>.
1908
1909 Beware that in a UTF-8 locale, anything you pass to this function must
1910 be in UTF-8; and when not in a UTF-8 locale, anything passed must not be
1911 UTF-8 encoded.
1912
1913 =item C<sysconf>
1914
1915 Retrieves values of system configurable variables.
1916
1917 The following will get the machine's clock speed.
1918
1919         $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
1920
1921 Returns C<undef> on failure.
1922
1923 =item C<system>
1924
1925 This is identical to Perl's builtin C<system()> function, see
1926 L<perlfunc/system>.
1927
1928 =item C<tan>
1929
1930 This is identical to the C function C<tan()>, returning the
1931 tangent of the numerical argument.  See also L<Math::Trig>.
1932
1933 =item C<tanh>
1934
1935 This is identical to the C function C<tanh()>, returning the
1936 hyperbolic tangent of the numerical argument.   See also L<Math::Trig>.
1937
1938 =item C<tcdrain>
1939
1940 This is similar to the C function C<tcdrain()> for draining
1941 the output queue of its argument stream.
1942
1943 Returns C<undef> on failure.
1944
1945 =item C<tcflow>
1946
1947 This is similar to the C function C<tcflow()> for controlling
1948 the flow of its argument stream.
1949
1950 Returns C<undef> on failure.
1951
1952 =item C<tcflush>
1953
1954 This is similar to the C function C<tcflush()> for flushing
1955 the I/O buffers of its argument stream.
1956
1957 Returns C<undef> on failure.
1958
1959 =item C<tcgetpgrp>
1960
1961 This is identical to the C function C<tcgetpgrp()> for returning the
1962 process group identifier of the foreground process group of the controlling
1963 terminal.
1964
1965 =item C<tcsendbreak>
1966
1967 This is similar to the C function C<tcsendbreak()> for sending
1968 a break on its argument stream.
1969
1970 Returns C<undef> on failure.
1971
1972 =item C<tcsetpgrp>
1973
1974 This is similar to the C function C<tcsetpgrp()> for setting the
1975 process group identifier of the foreground process group of the controlling
1976 terminal.
1977
1978 Returns C<undef> on failure.
1979
1980 =item C<tgamma>
1981
1982 The Gamma function [C99].
1983
1984 See also L</lgamma>.
1985
1986 =item C<time>
1987
1988 This is identical to Perl's builtin C<time()> function
1989 for returning the number of seconds since the epoch
1990 (whatever it is for the system), see L<perlfunc/time>.
1991
1992 =item C<times>
1993
1994 The C<times()> function returns elapsed realtime since some point in the past
1995 (such as system startup), user and system times for this process, and user
1996 and system times used by child processes.  All times are returned in clock
1997 ticks.
1998
1999     ($realtime, $user, $system, $cuser, $csystem)
2000         = POSIX::times();
2001
2002 Note: Perl's builtin C<times()> function returns four values, measured in
2003 seconds.
2004
2005 =item C<tmpfile>
2006
2007 Not implemented.  Use method C<IO::File::new_tmpfile()> instead, or see L<File::Temp>.
2008
2009 =item C<tmpnam>
2010
2011 For security reasons, which are probably detailed in your system's
2012 documentation for the C library C<tmpnam()> function, this interface
2013 is no longer available; instead use L<File::Temp>.
2014
2015 =item C<tolower>
2016
2017 This is identical to the C function, except that it can apply to a single
2018 character or to a whole string, and currently operates as if the locale
2019 always is "C".  Consider using the C<lc()> function, see L<perlfunc/lc>,
2020 see L<perlfunc/lc>, or the equivalent C<\L> operator inside doublequotish
2021 strings.
2022
2023 =item C<toupper>
2024
2025 This is similar to the C function, except that it can apply to a single
2026 character or to a whole string, and currently operates as if the locale
2027 always is "C".  Consider using the C<uc()> function, see L<perlfunc/uc>,
2028 or the equivalent C<\U> operator inside doublequotish strings.
2029
2030 =item C<trunc>
2031
2032 Returns the integer toward zero from the argument [C99].
2033
2034 See also L</ceil>, L</floor>, and L</round>.
2035
2036 =item C<ttyname>
2037
2038 This is identical to the C function C<ttyname()> for returning the
2039 name of the current terminal.
2040
2041 =item C<tzname>
2042
2043 Retrieves the time conversion information from the C<tzname> variable.
2044
2045         POSIX::tzset();
2046         ($std, $dst) = POSIX::tzname();
2047
2048 =item C<tzset>
2049
2050 This is identical to the C function C<tzset()> for setting
2051 the current timezone based on the environment variable C<TZ>,
2052 to be used by C<ctime()>, C<localtime()>, C<mktime()>, and C<strftime()>
2053 functions.
2054
2055 =item C<umask>
2056
2057 This is identical to Perl's builtin C<umask()> function
2058 for setting (and querying) the file creation permission mask,
2059 see L<perlfunc/umask>.
2060
2061 =item C<uname>
2062
2063 Get name of current operating system.
2064
2065         ($sysname, $nodename, $release, $version, $machine)
2066                 = POSIX::uname();
2067
2068 Note that the actual meanings of the various fields are not
2069 that well standardized, do not expect any great portability.
2070 The C<$sysname> might be the name of the operating system,
2071 the C<$nodename> might be the name of the host, the C<$release>
2072 might be the (major) release number of the operating system,
2073 the C<$version> might be the (minor) release number of the
2074 operating system, and the C<$machine> might be a hardware identifier.
2075 Maybe.
2076
2077 =item C<ungetc>
2078
2079 Not implemented.  Use method C<IO::Handle::ungetc()> instead.
2080
2081 =item C<unlink>
2082
2083 This is identical to Perl's builtin C<unlink()> function
2084 for removing files, see L<perlfunc/unlink>.
2085
2086 =item C<utime>
2087
2088 This is identical to Perl's builtin C<utime()> function
2089 for changing the time stamps of files and directories,
2090 see L<perlfunc/utime>.
2091
2092 =item C<vfprintf>
2093
2094 Not implemented.  C<vfprintf()> is C-specific, see L<perlfunc/printf> instead.
2095
2096 =item C<vprintf>
2097
2098 Not implemented.  C<vprintf()> is C-specific, see L<perlfunc/printf> instead.
2099
2100 =item C<vsprintf>
2101
2102 Not implemented.  C<vsprintf()> is C-specific, see L<perlfunc/sprintf> instead.
2103
2104 =item C<wait>
2105
2106 This is identical to Perl's builtin C<wait()> function,
2107 see L<perlfunc/wait>.
2108
2109 =item C<waitpid>
2110
2111 Wait for a child process to change state.  This is identical to Perl's
2112 builtin C<waitpid()> function, see L<perlfunc/waitpid>.
2113
2114         $pid = POSIX::waitpid( -1, POSIX::WNOHANG );
2115         print "status = ", ($? / 256), "\n";
2116
2117 =item C<wcstombs>
2118
2119 This is identical to the C function C<wcstombs()>.
2120
2121 See L</mblen>.
2122
2123 =item C<wctomb>
2124
2125 This is identical to the C function C<wctomb()>.
2126
2127 See L</mblen>.
2128
2129 =item C<write>
2130
2131 Write to a file.  This uses file descriptors such as those obtained by
2132 calling C<POSIX::open>.
2133
2134         $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
2135         $buf = "hello";
2136         $bytes = POSIX::write( $fd, $buf, 5 );
2137
2138 Returns C<undef> on failure.
2139
2140 See also L<perlfunc/syswrite>.
2141
2142 =back
2143
2144 =head1 CLASSES
2145
2146 =head2 C<POSIX::SigAction>
2147
2148 =over 8
2149
2150 =item C<new>
2151
2152 Creates a new C<POSIX::SigAction> object which corresponds to the C
2153 C<struct sigaction>.  This object will be destroyed automatically when
2154 it is no longer needed.  The first parameter is the handler, a sub
2155 reference.  The second parameter is a C<POSIX::SigSet> object, it
2156 defaults to the empty set.  The third parameter contains the
2157 C<sa_flags>, it defaults to 0.
2158
2159         $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
2160         $sigaction = POSIX::SigAction->new(
2161                         \&handler, $sigset, &POSIX::SA_NOCLDSTOP
2162                      );
2163
2164 This C<POSIX::SigAction> object is intended for use with the C<POSIX::sigaction()>
2165 function.
2166
2167 =back
2168
2169 =over 8
2170
2171 =item C<handler>
2172
2173 =item C<mask>
2174
2175 =item C<flags>
2176
2177 accessor functions to get/set the values of a SigAction object.
2178
2179         $sigset = $sigaction->mask;
2180         $sigaction->flags(&POSIX::SA_RESTART);
2181
2182 =item C<safe>
2183
2184 accessor function for the "safe signals" flag of a SigAction object; see
2185 L<perlipc> for general information on safe (a.k.a. "deferred") signals.  If
2186 you wish to handle a signal safely, use this accessor to set the "safe" flag
2187 in the C<POSIX::SigAction> object:
2188
2189         $sigaction->safe(1);
2190
2191 You may also examine the "safe" flag on the output action object which is
2192 filled in when given as the third parameter to C<POSIX::sigaction()>:
2193
2194         sigaction(SIGINT, $new_action, $old_action);
2195         if ($old_action->safe) {
2196             # previous SIGINT handler used safe signals
2197         }
2198
2199 =back
2200
2201 =head2 C<POSIX::SigRt>
2202
2203 =over 8
2204
2205 =item C<%SIGRT>
2206
2207 A hash of the POSIX realtime signal handlers.  It is an extension of
2208 the standard C<%SIG>, the C<$POSIX::SIGRT{SIGRTMIN}> is roughly equivalent
2209 to C<$SIG{SIGRTMIN}>, but the right POSIX moves (see below) are made with
2210 the C<POSIX::SigSet> and C<POSIX::sigaction> instead of accessing the C<%SIG>.
2211
2212 You can set the C<%POSIX::SIGRT> elements to set the POSIX realtime
2213 signal handlers, use C<delete> and C<exists> on the elements, and use
2214 C<scalar> on the C<%POSIX::SIGRT> to find out how many POSIX realtime
2215 signals there are available S<C<(SIGRTMAX - SIGRTMIN + 1>>, the C<SIGRTMAX> is
2216 a valid POSIX realtime signal).
2217
2218 Setting the C<%SIGRT> elements is equivalent to calling this:
2219
2220   sub new {
2221     my ($rtsig, $handler, $flags) = @_;
2222     my $sigset = POSIX::SigSet($rtsig);
2223     my $sigact = POSIX::SigAction->new($handler,$sigset,$flags);
2224     sigaction($rtsig, $sigact);
2225   }
2226
2227 The flags default to zero, if you want something different you can
2228 either use C<local> on C<$POSIX::SigRt::SIGACTION_FLAGS>, or you can
2229 derive from POSIX::SigRt and define your own C<new()> (the tied hash
2230 STORE method of the C<%SIGRT> calls C<new($rtsig, $handler, $SIGACTION_FLAGS)>,
2231 where the C<$rtsig> ranges from zero to S<C<SIGRTMAX - SIGRTMIN + 1)>>.
2232
2233 Just as with any signal, you can use C<sigaction($rtsig, undef, $oa)> to
2234 retrieve the installed signal handler (or, rather, the signal action).
2235
2236 B<NOTE:> whether POSIX realtime signals really work in your system, or
2237 whether Perl has been compiled so that it works with them, is outside
2238 of this discussion.
2239
2240 =item C<SIGRTMIN>
2241
2242 Return the minimum POSIX realtime signal number available, or C<undef>
2243 if no POSIX realtime signals are available.
2244
2245 =item C<SIGRTMAX>
2246
2247 Return the maximum POSIX realtime signal number available, or C<undef>
2248 if no POSIX realtime signals are available.
2249
2250 =back
2251
2252 =head2 C<POSIX::SigSet>
2253
2254 =over 8
2255
2256 =item C<new>
2257
2258 Create a new SigSet object.  This object will be destroyed automatically
2259 when it is no longer needed.  Arguments may be supplied to initialize the
2260 set.
2261
2262 Create an empty set.
2263
2264         $sigset = POSIX::SigSet->new;
2265
2266 Create a set with C<SIGUSR1>.
2267
2268         $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
2269
2270 =item C<addset>
2271
2272 Add a signal to a SigSet object.
2273
2274         $sigset->addset( &POSIX::SIGUSR2 );
2275
2276 Returns C<undef> on failure.
2277
2278 =item C<delset>
2279
2280 Remove a signal from the SigSet object.
2281
2282         $sigset->delset( &POSIX::SIGUSR2 );
2283
2284 Returns C<undef> on failure.
2285
2286 =item C<emptyset>
2287
2288 Initialize the SigSet object to be empty.
2289
2290         $sigset->emptyset();
2291
2292 Returns C<undef> on failure.
2293
2294 =item C<fillset>
2295
2296 Initialize the SigSet object to include all signals.
2297
2298         $sigset->fillset();
2299
2300 Returns C<undef> on failure.
2301
2302 =item C<ismember>
2303
2304 Tests the SigSet object to see if it contains a specific signal.
2305
2306         if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
2307                 print "contains SIGUSR1\n";
2308         }
2309
2310 =back
2311
2312 =head2 C<POSIX::Termios>
2313
2314 =over 8
2315
2316 =item C<new>
2317
2318 Create a new Termios object.  This object will be destroyed automatically
2319 when it is no longer needed.  A Termios object corresponds to the C<termios>
2320 C struct.  C<new()> mallocs a new one, C<getattr()> fills it from a file descriptor,
2321 and C<setattr()> sets a file descriptor's parameters to match Termios' contents.
2322
2323         $termios = POSIX::Termios->new;
2324
2325 =item C<getattr>
2326
2327 Get terminal control attributes.
2328
2329 Obtain the attributes for C<stdin>.
2330
2331         $termios->getattr( 0 ) # Recommended for clarity.
2332         $termios->getattr()
2333
2334 Obtain the attributes for stdout.
2335
2336         $termios->getattr( 1 )
2337
2338 Returns C<undef> on failure.
2339
2340 =item C<getcc>
2341
2342 Retrieve a value from the C<c_cc> field of a C<termios> object.  The C<c_cc> field is
2343 an array so an index must be specified.
2344
2345         $c_cc[1] = $termios->getcc(1);
2346
2347 =item C<getcflag>
2348
2349 Retrieve the C<c_cflag> field of a C<termios> object.
2350
2351         $c_cflag = $termios->getcflag;
2352
2353 =item C<getiflag>
2354
2355 Retrieve the C<c_iflag> field of a C<termios> object.
2356
2357         $c_iflag = $termios->getiflag;
2358
2359 =item C<getispeed>
2360
2361 Retrieve the input baud rate.
2362
2363         $ispeed = $termios->getispeed;
2364
2365 =item C<getlflag>
2366
2367 Retrieve the C<c_lflag> field of a C<termios> object.
2368
2369         $c_lflag = $termios->getlflag;
2370
2371 =item C<getoflag>
2372
2373 Retrieve the C<c_oflag> field of a C<termios> object.
2374
2375         $c_oflag = $termios->getoflag;
2376
2377 =item C<getospeed>
2378
2379 Retrieve the output baud rate.
2380
2381         $ospeed = $termios->getospeed;
2382
2383 =item C<setattr>
2384
2385 Set terminal control attributes.
2386
2387 Set attributes immediately for stdout.
2388
2389         $termios->setattr( 1, &POSIX::TCSANOW );
2390
2391 Returns C<undef> on failure.
2392
2393 =item C<setcc>
2394
2395 Set a value in the C<c_cc> field of a C<termios> object.  The C<c_cc> field is an
2396 array so an index must be specified.
2397
2398         $termios->setcc( &POSIX::VEOF, 1 );
2399
2400 =item C<setcflag>
2401
2402 Set the C<c_cflag> field of a C<termios> object.
2403
2404         $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
2405
2406 =item C<setiflag>
2407
2408 Set the C<c_iflag> field of a C<termios> object.
2409
2410         $termios->setiflag( $c_iflag | &POSIX::BRKINT );
2411
2412 =item C<setispeed>
2413
2414 Set the input baud rate.
2415
2416         $termios->setispeed( &POSIX::B9600 );
2417
2418 Returns C<undef> on failure.
2419
2420 =item C<setlflag>
2421
2422 Set the C<c_lflag> field of a C<termios> object.
2423
2424         $termios->setlflag( $c_lflag | &POSIX::ECHO );
2425
2426 =item C<setoflag>
2427
2428 Set the C<c_oflag> field of a C<termios> object.
2429
2430         $termios->setoflag( $c_oflag | &POSIX::OPOST );
2431
2432 =item C<setospeed>
2433
2434 Set the output baud rate.
2435
2436         $termios->setospeed( &POSIX::B9600 );
2437
2438 Returns C<undef> on failure.
2439
2440 =item Baud rate values
2441
2442 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>
2443
2444 =item Terminal interface values
2445
2446 C<TCSADRAIN> C<TCSANOW> C<TCOON> C<TCIOFLUSH> C<TCOFLUSH> C<TCION> C<TCIFLUSH> C<TCSAFLUSH> C<TCIOFF> C<TCOOFF>
2447
2448 =item C<c_cc> field values
2449
2450 C<VEOF> C<VEOL> C<VERASE> C<VINTR> C<VKILL> C<VQUIT> C<VSUSP> C<VSTART> C<VSTOP> C<VMIN> C<VTIME> C<NCCS>
2451
2452 =item C<c_cflag> field values
2453
2454 C<CLOCAL> C<CREAD> C<CSIZE> C<CS5> C<CS6> C<CS7> C<CS8> C<CSTOPB> C<HUPCL> C<PARENB> C<PARODD>
2455
2456 =item C<c_iflag> field values
2457
2458 C<BRKINT> C<ICRNL> C<IGNBRK> C<IGNCR> C<IGNPAR> C<INLCR> C<INPCK> C<ISTRIP> C<IXOFF> C<IXON> C<PARMRK>
2459
2460 =item C<c_lflag> field values
2461
2462 C<ECHO> C<ECHOE> C<ECHOK> C<ECHONL> C<ICANON> C<IEXTEN> C<ISIG> C<NOFLSH> C<TOSTOP>
2463
2464 =item C<c_oflag> field values
2465
2466 C<OPOST>
2467
2468 =back
2469
2470 =head1 PATHNAME CONSTANTS
2471
2472 =over 8
2473
2474 =item Constants
2475
2476 C<_PC_CHOWN_RESTRICTED> C<_PC_LINK_MAX> C<_PC_MAX_CANON> C<_PC_MAX_INPUT> C<_PC_NAME_MAX>
2477 C<_PC_NO_TRUNC> C<_PC_PATH_MAX> C<_PC_PIPE_BUF> C<_PC_VDISABLE>
2478
2479 =back
2480
2481 =head1 POSIX CONSTANTS
2482
2483 =over 8
2484
2485 =item Constants
2486
2487 C<_POSIX_ARG_MAX> C<_POSIX_CHILD_MAX> C<_POSIX_CHOWN_RESTRICTED> C<_POSIX_JOB_CONTROL>
2488 C<_POSIX_LINK_MAX> C<_POSIX_MAX_CANON> C<_POSIX_MAX_INPUT> C<_POSIX_NAME_MAX>
2489 C<_POSIX_NGROUPS_MAX> C<_POSIX_NO_TRUNC> C<_POSIX_OPEN_MAX> C<_POSIX_PATH_MAX>
2490 C<_POSIX_PIPE_BUF> C<_POSIX_SAVED_IDS> C<_POSIX_SSIZE_MAX> C<_POSIX_STREAM_MAX>
2491 C<_POSIX_TZNAME_MAX> C<_POSIX_VDISABLE> C<_POSIX_VERSION>
2492
2493 =back
2494
2495 =head1 RESOURCE CONSTANTS
2496
2497 Imported with the C<:sys_resource_h> tag.
2498
2499 =over 8
2500
2501 =item Constants
2502
2503 C<PRIO_PROCESS> C<PRIO_PGRP> C<PRIO_USER>
2504
2505 =back
2506
2507 =head1 SYSTEM CONFIGURATION
2508
2509 =over 8
2510
2511 =item Constants
2512
2513 C<_SC_ARG_MAX> C<_SC_CHILD_MAX> C<_SC_CLK_TCK> C<_SC_JOB_CONTROL> C<_SC_NGROUPS_MAX>
2514 C<_SC_OPEN_MAX> C<_SC_PAGESIZE> C<_SC_SAVED_IDS> C<_SC_STREAM_MAX> C<_SC_TZNAME_MAX>
2515 C<_SC_VERSION>
2516
2517 =back
2518
2519 =head1 ERRNO
2520
2521 =over 8
2522
2523 =item Constants
2524
2525 C<E2BIG> C<EACCES> C<EADDRINUSE> C<EADDRNOTAVAIL> C<EAFNOSUPPORT> C<EAGAIN> C<EALREADY> C<EBADF> C<EBADMSG>
2526 C<EBUSY> C<ECANCELED> C<ECHILD> C<ECONNABORTED> C<ECONNREFUSED> C<ECONNRESET> C<EDEADLK> C<EDESTADDRREQ>
2527 C<EDOM> C<EDQUOT> C<EEXIST> C<EFAULT> C<EFBIG> C<EHOSTDOWN> C<EHOSTUNREACH> C<EIDRM> C<EILSEQ> C<EINPROGRESS>
2528 C<EINTR> C<EINVAL> C<EIO> C<EISCONN> C<EISDIR> C<ELOOP> C<EMFILE> C<EMLINK> C<EMSGSIZE> C<ENAMETOOLONG>
2529 C<ENETDOWN> C<ENETRESET> C<ENETUNREACH> C<ENFILE> C<ENOBUFS> C<ENODATA> C<ENODEV> C<ENOENT> C<ENOEXEC>
2530 C<ENOLCK> C<ENOLINK> C<ENOMEM> C<ENOMSG> C<ENOPROTOOPT> C<ENOSPC> C<ENOSR> C<ENOSTR> C<ENOSYS> C<ENOTBLK>
2531 C<ENOTCONN> C<ENOTDIR> C<ENOTEMPTY> C<ENOTRECOVERABLE> C<ENOTSOCK> C<ENOTSUP> C<ENOTTY> C<ENXIO>
2532 C<EOPNOTSUPP> C<EOTHER> C<EOVERFLOW> C<EOWNERDEAD> C<EPERM> C<EPFNOSUPPORT> C<EPIPE> C<EPROCLIM> C<EPROTO>
2533 C<EPROTONOSUPPORT> C<EPROTOTYPE> C<ERANGE> C<EREMOTE> C<ERESTART> C<EROFS> C<ESHUTDOWN>
2534 C<ESOCKTNOSUPPORT> C<ESPIPE> C<ESRCH> C<ESTALE> C<ETIME> C<ETIMEDOUT> C<ETOOMANYREFS> C<ETXTBSY> C<EUSERS>
2535 C<EWOULDBLOCK> C<EXDEV>
2536
2537 =back
2538
2539 =head1 FCNTL
2540
2541 =over 8
2542
2543 =item Constants
2544
2545 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>
2546 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>
2547 C<O_RDONLY> C<O_RDWR> C<O_TRUNC> C<O_WRONLY>
2548
2549 =back
2550
2551 =head1 FLOAT
2552
2553 =over 8
2554
2555 =item Constants
2556
2557 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>
2558 C<DBL_MIN_10_EXP> C<DBL_MIN_EXP> C<FLT_DIG> C<FLT_EPSILON> C<FLT_MANT_DIG> C<FLT_MAX>
2559 C<FLT_MAX_10_EXP> C<FLT_MAX_EXP> C<FLT_MIN> C<FLT_MIN_10_EXP> C<FLT_MIN_EXP> C<FLT_RADIX>
2560 C<FLT_ROUNDS> C<LDBL_DIG> C<LDBL_EPSILON> C<LDBL_MANT_DIG> C<LDBL_MAX> C<LDBL_MAX_10_EXP>
2561 C<LDBL_MAX_EXP> C<LDBL_MIN> C<LDBL_MIN_10_EXP> C<LDBL_MIN_EXP>
2562
2563 =back
2564
2565 =head1 FLOATING-POINT ENVIRONMENT
2566
2567 =over 8
2568
2569 =item Constants
2570
2571 C<FE_DOWNWARD> C<FE_TONEAREST> C<FE_TOWARDZERO> C<FE_UPWARD>
2572 on systems that support them.
2573
2574 =back
2575
2576 =head1 LIMITS
2577
2578 =over 8
2579
2580 =item Constants
2581
2582 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>
2583 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>
2584 C<PIPE_BUF> C<SCHAR_MAX> C<SCHAR_MIN> C<SHRT_MAX> C<SHRT_MIN> C<SSIZE_MAX> C<STREAM_MAX> C<TZNAME_MAX>
2585 C<UCHAR_MAX> C<UINT_MAX> C<ULONG_MAX> C<USHRT_MAX>
2586
2587 =back
2588
2589 =head1 LOCALE
2590
2591 =over 8
2592
2593 =item Constants
2594
2595 C<LC_ALL> C<LC_COLLATE> C<LC_CTYPE> C<LC_MONETARY> C<LC_NUMERIC> C<LC_TIME> C<LC_MESSAGES>
2596 on systems that support them.
2597
2598 =back
2599
2600 =head1 MATH
2601
2602 =over 8
2603
2604 =item Constants
2605
2606 C<HUGE_VAL>
2607
2608 C<FP_ILOGB0> C<FP_ILOGBNAN> C<FP_INFINITE> C<FP_NAN> C<FP_NORMAL> C<FP_SUBNORMAL> C<FP_ZERO>
2609 C<INFINITY> C<NAN> C<Inf> C<NaN>
2610 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>
2611 C<M_PI_2> C<M_PI_4> C<M_SQRT1_2> C<M_SQRT2>
2612 on systems with C99 support.
2613
2614 =back
2615
2616 =head1 SIGNAL
2617
2618 =over 8
2619
2620 =item Constants
2621
2622 C<SA_NOCLDSTOP> C<SA_NOCLDWAIT> C<SA_NODEFER> C<SA_ONSTACK> C<SA_RESETHAND> C<SA_RESTART>
2623 C<SA_SIGINFO> C<SIGABRT> C<SIGALRM> C<SIGCHLD> C<SIGCONT> C<SIGFPE> C<SIGHUP> C<SIGILL> C<SIGINT>
2624 C<SIGKILL> C<SIGPIPE> C<SIGQUIT> C<SIGSEGV> C<SIGSTOP> C<SIGTERM> C<SIGTSTP> C<SIGTTIN> C<SIGTTOU>
2625 C<SIGUSR1> C<SIGUSR2> C<SIG_BLOCK> C<SIG_DFL> C<SIG_ERR> C<SIG_IGN> C<SIG_SETMASK>
2626 C<SIG_UNBLOCK>
2627 C<ILL_ILLOPC> C<ILL_ILLOPN> C<ILL_ILLADR> C<ILL_ILLTRP> C<ILL_PRVOPC> C<ILL_PRVREG> C<ILL_COPROC>
2628 C<ILL_BADSTK> C<FPE_INTDIV> C<FPE_INTOVF> C<FPE_FLTDIV> C<FPE_FLTOVF> C<FPE_FLTUND> C<FPE_FLTRES>
2629 C<FPE_FLTINV> C<FPE_FLTSUB> C<SEGV_MAPERR> C<SEGV_ACCERR> C<BUS_ADRALN> C<BUS_ADRERR>
2630 C<BUS_OBJERR> C<TRAP_BRKPT> C<TRAP_TRACE> C<CLD_EXITED> C<CLD_KILLED> C<CLD_DUMPED> C<CLD_TRAPPED>
2631 C<CLD_STOPPED> C<CLD_CONTINUED> C<POLL_IN> C<POLL_OUT> C<POLL_MSG> C<POLL_ERR> C<POLL_PRI>
2632 C<POLL_HUP> C<SI_USER> C<SI_QUEUE> C<SI_TIMER> C<SI_ASYNCIO> C<SI_MESGQ>
2633
2634 =back
2635
2636 =head1 STAT
2637
2638 =over 8
2639
2640 =item Constants
2641
2642 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>
2643 C<S_IWUSR> C<S_IXGRP> C<S_IXOTH> C<S_IXUSR>
2644
2645 =item Macros
2646
2647 C<S_ISBLK> C<S_ISCHR> C<S_ISDIR> C<S_ISFIFO> C<S_ISREG>
2648
2649 =back
2650
2651 =head1 STDLIB
2652
2653 =over 8
2654
2655 =item Constants
2656
2657 C<EXIT_FAILURE> C<EXIT_SUCCESS> C<MB_CUR_MAX> C<RAND_MAX>
2658
2659 =back
2660
2661 =head1 STDIO
2662
2663 =over 8
2664
2665 =item Constants
2666
2667 C<BUFSIZ> C<EOF> C<FILENAME_MAX> C<L_ctermid> C<L_cuserid> C<TMP_MAX>
2668
2669 =back
2670
2671 =head1 TIME
2672
2673 =over 8
2674
2675 =item Constants
2676
2677 C<CLK_TCK> C<CLOCKS_PER_SEC>
2678
2679 =back
2680
2681 =head1 UNISTD
2682
2683 =over 8
2684
2685 =item Constants
2686
2687 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>
2688
2689 =back
2690
2691 =head1 WAIT
2692
2693 =over 8
2694
2695 =item Constants
2696
2697 C<WNOHANG> C<WUNTRACED>
2698
2699 =over 16
2700
2701 =item C<WNOHANG>
2702
2703 Do not suspend the calling process until a child process
2704 changes state but instead return immediately.
2705
2706 =item C<WUNTRACED>
2707
2708 Catch stopped child processes.
2709
2710 =back
2711
2712 =item Macros
2713
2714 C<WIFEXITED> C<WEXITSTATUS> C<WIFSIGNALED> C<WTERMSIG> C<WIFSTOPPED> C<WSTOPSIG>
2715
2716 =over 16
2717
2718 =item C<WIFEXITED>
2719
2720 C<WIFEXITED(${^CHILD_ERROR_NATIVE})> returns true if the child process
2721 exited normally (C<exit()> or by falling off the end of C<main()>)
2722
2723 =item C<WEXITSTATUS>
2724
2725 C<WEXITSTATUS(${^CHILD_ERROR_NATIVE})> returns the normal exit status of
2726 the child process (only meaningful if C<WIFEXITED(${^CHILD_ERROR_NATIVE})>
2727 is true)
2728
2729 =item C<WIFSIGNALED>
2730
2731 C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})> returns true if the child process
2732 terminated because of a signal
2733
2734 =item C<WTERMSIG>
2735
2736 C<WTERMSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process
2737 terminated for (only meaningful if
2738 C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})>
2739 is true)
2740
2741 =item C<WIFSTOPPED>
2742
2743 C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})> returns true if the child process is
2744 currently stopped (can happen only if you specified the WUNTRACED flag
2745 to C<waitpid()>)
2746
2747 =item C<WSTOPSIG>
2748
2749 C<WSTOPSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process
2750 was stopped for (only meaningful if
2751 C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})>
2752 is true)
2753
2754 =back
2755
2756 =back
2757
2758 =head1 WINSOCK
2759
2760 (Windows only.)
2761
2762 =over 8
2763
2764 =item Constants
2765
2766 C<WSAEINTR> C<WSAEBADF> C<WSAEACCES> C<WSAEFAULT> C<WSAEINVAL> C<WSAEMFILE> C<WSAEWOULDBLOCK>
2767 C<WSAEINPROGRESS> C<WSAEALREADY> C<WSAENOTSOCK> C<WSAEDESTADDRREQ> C<WSAEMSGSIZE>
2768 C<WSAEPROTOTYPE> C<WSAENOPROTOOPT> C<WSAEPROTONOSUPPORT> C<WSAESOCKTNOSUPPORT>
2769 C<WSAEOPNOTSUPP> C<WSAEPFNOSUPPORT> C<WSAEAFNOSUPPORT> C<WSAEADDRINUSE>
2770 C<WSAEADDRNOTAVAIL> C<WSAENETDOWN> C<WSAENETUNREACH> C<WSAENETRESET> C<WSAECONNABORTED>
2771 C<WSAECONNRESET> C<WSAENOBUFS> C<WSAEISCONN> C<WSAENOTCONN> C<WSAESHUTDOWN>
2772 C<WSAETOOMANYREFS> C<WSAETIMEDOUT> C<WSAECONNREFUSED> C<WSAELOOP> C<WSAENAMETOOLONG>
2773 C<WSAEHOSTDOWN> C<WSAEHOSTUNREACH> C<WSAENOTEMPTY> C<WSAEPROCLIM> C<WSAEUSERS>
2774 C<WSAEDQUOT> C<WSAESTALE> C<WSAEREMOTE> C<WSAEDISCON> C<WSAENOMORE> C<WSAECANCELLED>
2775 C<WSAEINVALIDPROCTABLE> C<WSAEINVALIDPROVIDER> C<WSAEPROVIDERFAILEDINIT>
2776 C<WSAEREFUSED>
2777
2778 =back
2779