This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Better document setlocale, "use locale" interactions
[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 I<Everything is exported by default> with the exception of any POSIX
25 functions with the same name as a built-in Perl function, such as
26 C<abs>, C<alarm>, C<rmdir>, C<write>, etc.., which will be exported
27 only if you ask for them explicitly.  This is an unfortunate backwards
28 compatibility feature.  You can stop the exporting by saying C<use
29 POSIX ()> and then use the fully qualified names (ie. C<POSIX::SEEK_END>),
30 or by giving an explicit import list.  If you do neither, and opt for the
31 default, C<use POSIX;> has to import I<553 symbols>.
32
33 This document gives a condensed list of the features available in the POSIX
34 module.  Consult your operating system's manpages for general information on
35 most features.  Consult L<perlfunc> for functions which are noted as being
36 identical to Perl's builtin functions.
37
38 The first section describes POSIX functions from the 1003.1 specification.
39 The second section describes some classes for signal objects, TTY objects,
40 and other miscellaneous objects.  The remaining sections list various
41 constants and macros in an organization which roughly follows IEEE Std
42 1003.1b-1993.
43
44 =head1 CAVEATS
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 setjmp() call will elicit the
50 message "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 EDEADLK, or the semantics of the
55 errno values set by 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 ICANON macro after
59 all.  This could be construed to be a bug.
60
61 =head1 FUNCTIONS
62
63 =over 8
64
65 =item _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 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 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 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 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 alarm
106
107 This is identical to Perl's builtin C<alarm()> function,
108 either for arming or disarming the C<SIGARLM> timer.
109
110 =item asctime
111
112 This is identical to the C function C<asctime()>.  It returns
113 a string of the form
114
115         "Fri Jun  2 18:22:13 2000\n\0"
116
117 and it is called thusly
118
119         $asctime = asctime($sec, $min, $hour, $mday, $mon,
120                            $year, $wday, $yday, $isdst);
121
122 The C<$mon> is zero-based: January equals C<0>.  The C<$year> is
123 1900-based: 2001 equals C<101>.  C<$wday> and C<$yday> default to zero
124 (and are usually ignored anyway), and C<$isdst> defaults to -1.
125
126 =item asin
127
128 This is identical to the C function C<asin()>, returning
129 the arcus sine of its numerical argument.  See also L<Math::Trig>.
130
131 =item assert
132
133 Unimplemented, but you can use L<perlfunc/die> and the L<Carp> module
134 to achieve similar things.
135
136 =item atan
137
138 This is identical to the C function C<atan()>, returning the
139 arcus tangent of its numerical argument.  See also L<Math::Trig>.
140
141 =item atan2
142
143 This is identical to Perl's builtin C<atan2()> function, returning
144 the arcus tangent defined by its two numerical arguments, the I<y>
145 coordinate and the I<x> coordinate.  See also L<Math::Trig>.
146
147 =item atexit
148
149 atexit() is C-specific: use C<END {}> instead, see L<perlsub>.
150
151 =item atof
152
153 atof() is C-specific.  Perl converts strings to numbers transparently.
154 If you need to force a scalar to a number, add a zero to it.
155
156 =item atoi
157
158 atoi() is C-specific.  Perl converts strings to numbers transparently.
159 If you need to force a scalar to a number, add a zero to it.
160 If you need to have just the integer part, see L<perlfunc/int>.
161
162 =item atol
163
164 atol() is C-specific.  Perl converts strings to numbers transparently.
165 If you need to force a scalar to a number, add a zero to it.
166 If you need to have just the integer part, see L<perlfunc/int>.
167
168 =item bsearch
169
170 bsearch() not supplied.  For doing binary search on wordlists,
171 see L<Search::Dict>.
172
173 =item calloc
174
175 calloc() is C-specific.  Perl does memory management transparently.
176
177 =item ceil
178
179 This is identical to the C function C<ceil()>, returning the smallest
180 integer value greater than or equal to the given numerical argument.
181
182 =item chdir
183
184 This is identical to Perl's builtin C<chdir()> function, allowing
185 one to change the working (default) directory, see L<perlfunc/chdir>.
186
187 =item chmod
188
189 This is identical to Perl's builtin C<chmod()> function, allowing
190 one to change file and directory permissions, see L<perlfunc/chmod>.
191
192 =item chown
193
194 This is identical to Perl's builtin C<chown()> function, allowing one
195 to change file and directory owners and groups, see L<perlfunc/chown>.
196
197 =item clearerr
198
199 Use the method C<IO::Handle::clearerr()> instead, to reset the error
200 state (if any) and EOF state (if any) of the given stream.
201
202 =item clock
203
204 This is identical to the C function C<clock()>, returning the
205 amount of spent processor time in microseconds.
206
207 =item close
208
209 Close the file.  This uses file descriptors such as those obtained by calling
210 C<POSIX::open>.
211
212         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
213         POSIX::close( $fd );
214
215 Returns C<undef> on failure.
216
217 See also L<perlfunc/close>.
218
219 =item closedir
220
221 This is identical to Perl's builtin C<closedir()> function for closing
222 a directory handle, see L<perlfunc/closedir>.
223
224 =item cos
225
226 This is identical to Perl's builtin C<cos()> function, for returning
227 the cosine of its numerical argument, see L<perlfunc/cos>.
228 See also L<Math::Trig>.
229
230 =item cosh
231
232 This is identical to the C function C<cosh()>, for returning
233 the hyperbolic cosine of its numeric argument.  See also L<Math::Trig>.
234
235 =item creat
236
237 Create a new file.  This returns a file descriptor like the ones returned by
238 C<POSIX::open>.  Use C<POSIX::close> to close the file.
239
240         $fd = POSIX::creat( "foo", 0611 );
241         POSIX::close( $fd );
242
243 See also L<perlfunc/sysopen> and its C<O_CREAT> flag.
244
245 =item ctermid
246
247 Generates the path name for the controlling terminal.
248
249         $path = POSIX::ctermid();
250
251 =item ctime
252
253 This is identical to the C function C<ctime()> and equivalent
254 to C<asctime(localtime(...))>, see L</asctime> and L</localtime>.
255
256 =item cuserid
257
258 Get the login name of the owner of the current process.
259
260         $name = POSIX::cuserid();
261
262 =item difftime
263
264 This is identical to the C function C<difftime()>, for returning
265 the time difference (in seconds) between two times (as returned
266 by C<time()>), see L</time>.
267
268 =item div
269
270 div() is C-specific, use L<perlfunc/int> on the usual C</> division and
271 the modulus C<%>.
272
273 =item dup
274
275 This is similar to the C function C<dup()>, for duplicating a file
276 descriptor.
277
278 This uses file descriptors such as those obtained by calling
279 C<POSIX::open>.
280
281 Returns C<undef> on failure.
282
283 =item dup2
284
285 This is similar to the C function C<dup2()>, for duplicating a file
286 descriptor to an another known file descriptor.
287
288 This uses file descriptors such as those obtained by calling
289 C<POSIX::open>.
290
291 Returns C<undef> on failure.
292
293 =item errno
294
295 Returns the value of errno.
296
297         $errno = POSIX::errno();
298
299 This identical to the numerical values of the C<$!>, see L<perlvar/$ERRNO>.
300
301 =item execl
302
303 execl() is C-specific, see L<perlfunc/exec>.
304
305 =item execle
306
307 execle() is C-specific, see L<perlfunc/exec>.
308
309 =item execlp
310
311 execlp() is C-specific, see L<perlfunc/exec>.
312
313 =item execv
314
315 execv() is C-specific, see L<perlfunc/exec>.
316
317 =item execve
318
319 execve() is C-specific, see L<perlfunc/exec>.
320
321 =item execvp
322
323 execvp() is C-specific, see L<perlfunc/exec>.
324
325 =item exit
326
327 This is identical to Perl's builtin C<exit()> function for exiting the
328 program, see L<perlfunc/exit>.
329
330 =item exp
331
332 This is identical to Perl's builtin C<exp()> function for
333 returning the exponent (I<e>-based) of the numerical argument,
334 see L<perlfunc/exp>.
335
336 =item fabs
337
338 This is identical to Perl's builtin C<abs()> function for returning
339 the absolute value of the numerical argument, see L<perlfunc/abs>.
340
341 =item fclose
342
343 Use method C<IO::Handle::close()> instead, or see L<perlfunc/close>.
344
345 =item fcntl
346
347 This is identical to Perl's builtin C<fcntl()> function,
348 see L<perlfunc/fcntl>.
349
350 =item fdopen
351
352 Use method C<IO::Handle::new_from_fd()> instead, or see L<perlfunc/open>.
353
354 =item feof
355
356 Use method C<IO::Handle::eof()> instead, or see L<perlfunc/eof>.
357
358 =item ferror
359
360 Use method C<IO::Handle::error()> instead.
361
362 =item fflush
363
364 Use method C<IO::Handle::flush()> instead.
365 See also L<perlvar/$OUTPUT_AUTOFLUSH>.
366
367 =item fgetc
368
369 Use method C<IO::Handle::getc()> instead, or see L<perlfunc/read>.
370
371 =item fgetpos
372
373 Use method C<IO::Seekable::getpos()> instead, or see L<perlfunc/seek>.
374
375 =item fgets
376
377 Use method C<IO::Handle::gets()> instead.  Similar to E<lt>E<gt>, also known
378 as L<perlfunc/readline>.
379
380 =item fileno
381
382 Use method C<IO::Handle::fileno()> instead, or see L<perlfunc/fileno>.
383
384 =item floor
385
386 This is identical to the C function C<floor()>, returning the largest
387 integer value less than or equal to the numerical argument.
388
389 =item fmod
390
391 This is identical to the C function C<fmod()>.
392
393         $r = fmod($x, $y);
394
395 It returns the remainder C<$r = $x - $n*$y>, where C<$n = trunc($x/$y)>.
396 The C<$r> has the same sign as C<$x> and magnitude (absolute value)
397 less than the magnitude of C<$y>.
398
399 =item fopen
400
401 Use method C<IO::File::open()> instead, or see L<perlfunc/open>.
402
403 =item fork
404
405 This is identical to Perl's builtin C<fork()> function
406 for duplicating the current process, see L<perlfunc/fork>
407 and L<perlfork> if you are in Windows.
408
409 =item fpathconf
410
411 Retrieves the value of a configurable limit on a file or directory.  This
412 uses file descriptors such as those obtained by calling C<POSIX::open>.
413
414 The following will determine the maximum length of the longest allowable
415 pathname on the filesystem which holds F</var/foo>.
416
417         $fd = POSIX::open( "/var/foo", &POSIX::O_RDONLY );
418         $path_max = POSIX::fpathconf($fd, &POSIX::_PC_PATH_MAX);
419
420 Returns C<undef> on failure.
421
422 =item fprintf
423
424 fprintf() is C-specific, see L<perlfunc/printf> instead.
425
426 =item fputc
427
428 fputc() is C-specific, see L<perlfunc/print> instead.
429
430 =item fputs
431
432 fputs() is C-specific, see L<perlfunc/print> instead.
433
434 =item fread
435
436 fread() is C-specific, see L<perlfunc/read> instead.
437
438 =item free
439
440 free() is C-specific.  Perl does memory management transparently.
441
442 =item freopen
443
444 freopen() is C-specific, see L<perlfunc/open> instead.
445
446 =item frexp
447
448 Return the mantissa and exponent of a floating-point number.
449
450         ($mantissa, $exponent) = POSIX::frexp( 1.234e56 );
451
452 =item fscanf
453
454 fscanf() is C-specific, use E<lt>E<gt> and regular expressions instead.
455
456 =item fseek
457
458 Use method C<IO::Seekable::seek()> instead, or see L<perlfunc/seek>.
459
460 =item fsetpos
461
462 Use method C<IO::Seekable::setpos()> instead, or seek L<perlfunc/seek>.
463
464 =item fstat
465
466 Get file status.  This uses file descriptors such as those obtained by
467 calling C<POSIX::open>.  The data returned is identical to the data from
468 Perl's builtin C<stat> function.
469
470         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
471         @stats = POSIX::fstat( $fd );
472
473 =item fsync
474
475 Use method C<IO::Handle::sync()> instead.
476
477 =item ftell
478
479 Use method C<IO::Seekable::tell()> instead, or see L<perlfunc/tell>.
480
481 =item fwrite
482
483 fwrite() is C-specific, see L<perlfunc/print> instead.
484
485 =item getc
486
487 This is identical to Perl's builtin C<getc()> function,
488 see L<perlfunc/getc>.
489
490 =item getchar
491
492 Returns one character from STDIN.  Identical to Perl's C<getc()>,
493 see L<perlfunc/getc>.
494
495 =item getcwd
496
497 Returns the name of the current working directory.
498 See also L<Cwd>.
499
500 =item getegid
501
502 Returns the effective group identifier.  Similar to Perl' s builtin
503 variable C<$(>, see L<perlvar/$EGID>.
504
505 =item getenv
506
507 Returns the value of the specified environment variable.
508 The same information is available through the C<%ENV> array.
509
510 =item geteuid
511
512 Returns the effective user identifier.  Identical to Perl's builtin C<$E<gt>>
513 variable, see L<perlvar/$EUID>.
514
515 =item getgid
516
517 Returns the user's real group identifier.  Similar to Perl's builtin
518 variable C<$)>, see L<perlvar/$GID>.
519
520 =item getgrgid
521
522 This is identical to Perl's builtin C<getgrgid()> function for
523 returning group entries by group identifiers, see
524 L<perlfunc/getgrgid>.
525
526 =item getgrnam
527
528 This is identical to Perl's builtin C<getgrnam()> function for
529 returning group entries by group names, see L<perlfunc/getgrnam>.
530
531 =item getgroups
532
533 Returns the ids of the user's supplementary groups.  Similar to Perl's
534 builtin variable C<$)>, see L<perlvar/$GID>.
535
536 =item getlogin
537
538 This is identical to Perl's builtin C<getlogin()> function for
539 returning the user name associated with the current session, see
540 L<perlfunc/getlogin>.
541
542 =item getpgrp
543
544 This is identical to Perl's builtin C<getpgrp()> function for
545 returning the process group identifier of the current process, see
546 L<perlfunc/getpgrp>.
547
548 =item getpid
549
550 Returns the process identifier.  Identical to Perl's builtin
551 variable C<$$>, see L<perlvar/$PID>.
552
553 =item getppid
554
555 This is identical to Perl's builtin C<getppid()> function for
556 returning the process identifier of the parent process of the current
557 process , see L<perlfunc/getppid>.
558
559 =item getpwnam
560
561 This is identical to Perl's builtin C<getpwnam()> function for
562 returning user entries by user names, see L<perlfunc/getpwnam>.
563
564 =item getpwuid
565
566 This is identical to Perl's builtin C<getpwuid()> function for
567 returning user entries by user identifiers, see L<perlfunc/getpwuid>.
568
569 =item gets
570
571 Returns one line from C<STDIN>, similar to E<lt>E<gt>, also known
572 as the C<readline()> function, see L<perlfunc/readline>.
573
574 B<NOTE>: if you have C programs that still use C<gets()>, be very
575 afraid.  The C<gets()> function is a source of endless grief because
576 it has no buffer overrun checks.  It should B<never> be used.  The
577 C<fgets()> function should be preferred instead.
578
579 =item getuid
580
581 Returns the user's identifier.  Identical to Perl's builtin C<$E<lt>> variable,
582 see L<perlvar/$UID>.
583
584 =item gmtime
585
586 This is identical to Perl's builtin C<gmtime()> function for
587 converting seconds since the epoch to a date in Greenwich Mean Time,
588 see L<perlfunc/gmtime>.
589
590 =item isalnum
591
592 This is identical to the C function, except that it can apply to a
593 single character or to a whole string.  Note that locale settings may
594 affect what characters are considered C<isalnum>.  Does not work on
595 Unicode characters code point 256 or higher.  Consider using regular
596 expressions and the C</[[:alnum:]]/> construct instead, or possibly
597 the C</\w/> construct.
598
599 =item isalpha
600
601 This is identical to the C function, except that it can apply to
602 a single character or to a whole string.  Note that locale settings
603 may affect what characters are considered C<isalpha>.  Does not work
604 on Unicode characters code point 256 or higher.  Consider using regular
605 expressions and the C</[[:alpha:]]/> construct instead.
606
607 =item isatty
608
609 Returns a boolean indicating whether the specified filehandle is connected
610 to a tty.  Similar to the C<-t> operator, see L<perlfunc/-X>.
611
612 =item iscntrl
613
614 This is identical to the C function, except that it can apply to
615 a single character or to a whole string.  Note that locale settings
616 may affect what characters are considered C<iscntrl>.  Does not work
617 on Unicode characters code point 256 or higher.  Consider using regular
618 expressions and the C</[[:cntrl:]]/> construct instead.
619
620 =item isdigit
621
622 This is identical to the C function, except that it can apply to
623 a single character or to a whole string.  Note that locale settings
624 may affect what characters are considered C<isdigit> (unlikely, but
625 still possible). Does not work on Unicode characters code point 256
626 or higher.  Consider using regular expressions and the C</[[:digit:]]/>
627 construct instead, or the C</\d/> construct.
628
629 =item isgraph
630
631 This is identical to the C function, except that it can apply to
632 a single character or to a whole string.  Note that locale settings
633 may affect what characters are considered C<isgraph>.  Does not work
634 on Unicode characters code point 256 or higher.  Consider using regular
635 expressions and the C</[[:graph:]]/> construct instead.
636
637 =item islower
638
639 This is identical to the C function, except that it can apply to
640 a single character or to a whole string.  Note that locale settings
641 may affect what characters are considered C<islower>.  Does not work
642 on Unicode characters code point 256 or higher.  Consider using regular
643 expressions and the C</[[:lower:]]/> construct instead.  Do B<not> use
644 C</[a-z]/>.
645
646 =item isprint
647
648 This is identical to the C function, except that it can apply to
649 a single character or to a whole string.  Note that locale settings
650 may affect what characters are considered C<isprint>.  Does not work
651 on Unicode characters code point 256 or higher.  Consider using regular
652 expressions and the C</[[:print:]]/> construct instead.
653
654 =item ispunct
655
656 This is identical to the C function, except that it can apply to
657 a single character or to a whole string.  Note that locale settings
658 may affect what characters are considered C<ispunct>.  Does not work
659 on Unicode characters code point 256 or higher.  Consider using regular
660 expressions and the C</[[:punct:]]/> construct instead.
661
662 =item isspace
663
664 This is identical to the C function, except that it can apply to
665 a single character or to a whole string.  Note that locale settings
666 may affect what characters are considered C<isspace>.  Does not work
667 on Unicode characters code point 256 or higher.  Consider using regular
668 expressions and the C</[[:space:]]/> construct instead, or the C</\s/>
669 construct.  (Note that C</\s/> and C</[[:space:]]/> are slightly
670 different in that C</[[:space:]]/> can normally match a vertical tab,
671 while C</\s/> does not.)
672
673 =item isupper
674
675 This is identical to the C function, except that it can apply to
676 a single character or to a whole string.  Note that locale settings
677 may affect what characters are considered C<isupper>.  Does not work
678 on Unicode characters code point 256 or higher.  Consider using regular
679 expressions and the C</[[:upper:]]/> construct instead.  Do B<not> use
680 C</[A-Z]/>.
681
682 =item isxdigit
683
684 This is identical to the C function, except that it can apply to a single
685 character or to a whole string.  Note that locale settings may affect what
686 characters are considered C<isxdigit> (unlikely, but still possible).
687 Does not work on Unicode characters code point 256 or higher.
688 Consider using regular expressions and the C</[[:xdigit:]]/>
689 construct instead, or simply C</[0-9a-f]/i>.
690
691 =item kill
692
693 This is identical to Perl's builtin C<kill()> function for sending
694 signals to processes (often to terminate them), see L<perlfunc/kill>.
695
696 =item labs
697
698 (For returning absolute values of long integers.)
699 labs() is C-specific, see L<perlfunc/abs> instead.
700
701 =item lchown
702
703 This is identical to the C function, except the order of arguments is
704 consistent with Perl's builtin C<chown()> with the added restriction
705 of only one path, not an list of paths.  Does the same thing as the 
706 C<chown()> function but changes the owner of a symbolic link instead 
707 of the file the symbolic link points to.
708
709 =item ldexp
710
711 This is identical to the C function C<ldexp()>
712 for multiplying floating point numbers with powers of two.
713
714         $x_quadrupled = POSIX::ldexp($x, 2);
715
716 =item ldiv
717
718 (For computing dividends of long integers.)
719 ldiv() is C-specific, use C</> and C<int()> instead.
720
721 =item link
722
723 This is identical to Perl's builtin C<link()> function
724 for creating hard links into files, see L<perlfunc/link>.
725
726 =item localeconv
727
728 Get numeric formatting information.  Returns a reference to a hash
729 containing the current locale formatting values.
730 Users of this function should also read L<perllocale>, where there is a
731 discussion devoted to this function
732 (L<perllocale/The localeconv function>).
733
734 Here is how to query the database for the B<de> (Deutsch or German) locale.
735
736         my $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" );
737         print "Locale: \"$loc\"\n";
738         my $lconv = POSIX::localeconv();
739         foreach my $property (qw(
740                 decimal_point
741                 thousands_sep
742                 grouping
743                 int_curr_symbol
744                 currency_symbol
745                 mon_decimal_point
746                 mon_thousands_sep
747                 mon_grouping
748                 positive_sign
749                 negative_sign
750                 int_frac_digits
751                 frac_digits
752                 p_cs_precedes
753                 p_sep_by_space
754                 n_cs_precedes
755                 n_sep_by_space
756                 p_sign_posn
757                 n_sign_posn
758         ))
759         {
760                 printf qq(%s: "%s",\n),
761                         $property, $lconv->{$property};
762         }
763
764 =item localtime
765
766 This is identical to Perl's builtin C<localtime()> function for
767 converting seconds since the epoch to a date see L<perlfunc/localtime>.
768
769 =item log
770
771 This is identical to Perl's builtin C<log()> function,
772 returning the natural (I<e>-based) logarithm of the numerical argument,
773 see L<perlfunc/log>.
774
775 =item log10
776
777 This is identical to the C function C<log10()>,
778 returning the 10-base logarithm of the numerical argument.
779 You can also use
780
781     sub log10 { log($_[0]) / log(10) }
782
783 or
784
785     sub log10 { log($_[0]) / 2.30258509299405 }
786
787 or
788
789     sub log10 { log($_[0]) * 0.434294481903252 }
790
791 =item longjmp
792
793 longjmp() is C-specific: use L<perlfunc/die> instead.
794
795 =item lseek
796
797 Move the file's read/write position.  This uses file descriptors such as
798 those obtained by calling C<POSIX::open>.
799
800         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
801         $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET );
802
803 Returns C<undef> on failure.
804
805 =item malloc
806
807 malloc() is C-specific.  Perl does memory management transparently.
808
809 =item mblen
810
811 This is identical to the C function C<mblen()>.
812 Perl does not have any support for the wide and multibyte
813 characters of the C standards, so this might be a rather
814 useless function.
815
816 =item mbstowcs
817
818 This is identical to the C function C<mbstowcs()>.
819 Perl does not have any support for the wide and multibyte
820 characters of the C standards, so this might be a rather
821 useless function.
822
823 =item mbtowc
824
825 This is identical to the C function C<mbtowc()>.
826 Perl does not have any support for the wide and multibyte
827 characters of the C standards, so this might be a rather
828 useless function.
829
830 =item memchr
831
832 memchr() is C-specific, see L<perlfunc/index> instead.
833
834 =item memcmp
835
836 memcmp() is C-specific, use C<eq> instead, see L<perlop>.
837
838 =item memcpy
839
840 memcpy() is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
841
842 =item memmove
843
844 memmove() is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
845
846 =item memset
847
848 memset() is C-specific, use C<x> instead, see L<perlop>.
849
850 =item mkdir
851
852 This is identical to Perl's builtin C<mkdir()> function
853 for creating directories, see L<perlfunc/mkdir>.
854
855 =item mkfifo
856
857 This is similar to the C function C<mkfifo()> for creating
858 FIFO special files.
859
860         if (mkfifo($path, $mode)) { ....
861
862 Returns C<undef> on failure.  The C<$mode> is similar to the
863 mode of C<mkdir()>, see L<perlfunc/mkdir>, though for C<mkfifo>
864 you B<must> specify the C<$mode>.
865
866 =item mktime
867
868 Convert date/time info to a calendar time.
869
870 Synopsis:
871
872         mktime(sec, min, hour, mday, mon, year, wday = 0,
873                yday = 0, isdst = -1)
874
875 The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
876 I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
877 year (C<year>) is given in years since 1900.  I.e. The year 1995 is 95; the
878 year 2001 is 101.  Consult your system's C<mktime()> manpage for details
879 about these and the other arguments.
880
881 Calendar time for December 12, 1995, at 10:30 am.
882
883         $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 );
884         print "Date = ", POSIX::ctime($time_t);
885
886 Returns C<undef> on failure.
887
888 =item modf
889
890 Return the integral and fractional parts of a floating-point number.
891
892         ($fractional, $integral) = POSIX::modf( 3.14 );
893
894 =item nice
895
896 This is similar to the C function C<nice()>, for changing
897 the scheduling preference of the current process.  Positive
898 arguments mean more polite process, negative values more
899 needy process.  Normal user processes can only be more polite.
900
901 Returns C<undef> on failure.
902
903 =item offsetof
904
905 offsetof() is C-specific, you probably want to see L<perlfunc/pack> instead.
906
907 =item open
908
909 Open a file for reading for writing.  This returns file descriptors, not
910 Perl filehandles.  Use C<POSIX::close> to close the file.
911
912 Open a file read-only with mode 0666.
913
914         $fd = POSIX::open( "foo" );
915
916 Open a file for read and write.
917
918         $fd = POSIX::open( "foo", &POSIX::O_RDWR );
919
920 Open a file for write, with truncation.
921
922         $fd = POSIX::open(
923                 "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC
924         );
925
926 Create a new file with mode 0640.  Set up the file for writing.
927
928         $fd = POSIX::open(
929                 "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640
930         );
931
932 Returns C<undef> on failure.
933
934 See also L<perlfunc/sysopen>.
935
936 =item opendir
937
938 Open a directory for reading.
939
940         $dir = POSIX::opendir( "/var" );
941         @files = POSIX::readdir( $dir );
942         POSIX::closedir( $dir );
943
944 Returns C<undef> on failure.
945
946 =item pathconf
947
948 Retrieves the value of a configurable limit on a file or directory.
949
950 The following will determine the maximum length of the longest allowable
951 pathname on the filesystem which holds C</var>.
952
953         $path_max = POSIX::pathconf( "/var",
954                                       &POSIX::_PC_PATH_MAX );
955
956 Returns C<undef> on failure.
957
958 =item pause
959
960 This is similar to the C function C<pause()>, which suspends
961 the execution of the current process until a signal is received.
962
963 Returns C<undef> on failure.
964
965 =item perror
966
967 This is identical to the C function C<perror()>, which outputs to the
968 standard error stream the specified message followed by ": " and the
969 current error string.  Use the C<warn()> function and the C<$!>
970 variable instead, see L<perlfunc/warn> and L<perlvar/$ERRNO>.
971
972 =item pipe
973
974 Create an interprocess channel.  This returns file descriptors like those
975 returned by C<POSIX::open>.
976
977         my ($read, $write) = POSIX::pipe();
978         POSIX::write( $write, "hello", 5 );
979         POSIX::read( $read, $buf, 5 );
980
981 See also L<perlfunc/pipe>.
982
983 =item pow
984
985 Computes C<$x> raised to the power C<$exponent>.
986
987         $ret = POSIX::pow( $x, $exponent );
988
989 You can also use the C<**> operator, see L<perlop>.
990
991 =item printf
992
993 Formats and prints the specified arguments to STDOUT.
994 See also L<perlfunc/printf>.
995
996 =item putc
997
998 putc() is C-specific, see L<perlfunc/print> instead.
999
1000 =item putchar
1001
1002 putchar() is C-specific, see L<perlfunc/print> instead.
1003
1004 =item puts
1005
1006 puts() is C-specific, see L<perlfunc/print> instead.
1007
1008 =item qsort
1009
1010 qsort() is C-specific, see L<perlfunc/sort> instead.
1011
1012 =item raise
1013
1014 Sends the specified signal to the current process.
1015 See also L<perlfunc/kill> and the C<$$> in L<perlvar/$PID>.
1016
1017 =item rand
1018
1019 C<rand()> is non-portable, see L<perlfunc/rand> instead.
1020
1021 =item read
1022
1023 Read from a file.  This uses file descriptors such as those obtained by
1024 calling C<POSIX::open>.  If the buffer C<$buf> is not large enough for the
1025 read then Perl will extend it to make room for the request.
1026
1027         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
1028         $bytes = POSIX::read( $fd, $buf, 3 );
1029
1030 Returns C<undef> on failure.
1031
1032 See also L<perlfunc/sysread>.
1033
1034 =item readdir
1035
1036 This is identical to Perl's builtin C<readdir()> function
1037 for reading directory entries, see L<perlfunc/readdir>.
1038
1039 =item realloc
1040
1041 realloc() is C-specific.  Perl does memory management transparently.
1042
1043 =item remove
1044
1045 This is identical to Perl's builtin C<unlink()> function
1046 for removing files, see L<perlfunc/unlink>.
1047
1048 =item rename
1049
1050 This is identical to Perl's builtin C<rename()> function
1051 for renaming files, see L<perlfunc/rename>.
1052
1053 =item rewind
1054
1055 Seeks to the beginning of the file.
1056
1057 =item rewinddir
1058
1059 This is identical to Perl's builtin C<rewinddir()> function for
1060 rewinding directory entry streams, see L<perlfunc/rewinddir>.
1061
1062 =item rmdir
1063
1064 This is identical to Perl's builtin C<rmdir()> function
1065 for removing (empty) directories, see L<perlfunc/rmdir>.
1066
1067 =item scanf
1068
1069 scanf() is C-specific, use E<lt>E<gt> and regular expressions instead,
1070 see L<perlre>.
1071
1072 =item setgid
1073
1074 Sets the real group identifier and the effective group identifier for
1075 this process.  Similar to assigning a value to the Perl's builtin
1076 C<$)> variable, see L<perlvar/$EGID>, except that the latter
1077 will change only the real user identifier, and that the setgid()
1078 uses only a single numeric argument, as opposed to a space-separated
1079 list of numbers.
1080
1081 =item setjmp
1082
1083 C<setjmp()> is C-specific: use C<eval {}> instead,
1084 see L<perlfunc/eval>.
1085
1086 =item setlocale
1087
1088 Modifies and queries the program's underlying locale.  Users of this
1089 function should also read L<perllocale>, where there is a discussion
1090 devoted to this function (L<perllocale/The setlocale function>).
1091 Note that Perl itself is almost entirely unaffected by the locale
1092 except within the scope of S<C<"use locale">>.  (Exceptions are listed
1093 in L<perllocale/Not within the scope of any use locale variant>.)
1094
1095 The following examples assume
1096
1097         use POSIX qw(setlocale LC_ALL LC_CTYPE);
1098
1099 has been issued.
1100
1101 The following will set the traditional UNIX system locale behavior
1102 (the second argument C<"C">).
1103
1104         $loc = setlocale( LC_ALL, "C" );
1105
1106 The following will query the current LC_CTYPE category.  (No second
1107 argument means 'query'.)
1108
1109         $loc = setlocale( LC_CTYPE );
1110
1111 The following will set the LC_CTYPE behaviour according to the locale
1112 environment variables (the second argument C<"">).
1113 Please see your systems C<setlocale(3)> documentation for the locale
1114 environment variables' meaning or consult L<perllocale>.
1115
1116         $loc = setlocale( LC_CTYPE, "" );
1117
1118 The following will set the LC_COLLATE behaviour to Argentinian
1119 Spanish. B<NOTE>: The naming and availability of locales depends on
1120 your operating system. Please consult L<perllocale> for how to find
1121 out which locales are available in your system.
1122
1123         $loc = setlocale( LC_COLLATE, "es_AR.ISO8859-1" );
1124
1125 =item setpgid
1126
1127 This is similar to the C function C<setpgid()> for
1128 setting the process group identifier of the current process.
1129
1130 Returns C<undef> on failure.
1131
1132 =item setsid
1133
1134 This is identical to the C function C<setsid()> for
1135 setting the session identifier of the current process.
1136
1137 =item setuid
1138
1139 Sets the real user identifier and the effective user identifier for
1140 this process.  Similar to assigning a value to the Perl's builtin
1141 C<$E<lt>> variable, see L<perlvar/$UID>, except that the latter
1142 will change only the real user identifier.
1143
1144 =item sigaction
1145
1146 Detailed signal management.  This uses C<POSIX::SigAction> objects for
1147 the C<action> and C<oldaction> arguments (the oldaction can also be
1148 just a hash reference).  Consult your system's C<sigaction> manpage
1149 for details, see also C<POSIX::SigRt>.
1150
1151 Synopsis:
1152
1153         sigaction(signal, action, oldaction = 0)
1154
1155 Returns C<undef> on failure.  The C<signal> must be a number (like
1156 SIGHUP), not a string (like "SIGHUP"), though Perl does try hard
1157 to understand you.
1158
1159 If you use the SA_SIGINFO flag, the signal handler will in addition to
1160 the first argument, the signal name, also receive a second argument, a
1161 hash reference, inside which are the following keys with the following
1162 semantics, as defined by POSIX/SUSv3:
1163
1164     signo       the signal number
1165     errno       the error number
1166     code        if this is zero or less, the signal was sent by
1167                 a user process and the uid and pid make sense,
1168                 otherwise the signal was sent by the kernel
1169
1170 The following are also defined by POSIX/SUSv3, but unfortunately
1171 not very widely implemented:
1172
1173     pid         the process id generating the signal
1174     uid         the uid of the process id generating the signal
1175     status      exit value or signal for SIGCHLD
1176     band        band event for SIGPOLL
1177
1178 A third argument is also passed to the handler, which contains a copy
1179 of the raw binary contents of the siginfo structure: if a system has
1180 some non-POSIX fields, this third argument is where to unpack() them
1181 from.
1182
1183 Note that not all siginfo values make sense simultaneously (some are
1184 valid only for certain signals, for example), and not all values make
1185 sense from Perl perspective, you should to consult your system's
1186 C<sigaction> and possibly also C<siginfo> documentation.
1187
1188 =item siglongjmp
1189
1190 siglongjmp() is C-specific: use L<perlfunc/die> instead.
1191
1192 =item sigpending
1193
1194 Examine signals that are blocked and pending.  This uses C<POSIX::SigSet>
1195 objects for the C<sigset> argument.  Consult your system's C<sigpending>
1196 manpage for details.
1197
1198 Synopsis:
1199
1200         sigpending(sigset)
1201
1202 Returns C<undef> on failure.
1203
1204 =item sigprocmask
1205
1206 Change and/or examine calling process's signal mask.  This uses
1207 C<POSIX::SigSet> objects for the C<sigset> and C<oldsigset> arguments.
1208 Consult your system's C<sigprocmask> manpage for details.
1209
1210 Synopsis:
1211
1212         sigprocmask(how, sigset, oldsigset = 0)
1213
1214 Returns C<undef> on failure.
1215
1216 Note that you can't reliably block or unblock a signal from its own signal
1217 handler if you're using safe signals. Other signals can be blocked or unblocked
1218 reliably.
1219
1220 =item sigsetjmp
1221
1222 C<sigsetjmp()> is C-specific: use C<eval {}> instead,
1223 see L<perlfunc/eval>.
1224
1225 =item sigsuspend
1226
1227 Install a signal mask and suspend process until signal arrives.  This uses
1228 C<POSIX::SigSet> objects for the C<signal_mask> argument.  Consult your
1229 system's C<sigsuspend> manpage for details.
1230
1231 Synopsis:
1232
1233         sigsuspend(signal_mask)
1234
1235 Returns C<undef> on failure.
1236
1237 =item sin
1238
1239 This is identical to Perl's builtin C<sin()> function
1240 for returning the sine of the numerical argument,
1241 see L<perlfunc/sin>.  See also L<Math::Trig>.
1242
1243 =item sinh
1244
1245 This is identical to the C function C<sinh()>
1246 for returning the hyperbolic sine of the numerical argument.
1247 See also L<Math::Trig>.
1248
1249 =item sleep
1250
1251 This is functionally identical to Perl's builtin C<sleep()> function
1252 for suspending the execution of the current for process for certain
1253 number of seconds, see L<perlfunc/sleep>.  There is one significant
1254 difference, however: C<POSIX::sleep()> returns the number of
1255 B<unslept> seconds, while the C<CORE::sleep()> returns the
1256 number of slept seconds.
1257
1258 =item sprintf
1259
1260 This is similar to Perl's builtin C<sprintf()> function
1261 for returning a string that has the arguments formatted as requested,
1262 see L<perlfunc/sprintf>.
1263
1264 =item sqrt
1265
1266 This is identical to Perl's builtin C<sqrt()> function.
1267 for returning the square root of the numerical argument,
1268 see L<perlfunc/sqrt>.
1269
1270 =item srand
1271
1272 Give a seed the pseudorandom number generator, see L<perlfunc/srand>.
1273
1274 =item sscanf
1275
1276 sscanf() is C-specific, use regular expressions instead,
1277 see L<perlre>.
1278
1279 =item stat
1280
1281 This is identical to Perl's builtin C<stat()> function
1282 for returning information about files and directories.
1283
1284 =item strcat
1285
1286 strcat() is C-specific, use C<.=> instead, see L<perlop>.
1287
1288 =item strchr
1289
1290 strchr() is C-specific, see L<perlfunc/index> instead.
1291
1292 =item strcmp
1293
1294 strcmp() is C-specific, use C<eq> or C<cmp> instead, see L<perlop>.
1295
1296 =item strcoll
1297
1298 This is identical to the C function C<strcoll()>
1299 for collating (comparing) strings transformed using
1300 the C<strxfrm()> function.  Not really needed since
1301 Perl can do this transparently, see L<perllocale>.
1302
1303 =item strcpy
1304
1305 strcpy() is C-specific, use C<=> instead, see L<perlop>.
1306
1307 =item strcspn
1308
1309 strcspn() is C-specific, use regular expressions instead,
1310 see L<perlre>.
1311
1312 =item strerror
1313
1314 Returns the error string for the specified errno.
1315 Identical to the string form of the C<$!>, see L<perlvar/$ERRNO>.
1316
1317 =item strftime
1318
1319 Convert date and time information to string.  Returns the string.
1320
1321 Synopsis:
1322
1323         strftime(fmt, sec, min, hour, mday, mon, year,
1324                  wday = -1, yday = -1, isdst = -1)
1325
1326 The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
1327 I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
1328 year (C<year>) is given in years since 1900.  I.e., the year 1995 is 95; the
1329 year 2001 is 101.  Consult your system's C<strftime()> manpage for details
1330 about these and the other arguments.
1331
1332 If you want your code to be portable, your format (C<fmt>) argument
1333 should use only the conversion specifiers defined by the ANSI C
1334 standard (C89, to play safe).  These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
1335 But even then, the B<results> of some of the conversion specifiers are
1336 non-portable.  For example, the specifiers C<aAbBcpZ> change according
1337 to the locale settings of the user, and both how to set locales (the
1338 locale names) and what output to expect are non-standard.
1339 The specifier C<c> changes according to the timezone settings of the
1340 user and the timezone computation rules of the operating system.
1341 The C<Z> specifier is notoriously unportable since the names of
1342 timezones are non-standard. Sticking to the numeric specifiers is the
1343 safest route.
1344
1345 The given arguments are made consistent as though by calling
1346 C<mktime()> before calling your system's C<strftime()> function,
1347 except that the C<isdst> value is not affected.
1348
1349 The string for Tuesday, December 12, 1995.
1350
1351         $str = POSIX::strftime( "%A, %B %d, %Y",
1352                                  0, 0, 0, 12, 11, 95, 2 );
1353         print "$str\n";
1354
1355 =item strlen
1356
1357 strlen() is C-specific, use C<length()> instead, see L<perlfunc/length>.
1358
1359 =item strncat
1360
1361 strncat() is C-specific, use C<.=> instead, see L<perlop>.
1362
1363 =item strncmp
1364
1365 strncmp() is C-specific, use C<eq> instead, see L<perlop>.
1366
1367 =item strncpy
1368
1369 strncpy() is C-specific, use C<=> instead, see L<perlop>.
1370
1371 =item strpbrk
1372
1373 strpbrk() is C-specific, use regular expressions instead,
1374 see L<perlre>.
1375
1376 =item strrchr
1377
1378 strrchr() is C-specific, see L<perlfunc/rindex> instead.
1379
1380 =item strspn
1381
1382 strspn() is C-specific, use regular expressions instead,
1383 see L<perlre>.
1384
1385 =item strstr
1386
1387 This is identical to Perl's builtin C<index()> function,
1388 see L<perlfunc/index>.
1389
1390 =item strtod
1391
1392 String to double translation. Returns the parsed number and the number
1393 of characters in the unparsed portion of the string.  Truly
1394 POSIX-compliant systems set $! ($ERRNO) to indicate a translation
1395 error, so clear $! before calling strtod.  However, non-POSIX systems
1396 may not check for overflow, and therefore will never set $!.
1397
1398 strtod should respect any POSIX I<setlocale()> settings.
1399
1400 To parse a string $str as a floating point number use
1401
1402     $! = 0;
1403     ($num, $n_unparsed) = POSIX::strtod($str);
1404
1405 The second returned item and $! can be used to check for valid input:
1406
1407     if (($str eq '') || ($n_unparsed != 0) || $!) {
1408         die "Non-numeric input $str" . ($! ? ": $!\n" : "\n");
1409     }
1410
1411 When called in a scalar context strtod returns the parsed number.
1412
1413 =item strtok
1414
1415 strtok() is C-specific, use regular expressions instead, see
1416 L<perlre>, or L<perlfunc/split>.
1417
1418 =item strtol
1419
1420 String to (long) integer translation.  Returns the parsed number and
1421 the number of characters in the unparsed portion of the string.  Truly
1422 POSIX-compliant systems set $! ($ERRNO) to indicate a translation
1423 error, so clear $! before calling strtol.  However, non-POSIX systems
1424 may not check for overflow, and therefore will never set $!.
1425
1426 strtol should respect any POSIX I<setlocale()> settings.
1427
1428 To parse a string $str as a number in some base $base use
1429
1430     $! = 0;
1431     ($num, $n_unparsed) = POSIX::strtol($str, $base);
1432
1433 The base should be zero or between 2 and 36, inclusive.  When the base
1434 is zero or omitted strtol will use the string itself to determine the
1435 base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
1436 octal; any other leading characters mean decimal.  Thus, "1234" is
1437 parsed as a decimal number, "01234" as an octal number, and "0x1234"
1438 as a hexadecimal number.
1439
1440 The second returned item and $! can be used to check for valid input:
1441
1442     if (($str eq '') || ($n_unparsed != 0) || !$!) {
1443         die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1444     }
1445
1446 When called in a scalar context strtol returns the parsed number.
1447
1448 =item strtoul
1449
1450 String to unsigned (long) integer translation.  strtoul() is identical
1451 to strtol() except that strtoul() only parses unsigned integers.  See
1452 L</strtol> for details.
1453
1454 Note: Some vendors supply strtod() and strtol() but not strtoul().
1455 Other vendors that do supply strtoul() parse "-1" as a valid value.
1456
1457 =item strxfrm
1458
1459 String transformation.  Returns the transformed string.
1460
1461         $dst = POSIX::strxfrm( $src );
1462
1463 Used in conjunction with the C<strcoll()> function, see L</strcoll>.
1464
1465 Not really needed since Perl can do this transparently, see
1466 L<perllocale>.
1467
1468 =item sysconf
1469
1470 Retrieves values of system configurable variables.
1471
1472 The following will get the machine's clock speed.
1473
1474         $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
1475
1476 Returns C<undef> on failure.
1477
1478 =item system
1479
1480 This is identical to Perl's builtin C<system()> function, see
1481 L<perlfunc/system>.
1482
1483 =item tan
1484
1485 This is identical to the C function C<tan()>, returning the
1486 tangent of the numerical argument.  See also L<Math::Trig>.
1487
1488 =item tanh
1489
1490 This is identical to the C function C<tanh()>, returning the
1491 hyperbolic tangent of the numerical argument.   See also L<Math::Trig>.
1492
1493 =item tcdrain
1494
1495 This is similar to the C function C<tcdrain()> for draining
1496 the output queue of its argument stream.
1497
1498 Returns C<undef> on failure.
1499
1500 =item tcflow
1501
1502 This is similar to the C function C<tcflow()> for controlling
1503 the flow of its argument stream.
1504
1505 Returns C<undef> on failure.
1506
1507 =item tcflush
1508
1509 This is similar to the C function C<tcflush()> for flushing
1510 the I/O buffers of its argument stream.
1511
1512 Returns C<undef> on failure.
1513
1514 =item tcgetpgrp
1515
1516 This is identical to the C function C<tcgetpgrp()> for returning the
1517 process group identifier of the foreground process group of the controlling
1518 terminal.
1519
1520 =item tcsendbreak
1521
1522 This is similar to the C function C<tcsendbreak()> for sending
1523 a break on its argument stream.
1524
1525 Returns C<undef> on failure.
1526
1527 =item tcsetpgrp
1528
1529 This is similar to the C function C<tcsetpgrp()> for setting the
1530 process group identifier of the foreground process group of the controlling
1531 terminal.
1532
1533 Returns C<undef> on failure.
1534
1535 =item time
1536
1537 This is identical to Perl's builtin C<time()> function
1538 for returning the number of seconds since the epoch
1539 (whatever it is for the system), see L<perlfunc/time>.
1540
1541 =item times
1542
1543 The times() function returns elapsed realtime since some point in the past
1544 (such as system startup), user and system times for this process, and user
1545 and system times used by child processes.  All times are returned in clock
1546 ticks.
1547
1548     ($realtime, $user, $system, $cuser, $csystem) 
1549         = POSIX::times();
1550
1551 Note: Perl's builtin C<times()> function returns four values, measured in
1552 seconds.
1553
1554 =item tmpfile
1555
1556 Use method C<IO::File::new_tmpfile()> instead, or see L<File::Temp>.
1557
1558 =item tmpnam
1559
1560 Returns a name for a temporary file.
1561
1562         $tmpfile = POSIX::tmpnam();
1563
1564 For security reasons, which are probably detailed in your system's
1565 documentation for the C library tmpnam() function, this interface
1566 should not be used; instead see L<File::Temp>.
1567
1568 =item tolower
1569
1570 This is identical to the C function, except that it can apply to a single
1571 character or to a whole string.  Consider using the C<lc()> function,
1572 see L<perlfunc/lc>, or the equivalent C<\L> operator inside doublequotish
1573 strings.
1574
1575 =item toupper
1576
1577 This is identical to the C function, except that it can apply to a single
1578 character or to a whole string.  Consider using the C<uc()> function,
1579 see L<perlfunc/uc>, or the equivalent C<\U> operator inside doublequotish
1580 strings.
1581
1582 =item ttyname
1583
1584 This is identical to the C function C<ttyname()> for returning the
1585 name of the current terminal.
1586
1587 =item tzname
1588
1589 Retrieves the time conversion information from the C<tzname> variable.
1590
1591         POSIX::tzset();
1592         ($std, $dst) = POSIX::tzname();
1593
1594 =item tzset
1595
1596 This is identical to the C function C<tzset()> for setting
1597 the current timezone based on the environment variable C<TZ>,
1598 to be used by C<ctime()>, C<localtime()>, C<mktime()>, and C<strftime()>
1599 functions.
1600
1601 =item umask
1602
1603 This is identical to Perl's builtin C<umask()> function
1604 for setting (and querying) the file creation permission mask,
1605 see L<perlfunc/umask>.
1606
1607 =item uname
1608
1609 Get name of current operating system.
1610
1611         ($sysname, $nodename, $release, $version, $machine)
1612                 = POSIX::uname();
1613
1614 Note that the actual meanings of the various fields are not
1615 that well standardized, do not expect any great portability.
1616 The C<$sysname> might be the name of the operating system,
1617 the C<$nodename> might be the name of the host, the C<$release>
1618 might be the (major) release number of the operating system,
1619 the C<$version> might be the (minor) release number of the
1620 operating system, and the C<$machine> might be a hardware identifier.
1621 Maybe.
1622
1623 =item ungetc
1624
1625 Use method C<IO::Handle::ungetc()> instead.
1626
1627 =item unlink
1628
1629 This is identical to Perl's builtin C<unlink()> function
1630 for removing files, see L<perlfunc/unlink>.
1631
1632 =item utime
1633
1634 This is identical to Perl's builtin C<utime()> function
1635 for changing the time stamps of files and directories,
1636 see L<perlfunc/utime>.
1637
1638 =item vfprintf
1639
1640 vfprintf() is C-specific, see L<perlfunc/printf> instead.
1641
1642 =item vprintf
1643
1644 vprintf() is C-specific, see L<perlfunc/printf> instead.
1645
1646 =item vsprintf
1647
1648 vsprintf() is C-specific, see L<perlfunc/sprintf> instead.
1649
1650 =item wait
1651
1652 This is identical to Perl's builtin C<wait()> function,
1653 see L<perlfunc/wait>.
1654
1655 =item waitpid
1656
1657 Wait for a child process to change state.  This is identical to Perl's
1658 builtin C<waitpid()> function, see L<perlfunc/waitpid>.
1659
1660         $pid = POSIX::waitpid( -1, POSIX::WNOHANG );
1661         print "status = ", ($? / 256), "\n";
1662
1663 =item wcstombs
1664
1665 This is identical to the C function C<wcstombs()>.
1666 Perl does not have any support for the wide and multibyte
1667 characters of the C standards, so this might be a rather
1668 useless function.
1669
1670 =item wctomb
1671
1672 This is identical to the C function C<wctomb()>.
1673 Perl does not have any support for the wide and multibyte
1674 characters of the C standards, so this might be a rather
1675 useless function.
1676
1677 =item write
1678
1679 Write to a file.  This uses file descriptors such as those obtained by
1680 calling C<POSIX::open>.
1681
1682         $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
1683         $buf = "hello";
1684         $bytes = POSIX::write( $fd, $buf, 5 );
1685
1686 Returns C<undef> on failure.
1687
1688 See also L<perlfunc/syswrite>.
1689
1690 =back
1691
1692 =head1 CLASSES
1693
1694 =head2 POSIX::SigAction
1695
1696 =over 8
1697
1698 =item new
1699
1700 Creates a new C<POSIX::SigAction> object which corresponds to the C
1701 C<struct sigaction>.  This object will be destroyed automatically when
1702 it is no longer needed.  The first parameter is the handler, a sub
1703 reference.  The second parameter is a C<POSIX::SigSet> object, it
1704 defaults to the empty set.  The third parameter contains the
1705 C<sa_flags>, it defaults to 0.
1706
1707         $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
1708         $sigaction = POSIX::SigAction->new(
1709                         \&handler, $sigset, &POSIX::SA_NOCLDSTOP
1710                      );
1711
1712 This C<POSIX::SigAction> object is intended for use with the C<POSIX::sigaction()>
1713 function.
1714
1715 =back
1716
1717 =over 8
1718
1719 =item handler
1720
1721 =item mask
1722
1723 =item flags
1724
1725 accessor functions to get/set the values of a SigAction object.
1726
1727         $sigset = $sigaction->mask;
1728         $sigaction->flags(&POSIX::SA_RESTART);
1729
1730 =item safe
1731
1732 accessor function for the "safe signals" flag of a SigAction object; see
1733 L<perlipc> for general information on safe (a.k.a. "deferred") signals.  If
1734 you wish to handle a signal safely, use this accessor to set the "safe" flag
1735 in the C<POSIX::SigAction> object:
1736
1737         $sigaction->safe(1);
1738
1739 You may also examine the "safe" flag on the output action object which is
1740 filled in when given as the third parameter to C<POSIX::sigaction()>:
1741
1742         sigaction(SIGINT, $new_action, $old_action);
1743         if ($old_action->safe) {
1744             # previous SIGINT handler used safe signals
1745         }
1746
1747 =back
1748
1749 =head2 POSIX::SigRt
1750
1751 =over 8
1752
1753 =item %SIGRT
1754
1755 A hash of the POSIX realtime signal handlers.  It is an extension of
1756 the standard %SIG, the $POSIX::SIGRT{SIGRTMIN} is roughly equivalent
1757 to $SIG{SIGRTMIN}, but the right POSIX moves (see below) are made with
1758 the POSIX::SigSet and POSIX::sigaction instead of accessing the %SIG.
1759
1760 You can set the %POSIX::SIGRT elements to set the POSIX realtime
1761 signal handlers, use C<delete> and C<exists> on the elements, and use
1762 C<scalar> on the C<%POSIX::SIGRT> to find out how many POSIX realtime
1763 signals there are available (SIGRTMAX - SIGRTMIN + 1, the SIGRTMAX is
1764 a valid POSIX realtime signal).
1765
1766 Setting the %SIGRT elements is equivalent to calling this:
1767
1768   sub new {
1769     my ($rtsig, $handler, $flags) = @_;
1770     my $sigset = POSIX::SigSet($rtsig);
1771     my $sigact = POSIX::SigAction->new($handler,$sigset,$flags);
1772     sigaction($rtsig, $sigact);
1773   }
1774
1775 The flags default to zero, if you want something different you can
1776 either use C<local> on $POSIX::SigRt::SIGACTION_FLAGS, or you can
1777 derive from POSIX::SigRt and define your own C<new()> (the tied hash
1778 STORE method of the %SIGRT calls C<new($rtsig, $handler, $SIGACTION_FLAGS)>,
1779 where the $rtsig ranges from zero to SIGRTMAX - SIGRTMIN + 1).
1780
1781 Just as with any signal, you can use sigaction($rtsig, undef, $oa) to
1782 retrieve the installed signal handler (or, rather, the signal action).
1783
1784 B<NOTE:> whether POSIX realtime signals really work in your system, or
1785 whether Perl has been compiled so that it works with them, is outside
1786 of this discussion.
1787
1788 =item SIGRTMIN
1789
1790 Return the minimum POSIX realtime signal number available, or C<undef>
1791 if no POSIX realtime signals are available.
1792
1793 =item SIGRTMAX
1794
1795 Return the maximum POSIX realtime signal number available, or C<undef>
1796 if no POSIX realtime signals are available.
1797
1798 =back
1799
1800 =head2 POSIX::SigSet
1801
1802 =over 8
1803
1804 =item new
1805
1806 Create a new SigSet object.  This object will be destroyed automatically
1807 when it is no longer needed.  Arguments may be supplied to initialize the
1808 set.
1809
1810 Create an empty set.
1811
1812         $sigset = POSIX::SigSet->new;
1813
1814 Create a set with SIGUSR1.
1815
1816         $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
1817
1818 =item addset
1819
1820 Add a signal to a SigSet object.
1821
1822         $sigset->addset( &POSIX::SIGUSR2 );
1823
1824 Returns C<undef> on failure.
1825
1826 =item delset
1827
1828 Remove a signal from the SigSet object.
1829
1830         $sigset->delset( &POSIX::SIGUSR2 );
1831
1832 Returns C<undef> on failure.
1833
1834 =item emptyset
1835
1836 Initialize the SigSet object to be empty.
1837
1838         $sigset->emptyset();
1839
1840 Returns C<undef> on failure.
1841
1842 =item fillset
1843
1844 Initialize the SigSet object to include all signals.
1845
1846         $sigset->fillset();
1847
1848 Returns C<undef> on failure.
1849
1850 =item ismember
1851
1852 Tests the SigSet object to see if it contains a specific signal.
1853
1854         if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
1855                 print "contains SIGUSR1\n";
1856         }
1857
1858 =back
1859
1860 =head2 POSIX::Termios
1861
1862 =over 8
1863
1864 =item new
1865
1866 Create a new Termios object.  This object will be destroyed automatically
1867 when it is no longer needed.  A Termios object corresponds to the termios
1868 C struct.  new() mallocs a new one, getattr() fills it from a file descriptor,
1869 and setattr() sets a file descriptor's parameters to match Termios' contents.
1870
1871         $termios = POSIX::Termios->new;
1872
1873 =item getattr
1874
1875 Get terminal control attributes.
1876
1877 Obtain the attributes for stdin.
1878
1879         $termios->getattr( 0 ) # Recommended for clarity.
1880         $termios->getattr()
1881
1882 Obtain the attributes for stdout.
1883
1884         $termios->getattr( 1 )
1885
1886 Returns C<undef> on failure.
1887
1888 =item getcc
1889
1890 Retrieve a value from the c_cc field of a termios object.  The c_cc field is
1891 an array so an index must be specified.
1892
1893         $c_cc[1] = $termios->getcc(1);
1894
1895 =item getcflag
1896
1897 Retrieve the c_cflag field of a termios object.
1898
1899         $c_cflag = $termios->getcflag;
1900
1901 =item getiflag
1902
1903 Retrieve the c_iflag field of a termios object.
1904
1905         $c_iflag = $termios->getiflag;
1906
1907 =item getispeed
1908
1909 Retrieve the input baud rate.
1910
1911         $ispeed = $termios->getispeed;
1912
1913 =item getlflag
1914
1915 Retrieve the c_lflag field of a termios object.
1916
1917         $c_lflag = $termios->getlflag;
1918
1919 =item getoflag
1920
1921 Retrieve the c_oflag field of a termios object.
1922
1923         $c_oflag = $termios->getoflag;
1924
1925 =item getospeed
1926
1927 Retrieve the output baud rate.
1928
1929         $ospeed = $termios->getospeed;
1930
1931 =item setattr
1932
1933 Set terminal control attributes.
1934
1935 Set attributes immediately for stdout.
1936
1937         $termios->setattr( 1, &POSIX::TCSANOW );
1938
1939 Returns C<undef> on failure.
1940
1941 =item setcc
1942
1943 Set a value in the c_cc field of a termios object.  The c_cc field is an
1944 array so an index must be specified.
1945
1946         $termios->setcc( &POSIX::VEOF, 1 );
1947
1948 =item setcflag
1949
1950 Set the c_cflag field of a termios object.
1951
1952         $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
1953
1954 =item setiflag
1955
1956 Set the c_iflag field of a termios object.
1957
1958         $termios->setiflag( $c_iflag | &POSIX::BRKINT );
1959
1960 =item setispeed
1961
1962 Set the input baud rate.
1963
1964         $termios->setispeed( &POSIX::B9600 );
1965
1966 Returns C<undef> on failure.
1967
1968 =item setlflag
1969
1970 Set the c_lflag field of a termios object.
1971
1972         $termios->setlflag( $c_lflag | &POSIX::ECHO );
1973
1974 =item setoflag
1975
1976 Set the c_oflag field of a termios object.
1977
1978         $termios->setoflag( $c_oflag | &POSIX::OPOST );
1979
1980 =item setospeed
1981
1982 Set the output baud rate.
1983
1984         $termios->setospeed( &POSIX::B9600 );
1985
1986 Returns C<undef> on failure.
1987
1988 =item Baud rate values
1989
1990 B38400 B75 B200 B134 B300 B1800 B150 B0 B19200 B1200 B9600 B600 B4800 B50 B2400 B110
1991
1992 =item Terminal interface values
1993
1994 TCSADRAIN TCSANOW TCOON TCIOFLUSH TCOFLUSH TCION TCIFLUSH TCSAFLUSH TCIOFF TCOOFF
1995
1996 =item c_cc field values
1997
1998 VEOF VEOL VERASE VINTR VKILL VQUIT VSUSP VSTART VSTOP VMIN VTIME NCCS
1999
2000 =item c_cflag field values
2001
2002 CLOCAL CREAD CSIZE CS5 CS6 CS7 CS8 CSTOPB HUPCL PARENB PARODD
2003
2004 =item c_iflag field values
2005
2006 BRKINT ICRNL IGNBRK IGNCR IGNPAR INLCR INPCK ISTRIP IXOFF IXON PARMRK
2007
2008 =item c_lflag field values
2009
2010 ECHO ECHOE ECHOK ECHONL ICANON IEXTEN ISIG NOFLSH TOSTOP
2011
2012 =item c_oflag field values
2013
2014 OPOST
2015
2016 =back
2017
2018 =head1 PATHNAME CONSTANTS
2019
2020 =over 8
2021
2022 =item Constants
2023
2024 _PC_CHOWN_RESTRICTED _PC_LINK_MAX _PC_MAX_CANON _PC_MAX_INPUT _PC_NAME_MAX
2025 _PC_NO_TRUNC _PC_PATH_MAX _PC_PIPE_BUF _PC_VDISABLE
2026
2027 =back
2028
2029 =head1 POSIX CONSTANTS
2030
2031 =over 8
2032
2033 =item Constants
2034
2035 _POSIX_ARG_MAX _POSIX_CHILD_MAX _POSIX_CHOWN_RESTRICTED _POSIX_JOB_CONTROL
2036 _POSIX_LINK_MAX _POSIX_MAX_CANON _POSIX_MAX_INPUT _POSIX_NAME_MAX
2037 _POSIX_NGROUPS_MAX _POSIX_NO_TRUNC _POSIX_OPEN_MAX _POSIX_PATH_MAX
2038 _POSIX_PIPE_BUF _POSIX_SAVED_IDS _POSIX_SSIZE_MAX _POSIX_STREAM_MAX
2039 _POSIX_TZNAME_MAX _POSIX_VDISABLE _POSIX_VERSION
2040
2041 =back
2042
2043 =head1 SYSTEM CONFIGURATION
2044
2045 =over 8
2046
2047 =item Constants
2048
2049 _SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_JOB_CONTROL _SC_NGROUPS_MAX
2050 _SC_OPEN_MAX _SC_PAGESIZE _SC_SAVED_IDS _SC_STREAM_MAX _SC_TZNAME_MAX
2051 _SC_VERSION
2052
2053 =back
2054
2055 =head1 ERRNO
2056
2057 =over 8
2058
2059 =item Constants
2060
2061 E2BIG EACCES EADDRINUSE EADDRNOTAVAIL EAFNOSUPPORT EAGAIN EALREADY EBADF
2062 EBUSY ECHILD ECONNABORTED ECONNREFUSED ECONNRESET EDEADLK EDESTADDRREQ
2063 EDOM EDQUOT EEXIST EFAULT EFBIG EHOSTDOWN EHOSTUNREACH EINPROGRESS EINTR
2064 EINVAL EIO EISCONN EISDIR ELOOP EMFILE EMLINK EMSGSIZE ENAMETOOLONG
2065 ENETDOWN ENETRESET ENETUNREACH ENFILE ENOBUFS ENODEV ENOENT ENOEXEC
2066 ENOLCK ENOMEM ENOPROTOOPT ENOSPC ENOSYS ENOTBLK ENOTCONN ENOTDIR
2067 ENOTEMPTY ENOTSOCK ENOTTY ENXIO EOPNOTSUPP EPERM EPFNOSUPPORT EPIPE
2068 EPROCLIM EPROTONOSUPPORT EPROTOTYPE ERANGE EREMOTE ERESTART EROFS
2069 ESHUTDOWN ESOCKTNOSUPPORT ESPIPE ESRCH ESTALE ETIMEDOUT ETOOMANYREFS
2070 ETXTBSY EUSERS EWOULDBLOCK EXDEV
2071
2072 =back
2073
2074 =head1 FCNTL
2075
2076 =over 8
2077
2078 =item Constants
2079
2080 FD_CLOEXEC F_DUPFD F_GETFD F_GETFL F_GETLK F_OK F_RDLCK F_SETFD F_SETFL F_SETLK
2081 F_SETLKW F_UNLCK F_WRLCK O_ACCMODE O_APPEND O_CREAT O_EXCL O_NOCTTY O_NONBLOCK
2082 O_RDONLY O_RDWR O_TRUNC O_WRONLY
2083
2084 =back
2085
2086 =head1 FLOAT
2087
2088 =over 8
2089
2090 =item Constants
2091
2092 DBL_DIG DBL_EPSILON DBL_MANT_DIG DBL_MAX DBL_MAX_10_EXP DBL_MAX_EXP DBL_MIN
2093 DBL_MIN_10_EXP DBL_MIN_EXP FLT_DIG FLT_EPSILON FLT_MANT_DIG FLT_MAX
2094 FLT_MAX_10_EXP FLT_MAX_EXP FLT_MIN FLT_MIN_10_EXP FLT_MIN_EXP FLT_RADIX
2095 FLT_ROUNDS LDBL_DIG LDBL_EPSILON LDBL_MANT_DIG LDBL_MAX LDBL_MAX_10_EXP
2096 LDBL_MAX_EXP LDBL_MIN LDBL_MIN_10_EXP LDBL_MIN_EXP
2097
2098 =back
2099
2100 =head1 LIMITS
2101
2102 =over 8
2103
2104 =item Constants
2105
2106 ARG_MAX CHAR_BIT CHAR_MAX CHAR_MIN CHILD_MAX INT_MAX INT_MIN LINK_MAX LONG_MAX
2107 LONG_MIN MAX_CANON MAX_INPUT MB_LEN_MAX NAME_MAX NGROUPS_MAX OPEN_MAX PATH_MAX
2108 PIPE_BUF SCHAR_MAX SCHAR_MIN SHRT_MAX SHRT_MIN SSIZE_MAX STREAM_MAX TZNAME_MAX
2109 UCHAR_MAX UINT_MAX ULONG_MAX USHRT_MAX
2110
2111 =back
2112
2113 =head1 LOCALE
2114
2115 =over 8
2116
2117 =item Constants
2118
2119 LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME
2120
2121 =back
2122
2123 =head1 MATH
2124
2125 =over 8
2126
2127 =item Constants
2128
2129 HUGE_VAL
2130
2131 =back
2132
2133 =head1 SIGNAL
2134
2135 =over 8
2136
2137 =item Constants
2138
2139 SA_NOCLDSTOP SA_NOCLDWAIT SA_NODEFER SA_ONSTACK SA_RESETHAND SA_RESTART
2140 SA_SIGINFO SIGABRT SIGALRM SIGCHLD SIGCONT SIGFPE SIGHUP SIGILL SIGINT
2141 SIGKILL SIGPIPE SIGQUIT SIGSEGV SIGSTOP SIGTERM SIGTSTP SIGTTIN SIGTTOU
2142 SIGUSR1 SIGUSR2 SIG_BLOCK SIG_DFL SIG_ERR SIG_IGN SIG_SETMASK
2143 SIG_UNBLOCK
2144
2145 =back
2146
2147 =head1 STAT
2148
2149 =over 8
2150
2151 =item Constants
2152
2153 S_IRGRP S_IROTH S_IRUSR S_IRWXG S_IRWXO S_IRWXU S_ISGID S_ISUID S_IWGRP S_IWOTH
2154 S_IWUSR S_IXGRP S_IXOTH S_IXUSR
2155
2156 =item Macros
2157
2158 S_ISBLK S_ISCHR S_ISDIR S_ISFIFO S_ISREG
2159
2160 =back
2161
2162 =head1 STDLIB
2163
2164 =over 8
2165
2166 =item Constants
2167
2168 EXIT_FAILURE EXIT_SUCCESS MB_CUR_MAX RAND_MAX
2169
2170 =back
2171
2172 =head1 STDIO
2173
2174 =over 8
2175
2176 =item Constants
2177
2178 BUFSIZ EOF FILENAME_MAX L_ctermid L_cuserid L_tmpname TMP_MAX
2179
2180 =back
2181
2182 =head1 TIME
2183
2184 =over 8
2185
2186 =item Constants
2187
2188 CLK_TCK CLOCKS_PER_SEC
2189
2190 =back
2191
2192 =head1 UNISTD
2193
2194 =over 8
2195
2196 =item Constants
2197
2198 R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STDERR_FILENO W_OK X_OK
2199
2200 =back
2201
2202 =head1 WAIT
2203
2204 =over 8
2205
2206 =item Constants
2207
2208 WNOHANG WUNTRACED
2209
2210 =over 16
2211
2212 =item WNOHANG
2213
2214 Do not suspend the calling process until a child process
2215 changes state but instead return immediately.
2216
2217 =item WUNTRACED
2218
2219 Catch stopped child processes.
2220
2221 =back
2222
2223 =item Macros
2224
2225 WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG WIFSTOPPED WSTOPSIG
2226
2227 =over 16
2228
2229 =item WIFEXITED
2230
2231 WIFEXITED(${^CHILD_ERROR_NATIVE}) returns true if the child process
2232 exited normally (C<exit()> or by falling off the end of C<main()>)
2233
2234 =item WEXITSTATUS
2235
2236 WEXITSTATUS(${^CHILD_ERROR_NATIVE}) returns the normal exit status of
2237 the child process (only meaningful if WIFEXITED(${^CHILD_ERROR_NATIVE})
2238 is true)
2239
2240 =item WIFSIGNALED
2241
2242 WIFSIGNALED(${^CHILD_ERROR_NATIVE}) returns true if the child process
2243 terminated because of a signal
2244
2245 =item WTERMSIG
2246
2247 WTERMSIG(${^CHILD_ERROR_NATIVE}) returns the signal the child process
2248 terminated for (only meaningful if WIFSIGNALED(${^CHILD_ERROR_NATIVE})
2249 is true)
2250
2251 =item WIFSTOPPED
2252
2253 WIFSTOPPED(${^CHILD_ERROR_NATIVE}) returns true if the child process is
2254 currently stopped (can happen only if you specified the WUNTRACED flag
2255 to waitpid())
2256
2257 =item WSTOPSIG
2258
2259 WSTOPSIG(${^CHILD_ERROR_NATIVE}) returns the signal the child process
2260 was stopped for (only meaningful if WIFSTOPPED(${^CHILD_ERROR_NATIVE})
2261 is true)
2262
2263 =back
2264
2265 =back
2266