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