This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
d5e93d0a05299773dcf2b7392864e9ef8c73040d
[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
731 Here is how to query the database for the B<de> (Deutsch or German) locale.
732
733         my $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" );
734         print "Locale: \"$loc\"\n";
735         my $lconv = POSIX::localeconv();
736         foreach my $property (qw(
737                 decimal_point
738                 thousands_sep
739                 grouping
740                 int_curr_symbol
741                 currency_symbol
742                 mon_decimal_point
743                 mon_thousands_sep
744                 mon_grouping
745                 positive_sign
746                 negative_sign
747                 int_frac_digits
748                 frac_digits
749                 p_cs_precedes
750                 p_sep_by_space
751                 n_cs_precedes
752                 n_sep_by_space
753                 p_sign_posn
754                 n_sign_posn
755         ))
756         {
757                 printf qq(%s: "%s",\n),
758                         $property, $lconv->{$property};
759         }
760
761 =item localtime
762
763 This is identical to Perl's builtin C<localtime()> function for
764 converting seconds since the epoch to a date see L<perlfunc/localtime>.
765
766 =item log
767
768 This is identical to Perl's builtin C<log()> function,
769 returning the natural (I<e>-based) logarithm of the numerical argument,
770 see L<perlfunc/log>.
771
772 =item log10
773
774 This is identical to the C function C<log10()>,
775 returning the 10-base logarithm of the numerical argument.
776 You can also use
777
778     sub log10 { log($_[0]) / log(10) }
779
780 or
781
782     sub log10 { log($_[0]) / 2.30258509299405 }
783
784 or
785
786     sub log10 { log($_[0]) * 0.434294481903252 }
787
788 =item longjmp
789
790 longjmp() is C-specific: use L<perlfunc/die> instead.
791
792 =item lseek
793
794 Move the file's read/write position.  This uses file descriptors such as
795 those obtained by calling C<POSIX::open>.
796
797         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
798         $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET );
799
800 Returns C<undef> on failure.
801
802 =item malloc
803
804 malloc() is C-specific.  Perl does memory management transparently.
805
806 =item mblen
807
808 This is identical to the C function C<mblen()>.
809 Perl does not have any support for the wide and multibyte
810 characters of the C standards, so this might be a rather
811 useless function.
812
813 =item mbstowcs
814
815 This is identical to the C function C<mbstowcs()>.
816 Perl does not have any support for the wide and multibyte
817 characters of the C standards, so this might be a rather
818 useless function.
819
820 =item mbtowc
821
822 This is identical to the C function C<mbtowc()>.
823 Perl does not have any support for the wide and multibyte
824 characters of the C standards, so this might be a rather
825 useless function.
826
827 =item memchr
828
829 memchr() is C-specific, see L<perlfunc/index> instead.
830
831 =item memcmp
832
833 memcmp() is C-specific, use C<eq> instead, see L<perlop>.
834
835 =item memcpy
836
837 memcpy() is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
838
839 =item memmove
840
841 memmove() is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
842
843 =item memset
844
845 memset() is C-specific, use C<x> instead, see L<perlop>.
846
847 =item mkdir
848
849 This is identical to Perl's builtin C<mkdir()> function
850 for creating directories, see L<perlfunc/mkdir>.
851
852 =item mkfifo
853
854 This is similar to the C function C<mkfifo()> for creating
855 FIFO special files.
856
857         if (mkfifo($path, $mode)) { ....
858
859 Returns C<undef> on failure.  The C<$mode> is similar to the
860 mode of C<mkdir()>, see L<perlfunc/mkdir>, though for C<mkfifo>
861 you B<must> specify the C<$mode>.
862
863 =item mktime
864
865 Convert date/time info to a calendar time.
866
867 Synopsis:
868
869         mktime(sec, min, hour, mday, mon, year, wday = 0,
870                yday = 0, isdst = -1)
871
872 The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
873 I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
874 year (C<year>) is given in years since 1900.  I.e. The year 1995 is 95; the
875 year 2001 is 101.  Consult your system's C<mktime()> manpage for details
876 about these and the other arguments.
877
878 Calendar time for December 12, 1995, at 10:30 am.
879
880         $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 );
881         print "Date = ", POSIX::ctime($time_t);
882
883 Returns C<undef> on failure.
884
885 =item modf
886
887 Return the integral and fractional parts of a floating-point number.
888
889         ($fractional, $integral) = POSIX::modf( 3.14 );
890
891 =item nice
892
893 This is similar to the C function C<nice()>, for changing
894 the scheduling preference of the current process.  Positive
895 arguments mean more polite process, negative values more
896 needy process.  Normal user processes can only be more polite.
897
898 Returns C<undef> on failure.
899
900 =item offsetof
901
902 offsetof() is C-specific, you probably want to see L<perlfunc/pack> instead.
903
904 =item open
905
906 Open a file for reading for writing.  This returns file descriptors, not
907 Perl filehandles.  Use C<POSIX::close> to close the file.
908
909 Open a file read-only with mode 0666.
910
911         $fd = POSIX::open( "foo" );
912
913 Open a file for read and write.
914
915         $fd = POSIX::open( "foo", &POSIX::O_RDWR );
916
917 Open a file for write, with truncation.
918
919         $fd = POSIX::open(
920                 "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC
921         );
922
923 Create a new file with mode 0640.  Set up the file for writing.
924
925         $fd = POSIX::open(
926                 "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640
927         );
928
929 Returns C<undef> on failure.
930
931 See also L<perlfunc/sysopen>.
932
933 =item opendir
934
935 Open a directory for reading.
936
937         $dir = POSIX::opendir( "/var" );
938         @files = POSIX::readdir( $dir );
939         POSIX::closedir( $dir );
940
941 Returns C<undef> on failure.
942
943 =item pathconf
944
945 Retrieves the value of a configurable limit on a file or directory.
946
947 The following will determine the maximum length of the longest allowable
948 pathname on the filesystem which holds C</var>.
949
950         $path_max = POSIX::pathconf( "/var",
951                                       &POSIX::_PC_PATH_MAX );
952
953 Returns C<undef> on failure.
954
955 =item pause
956
957 This is similar to the C function C<pause()>, which suspends
958 the execution of the current process until a signal is received.
959
960 Returns C<undef> on failure.
961
962 =item perror
963
964 This is identical to the C function C<perror()>, which outputs to the
965 standard error stream the specified message followed by ": " and the
966 current error string.  Use the C<warn()> function and the C<$!>
967 variable instead, see L<perlfunc/warn> and L<perlvar/$ERRNO>.
968
969 =item pipe
970
971 Create an interprocess channel.  This returns file descriptors like those
972 returned by C<POSIX::open>.
973
974         my ($read, $write) = POSIX::pipe();
975         POSIX::write( $write, "hello", 5 );
976         POSIX::read( $read, $buf, 5 );
977
978 See also L<perlfunc/pipe>.
979
980 =item pow
981
982 Computes C<$x> raised to the power C<$exponent>.
983
984         $ret = POSIX::pow( $x, $exponent );
985
986 You can also use the C<**> operator, see L<perlop>.
987
988 =item printf
989
990 Formats and prints the specified arguments to STDOUT.
991 See also L<perlfunc/printf>.
992
993 =item putc
994
995 putc() is C-specific, see L<perlfunc/print> instead.
996
997 =item putchar
998
999 putchar() is C-specific, see L<perlfunc/print> instead.
1000
1001 =item puts
1002
1003 puts() is C-specific, see L<perlfunc/print> instead.
1004
1005 =item qsort
1006
1007 qsort() is C-specific, see L<perlfunc/sort> instead.
1008
1009 =item raise
1010
1011 Sends the specified signal to the current process.
1012 See also L<perlfunc/kill> and the C<$$> in L<perlvar/$PID>.
1013
1014 =item rand
1015
1016 C<rand()> is non-portable, see L<perlfunc/rand> instead.
1017
1018 =item read
1019
1020 Read from a file.  This uses file descriptors such as those obtained by
1021 calling C<POSIX::open>.  If the buffer C<$buf> is not large enough for the
1022 read then Perl will extend it to make room for the request.
1023
1024         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
1025         $bytes = POSIX::read( $fd, $buf, 3 );
1026
1027 Returns C<undef> on failure.
1028
1029 See also L<perlfunc/sysread>.
1030
1031 =item readdir
1032
1033 This is identical to Perl's builtin C<readdir()> function
1034 for reading directory entries, see L<perlfunc/readdir>.
1035
1036 =item realloc
1037
1038 realloc() is C-specific.  Perl does memory management transparently.
1039
1040 =item remove
1041
1042 This is identical to Perl's builtin C<unlink()> function
1043 for removing files, see L<perlfunc/unlink>.
1044
1045 =item rename
1046
1047 This is identical to Perl's builtin C<rename()> function
1048 for renaming files, see L<perlfunc/rename>.
1049
1050 =item rewind
1051
1052 Seeks to the beginning of the file.
1053
1054 =item rewinddir
1055
1056 This is identical to Perl's builtin C<rewinddir()> function for
1057 rewinding directory entry streams, see L<perlfunc/rewinddir>.
1058
1059 =item rmdir
1060
1061 This is identical to Perl's builtin C<rmdir()> function
1062 for removing (empty) directories, see L<perlfunc/rmdir>.
1063
1064 =item scanf
1065
1066 scanf() is C-specific, use E<lt>E<gt> and regular expressions instead,
1067 see L<perlre>.
1068
1069 =item setgid
1070
1071 Sets the real group identifier and the effective group identifier for
1072 this process.  Similar to assigning a value to the Perl's builtin
1073 C<$)> variable, see L<perlvar/$EGID>, except that the latter
1074 will change only the real user identifier, and that the setgid()
1075 uses only a single numeric argument, as opposed to a space-separated
1076 list of numbers.
1077
1078 =item setjmp
1079
1080 C<setjmp()> is C-specific: use C<eval {}> instead,
1081 see L<perlfunc/eval>.
1082
1083 =item setlocale
1084
1085 Modifies and queries program's locale.  The following examples assume
1086
1087         use POSIX qw(setlocale LC_ALL LC_CTYPE);
1088
1089 has been issued.
1090
1091 The following will set the traditional UNIX system locale behavior
1092 (the second argument C<"C">).
1093
1094         $loc = setlocale( LC_ALL, "C" );
1095
1096 The following will query the current LC_CTYPE category.  (No second
1097 argument means 'query'.)
1098
1099         $loc = setlocale( LC_CTYPE );
1100
1101 The following will set the LC_CTYPE behaviour according to the locale
1102 environment variables (the second argument C<"">).
1103 Please see your systems C<setlocale(3)> documentation for the locale
1104 environment variables' meaning or consult L<perllocale>.
1105
1106         $loc = setlocale( LC_CTYPE, "" );
1107
1108 The following will set the LC_COLLATE behaviour to Argentinian
1109 Spanish. B<NOTE>: The naming and availability of locales depends on
1110 your operating system. Please consult L<perllocale> for how to find
1111 out which locales are available in your system.
1112
1113         $loc = setlocale( LC_COLLATE, "es_AR.ISO8859-1" );
1114
1115 =item setpgid
1116
1117 This is similar to the C function C<setpgid()> for
1118 setting the process group identifier of the current process.
1119
1120 Returns C<undef> on failure.
1121
1122 =item setsid
1123
1124 This is identical to the C function C<setsid()> for
1125 setting the session identifier of the current process.
1126
1127 =item setuid
1128
1129 Sets the real user identifier and the effective user identifier for
1130 this process.  Similar to assigning a value to the Perl's builtin
1131 C<$E<lt>> variable, see L<perlvar/$UID>, except that the latter
1132 will change only the real user identifier.
1133
1134 =item sigaction
1135
1136 Detailed signal management.  This uses C<POSIX::SigAction> objects for
1137 the C<action> and C<oldaction> arguments (the oldaction can also be
1138 just a hash reference).  Consult your system's C<sigaction> manpage
1139 for details, see also C<POSIX::SigRt>.
1140
1141 Synopsis:
1142
1143         sigaction(signal, action, oldaction = 0)
1144
1145 Returns C<undef> on failure.  The C<signal> must be a number (like
1146 SIGHUP), not a string (like "SIGHUP"), though Perl does try hard
1147 to understand you.
1148
1149 If you use the SA_SIGINFO flag, the signal handler will in addition to
1150 the first argument, the signal name, also receive a second argument, a
1151 hash reference, inside which are the following keys with the following
1152 semantics, as defined by POSIX/SUSv3:
1153
1154     signo       the signal number
1155     errno       the error number
1156     code        if this is zero or less, the signal was sent by
1157                 a user process and the uid and pid make sense,
1158                 otherwise the signal was sent by the kernel
1159
1160 The following are also defined by POSIX/SUSv3, but unfortunately
1161 not very widely implemented:
1162
1163     pid         the process id generating the signal
1164     uid         the uid of the process id generating the signal
1165     status      exit value or signal for SIGCHLD
1166     band        band event for SIGPOLL
1167
1168 A third argument is also passed to the handler, which contains a copy
1169 of the raw binary contents of the siginfo structure: if a system has
1170 some non-POSIX fields, this third argument is where to unpack() them
1171 from.
1172
1173 Note that not all siginfo values make sense simultaneously (some are
1174 valid only for certain signals, for example), and not all values make
1175 sense from Perl perspective, you should to consult your system's
1176 C<sigaction> and possibly also C<siginfo> documentation.
1177
1178 =item siglongjmp
1179
1180 siglongjmp() is C-specific: use L<perlfunc/die> instead.
1181
1182 =item sigpending
1183
1184 Examine signals that are blocked and pending.  This uses C<POSIX::SigSet>
1185 objects for the C<sigset> argument.  Consult your system's C<sigpending>
1186 manpage for details.
1187
1188 Synopsis:
1189
1190         sigpending(sigset)
1191
1192 Returns C<undef> on failure.
1193
1194 =item sigprocmask
1195
1196 Change and/or examine calling process's signal mask.  This uses
1197 C<POSIX::SigSet> objects for the C<sigset> and C<oldsigset> arguments.
1198 Consult your system's C<sigprocmask> manpage for details.
1199
1200 Synopsis:
1201
1202         sigprocmask(how, sigset, oldsigset = 0)
1203
1204 Returns C<undef> on failure.
1205
1206 Note that you can't reliably block or unblock a signal from its own signal
1207 handler if you're using safe signals. Other signals can be blocked or unblocked
1208 reliably.
1209
1210 =item sigsetjmp
1211
1212 C<sigsetjmp()> is C-specific: use C<eval {}> instead,
1213 see L<perlfunc/eval>.
1214
1215 =item sigsuspend
1216
1217 Install a signal mask and suspend process until signal arrives.  This uses
1218 C<POSIX::SigSet> objects for the C<signal_mask> argument.  Consult your
1219 system's C<sigsuspend> manpage for details.
1220
1221 Synopsis:
1222
1223         sigsuspend(signal_mask)
1224
1225 Returns C<undef> on failure.
1226
1227 =item sin
1228
1229 This is identical to Perl's builtin C<sin()> function
1230 for returning the sine of the numerical argument,
1231 see L<perlfunc/sin>.  See also L<Math::Trig>.
1232
1233 =item sinh
1234
1235 This is identical to the C function C<sinh()>
1236 for returning the hyperbolic sine of the numerical argument.
1237 See also L<Math::Trig>.
1238
1239 =item sleep
1240
1241 This is functionally identical to Perl's builtin C<sleep()> function
1242 for suspending the execution of the current for process for certain
1243 number of seconds, see L<perlfunc/sleep>.  There is one significant
1244 difference, however: C<POSIX::sleep()> returns the number of
1245 B<unslept> seconds, while the C<CORE::sleep()> returns the
1246 number of slept seconds.
1247
1248 =item sprintf
1249
1250 This is similar to Perl's builtin C<sprintf()> function
1251 for returning a string that has the arguments formatted as requested,
1252 see L<perlfunc/sprintf>.
1253
1254 =item sqrt
1255
1256 This is identical to Perl's builtin C<sqrt()> function.
1257 for returning the square root of the numerical argument,
1258 see L<perlfunc/sqrt>.
1259
1260 =item srand
1261
1262 Give a seed the pseudorandom number generator, see L<perlfunc/srand>.
1263
1264 =item sscanf
1265
1266 sscanf() is C-specific, use regular expressions instead,
1267 see L<perlre>.
1268
1269 =item stat
1270
1271 This is identical to Perl's builtin C<stat()> function
1272 for returning information about files and directories.
1273
1274 =item strcat
1275
1276 strcat() is C-specific, use C<.=> instead, see L<perlop>.
1277
1278 =item strchr
1279
1280 strchr() is C-specific, see L<perlfunc/index> instead.
1281
1282 =item strcmp
1283
1284 strcmp() is C-specific, use C<eq> or C<cmp> instead, see L<perlop>.
1285
1286 =item strcoll
1287
1288 This is identical to the C function C<strcoll()>
1289 for collating (comparing) strings transformed using
1290 the C<strxfrm()> function.  Not really needed since
1291 Perl can do this transparently, see L<perllocale>.
1292
1293 =item strcpy
1294
1295 strcpy() is C-specific, use C<=> instead, see L<perlop>.
1296
1297 =item strcspn
1298
1299 strcspn() is C-specific, use regular expressions instead,
1300 see L<perlre>.
1301
1302 =item strerror
1303
1304 Returns the error string for the specified errno.
1305 Identical to the string form of the C<$!>, see L<perlvar/$ERRNO>.
1306
1307 =item strftime
1308
1309 Convert date and time information to string.  Returns the string.
1310
1311 Synopsis:
1312
1313         strftime(fmt, sec, min, hour, mday, mon, year,
1314                  wday = -1, yday = -1, isdst = -1)
1315
1316 The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
1317 I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
1318 year (C<year>) is given in years since 1900.  I.e., the year 1995 is 95; the
1319 year 2001 is 101.  Consult your system's C<strftime()> manpage for details
1320 about these and the other arguments.
1321
1322 If you want your code to be portable, your format (C<fmt>) argument
1323 should use only the conversion specifiers defined by the ANSI C
1324 standard (C89, to play safe).  These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
1325 But even then, the B<results> of some of the conversion specifiers are
1326 non-portable.  For example, the specifiers C<aAbBcpZ> change according
1327 to the locale settings of the user, and both how to set locales (the
1328 locale names) and what output to expect are non-standard.
1329 The specifier C<c> changes according to the timezone settings of the
1330 user and the timezone computation rules of the operating system.
1331 The C<Z> specifier is notoriously unportable since the names of
1332 timezones are non-standard. Sticking to the numeric specifiers is the
1333 safest route.
1334
1335 The given arguments are made consistent as though by calling
1336 C<mktime()> before calling your system's C<strftime()> function,
1337 except that the C<isdst> value is not affected.
1338
1339 The string for Tuesday, December 12, 1995.
1340
1341         $str = POSIX::strftime( "%A, %B %d, %Y",
1342                                  0, 0, 0, 12, 11, 95, 2 );
1343         print "$str\n";
1344
1345 =item strlen
1346
1347 strlen() is C-specific, use C<length()> instead, see L<perlfunc/length>.
1348
1349 =item strncat
1350
1351 strncat() is C-specific, use C<.=> instead, see L<perlop>.
1352
1353 =item strncmp
1354
1355 strncmp() is C-specific, use C<eq> instead, see L<perlop>.
1356
1357 =item strncpy
1358
1359 strncpy() is C-specific, use C<=> instead, see L<perlop>.
1360
1361 =item strpbrk
1362
1363 strpbrk() is C-specific, use regular expressions instead,
1364 see L<perlre>.
1365
1366 =item strrchr
1367
1368 strrchr() is C-specific, see L<perlfunc/rindex> instead.
1369
1370 =item strspn
1371
1372 strspn() is C-specific, use regular expressions instead,
1373 see L<perlre>.
1374
1375 =item strstr
1376
1377 This is identical to Perl's builtin C<index()> function,
1378 see L<perlfunc/index>.
1379
1380 =item strtod
1381
1382 String to double translation. Returns the parsed number and the number
1383 of characters in the unparsed portion of the string.  Truly
1384 POSIX-compliant systems set $! ($ERRNO) to indicate a translation
1385 error, so clear $! before calling strtod.  However, non-POSIX systems
1386 may not check for overflow, and therefore will never set $!.
1387
1388 strtod should respect any POSIX I<setlocale()> settings.
1389
1390 To parse a string $str as a floating point number use
1391
1392     $! = 0;
1393     ($num, $n_unparsed) = POSIX::strtod($str);
1394
1395 The second returned item and $! can be used to check for valid input:
1396
1397     if (($str eq '') || ($n_unparsed != 0) || $!) {
1398         die "Non-numeric input $str" . ($! ? ": $!\n" : "\n");
1399     }
1400
1401 When called in a scalar context strtod returns the parsed number.
1402
1403 =item strtok
1404
1405 strtok() is C-specific, use regular expressions instead, see
1406 L<perlre>, or L<perlfunc/split>.
1407
1408 =item strtol
1409
1410 String to (long) integer translation.  Returns the parsed number and
1411 the number of characters in the unparsed portion of the string.  Truly
1412 POSIX-compliant systems set $! ($ERRNO) to indicate a translation
1413 error, so clear $! before calling strtol.  However, non-POSIX systems
1414 may not check for overflow, and therefore will never set $!.
1415
1416 strtol should respect any POSIX I<setlocale()> settings.
1417
1418 To parse a string $str as a number in some base $base use
1419
1420     $! = 0;
1421     ($num, $n_unparsed) = POSIX::strtol($str, $base);
1422
1423 The base should be zero or between 2 and 36, inclusive.  When the base
1424 is zero or omitted strtol will use the string itself to determine the
1425 base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
1426 octal; any other leading characters mean decimal.  Thus, "1234" is
1427 parsed as a decimal number, "01234" as an octal number, and "0x1234"
1428 as a hexadecimal number.
1429
1430 The second returned item and $! can be used to check for valid input:
1431
1432     if (($str eq '') || ($n_unparsed != 0) || !$!) {
1433         die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1434     }
1435
1436 When called in a scalar context strtol returns the parsed number.
1437
1438 =item strtoul
1439
1440 String to unsigned (long) integer translation.  strtoul() is identical
1441 to strtol() except that strtoul() only parses unsigned integers.  See
1442 L</strtol> for details.
1443
1444 Note: Some vendors supply strtod() and strtol() but not strtoul().
1445 Other vendors that do supply strtoul() parse "-1" as a valid value.
1446
1447 =item strxfrm
1448
1449 String transformation.  Returns the transformed string.
1450
1451         $dst = POSIX::strxfrm( $src );
1452
1453 Used in conjunction with the C<strcoll()> function, see L</strcoll>.
1454
1455 Not really needed since Perl can do this transparently, see
1456 L<perllocale>.
1457
1458 =item sysconf
1459
1460 Retrieves values of system configurable variables.
1461
1462 The following will get the machine's clock speed.
1463
1464         $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
1465
1466 Returns C<undef> on failure.
1467
1468 =item system
1469
1470 This is identical to Perl's builtin C<system()> function, see
1471 L<perlfunc/system>.
1472
1473 =item tan
1474
1475 This is identical to the C function C<tan()>, returning the
1476 tangent of the numerical argument.  See also L<Math::Trig>.
1477
1478 =item tanh
1479
1480 This is identical to the C function C<tanh()>, returning the
1481 hyperbolic tangent of the numerical argument.   See also L<Math::Trig>.
1482
1483 =item tcdrain
1484
1485 This is similar to the C function C<tcdrain()> for draining
1486 the output queue of its argument stream.
1487
1488 Returns C<undef> on failure.
1489
1490 =item tcflow
1491
1492 This is similar to the C function C<tcflow()> for controlling
1493 the flow of its argument stream.
1494
1495 Returns C<undef> on failure.
1496
1497 =item tcflush
1498
1499 This is similar to the C function C<tcflush()> for flushing
1500 the I/O buffers of its argument stream.
1501
1502 Returns C<undef> on failure.
1503
1504 =item tcgetpgrp
1505
1506 This is identical to the C function C<tcgetpgrp()> for returning the
1507 process group identifier of the foreground process group of the controlling
1508 terminal.
1509
1510 =item tcsendbreak
1511
1512 This is similar to the C function C<tcsendbreak()> for sending
1513 a break on its argument stream.
1514
1515 Returns C<undef> on failure.
1516
1517 =item tcsetpgrp
1518
1519 This is similar to the C function C<tcsetpgrp()> for setting the
1520 process group identifier of the foreground process group of the controlling
1521 terminal.
1522
1523 Returns C<undef> on failure.
1524
1525 =item time
1526
1527 This is identical to Perl's builtin C<time()> function
1528 for returning the number of seconds since the epoch
1529 (whatever it is for the system), see L<perlfunc/time>.
1530
1531 =item times
1532
1533 The times() function returns elapsed realtime since some point in the past
1534 (such as system startup), user and system times for this process, and user
1535 and system times used by child processes.  All times are returned in clock
1536 ticks.
1537
1538     ($realtime, $user, $system, $cuser, $csystem) 
1539         = POSIX::times();
1540
1541 Note: Perl's builtin C<times()> function returns four values, measured in
1542 seconds.
1543
1544 =item tmpfile
1545
1546 Use method C<IO::File::new_tmpfile()> instead, or see L<File::Temp>.
1547
1548 =item tmpnam
1549
1550 Returns a name for a temporary file.
1551
1552         $tmpfile = POSIX::tmpnam();
1553
1554 For security reasons, which are probably detailed in your system's
1555 documentation for the C library tmpnam() function, this interface
1556 should not be used; instead see L<File::Temp>.
1557
1558 =item tolower
1559
1560 This is identical to the C function, except that it can apply to a single
1561 character or to a whole string.  Consider using the C<lc()> function,
1562 see L<perlfunc/lc>, or the equivalent C<\L> operator inside doublequotish
1563 strings.
1564
1565 =item toupper
1566
1567 This is identical to the C function, except that it can apply to a single
1568 character or to a whole string.  Consider using the C<uc()> function,
1569 see L<perlfunc/uc>, or the equivalent C<\U> operator inside doublequotish
1570 strings.
1571
1572 =item ttyname
1573
1574 This is identical to the C function C<ttyname()> for returning the
1575 name of the current terminal.
1576
1577 =item tzname
1578
1579 Retrieves the time conversion information from the C<tzname> variable.
1580
1581         POSIX::tzset();
1582         ($std, $dst) = POSIX::tzname();
1583
1584 =item tzset
1585
1586 This is identical to the C function C<tzset()> for setting
1587 the current timezone based on the environment variable C<TZ>,
1588 to be used by C<ctime()>, C<localtime()>, C<mktime()>, and C<strftime()>
1589 functions.
1590
1591 =item umask
1592
1593 This is identical to Perl's builtin C<umask()> function
1594 for setting (and querying) the file creation permission mask,
1595 see L<perlfunc/umask>.
1596
1597 =item uname
1598
1599 Get name of current operating system.
1600
1601         ($sysname, $nodename, $release, $version, $machine)
1602                 = POSIX::uname();
1603
1604 Note that the actual meanings of the various fields are not
1605 that well standardized, do not expect any great portability.
1606 The C<$sysname> might be the name of the operating system,
1607 the C<$nodename> might be the name of the host, the C<$release>
1608 might be the (major) release number of the operating system,
1609 the C<$version> might be the (minor) release number of the
1610 operating system, and the C<$machine> might be a hardware identifier.
1611 Maybe.
1612
1613 =item ungetc
1614
1615 Use method C<IO::Handle::ungetc()> instead.
1616
1617 =item unlink
1618
1619 This is identical to Perl's builtin C<unlink()> function
1620 for removing files, see L<perlfunc/unlink>.
1621
1622 =item utime
1623
1624 This is identical to Perl's builtin C<utime()> function
1625 for changing the time stamps of files and directories,
1626 see L<perlfunc/utime>.
1627
1628 =item vfprintf
1629
1630 vfprintf() is C-specific, see L<perlfunc/printf> instead.
1631
1632 =item vprintf
1633
1634 vprintf() is C-specific, see L<perlfunc/printf> instead.
1635
1636 =item vsprintf
1637
1638 vsprintf() is C-specific, see L<perlfunc/sprintf> instead.
1639
1640 =item wait
1641
1642 This is identical to Perl's builtin C<wait()> function,
1643 see L<perlfunc/wait>.
1644
1645 =item waitpid
1646
1647 Wait for a child process to change state.  This is identical to Perl's
1648 builtin C<waitpid()> function, see L<perlfunc/waitpid>.
1649
1650         $pid = POSIX::waitpid( -1, POSIX::WNOHANG );
1651         print "status = ", ($? / 256), "\n";
1652
1653 =item wcstombs
1654
1655 This is identical to the C function C<wcstombs()>.
1656 Perl does not have any support for the wide and multibyte
1657 characters of the C standards, so this might be a rather
1658 useless function.
1659
1660 =item wctomb
1661
1662 This is identical to the C function C<wctomb()>.
1663 Perl does not have any support for the wide and multibyte
1664 characters of the C standards, so this might be a rather
1665 useless function.
1666
1667 =item write
1668
1669 Write to a file.  This uses file descriptors such as those obtained by
1670 calling C<POSIX::open>.
1671
1672         $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
1673         $buf = "hello";
1674         $bytes = POSIX::write( $fd, $buf, 5 );
1675
1676 Returns C<undef> on failure.
1677
1678 See also L<perlfunc/syswrite>.
1679
1680 =back
1681
1682 =head1 CLASSES
1683
1684 =head2 POSIX::SigAction
1685
1686 =over 8
1687
1688 =item new
1689
1690 Creates a new C<POSIX::SigAction> object which corresponds to the C
1691 C<struct sigaction>.  This object will be destroyed automatically when
1692 it is no longer needed.  The first parameter is the handler, a sub
1693 reference.  The second parameter is a C<POSIX::SigSet> object, it
1694 defaults to the empty set.  The third parameter contains the
1695 C<sa_flags>, it defaults to 0.
1696
1697         $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
1698         $sigaction = POSIX::SigAction->new(
1699                         \&handler, $sigset, &POSIX::SA_NOCLDSTOP
1700                      );
1701
1702 This C<POSIX::SigAction> object is intended for use with the C<POSIX::sigaction()>
1703 function.
1704
1705 =back
1706
1707 =over 8
1708
1709 =item handler
1710
1711 =item mask
1712
1713 =item flags
1714
1715 accessor functions to get/set the values of a SigAction object.
1716
1717         $sigset = $sigaction->mask;
1718         $sigaction->flags(&POSIX::SA_RESTART);
1719
1720 =item safe
1721
1722 accessor function for the "safe signals" flag of a SigAction object; see
1723 L<perlipc> for general information on safe (a.k.a. "deferred") signals.  If
1724 you wish to handle a signal safely, use this accessor to set the "safe" flag
1725 in the C<POSIX::SigAction> object:
1726
1727         $sigaction->safe(1);
1728
1729 You may also examine the "safe" flag on the output action object which is
1730 filled in when given as the third parameter to C<POSIX::sigaction()>:
1731
1732         sigaction(SIGINT, $new_action, $old_action);
1733         if ($old_action->safe) {
1734             # previous SIGINT handler used safe signals
1735         }
1736
1737 =back
1738
1739 =head2 POSIX::SigRt
1740
1741 =over 8
1742
1743 =item %SIGRT
1744
1745 A hash of the POSIX realtime signal handlers.  It is an extension of
1746 the standard %SIG, the $POSIX::SIGRT{SIGRTMIN} is roughly equivalent
1747 to $SIG{SIGRTMIN}, but the right POSIX moves (see below) are made with
1748 the POSIX::SigSet and POSIX::sigaction instead of accessing the %SIG.
1749
1750 You can set the %POSIX::SIGRT elements to set the POSIX realtime
1751 signal handlers, use C<delete> and C<exists> on the elements, and use
1752 C<scalar> on the C<%POSIX::SIGRT> to find out how many POSIX realtime
1753 signals there are available (SIGRTMAX - SIGRTMIN + 1, the SIGRTMAX is
1754 a valid POSIX realtime signal).
1755
1756 Setting the %SIGRT elements is equivalent to calling this:
1757
1758   sub new {
1759     my ($rtsig, $handler, $flags) = @_;
1760     my $sigset = POSIX::SigSet($rtsig);
1761     my $sigact = POSIX::SigAction->new($handler,$sigset,$flags);
1762     sigaction($rtsig, $sigact);
1763   }
1764
1765 The flags default to zero, if you want something different you can
1766 either use C<local> on $POSIX::SigRt::SIGACTION_FLAGS, or you can
1767 derive from POSIX::SigRt and define your own C<new()> (the tied hash
1768 STORE method of the %SIGRT calls C<new($rtsig, $handler, $SIGACTION_FLAGS)>,
1769 where the $rtsig ranges from zero to SIGRTMAX - SIGRTMIN + 1).
1770
1771 Just as with any signal, you can use sigaction($rtsig, undef, $oa) to
1772 retrieve the installed signal handler (or, rather, the signal action).
1773
1774 B<NOTE:> whether POSIX realtime signals really work in your system, or
1775 whether Perl has been compiled so that it works with them, is outside
1776 of this discussion.
1777
1778 =item SIGRTMIN
1779
1780 Return the minimum POSIX realtime signal number available, or C<undef>
1781 if no POSIX realtime signals are available.
1782
1783 =item SIGRTMAX
1784
1785 Return the maximum POSIX realtime signal number available, or C<undef>
1786 if no POSIX realtime signals are available.
1787
1788 =back
1789
1790 =head2 POSIX::SigSet
1791
1792 =over 8
1793
1794 =item new
1795
1796 Create a new SigSet object.  This object will be destroyed automatically
1797 when it is no longer needed.  Arguments may be supplied to initialize the
1798 set.
1799
1800 Create an empty set.
1801
1802         $sigset = POSIX::SigSet->new;
1803
1804 Create a set with SIGUSR1.
1805
1806         $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
1807
1808 =item addset
1809
1810 Add a signal to a SigSet object.
1811
1812         $sigset->addset( &POSIX::SIGUSR2 );
1813
1814 Returns C<undef> on failure.
1815
1816 =item delset
1817
1818 Remove a signal from the SigSet object.
1819
1820         $sigset->delset( &POSIX::SIGUSR2 );
1821
1822 Returns C<undef> on failure.
1823
1824 =item emptyset
1825
1826 Initialize the SigSet object to be empty.
1827
1828         $sigset->emptyset();
1829
1830 Returns C<undef> on failure.
1831
1832 =item fillset
1833
1834 Initialize the SigSet object to include all signals.
1835
1836         $sigset->fillset();
1837
1838 Returns C<undef> on failure.
1839
1840 =item ismember
1841
1842 Tests the SigSet object to see if it contains a specific signal.
1843
1844         if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
1845                 print "contains SIGUSR1\n";
1846         }
1847
1848 =back
1849
1850 =head2 POSIX::Termios
1851
1852 =over 8
1853
1854 =item new
1855
1856 Create a new Termios object.  This object will be destroyed automatically
1857 when it is no longer needed.  A Termios object corresponds to the termios
1858 C struct.  new() mallocs a new one, getattr() fills it from a file descriptor,
1859 and setattr() sets a file descriptor's parameters to match Termios' contents.
1860
1861         $termios = POSIX::Termios->new;
1862
1863 =item getattr
1864
1865 Get terminal control attributes.
1866
1867 Obtain the attributes for stdin.
1868
1869         $termios->getattr( 0 ) # Recommended for clarity.
1870         $termios->getattr()
1871
1872 Obtain the attributes for stdout.
1873
1874         $termios->getattr( 1 )
1875
1876 Returns C<undef> on failure.
1877
1878 =item getcc
1879
1880 Retrieve a value from the c_cc field of a termios object.  The c_cc field is
1881 an array so an index must be specified.
1882
1883         $c_cc[1] = $termios->getcc(1);
1884
1885 =item getcflag
1886
1887 Retrieve the c_cflag field of a termios object.
1888
1889         $c_cflag = $termios->getcflag;
1890
1891 =item getiflag
1892
1893 Retrieve the c_iflag field of a termios object.
1894
1895         $c_iflag = $termios->getiflag;
1896
1897 =item getispeed
1898
1899 Retrieve the input baud rate.
1900
1901         $ispeed = $termios->getispeed;
1902
1903 =item getlflag
1904
1905 Retrieve the c_lflag field of a termios object.
1906
1907         $c_lflag = $termios->getlflag;
1908
1909 =item getoflag
1910
1911 Retrieve the c_oflag field of a termios object.
1912
1913         $c_oflag = $termios->getoflag;
1914
1915 =item getospeed
1916
1917 Retrieve the output baud rate.
1918
1919         $ospeed = $termios->getospeed;
1920
1921 =item setattr
1922
1923 Set terminal control attributes.
1924
1925 Set attributes immediately for stdout.
1926
1927         $termios->setattr( 1, &POSIX::TCSANOW );
1928
1929 Returns C<undef> on failure.
1930
1931 =item setcc
1932
1933 Set a value in the c_cc field of a termios object.  The c_cc field is an
1934 array so an index must be specified.
1935
1936         $termios->setcc( &POSIX::VEOF, 1 );
1937
1938 =item setcflag
1939
1940 Set the c_cflag field of a termios object.
1941
1942         $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
1943
1944 =item setiflag
1945
1946 Set the c_iflag field of a termios object.
1947
1948         $termios->setiflag( $c_iflag | &POSIX::BRKINT );
1949
1950 =item setispeed
1951
1952 Set the input baud rate.
1953
1954         $termios->setispeed( &POSIX::B9600 );
1955
1956 Returns C<undef> on failure.
1957
1958 =item setlflag
1959
1960 Set the c_lflag field of a termios object.
1961
1962         $termios->setlflag( $c_lflag | &POSIX::ECHO );
1963
1964 =item setoflag
1965
1966 Set the c_oflag field of a termios object.
1967
1968         $termios->setoflag( $c_oflag | &POSIX::OPOST );
1969
1970 =item setospeed
1971
1972 Set the output baud rate.
1973
1974         $termios->setospeed( &POSIX::B9600 );
1975
1976 Returns C<undef> on failure.
1977
1978 =item Baud rate values
1979
1980 B38400 B75 B200 B134 B300 B1800 B150 B0 B19200 B1200 B9600 B600 B4800 B50 B2400 B110
1981
1982 =item Terminal interface values
1983
1984 TCSADRAIN TCSANOW TCOON TCIOFLUSH TCOFLUSH TCION TCIFLUSH TCSAFLUSH TCIOFF TCOOFF
1985
1986 =item c_cc field values
1987
1988 VEOF VEOL VERASE VINTR VKILL VQUIT VSUSP VSTART VSTOP VMIN VTIME NCCS
1989
1990 =item c_cflag field values
1991
1992 CLOCAL CREAD CSIZE CS5 CS6 CS7 CS8 CSTOPB HUPCL PARENB PARODD
1993
1994 =item c_iflag field values
1995
1996 BRKINT ICRNL IGNBRK IGNCR IGNPAR INLCR INPCK ISTRIP IXOFF IXON PARMRK
1997
1998 =item c_lflag field values
1999
2000 ECHO ECHOE ECHOK ECHONL ICANON IEXTEN ISIG NOFLSH TOSTOP
2001
2002 =item c_oflag field values
2003
2004 OPOST
2005
2006 =back
2007
2008 =head1 PATHNAME CONSTANTS
2009
2010 =over 8
2011
2012 =item Constants
2013
2014 _PC_CHOWN_RESTRICTED _PC_LINK_MAX _PC_MAX_CANON _PC_MAX_INPUT _PC_NAME_MAX
2015 _PC_NO_TRUNC _PC_PATH_MAX _PC_PIPE_BUF _PC_VDISABLE
2016
2017 =back
2018
2019 =head1 POSIX CONSTANTS
2020
2021 =over 8
2022
2023 =item Constants
2024
2025 _POSIX_ARG_MAX _POSIX_CHILD_MAX _POSIX_CHOWN_RESTRICTED _POSIX_JOB_CONTROL
2026 _POSIX_LINK_MAX _POSIX_MAX_CANON _POSIX_MAX_INPUT _POSIX_NAME_MAX
2027 _POSIX_NGROUPS_MAX _POSIX_NO_TRUNC _POSIX_OPEN_MAX _POSIX_PATH_MAX
2028 _POSIX_PIPE_BUF _POSIX_SAVED_IDS _POSIX_SSIZE_MAX _POSIX_STREAM_MAX
2029 _POSIX_TZNAME_MAX _POSIX_VDISABLE _POSIX_VERSION
2030
2031 =back
2032
2033 =head1 SYSTEM CONFIGURATION
2034
2035 =over 8
2036
2037 =item Constants
2038
2039 _SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_JOB_CONTROL _SC_NGROUPS_MAX
2040 _SC_OPEN_MAX _SC_PAGESIZE _SC_SAVED_IDS _SC_STREAM_MAX _SC_TZNAME_MAX
2041 _SC_VERSION
2042
2043 =back
2044
2045 =head1 ERRNO
2046
2047 =over 8
2048
2049 =item Constants
2050
2051 E2BIG EACCES EADDRINUSE EADDRNOTAVAIL EAFNOSUPPORT EAGAIN EALREADY EBADF
2052 EBUSY ECHILD ECONNABORTED ECONNREFUSED ECONNRESET EDEADLK EDESTADDRREQ
2053 EDOM EDQUOT EEXIST EFAULT EFBIG EHOSTDOWN EHOSTUNREACH EINPROGRESS EINTR
2054 EINVAL EIO EISCONN EISDIR ELOOP EMFILE EMLINK EMSGSIZE ENAMETOOLONG
2055 ENETDOWN ENETRESET ENETUNREACH ENFILE ENOBUFS ENODEV ENOENT ENOEXEC
2056 ENOLCK ENOMEM ENOPROTOOPT ENOSPC ENOSYS ENOTBLK ENOTCONN ENOTDIR
2057 ENOTEMPTY ENOTSOCK ENOTTY ENXIO EOPNOTSUPP EPERM EPFNOSUPPORT EPIPE
2058 EPROCLIM EPROTONOSUPPORT EPROTOTYPE ERANGE EREMOTE ERESTART EROFS
2059 ESHUTDOWN ESOCKTNOSUPPORT ESPIPE ESRCH ESTALE ETIMEDOUT ETOOMANYREFS
2060 ETXTBSY EUSERS EWOULDBLOCK EXDEV
2061
2062 =back
2063
2064 =head1 FCNTL
2065
2066 =over 8
2067
2068 =item Constants
2069
2070 FD_CLOEXEC F_DUPFD F_GETFD F_GETFL F_GETLK F_OK F_RDLCK F_SETFD F_SETFL F_SETLK
2071 F_SETLKW F_UNLCK F_WRLCK O_ACCMODE O_APPEND O_CREAT O_EXCL O_NOCTTY O_NONBLOCK
2072 O_RDONLY O_RDWR O_TRUNC O_WRONLY
2073
2074 =back
2075
2076 =head1 FLOAT
2077
2078 =over 8
2079
2080 =item Constants
2081
2082 DBL_DIG DBL_EPSILON DBL_MANT_DIG DBL_MAX DBL_MAX_10_EXP DBL_MAX_EXP DBL_MIN
2083 DBL_MIN_10_EXP DBL_MIN_EXP FLT_DIG FLT_EPSILON FLT_MANT_DIG FLT_MAX
2084 FLT_MAX_10_EXP FLT_MAX_EXP FLT_MIN FLT_MIN_10_EXP FLT_MIN_EXP FLT_RADIX
2085 FLT_ROUNDS LDBL_DIG LDBL_EPSILON LDBL_MANT_DIG LDBL_MAX LDBL_MAX_10_EXP
2086 LDBL_MAX_EXP LDBL_MIN LDBL_MIN_10_EXP LDBL_MIN_EXP
2087
2088 =back
2089
2090 =head1 LIMITS
2091
2092 =over 8
2093
2094 =item Constants
2095
2096 ARG_MAX CHAR_BIT CHAR_MAX CHAR_MIN CHILD_MAX INT_MAX INT_MIN LINK_MAX LONG_MAX
2097 LONG_MIN MAX_CANON MAX_INPUT MB_LEN_MAX NAME_MAX NGROUPS_MAX OPEN_MAX PATH_MAX
2098 PIPE_BUF SCHAR_MAX SCHAR_MIN SHRT_MAX SHRT_MIN SSIZE_MAX STREAM_MAX TZNAME_MAX
2099 UCHAR_MAX UINT_MAX ULONG_MAX USHRT_MAX
2100
2101 =back
2102
2103 =head1 LOCALE
2104
2105 =over 8
2106
2107 =item Constants
2108
2109 LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME
2110
2111 =back
2112
2113 =head1 MATH
2114
2115 =over 8
2116
2117 =item Constants
2118
2119 HUGE_VAL
2120
2121 =back
2122
2123 =head1 SIGNAL
2124
2125 =over 8
2126
2127 =item Constants
2128
2129 SA_NOCLDSTOP SA_NOCLDWAIT SA_NODEFER SA_ONSTACK SA_RESETHAND SA_RESTART
2130 SA_SIGINFO SIGABRT SIGALRM SIGCHLD SIGCONT SIGFPE SIGHUP SIGILL SIGINT
2131 SIGKILL SIGPIPE SIGQUIT SIGSEGV SIGSTOP SIGTERM SIGTSTP SIGTTIN SIGTTOU
2132 SIGUSR1 SIGUSR2 SIG_BLOCK SIG_DFL SIG_ERR SIG_IGN SIG_SETMASK
2133 SIG_UNBLOCK
2134
2135 =back
2136
2137 =head1 STAT
2138
2139 =over 8
2140
2141 =item Constants
2142
2143 S_IRGRP S_IROTH S_IRUSR S_IRWXG S_IRWXO S_IRWXU S_ISGID S_ISUID S_IWGRP S_IWOTH
2144 S_IWUSR S_IXGRP S_IXOTH S_IXUSR
2145
2146 =item Macros
2147
2148 S_ISBLK S_ISCHR S_ISDIR S_ISFIFO S_ISREG
2149
2150 =back
2151
2152 =head1 STDLIB
2153
2154 =over 8
2155
2156 =item Constants
2157
2158 EXIT_FAILURE EXIT_SUCCESS MB_CUR_MAX RAND_MAX
2159
2160 =back
2161
2162 =head1 STDIO
2163
2164 =over 8
2165
2166 =item Constants
2167
2168 BUFSIZ EOF FILENAME_MAX L_ctermid L_cuserid L_tmpname TMP_MAX
2169
2170 =back
2171
2172 =head1 TIME
2173
2174 =over 8
2175
2176 =item Constants
2177
2178 CLK_TCK CLOCKS_PER_SEC
2179
2180 =back
2181
2182 =head1 UNISTD
2183
2184 =over 8
2185
2186 =item Constants
2187
2188 R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STDERR_FILENO W_OK X_OK
2189
2190 =back
2191
2192 =head1 WAIT
2193
2194 =over 8
2195
2196 =item Constants
2197
2198 WNOHANG WUNTRACED
2199
2200 =over 16
2201
2202 =item WNOHANG
2203
2204 Do not suspend the calling process until a child process
2205 changes state but instead return immediately.
2206
2207 =item WUNTRACED
2208
2209 Catch stopped child processes.
2210
2211 =back
2212
2213 =item Macros
2214
2215 WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG WIFSTOPPED WSTOPSIG
2216
2217 =over 16
2218
2219 =item WIFEXITED
2220
2221 WIFEXITED(${^CHILD_ERROR_NATIVE}) returns true if the child process
2222 exited normally (C<exit()> or by falling off the end of C<main()>)
2223
2224 =item WEXITSTATUS
2225
2226 WEXITSTATUS(${^CHILD_ERROR_NATIVE}) returns the normal exit status of
2227 the child process (only meaningful if WIFEXITED(${^CHILD_ERROR_NATIVE})
2228 is true)
2229
2230 =item WIFSIGNALED
2231
2232 WIFSIGNALED(${^CHILD_ERROR_NATIVE}) returns true if the child process
2233 terminated because of a signal
2234
2235 =item WTERMSIG
2236
2237 WTERMSIG(${^CHILD_ERROR_NATIVE}) returns the signal the child process
2238 terminated for (only meaningful if WIFSIGNALED(${^CHILD_ERROR_NATIVE})
2239 is true)
2240
2241 =item WIFSTOPPED
2242
2243 WIFSTOPPED(${^CHILD_ERROR_NATIVE}) returns true if the child process is
2244 currently stopped (can happen only if you specified the WUNTRACED flag
2245 to waitpid())
2246
2247 =item WSTOPSIG
2248
2249 WSTOPSIG(${^CHILD_ERROR_NATIVE}) returns the signal the child process
2250 was stopped for (only meaningful if WIFSTOPPED(${^CHILD_ERROR_NATIVE})
2251 is true)
2252
2253 =back
2254
2255 =back
2256