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